pyedookit 0.3.0__tar.gz

pyedookit-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --group dev
+      - run: uv run pytest
+      - run: uv run ruff check .
+      - run: uv run mypy src

pyedookit-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+# Uses PyPI trusted publishing: register this repo + workflow + the "pypi"
+# environment as a trusted publisher on pypi.org first, no API token needed.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --group dev
+      - run: uv run pytest
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pyedookit-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.env
+cookies.json
+captures/
+.DS_Store

pyedookit-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomas Liska
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyedookit-0.3.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: pyedookit
+Version: 0.3.0
+Summary: Async client for the Edookit parent portal (edookit.net)
+Project-URL: Homepage, https://github.com/TFoxik/pyedookit
+Author: tomas.liska
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: lxml>=5.0
+Description-Content-Type: text/markdown
+
+# pyedookit
+
+Unofficial async Python client for the Edookit parent portal
+(`https://<school>.edookit.net`), used by Czech schools. Built for the
+`ha-edookit` Home Assistant integration but usable standalone.
+
+Edookit's official REST API exists but is only enabled per-school by an
+administrator, so this library works the way a parent actually does: it logs
+in through Plus4U (OIDC) and scrapes the portal's server-rendered pages.
+There is no vendor support for this - selectors may break when Edookit
+changes its markup.
+
+## Status
+
+v0.3.0 - timetable, upcoming school events and payments. Verified end-to-end against a real portal
+(login, session-settling after the OIDC callback, and the timetable parser
+all confirmed working on real data).
+
+**Only `week_offset=0` (the current week) is confirmed working.** The
+portal accepts `week_offset=1` ("next week") without error, but returns the
+same week's data back rather than actually advancing - the real
+week-navigation parameter hasn't been identified yet. Since a school's
+weekly timetable is typically the same all year, current-week-only is
+usually enough in practice. See `scripts/capture_fixtures.py` for how to
+capture and inspect real portal HTML if you want to chase this further (a
+browser HAR trace of clicking the forward-week arrow is what's needed).
+
+Cancelled/substituted lessons are also unverified: no real capture has had
+one yet, so `Lesson.is_changed`/`is_cancelled` are always `False` for now.
+
+## Install
+
+```bash
+pip install pyedookit
+```
+
+## Usage
+
+```python
+import asyncio
+from pyedookit import login, EdookitClient
+
+async def main():
+    session = await login("zs-example", "parent@example.com", "hunter2")
+    client = EdookitClient(session)
+    for lesson in await client.get_timetable(week_offset=0):
+        print(lesson.start, lesson.subject, lesson.room)
+
+asyncio.run(main())
+```
+
+`client.get_events()` returns upcoming school events (`SchoolEvent`, all-day
+events have `date` start/end with an inclusive end), and `client.get_payments()`
+returns the family's payment totals and requests (`Payments`, amounts as
+`Decimal`). Only paid requests have been seen on a real portal so far; a request
+without the "accepted" marker is reported as unpaid.
+
+`client.fetch_page(name)` returns the raw HTML of a page that has no parser yet
+(`CAPTURE_PAGES`: assignments, exams, inbox, consents), and
+`content_fingerprint(html)` tells you when such a page's content changed.
+
+Persist `session.to_json()` / `Session.from_json()` between runs instead of
+storing the password; use `pyedookit.refresh(session)` to renew the
+short-lived edookit session from the long-lived Plus4U cookie, and fall back
+to `login()` only when `refresh()` raises `AuthError`.
+
+Lesson times are timezone-aware (`pyedookit.PORTAL_TZ`, Europe/Prague).
+
+Errors all derive from `EdookitError`:
+
+| Exception | Meaning | What to do |
+|---|---|---|
+| `SessionExpired` | short-lived edookit session aged out | `refresh()` and retry |
+| `AuthError` | bad credentials, or the Plus4U cookie expired | full `login()` |
+| `EdookitConnectionError` | network error or 30 s timeout | retry later |
+| `ParseError` | portal markup changed | parser needs updating |
+
+`login()`, `refresh()` and `EdookitClient` all accept an optional
+`http: aiohttp.ClientSession` to reuse. Cookies are handled by hand, so
+create that session with `cookie_jar=aiohttp.DummyCookieJar()`; a session
+with a real cookie jar would also store and resend the portal's cookies.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check .
+uv run mypy src
+```
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, then push a `vX.Y.Z` tag. The
+`Publish to PyPI` workflow tests, builds and uploads using PyPI trusted
+publishing, which has to be configured once on pypi.org for this repository
+and the `pypi` environment.

pyedookit-0.3.0/README.md

@@ -0,0 +1,97 @@
+# pyedookit
+
+Unofficial async Python client for the Edookit parent portal
+(`https://<school>.edookit.net`), used by Czech schools. Built for the
+`ha-edookit` Home Assistant integration but usable standalone.
+
+Edookit's official REST API exists but is only enabled per-school by an
+administrator, so this library works the way a parent actually does: it logs
+in through Plus4U (OIDC) and scrapes the portal's server-rendered pages.
+There is no vendor support for this - selectors may break when Edookit
+changes its markup.
+
+## Status
+
+v0.3.0 - timetable, upcoming school events and payments. Verified end-to-end against a real portal
+(login, session-settling after the OIDC callback, and the timetable parser
+all confirmed working on real data).
+
+**Only `week_offset=0` (the current week) is confirmed working.** The
+portal accepts `week_offset=1` ("next week") without error, but returns the
+same week's data back rather than actually advancing - the real
+week-navigation parameter hasn't been identified yet. Since a school's
+weekly timetable is typically the same all year, current-week-only is
+usually enough in practice. See `scripts/capture_fixtures.py` for how to
+capture and inspect real portal HTML if you want to chase this further (a
+browser HAR trace of clicking the forward-week arrow is what's needed).
+
+Cancelled/substituted lessons are also unverified: no real capture has had
+one yet, so `Lesson.is_changed`/`is_cancelled` are always `False` for now.
+
+## Install
+
+```bash
+pip install pyedookit
+```
+
+## Usage
+
+```python
+import asyncio
+from pyedookit import login, EdookitClient
+
+async def main():
+    session = await login("zs-example", "parent@example.com", "hunter2")
+    client = EdookitClient(session)
+    for lesson in await client.get_timetable(week_offset=0):
+        print(lesson.start, lesson.subject, lesson.room)
+
+asyncio.run(main())
+```
+
+`client.get_events()` returns upcoming school events (`SchoolEvent`, all-day
+events have `date` start/end with an inclusive end), and `client.get_payments()`
+returns the family's payment totals and requests (`Payments`, amounts as
+`Decimal`). Only paid requests have been seen on a real portal so far; a request
+without the "accepted" marker is reported as unpaid.
+
+`client.fetch_page(name)` returns the raw HTML of a page that has no parser yet
+(`CAPTURE_PAGES`: assignments, exams, inbox, consents), and
+`content_fingerprint(html)` tells you when such a page's content changed.
+
+Persist `session.to_json()` / `Session.from_json()` between runs instead of
+storing the password; use `pyedookit.refresh(session)` to renew the
+short-lived edookit session from the long-lived Plus4U cookie, and fall back
+to `login()` only when `refresh()` raises `AuthError`.
+
+Lesson times are timezone-aware (`pyedookit.PORTAL_TZ`, Europe/Prague).
+
+Errors all derive from `EdookitError`:
+
+| Exception | Meaning | What to do |
+|---|---|---|
+| `SessionExpired` | short-lived edookit session aged out | `refresh()` and retry |
+| `AuthError` | bad credentials, or the Plus4U cookie expired | full `login()` |
+| `EdookitConnectionError` | network error or 30 s timeout | retry later |
+| `ParseError` | portal markup changed | parser needs updating |
+
+`login()`, `refresh()` and `EdookitClient` all accept an optional
+`http: aiohttp.ClientSession` to reuse. Cookies are handled by hand, so
+create that session with `cookie_jar=aiohttp.DummyCookieJar()`; a session
+with a real cookie jar would also store and resend the portal's cookies.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check .
+uv run mypy src
+```
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, then push a `vX.Y.Z` tag. The
+`Publish to PyPI` workflow tests, builds and uploads using PyPI trusted
+publishing, which has to be configured once on pypi.org for this repository
+and the `pypi` environment.

pyedookit-0.3.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyedookit"
+version = "0.3.0"
+description = "Async client for the Edookit parent portal (edookit.net)"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "tomas.liska" }]
+dependencies = [
+    "aiohttp>=3.9",
+    "beautifulsoup4>=4.12",
+    "lxml>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/TFoxik/pyedookit"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyedookit"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "multidict>=6.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]

pyedookit-0.3.0/scripts/capture_fixtures.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Log in to a real Edookit portal and save timetable HTML for inspection.
+
+Run this yourself so credentials never enter the assistant's session:
+
+    ! python scripts/capture_fixtures.py <school-subdomain>
+
+It first discovers this school's Plus4U client_id (scraped from its own
+/user/login page - it's per-school, not shared) without needing a password,
+then prompts for username/password interactively (not via argv, so they
+don't end up in shell history), logs in, and saves:
+
+  captures/timetable_current_week.html
+  captures/timetable_next_week.html
+
+`captures/` is gitignored. These files come from an authenticated session
+and can contain more than student/teacher names - a CSRF token, session
+identifiers, or the parent's e-mail may be echoed into the page. Read the
+printed warning before turning any of this into a committed test fixture.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import getpass
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from pyedookit import auth  # noqa: E402
+from pyedookit.client import EdookitClient  # noqa: E402
+
+CAPTURES_DIR = Path(__file__).resolve().parent.parent / "captures"
+
+
+async def main() -> None:
+    if len(sys.argv) != 2:
+        print("usage: capture_fixtures.py <school-subdomain>", file=sys.stderr)
+        raise SystemExit(2)
+    school = sys.argv[1]
+
+    client_id = await auth.probe_client_id(school)
+    print(f"Discovered Plus4U client_id for {school}: {client_id!r}")
+
+    username = input("Plus4U username/email: ")
+    password = getpass.getpass("Plus4U password: ")
+
+    print(f"Logging in to https://{school}.edookit.net ...")
+    session = await auth.login(school, username, password)
+    print("Login succeeded.")
+
+    client = EdookitClient(session)
+    CAPTURES_DIR.mkdir(parents=True, exist_ok=True)
+
+    weeks = ((0, "timetable_current_week.html"), (1, "timetable_next_week.html"))
+    for week_offset, filename in weeks:
+        html = await client.fetch_timetable_html(week_offset)
+        (CAPTURES_DIR / filename).write_text(html)
+        print(f"Saved {filename}")
+
+    print()
+    print(f"Files were saved to {CAPTURES_DIR}/ (gitignored) rather than tests/fixtures/,")
+    print("because an authenticated page can contain more than names. Before turning any")
+    print("of this into a committed test fixture:")
+    print("  1. Replace real student/teacher/parent names with placeholders.")
+    print("  2. Scrub any CSRF token, session id, or e-mail address you find in the HTML.")
+    print("  3. Confirm the day-column and lesson-entry markup matches the selectors in")
+    print("     src/pyedookit/parsers/timetable.py, and adjust them if the real markup")
+    print("     differs (view page source in a browser to compare class names).")
+    print("  4. Only then copy the relevant snippet into tests/fixtures/ and `git add` it.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pyedookit-0.3.0/src/pyedookit/__init__.py

@@ -0,0 +1,33 @@
+from .auth import login, refresh
+from .client import CAPTURE_PAGES, EdookitClient
+from .exceptions import (
+    AuthError,
+    EdookitConnectionError,
+    EdookitError,
+    ParseError,
+    SessionExpired,
+)
+from .models import PORTAL_TZ, Lesson, PaymentRequest, Payments, SchoolEvent, Student, Term
+from .parsers.fingerprint import content_fingerprint
+from .session import Session
+
+__all__ = [
+    "CAPTURE_PAGES",
+    "PORTAL_TZ",
+    "AuthError",
+    "EdookitClient",
+    "EdookitConnectionError",
+    "EdookitError",
+    "Lesson",
+    "ParseError",
+    "PaymentRequest",
+    "Payments",
+    "SchoolEvent",
+    "Session",
+    "SessionExpired",
+    "Student",
+    "Term",
+    "content_fingerprint",
+    "login",
+    "refresh",
+]