pyedookit 0.3.0__py3-none-any.whl

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",
+]

pyedookit/auth.py

@@ -0,0 +1,385 @@
+from __future__ import annotations
+
+import json as _json
+import re
+import secrets
+from collections.abc import AsyncIterator, Iterable, Mapping
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+import aiohttp
+from yarl import URL
+
+from .exceptions import AuthError, EdookitConnectionError
+from .session import Session
+
+_PLUS4U_OIDC_BASE = (
+    "https://uuidentity.plus4u.net/uu-oidc-maing02/bb977a99f4cc4c37a2afce3fd599d0a7"
+)
+_AUTH_URL = f"{_PLUS4U_OIDC_BASE}/oidc/auth"
+_AUTH_PASSWORD_URL = f"{_PLUS4U_OIDC_BASE}/authPassword/authenticate"
+_REALM_CODE = "uuIdentityPasswordAuthNRealm"
+
+# Confirmed against a real portal: the OIDC client_id is per-school, not a
+# single value shared across every Edookit install (third-party docs this
+# was originally inferred from implied otherwise). Each school's /user/login
+# page embeds it in a small inline JS config block, e.g.
+#   uu_app_oidc_providers_oidcg02_client_id: "983960dcb7b84b34b9aecc5194381d56"
+# so it has to be scraped fresh per school rather than hardcoded.
+_CLIENT_ID_RE = re.compile(
+    r"uu_app_oidc_providers_oidcg02_client_id\s*:\s*['\"]([^'\"]+)['\"]"
+)
+
+_PLUS4U_HOST = "uuidentity.plus4u.net"
+_MAX_REDIRECTS = 5
+
+# A school subdomain becomes part of a URL (redirect_uri, portal base) with
+# no other encoding, so reject anything that isn't a bare hostname label -
+# otherwise a value like "evil.com/" would redirect the OIDC flow off-portal.
+_SCHOOL_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,62}$")
+
+REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})
+
+REQUEST_TIMEOUT = aiohttp.ClientTimeout(total=30)
+
+# Edookit sends the browser back to one of these paths when a session has
+# expired or was never valid; shared with client.py so "did we get logged
+# out" is checked the same way everywhere.
+LOGIN_MARKERS = ("/user/login", "/user/oidc")
+
+
+def is_login_url(url: str) -> bool:
+    return any(marker in url for marker in LOGIN_MARKERS)
+
+
+# Cookies are tracked per host explicitly rather than via aiohttp's
+# CookieJar: the login flow hops between the plus4u.net and edookit.net
+# hosts, and a plain per-host dict is simpler to reason about (and to test)
+# than relying on the jar's own domain-matching for a flow that only ever
+# touches two hosts.
+CookiesByHost = dict[str, dict[str, str]]
+
+
+@dataclass(slots=True)
+class _FetchResult:
+    status: int
+    url: str
+    text: str
+    location: str | None
+    is_redirect: bool
+
+
+def _validate_school(school: str) -> None:
+    if not _SCHOOL_RE.match(school):
+        raise AuthError(f"{school!r} is not a valid Edookit school subdomain")
+
+
+def _school_host(school: str) -> str:
+    return f"{school}.edookit.net"
+
+
+def _school_base(school: str) -> str:
+    return f"https://{_school_host(school)}"
+
+
+def _callback_url(school: str) -> str:
+    return f"{_school_base(school)}/user/oidc-login-callback"
+
+
+def _apply_set_cookies(headers: Iterable[str], jar: dict[str, str]) -> None:
+    """Record Set-Cookie headers into `jar` the way a browser would.
+
+    Parsed by hand instead of via aiohttp's `resp.cookies`: that uses
+    SimpleCookie, which silently drops a whole header when it meets an
+    attribute it doesn't know (e.g. `Partitioned`) or an unquoted space or
+    quote in the value - and that is how Plus4U's long-lived `uoid.ps`
+    cookie was lost, breaking the silent refresh. Values are kept verbatim
+    (quotes included) because that is what gets sent back.
+    """
+    for header in headers:
+        pair, _, attributes = header.partition(";")
+        name, sep, value = pair.partition("=")
+        name = name.strip()
+        if not sep or not name:
+            continue
+        expired = any(
+            attr.strip().lower().replace(" ", "") in ("max-age=0", "max-age=-1")
+            for attr in attributes.split(";")
+        )
+        if expired:
+            jar.pop(name, None)
+        else:
+            jar[name] = value.strip()
+
+
+def _cookie_header(cookies: Mapping[str, str]) -> str:
+    return "; ".join(f"{k}={v}" for k, v in cookies.items())
+
+
+def _auth_params(
+    school: str, client_id: str, state: str, *, prompt_none: bool = False
+) -> dict[str, str]:
+    params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": _callback_url(school),
+        "scope": "openid",
+        "state": state,
+    }
+    if prompt_none:
+        params["prompt"] = "none"
+    return params
+
+
+async def _discover_client_id(
+    http: aiohttp.ClientSession, school: str, cookies_by_host: CookiesByHost
+) -> str:
+    """Scrape the school's own /user/login page for its Plus4U client_id.
+
+    Routed through `_fetch` (not a bare request) so its Set-Cookie response
+    - PHPSESSID etc. - joins the same cookie tracking the rest of the login
+    flow uses, rather than being discarded.
+    """
+    result = await _fetch(http, "GET", f"{_school_base(school)}/user/login", cookies_by_host)
+    match = _CLIENT_ID_RE.search(result.text)
+    if not match:
+        raise AuthError(f"could not find a Plus4U client_id on {school}'s login page")
+    return match.group(1)
+
+
+async def _fetch(
+    http: aiohttp.ClientSession,
+    method: str,
+    url: str,
+    cookies_by_host: CookiesByHost,
+    *,
+    json: dict[str, object] | None = None,
+    params: Mapping[str, str] | None = None,
+    follow_redirects: bool = False,
+) -> _FetchResult:
+    """Make one request (optionally chasing redirects), updating cookies_by_host in place.
+
+    Each hop sends only the cookies stored for that hop's own host, and any
+    Set-Cookie in the response is recorded under that same host - this is
+    what lets the flow move from plus4u.net to <school>.edookit.net without
+    leaking cookies to the wrong domain.
+    """
+    current_url = url
+    current_method = method
+    current_json = json
+    current_params = params
+
+    for _ in range(_MAX_REDIRECTS + 1):
+        host = URL(current_url).host or ""
+        headers: dict[str, str] = {}
+        host_cookies = cookies_by_host.get(host)
+        if host_cookies:
+            headers["Cookie"] = _cookie_header(host_cookies)
+
+        try:
+            async with http.request(
+                current_method,
+                current_url,
+                params=current_params,
+                json=current_json,
+                headers=headers,
+                allow_redirects=False,
+                timeout=REQUEST_TIMEOUT,
+            ) as resp:
+                if set_cookies := resp.headers.getall("Set-Cookie", []):
+                    _apply_set_cookies(set_cookies, cookies_by_host.setdefault(host, {}))
+
+                is_redirect = resp.status in REDIRECT_STATUSES
+                location = resp.headers.get("Location")
+                text = "" if is_redirect else await resp.text()
+                result = _FetchResult(
+                    status=resp.status,
+                    url=str(resp.url),
+                    text=text,
+                    location=location,
+                    is_redirect=is_redirect,
+                )
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise EdookitConnectionError(f"request to {host} failed: {err}") from err
+
+        if not (follow_redirects and is_redirect and location):
+            return result
+
+        current_url = str(URL(current_url).join(URL(location)))
+        current_method = "GET"
+        current_json = None
+        current_params = None
+
+    raise AuthError("too many redirects while following the Plus4U/edookit login flow")
+
+
+def _new_http_session() -> aiohttp.ClientSession:
+    # Cookies are tracked manually in `cookies_by_host`, not via aiohttp's own
+    # jar, so redirect-following never needs a real one; tests replace this
+    # factory with a fake session instead of mocking ClientSession internals.
+    return aiohttp.ClientSession(cookie_jar=aiohttp.DummyCookieJar())
+
+
+@asynccontextmanager
+async def _http_session(http: aiohttp.ClientSession | None) -> AsyncIterator[aiohttp.ClientSession]:
+    if http is not None:
+        yield http
+        return
+    async with _new_http_session() as own:
+        yield own
+
+
+def _session_from_cookies(school: str, cookies_by_host: CookiesByHost) -> Session:
+    edookit_cookies = cookies_by_host.get(_school_host(school), {})
+    plus4u_cookies = cookies_by_host.get(_PLUS4U_HOST, {})
+    if not edookit_cookies.get("PHPSESSID"):
+        raise AuthError("login flow completed but no edookit session cookie was set")
+    return Session(
+        school=school,
+        edookit_cookies=edookit_cookies,
+        plus4u_cookies=plus4u_cookies,
+        csrf_token=edookit_cookies.get("uu.app.csrf", ""),
+    )
+
+
+async def _finish_callback(
+    http: aiohttp.ClientSession,
+    callback_url: str,
+    cookies_by_host: CookiesByHost,
+    school: str,
+) -> Session:
+    """Follow the final OIDC callback redirect chain and build a Session from it.
+
+    Shared tail of login() and refresh(): both end with "GET the code=
+    callback, make sure we didn't land back on the login page, then read the
+    cookies that piled up along the way."
+
+    Confirmed against a real browser trace (HAR): after the callback GET
+    resolves (still 200 on /oidc/callback), the browser makes one more GET
+    to the portal root, which is what actually settles the session server
+    side - skipping it leaves the account looking like it has almost no
+    modules enabled (only the dashboard and badges), even though login
+    itself succeeded and the session cookies are valid.
+    """
+    result = await _fetch(http, "GET", callback_url, cookies_by_host, follow_redirects=True)
+    if is_login_url(result.url):
+        raise AuthError("edookit rejected the Plus4U authorization code")
+    settle = await _fetch(http, "GET", _school_base(school), cookies_by_host, follow_redirects=True)
+    if is_login_url(settle.url):
+        raise AuthError("session did not settle after the OIDC callback")
+    return _session_from_cookies(school, cookies_by_host)
+
+
+async def probe_client_id(school: str) -> str:
+    """Discover a school's Plus4U client_id without logging in.
+
+    Used by scripts/capture_fixtures.py to show what login()/refresh() will
+    use for this school before spending the user's password.
+    """
+    _validate_school(school)
+    cookies_by_host: CookiesByHost = {}
+    async with _new_http_session() as http:
+        return await _discover_client_id(http, school, cookies_by_host)
+
+
+async def login(
+    school: str,
+    username: str,
+    password: str,
+    *,
+    http: aiohttp.ClientSession | None = None,
+) -> Session:
+    """Run the Plus4U OIDC password login and return a usable Session.
+
+    Raises AuthError if the credentials are rejected or the flow's shape has
+    changed (e.g. Edookit or Plus4U altered a redirect), and
+    EdookitConnectionError if either host can't be reached.
+
+    A passed-in `http` session must not keep its own cookies (use
+    `aiohttp.DummyCookieJar()`): cookies are tracked per host by hand here,
+    and a real jar would also collect and resend them.
+    """
+    _validate_school(school)
+    cookies_by_host: CookiesByHost = {}
+    async with _http_session(http) as http:
+        client_id = await _discover_client_id(http, school, cookies_by_host)
+        state = secrets.token_urlsafe(16)
+        step1 = await _fetch(
+            http,
+            "GET",
+            _AUTH_URL,
+            cookies_by_host,
+            params=_auth_params(school, client_id, state),
+        )
+        if not step1.is_redirect or not step1.location:
+            raise AuthError(f"expected a redirect from Plus4U auth endpoint, got {step1.status}")
+        login_url = URL(step1.location)
+        server_state = login_url.query.get("state", state)
+        server_client_id = login_url.query.get("clientId", client_id)
+
+        payload = {
+            "clientId": server_client_id,
+            "state": server_state,
+            "rememberMe": True,
+            "realmCode": _REALM_CODE,
+            "username": username,
+            "password": password,
+        }
+        step2 = await _fetch(http, "POST", _AUTH_PASSWORD_URL, cookies_by_host, json=payload)
+        if step2.status in (400, 401):
+            raise AuthError("Plus4U rejected the username or password")
+        continue_url = step2.location
+        if not continue_url and step2.text:
+            try:
+                body = _json.loads(step2.text)
+            except ValueError:
+                body = None
+            if isinstance(body, dict):
+                continue_url = body.get("redirectUrl")
+        if not continue_url:
+            raise AuthError("Plus4U password auth did not return a continuation URL")
+
+        step3 = await _fetch(http, "GET", continue_url, cookies_by_host)
+        if not step3.location or "code=" not in step3.location:
+            raise AuthError("Plus4U did not return an authorization code")
+
+        return await _finish_callback(http, step3.location, cookies_by_host, school)
+
+
+async def refresh(session: Session, *, http: aiohttp.ClientSession | None = None) -> Session:
+    """Obtain a fresh edookit session using the stored Plus4U cookies.
+
+    No password is needed; this is what keeps a long-running Home Assistant
+    integration logged in across the ~30-60 minute edookit session lifetime.
+    Raises AuthError if the Plus4U cookies have themselves expired (roughly
+    every 19 days), which means a full `login()` with the password is needed.
+    `http` has the same cookie-jar requirement as in `login()`.
+    """
+    _validate_school(session.school)
+    # Only the Plus4U cookies: the portal answers /user/login with a redirect
+    # to /oidc/logout when it sees the expired edookit session, so the new
+    # edookit session is built from scratch, exactly like in login().
+    cookies_by_host: CookiesByHost = {_PLUS4U_HOST: dict(session.plus4u_cookies)}
+    async with _http_session(http) as http:
+        client_id = await _discover_client_id(http, session.school, cookies_by_host)
+        state = secrets.token_urlsafe(16)
+        step1 = await _fetch(
+            http,
+            "GET",
+            _AUTH_URL,
+            cookies_by_host,
+            params=_auth_params(session.school, client_id, state, prompt_none=True),
+        )
+        if not step1.is_redirect or not step1.location or "code=" not in step1.location:
+            raise AuthError("Plus4U session expired; full login required")
+
+        return await _finish_callback(http, step1.location, cookies_by_host, session.school)
+
+
+def build_headers(session: Session) -> dict[str, str]:
+    """Cookie/CSRF headers for a plain page request against the school's portal."""
+    return {
+        "Cookie": _cookie_header(session.edookit_cookies),
+        "X-CSRF-Token": session.csrf_token,
+        "X-Requested-With": "XMLHttpRequest",
+    }

