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 and CellarionPushNotSupported (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

API

Responses are returned as plain dicts (JsonDict); bodies over MAX_BODY_BYTES (4 MiB) are refused.

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