pystac.stac_io#

class pystac.stac_io.DefaultStacIO(headers: dict[str, str] | None = None)[source]#
read_text(source: str | PathLike, *_: 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() 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, 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 DefaultStacIO.write_text_from_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, *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: 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 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: str | 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:

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

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

abstract write_text(dest: str | 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 a Link enables implementations to use additional link information.

Parameters:

  • dest – The destination to write to.

  • txt – The text to write.