pyedookit/client.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import aiohttp
+
+from . import auth
+from .exceptions import EdookitConnectionError, SessionExpired
+from .models import Lesson, Payments, SchoolEvent, Term
+from .parsers.events import parse_events
+from .parsers.payments import parse_payments
+from .parsers.timetable import parse_terms, parse_timetable
+from .session import Session
+
+_TIMETABLE_PATH = "/timetable/"
+_EVENTS_PATH = "/timetable/upcoming"
+_PAYMENTS_PATH = "/payments/"
+
+CAPTURE_PAGES: dict[str, str] = {
+    "assignments": "/assignments/",
+    "exams": "/exams/",
+    "inbox": "/overview/updates",
+    "consents": "/consents/",
+}
+
+
+class EdookitClient:
+    """Fetches parsed data from one school's Edookit parent portal.
+
+    Holds a `Session` that the caller is responsible for persisting and
+    refreshing (see `pyedookit.auth.refresh`); this class only detects when
+    the current session has gone stale and raises `SessionExpired` so the
+    caller can refresh and retry.
+
+    Pass `http` to reuse an existing `aiohttp.ClientSession` across requests
+    instead of opening a new connection per call; otherwise one is created
+    and closed per request. Cookies are sent by hand, so give it a
+    `aiohttp.DummyCookieJar()` rather than a shared session whose jar would
+    also collect the portal's cookies.
+    """
+
+    def __init__(self, session: Session, http: aiohttp.ClientSession | None = None) -> None:
+        self._session = session
+        self._http = http
+
+    @property
+    def session(self) -> Session:
+        return self._session
+
+    async def get_terms(self) -> list[Term]:
+        html = await self.fetch_timetable_html()
+        return parse_terms(html)
+
+    async def get_timetable(self, week_offset: int = 0) -> list[Lesson]:
+        html = await self.fetch_timetable_html(week_offset)
+        return parse_timetable(html)
+
+    async def fetch_timetable_html(self, week_offset: int = 0) -> str:
+        """Raw `/timetable/` HTML for one week - also used by
+        scripts/capture_fixtures.py, so the request shape lives in one place."""
+        return await self._get(_TIMETABLE_PATH, params={"familyTimetable-value": week_offset})
+
+    async def get_events(self) -> list[SchoolEvent]:
+        return parse_events(await self._get(_EVENTS_PATH))
+
+    async def get_payments(self) -> Payments:
+        return parse_payments(await self._get(_PAYMENTS_PATH))
+
+    async def fetch_page(self, name: str) -> str:
+        """Raw HTML of one of `CAPTURE_PAGES`, for pages without a parser yet."""
+        try:
+            path = CAPTURE_PAGES[name]
+        except KeyError:
+            raise ValueError(f"{name!r} is not one of {sorted(CAPTURE_PAGES)}") from None
+        return await self._get(path)
+
+    async def _get(self, path: str, params: dict[str, int] | None = None) -> str:
+        url = f"{self._session.base_url}{path}"
+        headers = auth.build_headers(self._session)
+        if self._http is not None:
+            return await self._request(self._http, url, params, headers)
+        async with aiohttp.ClientSession() as http:
+            return await self._request(http, url, params, headers)
+
+    async def _request(
+        self,
+        http: aiohttp.ClientSession,
+        url: str,
+        params: dict[str, int] | None,
+        headers: dict[str, str],
+    ) -> str:
+        # allow_redirects=False: our Cookie/CSRF headers are set manually, and
+        # older aiohttp forwards a manually-set Cookie header to a redirect's
+        # target even when that target is a different host - so an expired
+        # session's redirect to Plus4U must never be followed with them
+        # attached. Any redirect at all means the session isn't good anymore.
+        try:
+            async with http.get(
+                url,
+                params=params,
+                headers=headers,
+                allow_redirects=False,
+                timeout=auth.REQUEST_TIMEOUT,
+            ) as resp:
+                if resp.status in auth.REDIRECT_STATUSES or auth.is_login_url(str(resp.url)):
+                    raise SessionExpired("edookit session has expired")
+                return await resp.text()
+        except (aiohttp.ClientError, TimeoutError) as err:
+            raise EdookitConnectionError(f"request to {url} failed: {err}") from err

