# `seroverse.client`

Asynchronous, token-bucket rate-limited HTTP clients and `msgspec` msgpack cassette utilities for querying NCBI, ENA, DSMZ BacDive, StrainInfo, and Pathogenwatch.

---

## Base Client & Msgpack Cassettes (`seroverse.client.base`)

## base

Unified asynchronous HTTP client and msgspec serialization helpers for SeroVerse.

Classes:

| Name | Description |
| --- | --- |
| `Client` | High-performance asynchronous HTTP client powered by `aiohttp` and `msgspec`. |

### Client

High-performance asynchronous HTTP client powered by `aiohttp` and `msgspec`.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `base_url` | `str` | Base endpoint URL. | *required* |
| `api_key_header` | `str \| None` | Optional HTTP header key for API authorization. | `None` |
| `api_key` | `str \| None` | Optional API key string. | `None` |
| `user_agent` | `str` | User-Agent header value. | `'seroverse-client/0.1'` |
| `timeout` | `float` | Total request timeout in seconds. | `30.0` |
| `max_concurrency` | `int` | Maximum concurrent in-flight requests per event loop. | `5` |
| `polite_delay` | `float` | Optional minimum delay (in seconds) after live network requests. | `0.0` |
| `recorder` | `Any \| None` | Optional `cassetter` recorder instance. | `None` |

Methods:

| Name | Description |
| --- | --- |
| `encode_msgpack` | Serialize an object or dataclass tree into compact MessagePack bytes. |
| `decode_msgpack` | Deserialize MessagePack bytes directly into a typed `@dataclass(frozen=True, slots=True)` structure. |
| `save_msgpack` | Atomically persist `obj` to `path` as binary MessagePack. |
| `load_msgpack` | Load and decode a binary MessagePack file into `type_`. |
| `polite_sleep` | Sleep politely after a live network request, skipping sleep on fast cassette replays. |
| `get_session` | Retrieve or instantiate the underlying `aiohttp.ClientSession` for the active event loop. |
| `close` | Close the underlying `aiohttp.ClientSession` if open. |
| `close_sync` | Close the underlying `aiohttp.ClientSession` synchronously. |
| `request` | Send an async HTTP request and return decoded JSON (via `msgspec`) or text. |
| `get` | Perform an async HTTP GET request. |
| `post` | Perform an async HTTP POST request. |
| `delete` | Perform an async HTTP DELETE request. |
| `stream_bytes` | Send an async HTTP request and read raw response bytes. |
| `get_json` | Fetch `endpoint` via GET and decode JSON directly into `type_` using `msgspec`. |
| `post_json` | Fetch `endpoint` via POST and decode JSON directly into `type_` using `msgspec`. |
| `stream_buffer` | Send an async HTTP request and return an in-memory `BytesIO` stream. |
| `stream_chunks` | Stream response bytes in chunks as an async generator, emitting progress when `Content-Length` is known. |
| `run_sync` | Execute a coroutine synchronously and close any session bound to the temporary event loop. |

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `api_key` | `str \| None` | Return the configured API key string, or `None`. |

#### api\_key

```python
api_key: str | None
```

Return the configured API key string, or `None`.

#### encode\_msgpack

```python
encode_msgpack(obj: Any) -> bytes
```

Serialize an object or dataclass tree into compact MessagePack bytes.

#### decode\_msgpack

```python
decode_msgpack(data: bytes, type_: type[T]) -> T
```

Deserialize MessagePack bytes directly into a typed `@dataclass(frozen=True, slots=True)` structure.

#### save\_msgpack

```python
save_msgpack(path: Path, obj: Any) -> None
```

Atomically persist `obj` to `path` as binary MessagePack.

#### load\_msgpack

```python
load_msgpack(path: Path, type_: type[T]) -> T
```

Load and decode a binary MessagePack file into `type_`.

#### polite\_sleep

```python
polite_sleep(
    t_req: float, delay: float | None = None
) -> None
```

Sleep politely after a live network request, skipping sleep on fast cassette replays.

#### get\_session

```python
get_session() -> ClientSession
```

Retrieve or instantiate the underlying `aiohttp.ClientSession` for the active event loop.

#### close

```python
close() -> None
```

