Strava.cz Python API

Python knihovna pro objednávání jídel ve školních jídelnách, které používají systém Strava.cz. Komunikuje přímo s interním JSON API webové aplikace, takže nepotřebuje prohlížeč ani parsování HTML.

pip install strava-cz          # knihovna
pip install "strava-cz[cli]"   # + bezpečné uložení hesla pro příkaz strava-cz

Ve složce notes najdete všechny moje poznatky o vnitřním fungování API Strava.cz. Kompletní dokumentace je na GitHub Wiki.

Co knihovna umí

• Přihlášení a odhlášení, včetně správy session
• Načtení a filtrování jídelníčku podle typu jídla, data a objednatelnosti
• Objednávání a rušení jídel v jedné transakci, s ověřením výsledku
• Rozpoznání, proč konkrétní jídlo objednat nelze (uzávěrka, prázdniny, ...)
• Sledování zůstatku na účtu
• Rozlišení dnů, na které jídelna neobjednává automaticky
• Příkaz strava-cz pro práci z terminálu, s výpisem pro lidi i s JSON pro skripty
• Profily, takže se přihlašovací údaje nezadávají znovu a heslo leží v klíčence
• Plné typové anotace (py.typed), takže vám editor napovídá

Rychlý start

from strava_cz import StravaCZ

with StravaCZ("vase.jmeno", "VaseHeslo123", "3753") as strava:
    print(strava.user)

    strava.menu.fetch()
    strava.menu.print()

    # Objedná oběd s ID 5 a 9
    strava.menu.order_meals(5, 9)

with blok se sám postará o odhlášení a uzavření spojení. Pokud ho nepoužijete, zavolejte na konci strava.logout() sami.

ID jídla je unikátní číslo jídla v rámci právě publikovaného jídelníčku (v API pole veta). Není trvale vázané na konkrétní jídlo a mění se s každou změnou jídelníčku, takže ho vždy berte z čerstvě načteného jídelníčku.

Práce s jídelníčkem

from strava_cz import StravaCZ, MealType

strava = StravaCZ("vase.jmeno", "VaseHeslo123", "3753")
strava.menu.fetch()

# Dny a jídla
dny = strava.menu.get_days()          # seznam objektů Day
jidla = strava.menu.get_meals()       # plochý seznam objektů Meal

# Filtrování - všechny parametry jdou kombinovat
obedy = strava.menu.get_meals(meal_types=[MealType.MAIN], orderable=True)
tento_tyden = strava.menu.get_days(date_from="2026-09-07", date_to="2026-09-11")
objednane = strava.menu.get_meals(ordered=True)

# Vyhledávání
den = strava.menu.get_by_date("2026-09-07")
jidlo = strava.menu.get_by_id(9)
print(strava.menu.is_ordered(9))

# Iterace, len() a indexování fungují přímo na menu
for den in strava.menu:
    print(den.date, [j.name for j in den.meals])

Ve výchozím nastavení se nic neskrývá — vrátí se každé publikované jídlo a u každého se dozvíte, jestli jde objednat. Jedinou výjimkou jsou dny, kdy se nevaří; ty se přidají pomocí include_no_school=True.

Objekt Meal

Objekt Day

Enumy

MealType — SOUP, MAIN, UNKNOWN. Odvozuje se z krátkého kódu druh ("PO", "O1", ...), který je stabilnější než zobrazovaný text.

Restriction — proč jídelna nedovolí jídlo objednat nebo změnit:

DayStatus — co jídelna říká o celém dni (pole omezeniObj.den). Na objednatelnost nemá vliv, tu určuje vždy jen konkrétní jídlo:

Dny, na které se neobjednává automaticky

Jídelna některé dny označuje kódem "T". Objednat na ně jde úplně normálně, jen se neobjednají samy — typicky pátek, kdy se ve škole neučí. Knihovna to vystavuje jako Day.auto_ordered a jako filtr:

# Co by automat objednal, kdyby na to byl
strava.menu.get_meals(auto_ordered=True, orderable=True)

# Dny, které si musíte objednat sami
[den.date for den in strava.menu.get_days(auto_ordered=False)]

Ve výchozím nastavení se tyhle dny nijak neskrývají — jsou to obyčejné objednatelné dny.

Objednávání

from strava_cz import StravaCZ, InsufficientBalanceError, MealNotOrderableError

strava = StravaCZ("vase.jmeno", "VaseHeslo123", "3753")
strava.menu.fetch()

