API documentation#

Read and download STAC items, item collections, collections, and assets.

The main entry points are free functions:

Use Config to configure how assets are downloaded. Every client inherits from Client, which defines a common interface for accessing assets. Writing items, item collections, collections, and assets is currently unsupported, but is on the roadmap.

exception stac_asset.AssetOverwriteError(hrefs: list[str])#

Raised when an asset would be overwritten during download.

class stac_asset.Client#

An abstract base class for all clients.

async assert_href_exists(href: str) → None#

Asserts that a href exists.

The default implementation naïvely opens the href and reads one chunk. Clients may implement specialized behavior.

Parameters:

href – The href to open

Raises:

Exception – The underlying error when trying to open the file.

async close() → None#

Close this client.

async download_href(href: str, path: PathLike[Any] | str, clean: bool = True, content_type: str | None = None, messages: Queue[Message] | None = None, stream: bool | None = None) → None#

Downloads a file to the local filesystem.

Parameters:

  • href – The input href

  • path – The output file path

  • clean – If an error occurs, delete the output file if it exists

  • content_type – The expected content type

  • messages – An optional queue to use for progress reporting

  • stream – If enabled, it iterates over the bytes of the response; otherwise, it reads the entire file into memory

async classmethod from_config(config: Config) → T#

Creates a client using the provided configuration.

Needed because some client setups require async operations.

Returns:

A new client Client

Return type:

T

async href_exists(href: str) → bool#

Returns true if the href exists.

The default implementation naïvely opens the href and reads one chunk. Clients may implement specialized behavior.

Parameters:

href – The href to open

Returns:

Whether the href exists

Return type:

bool

name: str#

The name of this client.

async open_href(href: str, content_type: str | None = None, messages: Queue[Message] | None = None, stream: bool | None = None) → AsyncIterator[bytes]#

Opens a href and yields an iterator over its bytes.

Parameters:

  • href – The input href

  • content_type – The expected content type

  • messages – An optional queue to use for progress reporting

  • stream – If enabled, it iterates over the bytes of the response; otherwise, it reads the entire file into memory

Yields:

AsyncIterator[bytes] – An iterator over chunks of the read file

abstractmethod async open_url(url: URL, content_type: str | None = None, messages: Queue[Message] | None = None, stream: bool | None = None) → AsyncIterator[bytes]#

Opens a url and yields an iterator over its bytes.

This is the core method that all clients must implement.

Parameters:

  • url – The input url

  • content_type – The expected content type, to be checked by the client implementations

  • messages – An optional queue to use for progress reporting

  • stream – If enabled, it iterates over the bytes of the response; otherwise, it reads the entire file into memory

Yields:

AsyncIterator[bytes] – An iterator over chunks of the read file

class stac_asset.Config(alternate_assets: list[str] = <factory>, file_name_strategy: FileNameStrategy = FileNameStrategy.FILE_NAME, warn: bool = False, fail_fast: bool = False, error_strategy: ErrorStrategy = ErrorStrategy.DELETE, exclude: list[str] = <factory>, include: list[str] = <factory>, make_directory: bool = True, clean: bool = True, overwrite: bool = False, client_override: str | None = None, http_client_timeout: float | None = 300, http_max_attempts: int = 10, http_assert_content_type: bool = False, http_headers: dict[str, str]=<factory>, earthdata_token: str | None = None, s3_region_name: str = 'us-west-2', s3_requester_pays: bool = False, s3_retry_mode: str = 'adaptive', s3_max_attempts: int = 10, s3_endpoint_url: str | None = None, oauth2_grant: str | None = None, oauth2_token_url: str | None = None, oauth2_authorization_url: str | None = None, oauth2_device_authorization_url: str | None = None, oauth2_client_id: str | None = None, oauth2_client_secret: str | None = None, oauth2_pkce: bool = True, oauth2_username: str | None = None, oauth2_password: str | None = None, oauth2_extra: dict[str, str]=<factory>)#

Configuration for downloading items and their assets.

alternate_assets: list[str]#

Alternate asset keys to prefer, if available.

clean: bool = True#

If true, clean up the downloaded file if it errors.

client_override: str | None = None#

Use the same client for all asset requests.

If not set, each asset’s client will be guessed from its href.

copy() → Config#

Returns a deep copy of this config.

Returns:

A deep copy of this config.

Return type:

Config

earthdata_token: str | None = None#

A token for logging in to Earthdata.

error_strategy: ErrorStrategy = 2#

The strategy to use when errors occur during download.