Close the underlying `aiohttp.ClientSession` if open.

#### close\_sync

```python
close_sync() -> None
```

Close the underlying `aiohttp.ClientSession` synchronously.

#### request

```python
request(method: str, endpoint: str, **kwargs: Any) -> Any
```

Send an async HTTP request and return decoded JSON (via `msgspec`) or text.

#### get

```python
get(endpoint: str, **kwargs: Any) -> Any
```

Perform an async HTTP GET request.

#### post

```python
post(endpoint: str, **kwargs: Any) -> Any
```

Perform an async HTTP POST request.

#### delete

```python
delete(endpoint: str, **kwargs: Any) -> Any
```

Perform an async HTTP DELETE request.

#### stream\_bytes

```python
stream_bytes(
    method: str, endpoint: str, **kwargs: Any
) -> bytes
```

Send an async HTTP request and read raw response bytes.

#### get\_json

```python
get_json(
    endpoint: str, *, type_: type[T], **kwargs: Any
) -> T
```

Fetch `endpoint` via GET and decode JSON directly into `type_` using `msgspec`.

#### post\_json

```python
post_json(
    endpoint: str, *, type_: type[T], **kwargs: Any
) -> T
```

Fetch `endpoint` via POST and decode JSON directly into `type_` using `msgspec`.

#### stream\_buffer

```python
stream_buffer(
    method: str, endpoint: str, **kwargs: Any
) -> BytesIO
```

Send an async HTTP request and return an in-memory `BytesIO` stream.

#### stream\_chunks

```python
stream_chunks(
    method: str,
    endpoint: str,
    chunk_size: int = 65536,
    **kwargs: Any,
) -> AsyncIterator[bytes]
```

Stream response bytes in chunks as an async generator, emitting progress when `Content-Length` is known.

#### run\_sync

```python
run_sync(coro: Coroutine[Any, Any, T]) -> T
```

Execute a coroutine synchronously and close any session bound to the temporary event loop.

---

## NCBI Entrez & Datasets (`seroverse.client.ncbi`)

## ncbi

NCBI Entrez E-Utilities and NCBI Datasets v2 REST API client and models.

Classes:

| Name | Description |
| --- | --- |
| `NuccoreSummary` | Immutable NCBI `nuccore` `esummary` record. |
| `PubMedArticleId` | Article identifier entry inside a PubMed `esummary` record. |
| `PubMedSummary` | Immutable PubMed `esummary` record. |
| `DatasetAssemblyReport` | Immutable NCBI Datasets v2 genome assembly report summary. |
| `NCBIClient` | Asynchronous client for NCBI Entrez E-Utilities and NCBI Datasets v2. |

### NuccoreSummary

Immutable NCBI `nuccore` `esummary` record.

### PubMedArticleId

Article identifier entry inside a PubMed `esummary` record.

### PubMedSummary

Immutable PubMed `esummary` record.

### DatasetAssemblyReport

Immutable NCBI Datasets v2 genome assembly report summary.

### NCBIClient

Bases: `Client`

Asynchronous client for NCBI Entrez E-Utilities and NCBI Datasets v2.

Methods:

| Name | Description |
| --- | --- |
| `esearch` | Run rate-limited `esearch.fcgi` and return matching UID strings. |
| `esummary` | Run batched `esummary.fcgi` POST requests and return `{uid: info_dict}`. |
| `fetch_nuccore_summaries` | Fetch `NuccoreSummary` records for `uids`, optionally filtering by sequence length `slen_range`. |
| `fetch_pubmed_summaries` | Fetch `PubMedSummary` records (including DOIs) for `pmids`. |
| `elink_pubmed_to_nuccore` | Map PubMed IDs to linked `nuccore` UIDs via `elink.fcgi` (`pubmed_nuccore`). |
| `efetch_fasta` | Download multi-FASTA bytes for `uids` via `efetch.fcgi`. |
| `fetch_taxon_assemblies` | Query NCBI Datasets v2 `genome/taxon/{taxon}/dataset_report` and return assembly reports. |
| `download_assembly_fasta` | Download genome FASTA bytes for `accession` via NCBI Datasets v2 archive endpoint. |

#### esearch