try:
    vysledek = strava.menu.order_meals(5, 9)
    print(vysledek)          # "2 changed"
    print(vysledek.changed)  # (5, 9)
except MealNotOrderableError as e:
    print(f"Tohle jídlo objednat nejde: {e}")
except InsufficientBalanceError:
    print(f"Nedostatečný zůstatek: {strava.user.balance} Kč")

# Zrušení objednávek
strava.menu.cancel_meals(5, 9)

Obě metody proběhnou jako jedna transakce: nejdřív se zaškrtnou všechna jídla, pak se změny uloží najednou a nakonec se výsledek ověří na čerstvě načteném jídelníčku. Když cokoliv selže, změny se zahodí a nic se neuloží. Pokud není co měnit, neodešle se žádný požadavek.

Parametry

• continue_on_error=True — neskončí u první chyby. Objedná, co jde, a zbytek vrátí v OrderResult, místo aby vyhodila výjimku.
• strict_duplicates=True — vyhodí DuplicateMealError, když se dvě zvolená jídla perou o stejné místo (stejný den, stejný typ). Ve výchozím stavu se objedná první z nich a u ostatních se jen vypíše varování.

vysledek = strava.menu.order_meals(5, 85, 999, continue_on_error=True)

print(vysledek.changed)    # (5,)   objednáno
print(vysledek.unchanged)  # ()     už bylo objednané, nic se neposílalo
print(vysledek.skipped)    # ()     vynecháno kvůli duplicitě
print(vysledek.failed)     # ((85, MealNotOrderableError(...)), (999, MealNotFoundError(...)))
print(vysledek.ok)         # False

Příkazová řádka

Balíček instaluje příkaz strava-cz. Umí všechno, co knihovna, a ve výchozím stavu vypisuje čitelnou tabulku; pro skripty je tu --format json.

# jednou uložit přihlášení (heslo jde do klíčenky operačního systému)
strava-cz profile add skola --username vase.jmeno --canteen 3753

strava-cz menu --week                  # jídelníček na tento týden
strava-cz menu --orderable --type main # jen hlavní jídla, která jdou objednat
strava-cz order 5 9                    # objednat
strava-cz order 5 9 --dry-run          # jen říct, co by se stalo
strava-cz cancel 5                     # zrušit
strava-cz ordered                      # co mám objednáno
strava-cz balance                      # 512.50 Kč

Mon 21.09.2026
  ·   102  Polévka    Zeleninová            this item cannot be ordered separately
  ○    37  Oběd 1     Bramborové knedlíky s kuřecím masem a špenátem          50 Kč
  ○    38  Oběd 2     Bramborové špalíky sypané cibulkou, kysané zelí         50 Kč

Fri 25.09.2026  not ordered automatically
  ○    49  Oběd 1     Kuřecí asijská pánev, kari rýže, tvaroháček             50 Kč

5 days · 15 meals · 10 orderable · 0 ordered · balance 0.00 Kč

Barvy se zapínají jen na terminálu — v rouře, v souboru nebo v cronu se nevypisují, stejně jako když je nastavená proměnná NO_COLOR. Vynutit je jde přes --color always.

Pro skripty

S --format json (nebo zkratkou --json) vypadne na standardní výstup jeden JSON objekt a všechna hlášení jdou na chybový výstup, takže výstup zůstane zpracovatelný. Chyba se hlásí taky JSONem, ne textem:

strava-cz --json menu --orderable | jq '.days[].meals[] | select(.type=="main") | .id'
strava-cz --json ordered | jq '.total_price'

{ "ok": false,
  "command": "order",
  "error": { "type": "MealNotOrderableError", "meal_id": 85, "reason": "unavailable",
             "message": "Cannot order meal 85: this item cannot be ordered separately" } }

Návratové kódy — aby se šlo v shellu rozhodnout, co se pokazilo:

--dry-run u order a cancel neodešle vůbec nic — jen spočítá, co by se změnilo, včetně jídel, která už jsou objednaná, a dvou jídel, která by soupeřila o stejné místo.

Úplný seznam přepínačů vypíše strava-cz --help a strava-cz menu --help.

Profily

Profil si pamatuje uživatelské jméno a číslo jídelny; heslo se do souboru nezapisuje. Ve výchozím stavu putuje do klíčenky operačního systému (GNOME Keyring, KWallet, macOS Keychain, Windows Credential Locker) přes balíček keyring.

strava-cz profile add skola --username vase.jmeno --canteen 3753 --verify
strava-cz profile list
strava-cz profile show skola
strava-cz profile default doma
strava-cz profile remove doma

