pystac.stac_io#
- class pystac.stac_io.DefaultStacIO[source]#
- read_text(source: Union[str, os.PathLike], *_: Any, **__: Any) str [source]#
A concrete implementation of
StacIO.read_text
. Converts thesource
argument to a string (if it is not already) and delegates toDefaultStacIO.read_text_from_href()
for opening and reading the file.
- read_text_from_href(href: str) str [source]#
Reads file as a UTF-8 string.
If
href
has a “scheme” (e.g. if it starts with “https://”) then this will useurllib.request.urlopen()
to open the file and read the contents; otherwise,open()
will be used to open a local file.- Parameters
href – The URI of the file to open.
- write_text(dest: Union[str, os.PathLike], txt: str, *_: Any, **__: Any) None [source]#
A concrete implementation of
StacIO.write_text
. Converts thedest
argument to a string (if it is not already) and delegates toDefaultStacIO.write_text_from_href()
for opening and reading the file.
- class pystac.stac_io.DuplicateKeyReportingMixin[source]#
A mixin for
pystac.StacIO
implementations that will report on duplicate keys in the JSON being read in.See https://github.com/stac-utils/pystac/issues/313
- json_loads(txt: str, *_: Any, **__: Any) Dict[str, Any] [source]#
Overwrites
StacIO.json_loads
as the internal method used byDuplicateKeyReportingMixin
for deserializing a JSON string to a dictionary while checking for duplicate object keys.- Raises
pystac.DuplicateObjectKeyError – If a duplicate object key is found.
- read_json(source: Union[str, os.PathLike], *args: Any, **kwargs: Any) Dict[str, Any] [source]#
Overwrites
StacIO.read_json
for deserializing a JSON file to a dictionary while checking for duplicate object keys.- Raises
pystac.DuplicateObjectKeyError – If a duplicate object key is found.
- class pystac.stac_io.StacIO[source]#
- classmethod default() pystac.stac_io.StacIO [source]#
- json_dumps(json_dict: Dict[str, Any], *args: Any, **kwargs: Any) str [source]#
Method used internally by
StacIO
instances to serialize a dictionary to a JSON string.This method may be overwritten in
StacIO
sub-classes to provide custom serialization logic. The method accepts arbitrary keyword arguments. These are not used by the default implementation, but may be used by sub-class implementations.- Parameters
json_dict – The dictionary to serialize
- json_loads(txt: str, *args: Any, **kwargs: Any) Dict[str, Any] [source]#
Method used internally by
StacIO
instances to deserialize a dictionary from a JSON string.This method may be overwritten in
StacIO
sub-classes to provide custom deserialization logic. The method accepts arbitrary keyword arguments. These are not used by the default implementation, but may be used by sub-class implementations.- Parameters
txt – The JSON string to deserialize to a dictionary.
- read_json(source: Union[str, os.PathLike], *args: Any, **kwargs: Any) Dict[str, Any] [source]#
Read a dict from the given source.
See
StacIO.read_text
for usage of str vs Link as a parameter.- Parameters
source – The source from which to read.
*args – Additional positional arguments to be passed to
StacIO.read_text()
.**kwargs – Additional keyword arguments to be passed to
StacIO.read_text()
.
- Returns
A dict representation of the JSON contained in the file at the given source.
- Return type
- read_stac_object(source: Union[str, os.PathLike], root: Optional[Catalog_Type] = None, *args: Any, **kwargs: Any) STACObject_Type [source]#
Read a STACObject from a JSON file at the given source.
See
StacIO.read_text
for usage of str vs Link as a parameter.- Parameters
source – The source from which to read.
root – Optional root of the catalog for this object. If provided, the root’s resolved object cache can be used to search for previously resolved instances of the STAC object.
*args – Additional positional arguments to be passed to
StacIO.read_json()
.**kwargs – Additional keyword arguments to be passed to
StacIO.read_json()
.
- Returns
The deserialized STACObject from the serialized JSON contained in the file at the given uri.
- Return type
- abstract read_text(source: Union[str, os.PathLike], *args: Any, **kwargs: Any) str [source]#
Read text from the given URI.
The source to read from can be specified as a string or
os.PathLike
object (Link
is a path-like object). If it is a string, it must be a URI or local path from which to read. Using aLink
enables implementations to use additional link information, such as paging information contained in the extended links described in the STAC API spec.- Parameters
source – The source to read from.
*args – Arbitrary positional arguments that may be utilized by the concrete implementation.
**kwargs – Arbitrary keyword arguments that may be utilized by the concrete implementation.
- Returns
The text contained in the file at the location specified by the uri.
- Return type
- save_json(dest: Union[str, os.PathLike], json_dict: Dict[str, Any], *args: Any, **kwargs: Any) None [source]#
Write a dict to the given URI as JSON.
See
StacIO.write_text
for usage of str vs Link as a parameter.- Parameters
dest – The destination file to write the text to.
json_dict – The JSON dict to write.
*args – Additional positional arguments to be passed to
StacIO.json_dumps()
.**kwargs – Additional keyword arguments to be passed to
StacIO.json_dumps()
.
- classmethod set_default(stac_io_class: Callable[[], pystac.stac_io.StacIO]) None [source]#
Set the default StacIO instance to use.
- stac_object_from_dict(d: Dict[str, Any], href: Optional[Union[str, os.PathLike]] = None, root: Optional[Catalog_Type] = None, preserve_dict: bool = True) STACObject_Type [source]#
Deserializes a
STACObject
sub-class instance from a dictionary.- Parameters
d – The dictionary to deserialize
href – Optional href to associate with the STAC object
root – Optional root
Catalog
to associate with the STAC object.preserve_dict – If
False
, the dict parameterd
may be modified during this method call. Otherwise the dict is not mutated. Defaults toTrue
, which results results in a deepcopy of the parameter. Set toFalse
when possible to avoid the performance hit of a deepcopy.
- abstract write_text(dest: Union[str, os.PathLike], txt: str, *args: Any, **kwargs: Any) None [source]#
Write the given text to a file at the given URI.
The destination to write to can be specified as a string or
os.PathLike
object (Link
is a path-like object). If it is a string, it must be a URI or local path from which to read. Using aLink
enables implementations to use additional link information.- Parameters
dest – The destination to write to.
txt – The text to write.