pyedookit/exceptions.py

@@ -0,0 +1,22 @@
+class EdookitError(Exception):
+    """Base error for all pyedookit failures."""
+
+
+class AuthError(EdookitError):
+    """Credentials were rejected, or the long-lived Plus4U session expired."""
+
+
+class SessionExpired(EdookitError):
+    """The short-lived edookit session cookie expired; caller should refresh and retry."""
+
+
+class ParseError(EdookitError):
+    """A portal page did not have the expected structure.
+
+    Edookit's markup isn't versioned, so this is the signal a parser needs updating
+    rather than a bug in the caller's usage.
+    """
+
+
+class EdookitConnectionError(EdookitError):
+    """The portal or Plus4U could not be reached (network error or timeout)."""

pyedookit/models.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from decimal import Decimal
+from zoneinfo import ZoneInfo
+
+# The portal renders wall-clock times with no zone; every Edookit school is
+# Czech, so parsed times are pinned to Prague rather than left naive.
+PORTAL_TZ = ZoneInfo("Europe/Prague")
+
+
+@dataclass(frozen=True, slots=True)
+class Lesson:
+    start: datetime
+    end: datetime
+    subject: str
+    teacher: str | None = None
+    room: str | None = None
+    group: str | None = None
+    is_changed: bool = False
+    is_cancelled: bool = False
+    note: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Term:
+    id: str
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class Student:
+    id: str
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class SchoolEvent:
+    id: str
+    title: str
+    start: datetime | date
+    end: datetime | date
+    description: str | None = None
+    created_by: str | None = None
+
+    @property
+    def all_day(self) -> bool:
+        return not isinstance(self.start, datetime)
+
+
+@dataclass(frozen=True, slots=True)
+class PaymentRequest:
+    title: str
+    amount: Decimal
+    currency: str
+    is_paid: bool
+
+
+@dataclass(frozen=True, slots=True)
+class Payments:
+    paid: Decimal
+    remaining: Decimal
+    overpaid: Decimal
+    currency: str
+    requests: list[PaymentRequest]

