Skip to main content
`Ctrl`+`K`

# pystac.utils

pystac.utils.HREF: TypeAlias = str | os.PathLike[str]

  HREF string or path-like object.

class pystac.utils.JoinType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  DEPRECATED.

  Deprecated since version 1.8.0: No longer used internally by pystac.

  Allowed join types for `join_path_or_url()`.

  PATH = 'path'
  URL = 'url'
  static from_parsed_uri(parsed_uri: ParseResult) → JoinType

    DEPRECATED.

    Deprecated since version 1.8.0: No longer used internally by pystac.

    Determines the appropriate join type based on the scheme of the parsed result.

    Parameters:

      parsed_uri (urllib.parse.ParseResult) – A named tuple representing the parsed URI.

    Returns:

      The join type for the URI.

    Return type:

      JoinType

class pystac.utils.StringEnum(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

  Base `enum.Enum` class for string enums that will serialize as the string value.

pystac.utils.datetime_to_str(dt: datetime, timespec: str = 'auto') → str

  Converts a `datetime.datetime` instance to an ISO8601 string in the RFC 3339, section 5.6 format required by the STAC Spec.

  Parameters:

    - dt – The datetime to convert.

    - timespec – An optional argument that specifies the number of additional terms of the time to include. Valid options are ‘auto’, ‘hours’, ‘minutes’, ‘seconds’, ‘milliseconds’ and ‘microseconds’. The default value is ‘auto’.

  Returns:

    The ISO8601 (RFC 3339) formatted string representing the datetime.

  Return type:

    str

pystac.utils.geometry_to_bbox(geometry: dict[str, Any]) → list[float]

  Extract the bounding box from a geojson geometry

  Parameters:

    geometry – GeoJSON geometry dict

  Returns:

    Bounding box of geojson geometry, formatted according to: https://tools.ietf.org/html/rfc7946#section-5

  Return type:

    list

pystac.utils.get_opt(option: T | None) → T

  Retrieves the value of the `Optional` type, raising a `ValueError` if the value is `None`.

  Use this to get a properly typed value from an optional in contexts where you can be certain the value is not `None`. If there is potential for a non-`None` value, it’s best to handle the `None` case of the optional instead of using this method.

  Parameters:

    option (Optional[T]) – Some `Optional` value

  Returns:

    The value of type T wrapped by the Optional[T]

  Examples

      d = {
          "some_key": "some_value"
      }

      # This passes
      val: str = get_opt(d.get("some_key"))

      # This raises a ValueError
      val: str = get_opt(d.get("does_not_exist"))

pystac.utils.get_required(option: T | None, obj: str | Any, prop: str) → T

  Retrieves an `Optional` value that comes from a required property of some object. If the option is `None`, throws an `pystac.RequiredPropertyMissing` with the given obj and property.

  This method is primarily used internally to retrieve properly typed required properties from dictionaries. For an example usage, see the `pystac.extensions.eo.Band.name` source code.

  Parameters:

    - option (Optional[T]) – The `Optional` value.

    - obj (str, Any) – The object from which the value is being retrieved. This will be passed to the `RequiredPropertyMissing` exception if `option` is `None`.

    - prop (str) – The name of the property being retrieved.

  Returns:

    The properly typed, non-`None` value.

  Return type:

    T

pystac.utils.is_absolute_href(href: str) → bool

  Determines if an HREF is absolute or not.

  May be used on either local file paths or URLs.

  Parameters:

    href – The HREF to consider.

  Returns:

    `True` if the given HREF is absolute, `False` if it is relative.

  Return type:

    bool

pystac.utils.is_file_path(href: str) → bool

  Checks if an HREF resembles a file path.

  This method checks if the given HREF resembles a file path. It checks if the path ends with any kind of file extension and if true, assumes it is a file. Unlike os.path.isfile() it does NOT check the actual file.

  Caution: There are cases for which this method may return wrong results!

  Parameters:

    href (str) – The HREF to consider.

  Returns:

    `True` if the given HREF resembles a file path,

      `False` if it does not.

  Return type:

    bool

pystac.utils.join_path_or_url(join_type: JoinType, *args: str) → str

  DEPRECATED.

  Deprecated since version 1.8.0: No longer used internally by pystac.

  Functions similarly to `os.path.join()`, but can be used to join either a local file path or a URL.

  Parameters:

    - join_type (JoinType) – One of `JoinType.PATH` or `JoinType.URL`. If `JoinType.PATH`, then `os.path.join()` is used for the join. If `JoinType.URL`, then `posixpath.join` is used.

    - *args (str) – Additional positional string arguments to be joined.

  Returns:

    The joined path

  Return type:

    str

pystac.utils.make_absolute_href(source_href: str, start_href: str | None = None, start_is_dir: bool = False) → str

  Returns a new string that represents `source_href` as an absolute path. If `source_href` is already absolute it is returned unchanged. If `source_href` is relative, the absolute HREF is constructed by joining `source_href` to `start_href`.

  May be used on either local file paths or URLs.

  Parameters:

    - source_href – The HREF to make absolute.

    - start_href – The HREF that will be used as the basis for resolving relative paths, if `source_href` is a relative path. Defaults to the current working directory.

    - start_is_dir – If `True`, `start_href` is treated as a directory. Otherwise, `start_href` is considered to be a path to a file. Defaults to `False`.

  Returns:

    The absolute HREF.

  Return type:

    str

pystac.utils.make_posix_style(href: str | PathLike[str]) → str

  Converts double back slashes and single back slashes to single forward slashes for converting Windows paths to Posix style.

  Parameters:

    href (str | os.PathLike) – The href string or path-like object.

  Returns:

    The converted href in string form.

  Return type:

    str

pystac.utils.make_relative_href(source_href: str, start_href: str, start_is_dir: bool = False) → str

  Returns a new string that represents the `source_href` as a path relative to `start_href`. If `source_href` and `start_href` do not share a common parent, then `source_href` is returned unchanged.

  May be used on either local file paths or URLs.

  Parameters:

    - source_href – The HREF to make relative.

    - start_href – The HREF that the resulting HREF will be relative to.

    - start_is_dir – If `True`, `start_href` is treated as a directory. Otherwise, `start_href` is considered to be a path to a file. Defaults to `False`.

  Returns:

    The relative HREF.

  Return type:

    str

pystac.utils.map_opt(fn: Callable[[T], U], v: T | None) → U | None

  Maps the value of an optional type to another value, returning `None` if the input option is `None`.

  Parameters:

    - fn (Callable) – A function that maps the non-optional value of type `T` to another value. This function will be called on non-`None` values of `v`.

    - v (Optional[T]) – The optional value to map.

  Examples

  Given an optional value like the following…

      maybe_item: Optional[pystac.Item] = ...

  …you could replace…

      maybe_item_id: Optional[str] = None
      if maybe_item is not None:
          maybe_item_id = maybe_item.id

  …with:

      maybe_item_id = map_opt(lambda item: item.id, maybe_item)

pystac.utils.now_in_utc() → datetime

  Returns a datetime value of now with the UTC timezone applied

pystac.utils.now_to_rfc3339_str() → str

  Returns an RFC 3339 string representing now

pystac.utils.safe_urlparse(href: str) → ParseResult

  Wrapper around `urllib.parse.urlparse()` that returns consistent results for both Windows and UNIX file paths.

  For Windows paths, this function will include the drive prefix (e.g. `"D:\"`) as part of the `path` of the `urllib.parse.ParseResult` rather than as the `scheme` for consistency with handling of UNIX/LINUX file paths.

  Parameters:

    href (str) – The HREF to parse. May be a local file path or URL.

  Returns:

    The named tuple representing the parsed HREF.

  Return type:

    urllib.parse.ParseResult

pystac.utils.str_to_datetime(s: str) → datetime

  Converts a string timestamp to a `datetime.datetime` instance using `dateutil.parser.parse()` under the hood. The input string may be in any format supported by the parser.parser>. This includes many formats including ISO 8601 and RFC 3339.

  Parameters:

    s (str) – The string to convert to `datetime.datetime`.

  Returns:

    The `datetime.datetime` represented the by the string.

  Return type:

    str

class pystac.utils.T

  alias of TypeVar(‘T’)

class pystac.utils.U

  alias of TypeVar(‘U’)