exclude: list[str]#

Assets to exclude from the download.

Mutually exclusive with include.

fail_fast: bool = False#

If an error occurs during download, fail immediately.

By default, all downloads are completed before raising/warning any errors. Mutually exclusive with warn.

file_name_strategy: FileNameStrategy = 1#

The file name strategy to use when downloading assets.

http_assert_content_type: bool = False#

If true, check the asset’s content type against the response from the server.

http_client_timeout: float | None = 300#

Total number of seconds for the whole request.

http_headers: dict[str, str]#

Extra headers to include in every http request.

http_max_attempts: int = 10#

The maximum number of attempts when downloading assets via http.

include: list[str]#

Assets to include in the download.

Mutually exclusive with exclude.

make_directory: bool = True#

Whether to create the output directory.

If False, and the output directory does not exist, an error will be raised.

oauth2_authorization_url: str | None = None#

OAuth2 authorization URL.

Can be configured with the OAUTH2_AUTHORIZATION_URL environment variable.

oauth2_client_id: str | None = None#

OAuth2 client identifier.

Can be configured with the OAUTH2_CLIENT_ID environment variable.

oauth2_client_secret: str | None = None#

OAuth2 client secret.

Can be configured with the OAUTH2_CLIENT_SECRET environment variable.

oauth2_device_authorization_url: str | None = None#

OAuth2 device authorization URL.

Can be configured with the OAUTH2_DEVICE_AUTHORIZATION_URL environment variable.

oauth2_extra: dict[str, str]#

Extra configuration options for the OAuth2 grant.

oauth2_grant: str | None = None#

OAuth2 grant type.

If a value is provided for this field, the HttpClient will be configured with support for OAuth2 access tokens. Can be configured with the OAUTH2_GRANT environment variable.

oauth2_password: str | None = None#

OAuth2 password for resource owner password credentials grant.

Can be configured with the OAUTH2_PASSWORD environment variable.

oauth2_pkce: bool = True#

OAuth2 Proof Key for Code Exchange.

Can be configured with the OAUTH2_PKCE environment variable. By default, PKCE is enabled.

oauth2_token_url: str | None = None#

OAuth2 token URL.

Can be configured with the OAUTH2_TOKEN_URL environment variable.

oauth2_username: str | None = None#

OAuth2 username for resource owner password credentials grant.

Can be configured with the OAUTH2_USERNAME environment variable.

overwrite: bool = False#

Download files even if they already exist locally.

s3_endpoint_url: str | None = None#

Set an optional custom endpoint url for s3.

s3_max_attempts: int = 10#

The maximum number of attempts when downloading assets from s3.

s3_region_name: str = 'us-west-2'#

Default s3 region.

s3_requester_pays: bool = False#

If using the s3 client, enable requester pays.

s3_retry_mode: str = 'adaptive'#

The retry mode to use for s3 requests.

validate() → None#

Validates this configuration.

Raises:

CannotIncludeAndExclude – include and exclude are mutually exclusive

warn: bool = False#

If an error occurs during download, warn instead of raising the error.

exception stac_asset.ConfigError#

Raised if the configuration is not valid.

exception stac_asset.ContentTypeError(actual: str, expected: str, *args: Any, **kwargs: Any)#

The expected content type does not match the actual content type.

exception stac_asset.DownloadError(exceptions: list[Exception], *args: Any, **kwargs: Any)#

A collection of exceptions encountered while downloading.

exception stac_asset.DownloadWarning#

A warning for when something couldn’t be downloaded.

Used when we don’t want to cancel all downloads, but still inform the user about the problem.

class stac_asset.EarthdataClient(session: ClientSession | RetryClient, assert_content_type: bool)#

Access data from https://www.earthdata.nasa.gov/.

To access data, you’ll need a personal access token.

  1. Create a new personal access token by going to https://urs.earthdata.nasa.gov/profile and then clicking “Generate Token” (you’ll need to log in).

  2. Set an environment variable named EARTHDATA_PAT to your token.

  3. Use EarthdataClient.from_config() to create a new client.

async classmethod from_config(config: Config) → EarthdataClient#

Logs in to Earthdata and returns the default earthdata client.

Uses a token stored in the EARTHDATA_PAT environment variable, if the token is not provided in the config.

Parameters:

config – A configuration object.

Returns:

A logged-in EarthData client.

Return type:

EarthdataClient

name: str = 'earthdata'#

The name of this client.

class stac_asset.ErrorStrategy(*values)#