pyedookit/parsers/dates.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import re
+from datetime import date, timedelta
+
+# The portal writes the year only when it isn't the current one, and uses a
+# word instead of a date for recent days ("Dnes , 8:00 – 8:45"; Včera/Dnes
+# confirmed, Zítra assumed).
+_RELATIVE_DAYS = {"včera": -1, "dnes": 0, "zítra": 1}
+_DAY_RE = re.compile(
+    r"(?P<relative>včera|dnes|zítra)\b"
+    r"|(?P<day>\d{1,2})\.\s*(?P<month>\d{1,2})\.(?:\s*(?P<year>\d{4}))?",
+    re.IGNORECASE,
+)
+TIME_RE = re.compile(r"(\d{1,2}):(\d{2})")
+
+
+def find_days(text: str, today: date) -> list[date]:
+    days: list[date] = []
+    for match in _DAY_RE.finditer(text):
+        if relative := match.group("relative"):
+            days.append(today + timedelta(days=_RELATIVE_DAYS[relative.lower()]))
+            continue
+        year = int(match.group("year")) if match.group("year") else today.year
+        try:
+            days.append(date(year, int(match.group("month")), int(match.group("day"))))
+        except ValueError:
+            continue
+    return days

pyedookit/parsers/events.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import logging
+import re
+from datetime import date, datetime, time
+
+from bs4 import BeautifulSoup, Tag
+
+from ..exceptions import ParseError
+from ..models import PORTAL_TZ, SchoolEvent
+from .dates import TIME_RE, find_days
+
+_EVENT_ID_RE = re.compile(r"event=(\d+)")
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def parse_events(html: str, today: date | None = None) -> list[SchoolEvent]:
+    """Parse `/timetable/upcoming` ("Mé budoucí události").
+
+    Confirmed against a real capture: one `ul.table_row` per event inside
+    `div.events_table`, after a `gridLabel` header row that shares the class.
+    Only a timed event on a single day, or an all-day event over one or more
+    days, has been seen; anything else is skipped with a warning.
+    """
+    soup = BeautifulSoup(html, "lxml")
+    if soup.select_one("section.content") is None:
+        raise ParseError("upcoming events page has no content section")
+    if today is None:
+        today = datetime.now(PORTAL_TZ).date()
+
+    events: list[SchoolEvent] = []
+    for row in soup.select("div.events_table ul.table_row"):
+        if "gridLabel" in (row.get("class") or []):
+            continue
+        event = _parse_row(row, today)
+        if event is None:
+            _LOGGER.warning("skipping unparseable event row %s", _event_id(row) or "?")
+        else:
+            events.append(event)
+    return events
+
+
+def _event_id(row: Tag) -> str | None:
+    link = row.select_one("li.c2 a[href]")
+    match = _EVENT_ID_RE.search(str(link.get("href"))) if link else None
+    return match.group(1) if match else None
+
+
+def _parse_row(row: Tag, today: date) -> SchoolEvent | None:
+    event_id = _event_id(row)
+    when = row.select_one("li.c1 b")
+    title = row.select_one("li.c2 div.bold")
+    if event_id is None or when is None or title is None:
+        return None
+
+    text = " ".join(when.get_text(" ", strip=True).split())
+    days = find_days(text, today)
+    times = [time(int(h), int(m)) for h, m in TIME_RE.findall(text)]
+    if not days:
+        return None
+
+    start: datetime | date
+    end: datetime | date
+    if times:
+        if len(days) != 1 or len(times) != 2:
+            return None
+        start = datetime.combine(days[0], times[0], tzinfo=PORTAL_TZ)
+        end = datetime.combine(days[0], times[1], tzinfo=PORTAL_TZ)
+    else:
+        start, end = days[0], days[-1]
+
+    description = " ".join(
+        p.get_text(" ", strip=True) for p in row.select("li.c2 > p") if p.get_text(strip=True)
+    )
+    creator = row.select_one("li.c3 div.smaller p b")
+    return SchoolEvent(
+        id=event_id,
+        title=title.get_text(" ", strip=True),
+        start=start,
+        end=end,
+        description=description or None,
+        created_by=creator.get_text(strip=True) if creator else None,
+    )