```python
esearch(db: str, term: str, retmax: int = 100) -> list[str]
```

Run rate-limited `esearch.fcgi` and return matching UID strings.

#### esummary

```python
esummary(
    db: str, uids: Sequence[str], chunk_size: int = 200
) -> dict[str, dict[str, Any]]
```

Run batched `esummary.fcgi` POST requests and return `{uid: info_dict}`.

#### fetch\_nuccore\_summaries

```python
fetch_nuccore_summaries(
    uids: Sequence[str],
    *,
    slen_range: tuple[int, int] | None = None,
    chunk_size: int = 200,
) -> dict[str, NuccoreSummary]
```

Fetch `NuccoreSummary` records for `uids`, optionally filtering by sequence length `slen_range`.

#### fetch\_pubmed\_summaries

```python
fetch_pubmed_summaries(
    pmids: Sequence[int | str], chunk_size: int = 150
) -> dict[int, PubMedSummary]
```

Fetch `PubMedSummary` records (including DOIs) for `pmids`.

#### elink\_pubmed\_to\_nuccore

```python
elink_pubmed_to_nuccore(
    pmids: Sequence[int], batch_size: int = 40
) -> dict[int, list[str]]
```

Map PubMed IDs to linked `nuccore` UIDs via `elink.fcgi` (`pubmed_nuccore`).

#### efetch\_fasta

```python
efetch_fasta(
    uids: Sequence[str], db: str = "nuccore"
) -> bytes
```

Download multi-FASTA bytes for `uids` via `efetch.fcgi`.

#### fetch\_taxon\_assemblies

```python
fetch_taxon_assemblies(
    taxon: str, page_size: int = 1000
) -> list[DatasetAssemblyReport]
```

Query NCBI Datasets v2 `genome/taxon/{taxon}/dataset_report` and return assembly reports.

#### download\_assembly\_fasta

```python
download_assembly_fasta(accession: str) -> bytes
```

Download genome FASTA bytes for `accession` via NCBI Datasets v2 archive endpoint.

---

## ENA Portal & Browser (`seroverse.client.ena`)

## ena

Asynchronous client for the EMBL-EBI ENA Portal REST API.

Classes:

| Name | Description |
| --- | --- |
| `ENASampleRecord` | Immutable ENA Portal `sample` record decoded via `msgspec`. |
| `ENAAssemblyRecord` | Immutable ENA Portal `assembly` record decoded via `msgspec`. |
| `ENAClient` | Asynchronous client for the EMBL-EBI ENA Portal API. |

### ENASampleRecord

Immutable ENA Portal `sample` record decoded via `msgspec`.

### ENAAssemblyRecord

Immutable ENA Portal `assembly` record decoded via `msgspec`.

### ENAClient

Bases: `Client`

Asynchronous client for the EMBL-EBI ENA Portal API.

Methods:

| Name | Description |
| --- | --- |
| `search_samples` | Query `search?result=sample` and decode directly into `list[ENASampleRecord]`. |
| `search_assemblies` | Query `search?result=assembly` and decode directly into `list[ENAAssemblyRecord]`. |

#### search\_samples

```python
search_samples(
    query: str,
    fields: Sequence[str] = (
        "sample_accession",
        "scientific_name",
        "strain",
        "serotype",
        "serovar",
        "tax_id",
    ),
    limit: int = 0,
) -> list[ENASampleRecord]
```

Query `search?result=sample` and decode directly into `list[ENASampleRecord]`.

#### search\_assemblies

```python
search_assemblies(
    query: str,
    fields: Sequence[str] = (
        "accession",
        "sample_accession",
        "scientific_name",
        "strain",
        "tax_id",
    ),
    limit: int = 0,
) -> list[ENAAssemblyRecord]
```

Query `search?result=assembly` and decode directly into `list[ENAAssemblyRecord]`.

---

## DSMZ BacDive & StrainInfo (`seroverse.client.dsmz`)

## dsmz

DSMZ StrainInfo v2 and BacDive v2 REST API clients and culture-collection models.

Classes:

