## catalog.BurstCatalog


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


Usage

``` python
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](cdse.CDSEAuth.md#s1bursts.cdse.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()](summary.OperationSummary.md#s1bursts.summary.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) | Download bursts with progress tracking and summary reporting. |
| [search()](#search) | Search for Sentinel-1 bursts matching the query. |

------------------------------------------------------------------------


#### download()


Download bursts with progress tracking and summary reporting.


Usage

``` python
download(bursts, *, overwrite=False, max_workers=5, endpoint=None)
```


##### Parameters


`bursts: Burst | BurstPair | Iterable[Burst | BurstPair]`  
Bursts to download: a single [Burst](burst.Burst.md#s1bursts.burst.Burst) or [BurstPair](burst.BurstPair.md#s1bursts.burst.BurstPair), or any iterable of them, such as a [BurstCollection](burst.BurstCollection.md#s1bursts.burst.BurstCollection), a [BurstPairCollection](burst.BurstPairCollection.md#s1bursts.burst.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](filemanager.FileManager.md#s1bursts.filemanager.FileManager) warns once when [slc_dir](filemanager.FileManager.md#s1bursts.filemanager.FileManager.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](filemanager.FileManager.md#s1bursts.filemanager.FileManager.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](errors.BurstNotFoundError.md#s1bursts.errors.BurstNotFoundError) if both found it missing, a [BurstDownloadError](errors.BurstDownloadError.md#s1bursts.errors.BurstDownloadError) otherwise.


##### Raises


`TypeError`  
If an item is neither a [Burst](burst.Burst.md#s1bursts.burst.Burst) nor a [BurstPair](burst.BurstPair.md#s1bursts.burst.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.


------------------------------------------------------------------------


#### search()


Search for Sentinel-1 bursts matching the query.


Usage

``` python
search(query)
```


##### Parameters


`query: SearchQuery`  
Search parameters.


##### Returns


`BurstCollection`  
Every burst that matches the query.


##### Raises


`TooManyResultsError`  
If more than 1000 bursts match, the most one catalog request returns. Narrow the query, or combine several searches with `+`.

`CatalogError`  
If the catalog cannot be reached or rejects the request, such as with HTTP 414 for an `intersects` geometry with too many vertices, or if its response is malformed or does not hold the number of bursts it reports as matching.