pystac.stac_io#

class pystac.stac_io.DefaultStacIO(headers: dict[str, str] | None = None)[source]#
read_text(source: str | PathLike[str], *_: Any, **__: Any) → str[source]#

A concrete implementation of StacIO.read_text. Converts the source argument to a string (if it is not already) and delegates to DefaultStacIO.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 use urllib.request.urlopen() (or func:urllib3.PoolManager().request if available) 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: str | PathLike[str], txt: str, *_: Any, **__: Any) → None[source]#

A concrete implementation of StacIO.write_text. Converts the dest argument to a string (if it is not already) and delegates to W:meth:~pystac.stac_io.DefaultStacIO.write_text_to_href for opening and reading the file.

write_text_to_href(href: str, txt: str) → None[source]#

Writes text to file using UTF-8 encoding.

This implementation uses open() and therefore can only write to the local file system.

Parameters:

  • href – The path to which the file will be written.

  • txt – The string content to write to the file.

class pystac.stac_io.DuplicateKeyReportingMixin(headers: dict[str, str] | None = None)[source]#

A mixin for pystac.StacIO implementations that will report on duplicate keys in the JSON being read in.

See stac-utils/pystac#313

json_loads(txt: str, *_: Any, **__: Any) → dict[str, Any][source]#

Overwrites StacIO.json_loads as the internal method used by DuplicateKeyReportingMixin 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: str | PathLike[str], *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.RetryStacIO(headers: dict[str, str] | None = None, retry: Retry | None = None)[source]#

A customized StacIO that retries requests, using urllib3.util.retry.Retry.

The headers are passed to DefaultStacIO. If retry is not provided, a default retry is used.

To use this class, you’ll need to install PySTAC with urllib3:

pip install pystac[urllib3]
read_text_from_href(href: str) → str[source]#

Reads file as a UTF-8 string, with retry support.

Parameters:

href – The URI of the file to open.

retry#

The urllib3.util.retry.Retry to use with all reading network requests.

class pystac.stac_io.StacIO(headers: dict[str, str] | None = None)[source]#
classmethod default() → 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 subclasses to provide custom serialization logic. The method accepts arbitrary keyword arguments. These are not used by the default implementation, but may be used by subclass 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 subclasses to provide custom deserialization logic. The method accepts arbitrary keyword arguments. These are not used by the default implementation, but may be used by subclass implementations.

Parameters:

txt – The JSON string to deserialize to a dictionary.

read_json(source: str | PathLike[str], *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:

dict

read_stac_object(source: HREF, root: Catalog | None = None, *args: Any, **kwargs: Any) → STACObject[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:

STACObject

abstractmethod read_text(source: str | PathLike[str], *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 a Link 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:

str

save_json(dest: str | PathLike[str], 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[[], StacIO]) → None[source]#

Set the default StacIO instance to use.

stac_object_from_dict(d: dict[str, Any], href: HREF | None = None, root: Catalog | None = None, preserve_dict: bool = True) → STACObject[source]#

Deserializes a STACObject subclass 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 parameter d may be modified during this method call. Otherwise, the dict is not mutated. Defaults to True, which results in a deepcopy of the parameter. Set to False when possible to avoid the performance hit of a deepcopy.

abstractmethod write_text(dest: str | PathLike[str], 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 a Link enables implementations to use additional link information.

Parameters:

  • dest – The destination to write to.

  • txt – The text to write.