pyedookit/parsers/fingerprint.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import hashlib
+import re
+
+from bs4 import BeautifulSoup
+
+_NUMBER_RE = re.compile(r"\d+")
+
+
+def content_fingerprint(html: str) -> str | None:
+    """Hash of a page's visible content, stable across counters and timestamps.
+
+    Used to notice when a page that has only ever been empty gets real items.
+    It can't rely on empty-state text disappearing, because some pages keep
+    their hidden "no data" block in the HTML even when items exist. Returns
+    None for error and maintenance pages, which lack the portal's content
+    section and must not count as a change.
+    """
+    root = BeautifulSoup(html, "lxml").select_one("section.content")
+    if root is None:
+        return None
+    for tag in root.select("script, style"):
+        tag.decompose()
+    text = " ".join(root.get_text(" ", strip=True).split())
+    return hashlib.sha256(_NUMBER_RE.sub("#", text).encode()).hexdigest()

pyedookit/parsers/payments.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import logging
+import re
+from decimal import Decimal
+
+from bs4 import BeautifulSoup, Tag
+
+from ..exceptions import ParseError
+from ..models import PaymentRequest, Payments
+
+_AMOUNT_RE = re.compile(r"(-?\d[\d\s ]*(?:,\d+)?)\s*(\S+)?")
+_CURRENCIES = {"Kč": "CZK", "CZK": "CZK", "€": "EUR", "EUR": "EUR"}
+_DEFAULT_CURRENCY = "CZK"
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def parse_amount(text: str) -> tuple[Decimal, str | None]:
+    match = _AMOUNT_RE.search(text)
+    if match is None:
+        raise ParseError(f"no amount in {text!r}")
+    number = re.sub(r"[\s ]", "", match.group(1)).replace(",", ".")
+    return Decimal(number), _CURRENCIES.get(match.group(2) or "")
+
+
+def parse_payments(html: str) -> Payments:
+    """Parse `/payments/` ("Platby") for the whole family.
+
+    Totals come from the `Everyone` spans because the portal bills parents
+    as well as the child. Only paid requests (`div.accepted`) have been seen
+    on a real portal, so every other request counts as unpaid and the
+    summary's "remaining" total stays the authoritative number.
+    """
+    soup = BeautifulSoup(html, "lxml")
+    summary = soup.select_one("table.payments-summary.desktop") or soup.select_one(
+        "table.payments-summary"
+    )
+    if summary is None:
+        raise ParseError("no payments summary table found")
+
+    paid, currency = _total(summary, "td.paid span.sumsEveryone")
+    remaining, _ = _total(summary, "td.remaining span.sumsEveryone")
+    overpaid, _ = _total(summary, "td.overpaymentEveryone span")
+
+    requests: list[PaymentRequest] = []
+    for item in soup.select("div.item.prescriptionEveryone"):
+        request = _parse_request(item, currency)
+        if request is None:
+            _LOGGER.warning("skipping unparseable payment request")
+        else:
+            requests.append(request)
+    return Payments(
+        paid=paid, remaining=remaining, overpaid=overpaid, currency=currency, requests=requests
+    )
+
+
+def _total(summary: Tag, selector: str) -> tuple[Decimal, str]:
+    cell = summary.select_one(selector)
+    if cell is None:
+        raise ParseError(f"payments summary has no {selector}")
+    amount, currency = parse_amount(cell.get_text(" ", strip=True))
+    return amount, currency or _DEFAULT_CURRENCY
+
+
+def _parse_request(item: Tag, default_currency: str) -> PaymentRequest | None:
+    title = item.select_one("div.heading div.text")
+    amount_cell = item.select_one("div.column.c4.desktop div.amount") or item.select_one(
+        "div.amount"
+    )
+    if title is None or amount_cell is None:
+        return None
+    try:
+        amount, currency = parse_amount(amount_cell.get_text(" ", strip=True))
+    except ParseError:
+        return None
+    return PaymentRequest(
+        title=title.get_text(" ", strip=True),
+        amount=amount,
+        currency=currency or default_currency,
+        is_paid=item.select_one("div.status-icon div.accepted") is not None,
+    )