| Name | Description |
| --- | --- |
| `StrainLiterature` | Immutable bibliographic entry linked to a StrainInfo culture deposit. |
| `StrainPassport` | Consolidated DSMZ StrainInfo v2 passport with culture-collection synonyms, PMIDs, and INSDC accessions. |
| `StrainInfoClient` | Asynchronous client for the public DSMZ StrainInfo v2 REST API. |
| `BacDiveClient` | Asynchronous client for the DSMZ BacDive v2 REST API. |

### StrainLiterature

Immutable bibliographic entry linked to a StrainInfo culture deposit.

### StrainPassport

Consolidated DSMZ StrainInfo v2 passport with culture-collection synonyms, PMIDs, and INSDC accessions.

Methods:

| Name | Description |
| --- | --- |
| `from_raw_dict` | Parse a raw StrainInfo `/v2/data/strain/max/` JSON object into a `StrainPassport`. |

#### from\_raw\_dict

```python
from_raw_dict(raw: dict[str, Any]) -> StrainPassport | None
```

Parse a raw StrainInfo `/v2/data/strain/max/` JSON object into a `StrainPassport`.

### StrainInfoClient

Bases: `Client`

Asynchronous client for the public DSMZ StrainInfo v2 REST API.

Methods:

| Name | Description |
| --- | --- |
| `search_by_taxon` | Return all StrainInfo IDs (`SI-ID`s) for a species or genus name. |
| `search_by_cc_no` | Return matching `SI-ID`s for a culture collection number (e.g. `ATCC 25238`, `NCTC 9001`). |
| `search_by_designation` | Return matching `SI-ID`s for an arbitrary strain designation (e.g. `Prague 1550/57`). |
| `search_by_collection` | Return all `SI-ID`s deposited in a culture collection (e.g. `CNCTC`, `NCTC`, `ATCC`). |
| `fetch_passports` | Batch-fetch `StrainPassport` records for `si_ids` via `/v2/data/strain/max/{ids}`. |
| `fetch_taxon_passports` | Search all strains for `taxon_name` and batch-fetch their complete `StrainPassport` records. |

#### search\_by\_taxon

```python
search_by_taxon(taxon_name: str) -> list[int]
```

Return all StrainInfo IDs (`SI-ID`s) for a species or genus name.

#### search\_by\_cc\_no

```python
search_by_cc_no(cc_no: str) -> list[int]
```

Return matching `SI-ID`s for a culture collection number (e.g. `ATCC 25238`, `NCTC 9001`).

#### search\_by\_designation

```python
search_by_designation(designation: str) -> list[int]
```

Return matching `SI-ID`s for an arbitrary strain designation (e.g. `Prague 1550/57`).

#### search\_by\_collection

```python
search_by_collection(collection_code: str) -> list[int]
```

Return all `SI-ID`s deposited in a culture collection (e.g. `CNCTC`, `NCTC`, `ATCC`).

#### fetch\_passports

```python
fetch_passports(
    si_ids: Sequence[int], batch_size: int = 50
) -> list[StrainPassport]
```

Batch-fetch `StrainPassport` records for `si_ids` via `/v2/data/strain/max/{ids}`.

#### fetch\_taxon\_passports

```python
fetch_taxon_passports(
    taxon_name: str, batch_size: int = 50
) -> list[StrainPassport]
```

Search all strains for `taxon_name` and batch-fetch their complete `StrainPassport` records.

### BacDiveClient

Bases: `Client`

Asynchronous client for the DSMZ BacDive v2 REST API.

Methods:

| Name | Description |
| --- | --- |
| `fetch_strain` | Fetch a BacDive strain record by its integer `bacdive_id`. |

#### fetch\_strain

```python
fetch_strain(bacdive_id: int) -> dict[str, Any]
```

Fetch a BacDive strain record by its integer `bacdive_id`.

---

## Pathogenwatch Collections (`seroverse.client.pathogenwatch`)

## pathogenwatch

Pathogenwatch REST API client and collection metadata models.

Classes:

| Name | Description |
| --- | --- |
| `PathogenwatchCollection` | Dataclass representing a Pathogenwatch collection metadata object. |
| `PathogenwatchCollectionBundle` | In-memory collection download bundle from Pathogenwatch. |
| `PathogenwatchClient` | Asynchronous and synchronous client for interacting with the Pathogenwatch REST API. |

