Skip to main content
`Ctrl`+`K`

# pystac.stac_io

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

    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

    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[str], txt: str, *_: Any, **__: Any) → None

    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

    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)

  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]

    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]

    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)

  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

    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)
  classmethod default() → StacIO
  json_dumps(json_dict: dict[str, Any], *args: Any, **kwargs: Any) → str

    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]

    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[str], *args: Any, **kwargs: Any) → dict[str, Any]

    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

    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[str], *args: Any, **kwargs: Any) → str

    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

    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

    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

    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[str], txt: str, *args: Any, **kwargs: Any) → None

    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.