Strategy to use when encountering errors during download.

DELETE = 2#

Delete the asset from the item.

KEEP = 1#

Keep the asset on the item with its original href.

class stac_asset.FileNameStrategy(*values)#

Strategy to use for naming files.

FILE_NAME = 1#

Save the asset with the file name in its href.

Could potentially conflict with another asset with the same file name but different path.

KEY = 2#

Save the asset with its key as its file name.

class stac_asset.FilesystemClient#

A simple client for moving files around on the filesystem.

Mostly used for testing, but could be useful in some real-world cases.

async assert_href_exists(href: str) → None#

Asserts that an href exists.

name: str = 'filesystem'#

The name of this client.

async open_url(url: URL, content_type: str | None = None, messages: Queue[Message] | None = None, stream: bool | None = None) → AsyncIterator[bytes]#

Iterates over data from a local url.

Parameters:

  • url – The url to read bytes from

  • content_type – The expected content type. Ignored by this client, because filesystems don’t have content types.

  • messages – An optional queue to use for progress reporting

  • stream – If enabled, it iterates over the bytes of the file; otherwise, it reads the entire file into memory

Yields:

AsyncIterator[bytes] – An iterator over the file’s bytes.

Raises:

ValueError – Raised if the url has a scheme. This behavior will change if/when we support Windows paths.

class stac_asset.HttpClient(session: ClientSession | RetryClient, assert_content_type: bool)#

A simple client for making HTTP requests.

By default, doesn’t do any authentication. Configure the session to customize its behavior.

assert_content_type: bool#

If true, check the asset’s content type against the response from the server.

See stac_asset.validate.content_type() for more information about the content type check.

async assert_href_exists(href: str) → None#

Asserts that the href exists.

Uses a HEAD request.

async close() → None#

Close this http client.

Closes the underlying session.

async classmethod from_config(config: Config) → T#

Creates an HTTP client with an aiohttp session object.

To use OAuth2 access tokens, configure the oauth2_grant and the necessary parameters for the chosen grant type.

OAuth2 device code grant (urn:ietf:params:oauth:grant-type:device_code or device_code):
OAuth2 authorization code grant (authorization_code):
OAuth2 resource owner password credentials grant (password):
OAuth2 client credentials grant (client_credentials):
name: str = 'http'#

The name of this client.

async open_url(url: URL, content_type: str | None = None, messages: Queue[Message] | None = None, stream: bool | None = None) → AsyncIterator[bytes]#

Opens a url with this client’s session and iterates over its bytes.

Parameters:

  • url – The url to open

  • content_type – The expected content type

  • messages – An optional queue to use for progress reporting

  • stream – If enabled, it uses the aiohttp streaming API

Yields:

AsyncIterator[bytes] – An iterator over the file’s bytes

Raises:

aiohttp.ClientResponseError – Raised if the response is not OK

session: ClientSession#

A aiohttp session that will be used for all requests.

class stac_asset.Message#

A message about downloading.

class stac_asset.PlanetaryComputerClient(session: ClientSession, assert_content_type: bool, sas_token_endpoint: str = 'https://planetarycomputer.microsoft.com/api/sas/v1/token')#

Open and download assets from Microsoft’s Planetary Computer.

Heavily cribbed from microsoft/planetary-computer-sdk-for-python, thanks Tom Augspurger!

async assert_href_exists(href: str) → None#

Asserts that the href exists.

Uses a HEAD request on a signed url.

name: str = 'planetary-computer'#

The name of this client.

async open_url(url: URL, content_type: str | None = None, messages: Queue[Any] | None = None, stream: bool | None = None) → AsyncIterator[bytes]#

Opens a url and iterates over its bytes.

Includes functionality to sign the url with a SAS token fetched from this client’s sas_token_endpoint. Tokens are cached on a per-client basis to prevent a large number of requests when fetching many assets.

Not every URL is modified with a SAS token. We only modify the url if:

  • The url is in Azure blob storage

  • The url is not in the public thumbnail storage account

  • The url hasn’t already signed (we check this by seeing if the url has

    SAS-like query parameters)

Parameters:

  • url – The url to open

  • content_type – The expected content type

  • messages – An optional queue to use for progress reporting

  • stream – If enabled, it uses the aiohttp streaming API

Yields:

AsyncIterator[bytes] – An iterator over the file’s bytes

sas_token_endpoint: URL#

The endpoint that will be used to fetch a SAS token for reading.

