Skip to content

API

pgstacrs.Client

A pgstac client.

open async classmethod 

open(params: str) -> Client

Opens a new client, backed by a connection pool.

Parameters:

  • params (str) –

    The connection parameters, either in postgresql:// or host=localhost user=username format.

Returns:

Examples:

>>> from pgstacrs import Client
>>> client = await Client.open("postgresql://username:password@localhost:5432/pgstac")
>>> client = await Client.open("user=username password=password dbname=pgstac")

search async 

search(
    *,
    intersects: str | dict[str, Any] | None = None,
    ids: str | list[str] | None = None,
    collections: str | list[str] | None = None,
    limit: int | None = None,
    bbox: list[float] | None = None,
    datetime: str | None = None,
    include: str | list[str] | None = None,
    exclude: str | list[str] | None = None,
    sortby: str | list[str] | None = None,
    filter: str | dict[str, Any] | None = None,
    query: dict[str, Any] | None = None,
    **kwargs: str,
) -> dict[str, Any]

Searches the database with STAC API item search.

Parameters:

  • collections (str | list[str] | None, default: None ) –

    Array of one or more Collection IDs that each matching Item must be in.

  • ids (str | list[str] | None, default: None ) –

    Array of Item ids to return.

  • intersects (str | dict[str, Any] | None, default: None ) –

    Searches items by performing intersection between their geometry and provided GeoJSON geometry.

  • bbox (list[float] | None, default: None ) –

    Requested bounding box.

  • datetime (str | None, default: None ) –

    Single date+time, or a range (/ separator), formatted to RFC 3339, section 5.6. Use double dots .. for open date ranges.

  • include (str | list[str] | None, default: None ) –

    Fields to include in the response (see the extension docs) for more on the semantics).

  • exclude (str | list[str] | None, default: None ) –

    Fields to exclude from the response (see the extension docs) for more on the semantics).

  • sortby (str | list[str] | None, default: None ) –

    Fields by which to sort results (use -field to sort descending).

  • filter (str | dict[str, Any] | None, default: None ) –

    CQL2 filter expression. Strings will be interpreted as cql2-text, dictionaries as cql2-json.

  • query (dict[str, Any] | None, default: None ) –

    Additional filtering based on properties. It is recommended to use filter instead, if possible.

  • limit (int | None, default: None ) –

    The page size returned from the server.

  • kwargs (str, default: {} ) –

    Any additional arguments to pass down into the search, e.g a pagination token

print_config async 

print_config() -> None

Prints the postgresql configuration.

Redacts the password

set_setting async 

set_setting(key: str, value: str) -> None

Sets a pgstac setting.

Parameters:

  • key (str) –

    The setting name, e.g. base_url

  • value (str) –

    The setting value, e.g. http://pgstacrs.test

get_version async 

get_version() -> str

Returns the pgstac version.

Returns:

  • str –

    The pgstac version as a string

get_collection async 

get_collection(id: str) -> dict[str, Any] | None

Returns a collection by id, or none if one does not exist.

Parameters:

  • id (str) –

    The collection id

Returns:

  • dict[str, Any] | None –

    A STAC collection, or None

create_collection async 

create_collection(collection: dict[str, Any]) -> None

Creates a new collection.

Parameters:

  • collection (dict[str, Any]) –

    The collection

Raises:

update_collection async 

update_collection(collection: dict[str, Any]) -> None

Updates a collection.

Parameters:

  • collection (dict[str, Any]) –

    The collection

Raises:

update_collection_extents async 

update_collection_extents() -> None

Updates all collection extents.

upsert_collection async 

upsert_collection(collection: dict[str, Any]) -> None

Upserts a collection.

Parameters:

  • collection (dict[str, Any]) –

    The collection

delete_collection async 

delete_collection(id: str) -> None

Deletes a collection by id.

Parameters:

  • id (str) –

    The collection id

all_collections async 

all_collections() -> list[dict[str, Any]]

Returns all collections.

Returns:

  • list[dict[str, Any]] –

    All collections in the database

get_item async 

get_item(
    id: str, collection_id: str | None = None
) -> dict[str, Any] | None

Returns an item by id.

Parameters:

  • id (str) –

    The item id

  • collection_id (str | None, default: None ) –

    The optional collection id

Returns:

  • dict[str, Any] | None –

    The item, or None if the item does not exist

create_item async 

create_item(item: dict[str, Any]) -> None

Creates an item.

Parameters:

  • item (dict[str, Any]) –

    The item

Raises:

  • PgstacError –

    If the item's collection does not exist. The collection is determined by the collection attribute of the item.

create_items async 

create_items(items: list[dict[str, Any]]) -> None

Creates many items.

Parameters:

  • items (list[dict[str, Any]]) –

    The items

Raises:

  • PgstacError –

    If the items' collection(s) does not exist.

update_item async 

update_item(item: dict[str, Any]) -> None

Updates an item.

Parameters:

  • item (dict[str, Any]) –

    The item

Raises:

upsert_item async 

upsert_item(item: dict[str, Any]) -> None

Upserts an item.

Parameters:

  • item (dict[str, Any]) –

    The item

Raises:

  • PgstacError –

    If the item's collection does not exist.

upsert_items async 

upsert_items(items: list[dict[str, Any]]) -> None

Upserts many items.

Parameters:

  • items (list[dict[str, Any]]) –

    The items

Raises:

  • PgstacError –

    If the items' collection(s) does not exist.

delete_item async 

delete_item(
    id: str, collection_id: str | None = None
) -> None

Deletes an item by id.

Parameters:

  • id (str) –

    The item id

  • collection_id (str | None, default: None ) –

    The optional collection id

Raises:

pgstacrs.StacError

Something doesn't match the STAC specification

pgstacrs.PgstacError

An exception returned from pgstac