pyedookit/parsers/timetable.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import logging
+import re
+from datetime import date, datetime, time
+
+from bs4 import BeautifulSoup, Tag
+
+from ..exceptions import ParseError
+from ..models import PORTAL_TZ, Lesson, Term
+from .dates import find_days
+
+_TIME_RANGE_RE = re.compile(r"(\d{1,2}):(\d{2})\s*[-–]\s*(\d{1,2}):(\d{2})")
+_TERM_ID_RE = re.compile(r"termSelector-new=(\d+)")
+_NOTE_PREFIX = "Učivo:"
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def parse_timetable(html: str, today: date | None = None) -> list[Lesson]:
+    """Parse the hidden `.lesson-info` detail blocks on a rendered `/timetable/` page.
+
+    Confirmed against a real portal capture: the *visible* week grid is an
+    absolutely-positioned canvas of `<a class="... lesson ...">` tiles with
+    no semantic day/time markup at all (position is encoded as inline CSS
+    percentages). Each lesson also gets a hidden
+    `<div class="lesson-info" id="lesson-info-{id}">` block, though, with a
+    fixed field order and a full date+time already inside it - parsing those
+    is far more reliable than reading positions off the canvas, and doesn't
+    need a day-column or week_start argument at all since each block already
+    carries its own date.
+
+    Yesterday's and today's lessons carry "Včera"/"Dnes" instead of a date;
+    those resolve against `today`, which defaults to the current date in
+    `PORTAL_TZ`.
+
+    Cancelled/substituted lessons could not be confirmed: the captured week
+    had none, so `is_changed`/`is_cancelled` are always False for now. Fix
+    once a real capture has one - see the parser test file for the exact gap.
+    """
+    soup = BeautifulSoup(html, "lxml")
+    blocks = soup.select("div.lesson-info")
+    if not blocks:
+        raise ParseError("no lesson-info blocks found on timetable page")
+
+    if today is None:
+        today = datetime.now(PORTAL_TZ).date()
+    lessons = []
+    for block in blocks:
+        lesson = _parse_lesson_info(block, today)
+        if lesson is None:
+            _LOGGER.warning("skipping unparseable lesson block %s", block.get("id"))
+        else:
+            lessons.append(lesson)
+    return lessons
+
+
+def parse_terms(html: str) -> list[Term]:
+    soup = BeautifulSoup(html, "lxml")
+    terms: list[Term] = []
+    seen: set[str] = set()
+    for link in soup.select('a[href*="termSelector-new"]'):
+        href = str(link.get("href") or "")
+        match = _TERM_ID_RE.search(href)
+        if not match:
+            continue
+        term_id = match.group(1)
+        if term_id in seen:
+            continue
+        seen.add(term_id)
+        terms.append(Term(id=term_id, name=link.get_text(strip=True)))
+    return terms
+
+
+def _parse_lesson_info(block: Tag, today: date) -> Lesson | None:
+    fields = block.find_all("div", recursive=False)
+    datetime_div = next((f for f in fields if f.select_one(".date_time")), None)
+    if datetime_div is None:
+        return None
+
+    text = datetime_div.get_text(" ", strip=True)
+    days = find_days(text, today)
+    lesson_date = days[0] if days else None
+    time_match = _TIME_RANGE_RE.search(text)
+    if lesson_date is None or not time_match:
+        return None
+    sh, sm, eh, em = (int(g) for g in time_match.groups())
+
+    # Field order after the date/time div is fixed on every lesson observed:
+    # "{code} - {group}", full subject name, teacher(s), room, curriculum
+    # notes (last one is sometimes absent).
+    rest = [f for f in fields if f is not datetime_div]
+    code_group = rest[0].get_text(strip=True) if len(rest) > 0 else ""
+    subject = rest[1].get_text(strip=True) if len(rest) > 1 else code_group
+    teacher = rest[2].get_text(strip=True) if len(rest) > 2 else None
+    room = rest[3].get_text(strip=True) if len(rest) > 3 else None
+
+    note = None
+    if len(rest) > 4:
+        note_text = rest[4].get_text(" ", strip=True)
+        if note_text.startswith(_NOTE_PREFIX):
+            note = note_text[len(_NOTE_PREFIX) :].strip() or None
+
+    _, _, group = code_group.partition(" - ")
+
+    return Lesson(
+        start=datetime.combine(lesson_date, time(sh, sm), tzinfo=PORTAL_TZ),
+        end=datetime.combine(lesson_date, time(eh, em), tzinfo=PORTAL_TZ),
+        subject=subject or code_group,
+        teacher=teacher or None,
+        room=room or None,
+        group=group or None,
+        note=note,
+    )