### PathogenwatchCollection

Dataclass representing a Pathogenwatch collection metadata object.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `uuid` | `str` | Short UUID identifier of the collection. |
| `name` | `str` | Human-readable title of the collection. |
| `id` | `int \| str \| None` | Optional numeric or string internal Pathogenwatch collection ID. |
| `description` | `str \| None` | Optional collection description text. |
| `size` | `int \| None` | Total number of genomes in the collection, or `None`. |
| `organism_id` | `str \| None` | Taxonomic organism identifier. |
| `organism_name` | `str \| None` | Human-readable species/organism name. |
| `owner` | `str \| None` | Ownership tag (e.g., `"me"` for user-owned collections). |
| `access` | `str \| None` | Visibility/access level (e.g., `"PUBLIC"` or `"PRIVATE"`). |
| `binned` | `bool \| None` | Whether the collection is binned/archived. |
| `created_at` | `str \| None` | ISO timestamp string when the collection was created. |

Methods:

| Name | Description |
| --- | --- |
| `from_dict` | Instantiates a `PathogenwatchCollection` from a raw API dictionary payload. |
| `group_choices` | Builds grouped selectize choices organized by species/organism (with owned collections first). |

#### organism\_label

```python
organism_label: str | None
```

Returns the resolved human-readable species/organism label for grouping, or `None`.

#### genome\_count

```python
genome_count: int | None
```

Returns the collection genome count.

#### is\_owned

```python
is_owned: bool
```

Returns whether this collection belongs to the authenticated user (`"me"`).

#### display\_label

```python
display_label: str
```

Returns a human-readable selector label including genome count when available.

#### from\_dict

```python
from_dict(data: dict[str, Any]) -> PathogenwatchCollection
```

Instantiates a `PathogenwatchCollection` from a raw API dictionary payload.

#### group\_choices

```python
group_choices(
    collections: Sequence[PathogenwatchCollection],
) -> dict[str, Any]
```

Builds grouped selectize choices organized by species/organism (with owned collections first).

### PathogenwatchCollectionBundle

In-memory collection download bundle from Pathogenwatch.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `uuid` | `str` | Short UUID identifier of the collection. |
| `name` | `str` | Resolved collection name. |
| `details` | `dict[str, Any]` | Raw collection details dictionary (`downloads`, `trees`, `organismName`). |
| `records` | `tuple[dict[str, Any], ...]` | Paginated genome records tuple. |
| `analyses` | `tuple[tuple[str, bytes], ...]` | Tuple of `(download_type, csv_bytes)` pairs in requested order. |
| `metadata_csv` | `bytes \| None` | Downloaded isolate metadata CSV bytes, or `None`. |
| `matrix_csv` | `bytes \| None` | Downloaded pairwise distance matrix CSV bytes, or `None`. |
| `fallback_newick` | `bytes` | First tree Newick byte string from `details['trees']` if available. |

### PathogenwatchClient

Bases: `Client`

Asynchronous and synchronous client for interacting with the Pathogenwatch REST API.

Methods:

| Name | Description |
| --- | --- |
| `get_collections` | Fetches collections available to the authenticated account or public collections. |
| `get_collection` | Fetches complete metadata and analysis jobs for a specific collection. |
| `get_collection_genomes` | Fetches genome analysis records for a collection. |
| `download_distance_matrix` | Downloads pairwise genomic distance matrix CSV bytes for a collection. |
| `download_analysis` | Downloads discrete analysis CSV bytes (e.g. Kleborate, Kaptive) for a collection. |
| `download_kleborate` | Downloads Kleborate analysis CSV bytes for a collection. |
| `download_kaptive` | Downloads Kaptive analysis CSV bytes for a collection. |
| `download_metadata` | Downloads isolate metadata CSV bytes for a collection. |
| `download_summary` | Downloads summary CSV bytes for a collection. |
| `fetch_collection_bundle` | Downloads collection details, genomes, analyses, metadata, and distance matrix in memory. |
| `download_collection_files` | Downloads discrete collection files to an output directory on disk. |
| `default_analysis_types` | Selects the default genotype analysis types from a collection's `downloads` list. |
| `get_collections_sync` | Synchronously fetches collections available to the authenticated account or public collections. |
| `get_collection_sync` | Synchronously fetches complete metadata and analysis jobs for a collection. |
| `get_collection_genomes_sync` | Synchronously fetches genome analysis records for a collection. |
| `download_distance_matrix_sync` | Synchronously downloads the pairwise genomic distance matrix CSV bytes for a collection. |
| `download_analysis_sync` | Synchronously downloads discrete analysis CSV bytes for a collection. |
| `download_kleborate_sync` | Synchronously downloads Kleborate analysis CSV bytes for a collection. |
| `download_kaptive_sync` | Synchronously downloads Kaptive analysis CSV bytes for a collection. |
| `download_metadata_sync` | Synchronously downloads isolate metadata CSV bytes for a collection. |
| `download_summary_sync` | Synchronously downloads summary CSV bytes for a collection. |
| `download_collection_files_sync` | Synchronously downloads collection CSV files to disk. |
| `fetch_collection_bundle_sync` | Synchronously downloads a collection bundle in memory. |

