> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colacloud.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Type-safe Python client with sync and async support.

## Installation

```bash theme={null}
pip install colacloud
```

Requires Python 3.9+.

## Quick Start

```python theme={null}
from colacloud import ColaCloud

client = ColaCloud(api_key="cola_xxxx")

# Search COLAs
results = client.colas.list(
    q="Tito's",
    product_type="distilled spirits",
    abv_min=35,
    per_page=10
)

for cola in results.data:
    print(f"{cola.brand_name} - {cola.product_name}")

# Get a specific COLA with images and barcodes
cola = client.colas.get("24001001000001")
print(cola.images[0].image_url)

# Barcode lookup
matches = client.barcode.lookup("012345678901")
print(f"Found {matches.total_colas} COLAs")
```

## Filtering

The COLA list endpoint supports generic text search plus structured filters for TTB product type, derived category/subcategory, ABV, package size, container type, permit number, and barcode.

```python theme={null}
results = client.colas.list(
    q="molson coors",
    category="Beer",
    derived_subcategory="Beer > Ale",
    container_type="can",
    volume_unit="fluid ounces",
    volume_min=12,
    volume_max=16,
)
```

Use `q` when you are not sure whether a word belongs to a brand, product, permit, or applicant/company name.

## Auto-Pagination

Iterate through all matching results without managing pages:

```python theme={null}
for cola in client.colas.iterate(q="bourbon"):
    print(f"{cola.ttb_id}: {cola.brand_name}")

for permittee in client.permittees.iterate(state="CA"):
    print(f"{permittee.company_name}: {permittee.colas} COLAs")
```

## Permittees

```python theme={null}
# Search permittees
results = client.permittees.list(state="NY", is_active=True)
for p in results.data:
    print(f"{p.company_name} ({p.permit_number})")

# Get a single permittee with recent COLAs
permittee = client.permittees.get("NY-I-12345")
print(f"Recent COLAs: {len(permittee.recent_colas)}")
```

## Usage Stats

```python theme={null}
usage = client.get_usage()
print(f"Detail views: {usage.detail_views.used} / {usage.detail_views.limit}")
print(f"List records: {usage.list_records.used} / {usage.list_records.limit}")
```

## Async Support

```python theme={null}
import asyncio
from colacloud import AsyncColaCloud

async def main():
    client = AsyncColaCloud(api_key="cola_xxxx")
    results = await client.colas.list(brand_name="Maker's Mark")
    print(f"Found {results.pagination.total} results")

    # Async iteration
    async for cola in client.colas.iterate(q="bourbon"):
        print(cola.brand_name)

asyncio.run(main())
```

## Authentication

Pass your API key directly to the client:

```python theme={null}
client = ColaCloud(api_key="cola_xxxx")
```

## Links

* [GitHub](https://github.com/cola-cloud-us/colacloud-python)
* [PyPI](https://pypi.org/project/colacloud/)