class stac_asset.S3Client(requester_pays: bool = False, region_name: str = 'us-west-2', retry_mode: str = 'adaptive', max_attempts: int = 10, endpoint_url: str | None = None)#

A client for interacting with s3 urls.

To use the requester_pays option, you need to configure your AWS credentials. See the AWS documentation for instructions.

async assert_href_exists(href: str) → None#

Asserts that the href exists.

Uses head_object

endpoint_url: str | None#

Custom endpoint url for s3.

async classmethod from_config(config: Config) → S3Client#

Creates an s3 client from a config.

Parameters:

config – The config object

Returns:

A new s3 client

Return type:

S3Client

async has_credentials() → bool#

Returns true if the sessions has credentials.

max_attempts: int#

The maximum number of attempts.

name: str = 's3'#

The name of this client.

async open_url(url: URL, content_type: str | None = None, messages: Queue[Message] | None = None, stream: bool | None = None) → AsyncIterator[bytes]#

Opens an s3 url and iterates over its bytes.

Parameters:

  • url – The url to open

  • content_type – The expected content type

  • messages – An optional queue to use for progress reporting

  • stream – If enabled, it iterates over the bytes of the response; otherwise, it reads the entire file into memory

Yields:

AsyncIterator[bytes] – An iterator over the file’s bytes

Raises:

SchemeError – Raised if the url’s scheme is not s3

region_name: str#

The region that all clients will be rooted in.

requester_pays: bool#

If True, enable access to requester pays buckets.

retry_mode: str#

The retry mode, one of “adaptive”, “legacy”, or “standard”.

See the boto3 docs for more information on the available modes.

session: AioSession#

The session that will be used for all s3 requests.

async stac_asset.assert_asset_exists(asset: Asset, config: Config | None = None, clients: list[Client] | None = None) → None#

Asserts that an asset exists.

Raises the source error if it does not.

Parameters:

  • asset – The asset the check for existence

  • config – The download configuration to use for the existence check

  • clients – Any pre-configured clients to use for the existence check

Raises:

Exception – An exception from the underlying client.

async stac_asset.asset_exists(asset: Asset, config: Config | None = None, clients: list[Client] | None = None) → bool#

Returns true if an asset exists.

Parameters:

  • asset – The asset the check for existence

  • config – The download configuration to use for the existence check

  • clients – Any pre-configured clients to use for the existence check

Returns:

Whether the asset exists or not

Return type:

bool

async stac_asset.download_asset(key: str, asset: Asset, path: Path, config: Config, messages: Queue[Message] | None = None, clients: Clients | None = None, stream: bool | None = None) → Asset#

Downloads an asset.

Parameters:

  • key – The asset key

  • asset – The asset

  • path – The path to which the asset will be downloaded

  • config – The download configuration

  • messages – An optional queue to use for progress reporting

  • clients – A async-safe cache of clients. If not provided, a new one will be created.

  • stream – If enabled, it iterates over the bytes of the response; otherwise, it reads the entire file into memory

Returns:

The asset with an updated href

Return type:

Asset

Raises:

ValueError – Raised if the asset does not have an absolute href

async stac_asset.download_collection(collection: Collection, directory: PathLike[Any] | str, file_name: str | None = 'collection.json', config: Config | None = None, messages: Queue[Message] | None = None, clients: list[Client] | None = None, keep_non_downloaded: bool = False, max_concurrent_downloads: int = 500, stream: bool = True) → Collection#

Downloads a collection to the local filesystem.

Does not download the collection’s items’ assets – use download_item_collection() to download multiple items.

Parameters:

  • collection – A pystac collection

  • directory – The destination directory

  • file_name – The name of the collection file to save. If not provided, will not be saved.

  • config – The download configuration

  • messages – An optional queue to use for progress reporting

  • clients – Pre-configured clients to use for access

  • keep_non_downloaded – Keep all assets on the item, even if they’re not downloaded.

  • max_concurrent_downloads – The maximum number of downloads that can be active at one time.

  • stream – If enabled, it iterates over the bytes of the response; otherwise, it reads the entire file into memory

Returns:

The collection, with updated asset hrefs

Return type:

Collection

Raises:

CantIncludeAndExclude – Raised if both include and exclude are not None.

async stac_asset.download_file(href: str, destination: PathLike[Any] | str, config: Config | None = None, clients: list[Client] | None = None) → None#

Downloads a file collection to the local filesystem.

Parameters:

  • href – The source href

  • destination – The destination file path

  • config – The download configuration

  • clients – Pre-configured clients to use for access