#### get\_collections

```python
get_collections(
    owner: str | None = None,
    exclude: str | None = None,
    binned: bool | None = None,
    limit: int | None = None,
) -> list[PathogenwatchCollection]
```

Fetches collections available to the authenticated account or public collections.

#### get\_collection

```python
get_collection(uuid: str) -> dict[str, Any]
```

Fetches complete metadata and analysis jobs for a specific collection.

#### get\_collection\_genomes

```python
get_collection_genomes(
    uuid: str,
    share_id: str | None = None,
    page: int = 1,
    all_pages: bool = True,
) -> list[dict[str, Any]]
```

Fetches genome analysis records for a collection.

#### download\_distance\_matrix

```python
download_distance_matrix(
    uuid: str, matrix_type: str = "difference"
) -> bytes
```

Downloads pairwise genomic distance matrix CSV bytes for a collection.

#### download\_analysis

```python
download_analysis(
    uuid: str,
    download_type: str,
    job: str | None = None,
    genome_ids: Sequence[str] | None = None,
    prefix: str | None = None,
) -> bytes
```

Downloads discrete analysis CSV bytes (e.g. Kleborate, Kaptive) for a collection.

#### download\_kleborate

```python
download_kleborate(
    uuid: str,
    genome_ids: Sequence[str] | None = None,
    prefix: str | None = None,
) -> bytes
```

Downloads Kleborate analysis CSV bytes for a collection.

#### download\_kaptive

```python
download_kaptive(
    uuid: str,
    genome_ids: Sequence[str] | None = None,
    prefix: str | None = None,
) -> bytes
```

Downloads Kaptive analysis CSV bytes for a collection.

#### download\_metadata

```python
download_metadata(
    uuid: str,
    genome_ids: Sequence[str] | None = None,
    prefix: str | None = None,
) -> bytes
```

Downloads isolate metadata CSV bytes for a collection.

#### download\_summary

```python
download_summary(
    uuid: str,
    genome_ids: Sequence[str] | None = None,
    prefix: str | None = None,
) -> bytes
```

Downloads summary CSV bytes for a collection.

#### fetch\_collection\_bundle

```python
fetch_collection_bundle(
    uuid: str,
    *,
    with_distances: bool = True,
    with_metadata: bool = True,
    matrix_type: str = "difference",
    dataset_name: str | None = None,
    strict_distances: bool = False,
    analysis_types: Sequence[str] | str | None = None,
) -> PathogenwatchCollectionBundle
```

Downloads collection details, genomes, analyses, metadata, and distance matrix in memory.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `uuid` | `str` | Short UUID of the collection. | *required* |
| `with_distances` | `bool` | Whether to download the pairwise distance matrix CSV. | `True` |
| `with_metadata` | `bool` | Whether to download spatiotemporal isolate metadata CSV. | `True` |
| `matrix_type` | `str` | Distance matrix type (`"difference"` or `"score"`). | `'difference'` |
| `dataset_name` | `str \| None` | Optional custom name override. Defaults to the collection title. | `None` |
| `strict_distances` | `bool` | If `True`, raise if the distance matrix endpoint fails. If `False` (default), fall back to Newick tree or emit a `RuntimeWarning`. | `False` |
| `analysis_types` | `Sequence[str] \| str \| None` | Optional analysis name or sequence of analysis names to fetch. When `None`, automatically selects `"kleborate"` if available, else `"kaptive"`. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `PathogenwatchCollectionBundle` | In-memory `PathogenwatchCollectionBundle` containing all downloaded CSV byte buffers. |