pyedookit/session.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime, timedelta
+
+
+@dataclass(slots=True)
+class Session:
+    """Everything needed to talk to a school's portal without the password.
+
+    `edookit_cookies` is short-lived (expires in roughly 30-60 minutes).
+    `plus4u_cookies` is long-lived (roughly 19 days) and is what `refresh()`
+    uses to obtain a fresh edookit session silently. The password itself is
+    never stored here.
+    """
+
+    school: str
+    edookit_cookies: dict[str, str]
+    plus4u_cookies: dict[str, str]
+    csrf_token: str
+    edookit_expires_at: datetime = field(
+        default_factory=lambda: datetime.now(UTC) + timedelta(minutes=30)
+    )
+
+    @property
+    def base_url(self) -> str:
+        return f"https://{self.school}.edookit.net"
+
+    @property
+    def is_edookit_expired(self) -> bool:
+        """True once the session is expected to have aged out.
+
+        A conservative estimate (login/refresh don't know the portal's real
+        TTL), meant for a caller to refresh proactively before it bothers
+        making a request that's likely to just be redirected to the login
+        page - not a substitute for handling `SessionExpired` reactively too.
+        """
+        return datetime.now(UTC) >= self.edookit_expires_at
+
+    def to_json(self) -> str:
+        data = asdict(self)
+        data["edookit_expires_at"] = self.edookit_expires_at.isoformat()
+        return json.dumps(data)
+
+    @classmethod
+    def from_json(cls, raw: str) -> Session:
+        data = json.loads(raw)
+        data["edookit_expires_at"] = datetime.fromisoformat(data["edookit_expires_at"])
+        return cls(**data)

