pycellarion

Async Python client for the Cellarion wine-cellar API. It is the library behind the Home Assistant integration, and usable on its own by anything that wants to read a cellar or mark a bottle as consumed.

• Async, typed, small. One dependency (aiohttp), py.typed, no I/O outside the calls you make.
• Two credentials. A personal API token (cel_…, created in Cellarion under Settings → API tokens), or email and password used once to mint such a token. Passwords are never kept beyond the login they were given for.
• Push events. Parses the server's text/event-stream and yields event names, so callers can refresh on change instead of polling.
• Honest errors. Status codes map to a small exception hierarchy: CellarionAuthError (re-authenticate), CellarionScopeError (the token lacks a scope), CellarionTokensNotSupported, CellarionPushNotSupported and CellarionInventoryNotSupported (older servers), CellarionPushForbidden, and CellarionApiError for everything else.

Install

pip install pycellarion

Use

import aiohttp
from pycellarion import CellarionClient

async with aiohttp.ClientSession() as session:
    client = CellarionClient(session, "https://cellarion.app", token="cel_…")

    stats = await client.get_stats_overview()
    print(stats["stats"]["overview"]["totalBottles"])

    async for event in client.events_stream():
        if event == "_connected":
            continue
        print("something changed:", event)

Minting a token from email and password:

client = CellarionClient(session, "https://cellarion.app", "me@example.com", "secret")
await client.authenticate()
token = await client.async_create_api_token("My script", ["read", "consume"])
# keep `token`; the password is not needed again

Inventory

get_inventory() returns every bottle in the user's cellars in one read: cellars, racks, the wines the bottles reference, each bottle's place (rack, shelf, row, slot) and drink window. Keep the etag and pass it back; while nothing has changed the server answers 304 and you keep your copy.

from pycellarion import CellarionInventoryNotSupported

try:
    result = await client.get_inventory()
except CellarionInventoryNotSupported:
    ...  # the server is older than the inventory endpoint
inventory, etag = result.data, result.etag

for bottle in inventory["bottles"]:
    wine = inventory["wines"].get(bottle["wine"]) or bottle["pending"]
    print(wine["name"], bottle["vintage"], bottle["location"])
    if bottle["image"]:  # a label thumbnail path
        body, content_type = await client.get_image(bottle["image"])

# Later: only download it again when something changed
result = await client.get_inventory(etag)
if not result.not_modified:
    inventory, etag = result.data, result.etag

get_image() fetches only paths matching IMAGE_PATH_RE (/api/uploads/thumbs/…/<name>.<ext>.webp) and raises ValueError for anything else without making a request. The uploads mount is public, so the request carries no credential and follows no redirect.

API

Responses are returned as plain dicts (JsonDict); bodies over MAX_BODY_BYTES (4 MiB) are refused. The inventory may be up to MAX_INVENTORY_BYTES (32 MiB) and an image up to MAX_IMAGE_BYTES (2 MiB); both caps are enforced on the bytes as they arrive, not only on the announced Content-Length.

API contract

The integration depends on a handful of endpoints and response shapes. tests/contract/ pins them down and runs nightly against a real Cellarion server (see the Contract badge above), so a change on the server side is caught before it reaches users. Run them yourself against any server with a read-scoped token:

CELLARION_CONTRACT_URL=https://cellarion.app CELLARION_CONTRACT_TOKEN=cel_… pytest tests/contract

They never write: no bottle is consumed and no token is revoked.

Development

pip install -e ".[test]"
ruff check . && ruff format --check . && mypy src
pytest --cov

Releases are published to PyPI from GitHub releases through trusted publishing.

License

MIT