#### download\_collection\_files

```python
download_collection_files(
    uuid: str,
    output_dir: str | Path,
    analysis_types: Sequence[str] = (
        "kleborate",
        "kaptive",
    ),
    include_metadata: bool = True,
    include_matrix: bool = True,
    matrix_type: str = "difference",
    prefix: str | None = None,
) -> dict[str, Path]
```

Downloads discrete collection files to an output directory on disk.

#### default\_analysis\_types

```python
default_analysis_types(
    downloads: Sequence[dict[str, Any]],
) -> tuple[str, ...]
```

Selects the default genotype analysis types from a collection's `downloads` list.

#### get\_collections\_sync

```python
get_collections_sync(
    owner: str | None = None,
    exclude: str | None = None,
    binned: bool | None = None,
    limit: int | None = None,
) -> list[PathogenwatchCollection]
```

Synchronously fetches collections available to the authenticated account or public collections.

#### get\_collection\_sync

```python
get_collection_sync(uuid: str) -> dict[str, Any]
```

Synchronously fetches complete metadata and analysis jobs for a collection.

#### get\_collection\_genomes\_sync

```python
get_collection_genomes_sync(
    uuid: str,
    share_id: str | None = None,
    page: int = 1,
    all_pages: bool = True,
) -> list[dict[str, Any]]
```

Synchronously fetches genome analysis records for a collection.

#### download\_distance\_matrix\_sync

```python
download_distance_matrix_sync(
    uuid: str, matrix_type: str = "difference"
) -> bytes
```

Synchronously downloads the pairwise genomic distance matrix CSV bytes for a collection.

#### download\_analysis\_sync

```python
download_analysis_sync(
    uuid: str,
    download_type: str,
    job: str | None = None,
    genome_ids: Sequence[str] | None = None,
    prefix: str | None = None,
) -> bytes
```

Synchronously downloads discrete analysis CSV bytes for a collection.

#### download\_kleborate\_sync

```python
download_kleborate_sync(
    uuid: str,
    genome_ids: Sequence[str] | None = None,
    prefix: str | None = None,
) -> bytes
```

Synchronously downloads Kleborate analysis CSV bytes for a collection.

#### download\_kaptive\_sync

```python
download_kaptive_sync(
    uuid: str,
    genome_ids: Sequence[str] | None = None,
    prefix: str | None = None,
) -> bytes
```

Synchronously downloads Kaptive analysis CSV bytes for a collection.

#### download\_metadata\_sync

```python
download_metadata_sync(
    uuid: str,
    genome_ids: Sequence[str] | None = None,
    prefix: str | None = None,
) -> bytes
```

Synchronously downloads isolate metadata CSV bytes for a collection.

#### download\_summary\_sync

```python
download_summary_sync(
    uuid: str,
    genome_ids: Sequence[str] | None = None,
    prefix: str | None = None,
) -> bytes
```

Synchronously downloads summary CSV bytes for a collection.

#### download\_collection\_files\_sync

```python
download_collection_files_sync(
    uuid: str,
    output_dir: str | Path,
    analysis_types: Sequence[str] = (
        "kleborate",
        "kaptive",
    ),
    include_metadata: bool = True,
    include_matrix: bool = True,
    matrix_type: str = "difference",
    prefix: str | None = None,
) -> dict[str, Path]
```

Synchronously downloads collection CSV files to disk.

#### fetch\_collection\_bundle\_sync

```python
fetch_collection_bundle_sync(
    uuid: str,
    *,
    with_distances: bool = True,
    with_metadata: bool = True,
    matrix_type: str = "difference",
    dataset_name: str | None = None,
    strict_distances: bool = False,
    analysis_types: Sequence[str] | str | None = None,
) -> PathogenwatchCollectionBundle
```

Synchronously downloads a collection bundle in memory.