Skip to main content

catalog.BurstCatalog

Search and download Sentinel-1 bursts from the CDSE catalog.

Usage

Source

catalog.BurstCatalog(
    file_manager,
    auth=None,
    *,
    show_progress=True,
    continue_on_error=True,
    default_endpoint="odata"
)

Provides search via the CDSE API and parallel download with progress tracking, skip-existing logic, and automatic endpoint fallback.

Parameters

file_manager: FileManager

File manager for determining SLC download paths.

auth: CDSEAuth | None = None

Authentication credentials for the CDSE API. If None, a CDSEAuth instance is created lazily from the CDSE_USERNAME / CDSE_PASSWORD settings on the first download. Searching the catalog requires no authentication.

show_progress: bool = True

Whether to show progress bars during downloads.

continue_on_error: bool = True

Whether to continue downloading after individual failures. True, the default, attempts every burst and records each failure in the summary, so one missing burst does not end a long download; False raises at the first burst that fails on both endpoints, once the downloads already running have finished, without starting the queued ones. A burst this catalog already found missing at the source is not requested again: it is recorded as failed without raising, whichever the setting, and a rerun on the same catalog reports it again rather than retrying it. Follow a run with OperationSummary.raise_on_failure() to fail once all bursts have been attempted.

default_endpoint: Endpoint = "odata"
Default download endpoint. If a download fails, the other endpoint is tried automatically.

Raises

ValueError
If default_endpoint is neither "odata" nor "s3".

Methods

Name Description
download() Download bursts with progress tracking and summary reporting.
search() Search for Sentinel-1 bursts matching the query.

download()

Download bursts with progress tracking and summary reporting.

Usage

Source

download(bursts, *, overwrite=False, max_workers=5, endpoint=None)
Parameters
bursts: Burst | BurstPair | Iterable[Burst | BurstPair]

Bursts to download: a single Burst or BurstPair, or any iterable of them, such as a BurstCollection, a BurstPairCollection, a list or a generator. A pair downloads both of its bursts, and a burst listed more than once, for example one shared by two pairs, is downloaded once.

overwrite: bool = False

Whether to overwrite existing files. SLC file names record the pass direction, so a burst downloaded under an earlier name is downloaded again; FileManager warns once when slc_dir holds such names.

max_workers: int = 5

Number of parallel download threads. Each one stages its burst whole in the system temp directory when extracting from S3 or downloading into a remote slc_dir, which takes about 100 to 200 MB of local space per thread.

endpoint: Endpoint | None = None
Download endpoint to use. If None, uses the default_endpoint specified during initialization. If a download fails, the other endpoint is tried automatically.
Returns
OperationSummary
Summary of download results. A burst that neither endpoint could download is recorded with one error naming the failure of each, such as OData: HTTPError: 503 ...; S3: ...: a BurstNotFoundError if both found it missing, a BurstDownloadError otherwise.
Raises
TypeError

If an item is neither a Burst nor a BurstPair.

ValueError

If endpoint is neither "odata" nor "s3", raised before any burst is downloaded.

ConfigurationError

If an environment variable holds an invalid value, or CDSE rejects the username and password with OData as endpoint, which the next call tries again. Missing credentials of an endpoint, and rejected ones of the fallback endpoint, are recorded per burst instead.

OSError
If the disk is full, over quota or read-only, which would fail every remaining burst alike.