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’)