General

pystac.get_stac_version

get_stac_version() -> str

DEPRECATED Returns the default STAC version.

Warning

This function is deprecated as of PySTAC v2.0 and will be removed in a future version. Just look at DEFAULT_STAC_VERSION.

Returns:

Type	Description
`str`	The default STAC version.

Examples:

>>> pystac.get_stac_version()
"1.1.0"

Source code in src/pystac/functions.py

@deprecate.function("Use DEFAULT_STAC_VERSION instead.")
def get_stac_version() -> str:
    """**DEPRECATED** Returns the default STAC version.

    Warning:
        This function is deprecated as of PySTAC v2.0 and will be removed in a
        future version. Just look at
        [DEFAULT_STAC_VERSION][pystac.DEFAULT_STAC_VERSION].

    Returns:
        The default STAC version.

    Examples:
        >>> pystac.get_stac_version()
        "1.1.0"
    """
    return DEFAULT_STAC_VERSION

pystac.set_stac_version

set_stac_version(version: str) -> None

DEPRECATED This function is a no-op and will be removed in a future version

Warning

In pre-v2.0 PySTAC, this function was used to set the global STAC version. In PySTAC v2.0 this global capability has been removed — the user should use Container.set_stac_version() to mutate an entire catalog.

Source code in src/pystac/functions.py

@deprecate.function(
    "This function is a no-op. Use `Container.set_stac_version()` to modify the STAC "
    "version of an entire catalog."
)
def set_stac_version(version: str) -> None:
    """**DEPRECATED** This function is a no-op and will be removed in a future version

    Warning:
        In pre-v2.0 PySTAC, this function was used to set the global STAC version.
        In PySTAC v2.0 this global capability has been removed — the user should
        use `Container.set_stac_version()` to mutate an entire catalog.
    """

pystac.read_file

read_file(
    href: str | Path,
    stac_io: Any = None,
    *,
    reader: Read | None = None,
) -> STACObject

Reads a file from a href.

Parameters:

Name	Type	Description	Default
`href`	`str \| Path`	The href to read	required
`reader`	`Read \| None`	The [Read][pystac.Read] to use for reading	`None`

Returns:

Type	Description
`STACObject`	The STAC object

Source code in src/pystac/io.py

def read_file(
    href: str | Path,
    stac_io: Any = None,
    *,
    reader: Read | None = None,
) -> STACObject:
    """Reads a file from a href.

    Args:
        href: The href to read
        reader: The [Read][pystac.Read] to use for reading

    Returns:
        The STAC object
    """
    if stac_io:
        deprecate.argument("stac_io")
    return STACObject.from_file(href, reader=reader)

pystac.read_dict

read_dict(d: dict[str, Any]) -> STACObject

DEPRECATED Reads a STAC object from a dictionary.

Warning

This function is deprecated as of PySTAC v2.0 and will be removed in a future version. Use STACObject.from_dict instead.

Source code in src/pystac/functions.py

@deprecate.function("Use STACObject.from_dict instead")
def read_dict(d: dict[str, Any]) -> STACObject:
    """**DEPRECATED** Reads a STAC object from a dictionary.

    Warning:
        This function is deprecated as of PySTAC v2.0 and will be removed in a
        future version. Use [STACObject.from_dict][pystac.STACObject.from_dict] instead.
    """
    return STACObject.from_dict(d)

pystac.write_file

write_file(
    obj: STACObject,
    include_self_link: bool | None = None,
    dest_href: str | Path | None = None,
    stac_io: Any = None,
    *,
    writer: Write | None = None,
) -> None

Writes a STAC object to a file, using its href.

If the href is not set, this will throw and error.

Parameters:

Name	Type	Description	Default
`obj`	`STACObject`	The STAC object to write	required
`dest_href`	`str \| Path \| None`	The href to write the STAC object to	`None`
`writer`	`Write \| None`	The [Write][pystac.Write] to use for writing	`None`

Source code in src/pystac/io.py

def write_file(
    obj: STACObject,
    include_self_link: bool | None = None,
    dest_href: str | Path | None = None,
    stac_io: Any = None,
    *,
    writer: Write | None = None,
) -> None:
    """Writes a STAC object to a file, using its href.

    If the href is not set, this will throw and error.

    Args:
        obj: The STAC object to write
        dest_href: The href to write the STAC object to
        writer: The [Write][pystac.Write] to use for writing
    """
    if include_self_link is not None:
        deprecate.argument("include_self_link")
    if stac_io:
        deprecate.argument("stac_io")

    if writer is None:
        writer = DefaultWriter()

    if dest_href is None:
        dest_href = obj.href
    if dest_href is None:
        raise PySTACError(f"cannot write {obj} without an href")
    d = obj.to_dict()
    if isinstance(dest_href, Path):
        writer.write_json_to_path(d, dest_href)
    else:
        url = urllib.parse.urlparse(dest_href)
        if url.scheme:
            writer.write_json_to_url(d, dest_href)
        else:
            writer.write_json_to_path(d, Path(dest_href))

pystac.PySTACError

Bases: Exception

A custom error class for this library.

Source code in src/pystac/errors.py

class PySTACError(Exception):
    """A custom error class for this library."""

pystac.STACError

Bases: PySTACError

A subclass of PySTACError for errors related to the STAC specification itself.

Source code in src/pystac/errors.py

class STACError(PySTACError):
    """A subclass of [PySTACError][pystac.PySTACError] for errors related to the
    STAC specification itself."""

pystac.PySTACWarning

Bases: Warning

A custom warning class for this library.

Source code in src/pystac/errors.py

class PySTACWarning(Warning):
    """A custom warning class for this library."""

pystac.STACWarning

Bases: PySTACWarning

A warning about something incorrect per the STAC specification.

Source code in src/pystac/errors.py

class STACWarning(PySTACWarning):
    """A warning about something incorrect per the STAC specification."""