v0.1.0

rohlik-api v0.1.0

Initial release of rohlik-api, an async Python client for the Rohlík.cz grocery API.

⚠️ Unofficial & personal-use only. This package wraps Rohlík.cz's private (non-public) API. It is not affiliated with, endorsed by, or supported by Rohlík.cz, and the upstream API may change without notice. Use it for your own account only.

Highlights

• Fully async, built on aiohttp — no blocking calls in the event loop.
• Bring your own session — pass an existing aiohttp.ClientSession (e.g. Home Assistant's shared session); an injected session is never closed by the client.
• Transparent re-authentication — when a request hits HTTP 401 (expired login), the client re-logs in and retries once, so long-lived clients keep working. Concurrent 401s trigger a single re-login.
• Typed dataclass models for parsed responses, with documented fields (units, IDs, meanings) — usable from an IDE or by an LLM without extra docs. Ships py.typed.
• Clean, service-based API under a single RohlikAPI facade.

Requirements

• Python 3.13+
• aiohttp (installed automatically)

Installation

pip install rohlik-api

Quick start

import asyncio
from rohlik_api import RohlikAPI

async def main():
    async with RohlikAPI("you@example.com", "password") as client:
        cart = await client.cart.get_content()
        print(cart.total_price, cart.total_items)

        results = await client.products.search("mléko", limit=5)
        for p in results.results:
            print(p.name, p.price)

asyncio.run(main())

What's included

• Cart — get_content, add_items, delete_item
• Products — search, get_ai_summary, get_composition, get_price, get_detail, get_categories
• Orders — get_next, get_last, get_delivered, get_all_delivered, get_detail
• Delivery — get_info, get_timeslot_reservation, get_next_slots, get_announcements
• Account — get_premium_profile, get_bags_info, get_announcements, get_shopping_list
• Recipes (Rohlík Chef) — search, get_detail, get_ingredient_products
• Aggregate — get_data() fetches account, delivery, orders, and cart in one call
• Errors — RohlikAPIError, InvalidCredentialsError, APIRequestFailedError

Conventions

• Read/optional fetches return None (and log a warning) on failure; lookups for resources that may not exist (e.g. a discontinued product) return None on HTTP 404.
• Mutating/critical operations (login, cart changes, shopping-list fetch) raise APIRequestFailedError.
• Used as an async context manager, the client logs in on entry and logs out + closes on exit.

Quality

• 135 tests; ruff, black, and strict mypy all green on Python 3.13.