async stac_asset.download_item(item: Item, directory: PathLike[Any] | str, file_name: str | None = None, infer_file_name: bool = True, config: Config | None = None, messages: Queue[Message] | None = None, clients: list[Client] | None = None, keep_non_downloaded: bool = False, max_concurrent_downloads: int = 500, stream: bool | None = None) → Item#

Downloads an item to the local filesystem.

Parameters:

  • item – The pystac.Item.

  • directory – The output directory that will hold the items and assets.

  • file_name – The name of the item file to save. If not provided, will not be saved.

  • infer_file_name – If file_name is None, infer the file name from the item’s id. This argument is unused if file_name is not None.

  • config – The download configuration

  • messages – An optional queue to use for progress reporting

  • clients – Pre-configured clients to use for access

  • keep_non_downloaded – Keep all assets on the item, even if they’re not downloaded.

  • max_concurrent_downloads – The maximum number of downloads that can be active at one time.

  • stream – If enabled, it iterates over the bytes of the response; otherwise, it reads the entire file into memory

Returns:

The ~pystac.Item, with the updated asset hrefs and self href.

Return type:

Item

Raises:

ValueError – Raised if the item doesn’t have any assets.

async stac_asset.download_item_collection(item_collection: ItemCollection, directory: PathLike[Any] | str, path_template: str | None = None, file_name: str | None = 'item-collection.json', config: Config | None = None, messages: Queue[Message] | None = None, clients: list[Client] | None = None, keep_non_downloaded: bool = False, max_concurrent_downloads: int = 500, stream: bool | None = None) → ItemCollection#

Downloads an item collection to the local filesystem.

Parameters:

  • item_collection – The item collection to download

  • directory – The destination directory

  • path_template – String to be interpolated to specify where to store downloaded files.

  • file_name – The name of the item collection file to save. If not provided, will not be saved.

  • config – The download configuration

  • messages – An optional queue to use for progress reporting

  • clients – Pre-configured clients to use for access

  • keep_non_downloaded – Keep all assets on the item, even if they’re not downloaded.

  • max_concurrent_downloads – The maximum number of downloads that can be active at one time.

  • stream – If enabled, it iterates over the bytes of the response; otherwise, it reads the entire file into memory

Returns:

The item collection, with updated asset hrefs

Return type:

ItemCollection

Raises:

CantIncludeAndExclude – Raised if both include and exclude are not None.

stac_asset.get_client_classes() → list[type[Client]]#

Returns a list of all known subclasses of Client.

async stac_asset.open_href(href: str, config: Config | None = None, clients: list[Client] | None = None) → AsyncIterator[bytes]#

Opens an href and yields byte chunks.

Parameters:

  • href – The href to read

  • config – The download configuration to use

  • clients – Any pre-configured clients to use

Yields:

bytes – The bytes from the href

async stac_asset.read_href(href: str, config: Config | None = None, clients: list[Client] | None = None) → bytes#

Reads an href and returns its bytes.

Parameters:

  • href – The href to read

  • config – The download configuration to use

  • clients – Any pre-configured clients to use

Returns:

The bytes from the href

Return type:

bytes

stac_asset.blocking#

Blocking interfaces for functions.

These should only be used from fully synchronous code. If you have _any_ async code in your application, prefer the top-level functions.

stac_asset.blocking.assert_asset_exists(asset: Asset, config: Config | None = None, clients: list[Client] | None = None) → None#

Asserts that an asset exists, synchronously.

Raises the source error if it does not.

Parameters:

  • asset – The asset the check for existence

  • config – The download configuration to use for the existence check

  • clients – Any pre-configured clients to use for the existence check

Raises:

Exception – An exception from the underlying client.

stac_asset.blocking.asset_exists(asset: Asset, config: Config | None = None, clients: list[Client] | None = None) → bool#

Returns true if an asset exists, synchronously.

Parameters:

  • asset – The asset the check for existence

  • config – The download configuration to use for the existence check

  • clients – Any pre-configured clients to use for the existence check

Returns:

Whether the asset exists or not

Return type:

bool

stac_asset.blocking.download_asset(key: str, asset: Asset, path: Path, config: Config, messages: Queue[Message] | None = None, clients: Clients | None = None) → Asset#

Downloads an asset, synchronously.

Parameters:

  • key – The asset key

  • asset – The asset

  • path – The path to which the asset will be downloaded

  • config – The download configuration

  • messages – An optional queue to use for progress reporting

  • clients – A async-safe cache of clients. If not provided, a new one will be created.

