pystac.utils#

class pystac.utils.JoinType(value)[source]#

Allowed join types for join_path_or_url().

PATH = 'path'#

URL = 'url'#

static from_parsed_uri(parsed_uri: urllib.parse.ParseResult) → pystac.utils.JoinType[source]#

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)[source]#: Base enum.Enum class for string enums that will serialize as the string value.

pystac.utils.datetime_to_str(dt: datetime.datetime) → str[source]#

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.
Returns: The ISO8601 (RFC 3339) formatted string representing the datetime.
Return type: str

pystac.utils.geometry_to_bbox(geometry: Dict[str, Any]) → List[float][source]#

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: Optional[pystac.utils.T]) → pystac.utils.T[source]#

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: Optional[pystac.utils.T], obj: Union[str, Any], prop: str) → pystac.utils.T[source]#

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

pystac.utils.is_absolute_href(href: str) → bool[source]#

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.join_path_or_url(join_type: pystac.utils.JoinType, *args: str) → str[source]#

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: Optional[str] = None, start_is_dir: bool = False) → str[source]#

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_relative_href(source_href: str, start_href: str, start_is_dir: bool = False) → str[source]#

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[[pystac.utils.T], pystac.utils.U], v: Optional[pystac.utils.T]) → Optional[pystac.utils.U][source]#

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.safe_urlparse(href: str) → urllib.parse.ParseResult[source]#

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.datetime[source]#

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.

Parameters: s (str) – The string to convert to datetime.datetime.

pystac.summaries

pystac.validation