strava-cz --profile doma menu   # jednorázově jiný profil

Přepínač --secret říká, odkud se heslo bere:

auto vždycky vypíše, kterou z obou cest zvolilo, a do profilu zapíše konkrétní výsledek — profile show tedy nikdy neuhýbá.

Profily leží v $XDG_CONFIG_HOME/strava-cz/profiles.json (soubor 0600, složka 0700). Prostředí má vždycky přednost před uloženým heslem, takže cron může použít existující profil, aniž by se do něj sahalo: $STRAVA_CZ_PASSWORD_<JMENO_PROFILU> přebije $STRAVA_CZ_PASSWORD a obojí přebije klíčenku.

Server bez klíčenky

Na serveru bez grafického prostředí klíčenka většinou nefunguje. strava-cz profile add to pozná dopředu a přepne na encrypted: heslo se zašifruje algoritmem AES-256-GCM klíčem, který z vaší heslové fráze odvodí scrypt (n=2^15, r=8, p=1). Parametry se ukládají do záznamu, takže i po jejich pozdější změně půjdou starší profily otevřít.

"encrypted": {
  "cipher": "aes-256-gcm",
  "kdf": { "name": "scrypt", "n": 32768, "r": 8, "p": 1, "salt": "…" },
  "nonce": "…",
  "ciphertext": "…"
}

Heslová fráze se hledá stejně jako heslo: $STRAVA_CZ_PASSPHRASE_<JMENO_PROFILU>, pak $STRAVA_CZ_PASSPHRASE, pak se na ni program zeptá na terminálu. Pro cron tedy stačí nastavit proměnnou.

Co to řeší a co ne. Šifrování chrání soubor v klidu — zálohu, kopii domovského adresáře, složku, která se omylem odsynchronizuje jinam. Kdo umí přečíst jen profiles.json, s ním nic nesvede. Nechrání vás před někým, kdo už čte vaše prostředí nebo paměť běžícího procesu. V cronu je heslová fráze v proměnné podobně, jako by tam bylo heslo — rozdíl je v tom, že samotný soubor s profily je pak bezpečné zálohovat a synchronizovat.

Zašifrovaný záznam je navíc ověřený (GCM), takže poškozený nebo pozměněný soubor skončí srozumitelnou chybou, ne tichým nesmyslem.

Profily jdou použít i z Pythonu:

from strava_cz import StravaCZ

with StravaCZ.from_profile("skola") as strava:   # bez profilu se vezme výchozí
    strava.menu.fetch()
    strava.menu.print()

Výjimky

Všechny výjimky knihovny dědí ze StravaError, takže je lze odchytit najednou.

Nastavení klienta

strava = StravaCZ(
    "vase.jmeno", "VaseHeslo123", "3753",
    timeout=30.0,      # výchozí je 15 s, z toho 10 s na navázání spojení
    retries=2,         # opakuje se jen spojení, které se nenavázalo
    language="CS",     # jazyk odpovědí z API
)

Heslo se použije jen pro přihlašovací požadavek a dál se nikde neukládá. Parametrem client= můžete také předat vlastní httpx.Client.

To-do

• Nahrát jako knihovnu na PyPI
• Lépe zorganizovat kód
• Lepší formát data
• Možnost detailnější filtrace jídelníčku
• Kontrola stavu po objednání
• Detekce a prevence duplicitních objednávek
• Rozpoznání důvodu, proč jídlo nelze objednat
• Lépe zdokumentovat použití
• Nástroj pro příkazovou řádku
• Profily s bezpečně uloženým heslem
• Uložení hesla i na stroji bez klíčenky
• Login rate limiting
• Debug/log mód
• Asynchronní klient

Co bude dál?

Plánuji udělat aplikaci, která bude uživateli automaticky objednávat obědy podle jeho preferencí.

Prosím, nepoužívejte tuto knihovnu k nekalým účelům. Používejte ji pouze s dobrými úmysly.

Jak mi pomoct

Našel jsi chybu nebo máš návrh na zlepšení? Skvělé! Vytvoř prosím bug report nebo feature request.

Udělal jsi sám nějaké zlepšení? Ještě lepší! Každý pull request je vítaný — postup najdeš v notes/repo_rules.md.

Použití AI

Na tomto projektu byly do jisté míry využity modely LLM, primárně na dokumentaci, testy a formátování kódu. Každá taková úprava prošla mojí kontrolou.

Licence

GPL-3.0-or-later