Returns:

The asset with an updated href

Return type:

Asset

Raises:

ValueError – Raised if the asset does not have an absolute href

stac_asset.blocking.download_collection(collection: Collection, directory: PathLike[Any] | str, file_name: str | None = 'collection.json', config: Config | None = None, messages: Queue[Message] | None = None, clients: list[Client] | None = None, keep_non_downloaded: bool = False, max_concurrent_downloads: int = 500) → Collection#

Downloads a collection to the local filesystem, synchronously.

Does not download the collection’s items’ assets – use download_item_collection() to download multiple items.

Parameters:

  • collection – A pystac collection

  • directory – The destination directory

  • file_name – The name of the collection file to save. If not provided, will not be saved.

  • config – The download configuration

  • messages – An optional queue to use for progress reporting

  • clients – Pre-configured clients to use for access

  • keep_non_downloaded – Keep all assets on the item, even if they’re not downloaded.

  • max_concurrent_downloads – The maximum number of downloads that can be active at one time.

Returns:

The collection, with updated asset hrefs

Return type:

Collection

Raises:

CantIncludeAndExclude – Raised if both include and exclude are not None.

stac_asset.blocking.download_file(href: str, destination: PathLike[Any] | str, config: Config | None = None, clients: list[Client] | None = None) → None#

Downloads a file collection to the local filesystem.

Parameters:

  • href – The source href

  • destination – The destination file path

  • config – The download configuration

  • clients – Pre-configured clients to use for access

stac_asset.blocking.download_item(item: Item, directory: PathLike[Any] | str, file_name: str | None = None, infer_file_name: bool = True, config: Config | None = None, messages: Queue[Message] | None = None, clients: list[Client] | None = None, keep_non_downloaded: bool = False, max_concurrent_downloads: int = 500) → Item#

Downloads an item to the local filesystem, synchronously.

Parameters:

  • item – The pystac.Item.

  • directory – The output directory that will hold the items and assets.

  • file_name – The name of the item file to save. If not provided, will not be saved.

  • infer_file_name – If file_name is None, infer the file name from the item’s id. This argument is unused if file_name is not None.

  • config – The download configuration

  • messages – An optional queue to use for progress reporting

  • clients – Pre-configured clients to use for access

  • keep_non_downloaded – Keep all assets on the item, even if they’re not downloaded.

  • max_concurrent_downloads – The maximum number of downloads that can be active at one time.

Returns:

The ~pystac.Item, with the updated asset hrefs and self href.

Return type:

Item

Raises:

ValueError – Raised if the item doesn’t have any assets.

stac_asset.blocking.download_item_collection(item_collection: ItemCollection, directory: PathLike[Any] | str, path_template: str | None = None, file_name: str | None = 'item-collection.json', config: Config | None = None, messages: Queue[Message] | None = None, clients: list[Client] | None = None, keep_non_downloaded: bool = False, max_concurrent_downloads: int = 500) → ItemCollection#

Downloads an item collection to the local filesystem, synchronously.

Parameters:

  • item_collection – The item collection to download

  • directory – The destination directory

  • path_template – String to be interpolated to specify where to store downloaded files.

  • file_name – The name of the item collection file to save. If not provided, will not be saved.

  • config – The download configuration

  • messages – An optional queue to use for progress reporting

  • clients – Pre-configured clients to use for access

  • keep_non_downloaded – Keep all assets on the item, even if they’re not downloaded.

  • max_concurrent_downloads – The maximum number of downloads that can be active at one time.

Returns:

The item collection, with updated asset hrefs

Return type:

ItemCollection

Raises:

CantIncludeAndExclude – Raised if both include and exclude are not None.

stac_asset.blocking.read_href(href: str, config: Config | None = None, clients: list[Client] | None = None) → bytes#

Reads an href and returns its bytes.

Parameters:

  • href – The href to read

  • config – The download configuration to use

  • clients – Any pre-configured clients to use

Returns:

The bytes from the href

Return type:

bytes

stac_asset.validate#

stac_asset.validate.content_type(actual: str, expected: str) → None#

Validates that the actual content type matches the expected.

This is normally a simple string comparison, but has some extra rules:

  • COGs are allowed in place of TIFFs, and vice versa

  • Responses with binary/octet-stream and application/octet-stream are always allowed

Parameters:

  • actual – The actual content type

  • expected – The expected content type

Raises:

ContentTypeError – Raised if the actual doesn’t match the expected.

On this page
Show Source