pyedookit-0.3.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+pyedookit/__init__.py,sha256=OJz_k3hKcHqzUgD-XiqcPoVyaHWGn_oKivy8xyyxF0s,730
+pyedookit/auth.py,sha256=3guqbDtrIVmF02sCVDx7rNcOBYOtpynZpNoVgElRBFw,14712
+pyedookit/client.py,sha256=v6Y_5Pt1JRf1zNrGzctTop6wmUwjko91Y5wtDLTVo9Q,4278
+pyedookit/exceptions.py,sha256=PgNJQ4-4OWDM-fUpzJPmvOmWsRUbUtZsWqDWV0iGO9Y,677
+pyedookit/models.py,sha256=kr2xDLhAAhP8wvTPpdZoa8G3KOu0bmL6oQOeUzakEJI,1391
+pyedookit/session.py,sha256=HzspoMGQnRNXge1XmGYoqgb3qPTSF2gwENVpBBS_EFg,1713
+pyedookit/parsers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyedookit/parsers/dates.py,sha256=A0v4FJrUnLTqkkzZX8Xy0OAZmjKB3SBYD6biCx-QGyw,1043
+pyedookit/parsers/events.py,sha256=Qx-L6vLm8D08whKB3xNRuPHjOL1hsTp4FsEqUiKZoQg,2816
+pyedookit/parsers/fingerprint.py,sha256=YvMs7Eeeb6JiNuPeFagFovxehtA_rzG4esh6TejvJe8,927
+pyedookit/parsers/payments.py,sha256=qW4DS-I4dXmmHPRz8wnbCeulWoRAtrO9BB_mtYAbTE0,2961
+pyedookit/parsers/timetable.py,sha256=OxIS18OzHBLgIITL3R11FYqQD50KZ30Rzh5xEzFa5Qk,4324
+pyedookit-0.3.0.dist-info/METADATA,sha256=fwlZpGqoXifd0d_hp4XnbP5Yh2dZ3Ahxjs-xA01i854,4221
+pyedookit-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pyedookit-0.3.0.dist-info/licenses/LICENSE,sha256=o2p-_Uzf9isg79dSi8fdeTa14Gl1OUe7j59D24Q-L_U,1068
+pyedookit-0.3.0.dist-info/RECORD,,

pyedookit-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pyedookit-0.3.0.dist-info/licenses/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.