librus-python-api 1.0.0rc1__py3-none-any.whl

librus_python_api/attachments.py

@@ -0,0 +1,297 @@
+"""Single-owner attachment streams with joined, service-owned resource lifetimes."""
+
+import asyncio
+import time
+from collections.abc import AsyncIterator
+from types import TracebackType
+from typing import TYPE_CHECKING, Literal, Self
+
+from librus_python_api.attachment_routes import (
+    modern_attachment_key,
+    signed_attachment_key,
+    validate_attachment_reference,
+    validate_max_bytes,
+    validate_modern_attachment_reference,
+)
+from librus_python_api.budget import RequestBudget
+from librus_python_api.config import ATTACHMENT_MAX_BYTES
+from librus_python_api.exceptions import ErrorKind, LibrusError, SessionExpiredError
+from librus_python_api.lifecycle import join_owned
+from librus_python_api.models import (
+    AttachmentHeaders,
+    AttachmentMetadata,
+    DiagnosticEvent,
+    MessageAttachmentReference,
+    ModernMessageAttachmentReference,
+    OperationName,
+)
+
+if TYPE_CHECKING:
+    from librus_python_api.service import AccountClient
+
+
+class AttachmentStream(AsyncIterator[bytes]):
+    """Use with async with. Uncached, non-reentrant and consumed by one task.
+
+    Construction has no I/O. The owned worker holds shared admission until EOF,
+    close or failure, even when the consumer is paused. No filesystem writes.
+    """
+
+    _operation: OperationName = "attachment_download"
+
+    def __init__(
+        self,
+        client: "AccountClient",
+        reference: MessageAttachmentReference | ModernMessageAttachmentReference,
+        *,
+        max_bytes: int = ATTACHMENT_MAX_BYTES,
+        budget: RequestBudget | None = None,
+    ) -> None:
+        self._validate_reference(reference, client._alias)
+        validate_max_bytes(max_bytes)
+        if budget is not None and not isinstance(budget, RequestBudget):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        self._client, self._reference = client, reference
+        self._max_bytes, self._budget = max_bytes, budget
+        self._task: asyncio.Task[None] | None = None
+        self._metadata: AttachmentMetadata | None = None
+        self._ready, self._demand, self._delivery = (asyncio.Event() for _ in range(3))
+        self._chunk: bytes | None = None
+        self._error: ErrorKind | None = None
+        self._consumer: asyncio.Task[object] | None = None
+        self._entered = self._closed = self._complete = self._reading = (
+            self._admitted
+        ) = False
+
+    @property
+    def metadata(self) -> AttachmentMetadata:
+        if self._metadata is None:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        return self._metadata
+
+    @staticmethod
+    def _validate_reference(
+        reference: MessageAttachmentReference | ModernMessageAttachmentReference,
+        account: str,
+    ) -> None:
+        if not isinstance(reference, MessageAttachmentReference):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        validate_attachment_reference(reference, account)
+
+    @property
+    def complete(self) -> bool:
+        return self._complete
+
+    async def __aenter__(self) -> Self:
+        if self._entered or self._closed:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        client, service = self._client, self._client._service
+        service._bind()
+        budget = self._budget or service._budget()
+        budget._bind_loop()
+        budget.remaining_seconds()
+        client._admit_operation()
+        self._entered = self._admitted = True
+        self._task = asyncio.create_task(self._run(budget))
+        service._tasks.add(self._task)
+        self._task.add_done_callback(self._finished)
+        try:
+            await self._ready.wait()
+            self._raise_failure()
+            return self
+        except BaseException:
+            await self.aclose()
+            raise
+
+    def __aiter__(self) -> Self:
+        return self
+
+    async def __anext__(self) -> bytes:
+        if not self._entered or self._closed:
+            raise LibrusError(ErrorKind.CLOSED)
+        consumer = asyncio.current_task()
+        if self._reading or (
+            self._consumer is not None and self._consumer is not consumer
+        ):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        self._consumer = consumer
+        self._reading = True
+        try:
+            self._raise_failure()
+            if self._complete:
+                raise StopAsyncIteration
+            self._demand.set()
+            await self._delivery.wait()
+            self._delivery.clear()
+            self._raise_failure()
+            if self._chunk is None:
+                assert self._task is not None
+                await join_owned(self._task)
+                self._raise_failure()
+                assert self._complete
+                raise StopAsyncIteration
+            chunk, self._chunk = self._chunk, None
+            return chunk
+        except asyncio.CancelledError:
+            await self.aclose()
+            raise
+        finally:
+            self._reading = False
+
+    def _raise_failure(self) -> None:
+        if self._error is not None:
+            raise LibrusError(self._error)
+
+    def _opened(self, headers: AttachmentHeaders) -> None:
+        self._metadata = AttachmentMetadata(
+            self._client._session_identity(),
+            self._reference,
+            headers,
+            self._client._observation(self._operation),
+        )
+        self._ready.set()
+
+    async def _pull(self) -> None:
+        async with asyncio.timeout(
+            self._client._service._transport_limits.attachment_idle_timeout_seconds
+        ):
+            await self._demand.wait()
+        self._demand.clear()
+
+    def _deliver(self, chunk: bytes) -> None:
+        assert self._chunk is None
+        self._chunk = chunk
+        self._delivery.set()
+
+    async def _fetch(self, budget: RequestBudget, _: bool) -> None:
+        client = self._client
+        assert isinstance(self._reference, MessageAttachmentReference)
+        response = await client._transport.resolve_attachment(self._reference, budget)
+        if response.status == 302 and client._is_login_redirect(response):
+            raise LibrusError(ErrorKind.SESSION_EXPIRED)
+        if response.status != 302:
+            raise LibrusError(ErrorKind.PARSE)
+        key = signed_attachment_key(
+            response.headers.get("location", ""), client._service._connection
+        )
+        await client._transport.stream_download(
+            key, budget, self._max_bytes, self._opened, self._pull, self._deliver
+        )
+
+    async def _run(self, budget: RequestBudget) -> None:
+        client = self._client
+        started = time.monotonic()
+        outcome: ErrorKind | Literal["ok", "cancelled"] = "ok"
+        try:
+            async with asyncio.timeout(budget.remaining_seconds()):
+                async with client._lock:
+                    client._check_cooldown("authentication")
+                    client._check_cooldown(self._operation)
+                    await client._authenticated(self._fetch, budget, False)
+            self._complete = True
+        except LibrusError as error:
+            self._error = outcome = error.kind
+            if error.kind in (ErrorKind.ACCESS_DENIED, ErrorKind.SESSION_EXPIRED):
+                client._cooldowns[self._operation] = (
+                    time.monotonic()
+                    + client._service._transport_limits.cooldown_seconds,
+                    error.kind,
+                )
+        except TimeoutError:
+            self._error = outcome = ErrorKind.TIMEOUT
+        except asyncio.CancelledError:
+            self._error = ErrorKind.CLOSED
+            outcome = "cancelled"
+        except Exception:
+            # Never attach URL-bearing exceptions from a custom transport.
+            self._error = outcome = ErrorKind.CONNECTION
+        finally:
+            if self._error is not None:
+                self._chunk = None
+            self._release()
+            self._ready.set()
+            self._delivery.set()
+            client._emit(
+                DiagnosticEvent(
+                    self._operation,
+                    outcome,
+                    time.monotonic() - started,
+                    budget.requests_dispatched,
+                    budget.response_bytes,
+                )
+            )
+
+    def _release(self) -> None:
+        if self._admitted:
+            self._admitted = False
+            self._client._release_operation()
+
+    def _finished(self, task: asyncio.Task[None]) -> None:
+        self._client._service._tasks.discard(task)
+        # Cancellation can happen before the worker's first instruction.
+        self._release()
+        if task.cancelled():
+            self._error = ErrorKind.CLOSED
+        self._ready.set()
+        self._delivery.set()
+
+    async def aclose(self) -> None:
+        self._closed = True
+        self._chunk = None
+        if self._task is not None:
+            if not self._task.done() and not self._task.cancelling():
+                self._task.cancel()
+            if await join_owned(self._task):
+                raise asyncio.CancelledError
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+
+class ModernAttachmentStream(AttachmentStream):
+    """Explicit modern resolution with the shared credential-free download worker."""
+
+    _operation: OperationName = "modern_attachment_download"
+
+    @staticmethod
+    def _validate_reference(
+        reference: MessageAttachmentReference | ModernMessageAttachmentReference,
+        account: str,
+    ) -> None:
+        if not isinstance(reference, ModernMessageAttachmentReference):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        validate_modern_attachment_reference(reference, account)
+
+    async def _fetch(self, budget: RequestBudget, _: bool) -> None:
+        client = self._client
+        assert isinstance(self._reference, ModernMessageAttachmentReference)
+        resolver = getattr(client._transport, "resolve_modern_attachment", None)
+        if not callable(resolver):
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+        await client._modern_ready(budget)
+        try:
+            response = await resolver(self._reference, budget)
+            client._validate_read_response(response, "application/json")
+            key = await client._service._parsers.run(
+                lambda body: modern_attachment_key(body, client._service._connection),
+                response.body,
+                budget,
+            )
+        except BaseException as error:
+            client._invalidate_modern()
+            if isinstance(error, SessionExpiredError):
+                error._messages_origin = True
+            raise
+        await client._transport.stream_download(
+            key,
+            budget,
+            self._max_bytes,
+            self._opened,
+            self._pull,
+            self._deliver,
+        )

librus_python_api/attendance.py

@@ -0,0 +1,182 @@
+"""Original bounded attendance HTML parser from source-informed requirements."""
+
+import re
+from typing import Literal, cast
+
+from lxml import html
+
+from librus_python_api import markup
+from librus_python_api.config import (
+    ATTENDANCE_DETAIL_MAX_FIELDS,
+    ATTENDANCE_EMPTY_MARKERS,
+    ATTENDANCE_MAX_RECORDS,
+    ATTENDANCE_SEMESTER_LABELS,
+    GRADE_MAX_METADATA_LENGTH,
+    GRADE_MAX_VALUE_LENGTH,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import (
+    AttendanceDetailContent,
+    AttendanceRecord,
+    AttendanceRecords,
+)
+from librus_python_api.parsers import parse_page
+
+
+def _entry(element: html.HtmlElement, semester: Literal[1, 2]) -> AttendanceRecord:
+    # Some source-informed tooltips separate complete bold label/value blocks
+    # without BR tags. Retain the closing tags while adding field boundaries.
+    title = element.get("title", "")
+    if len(title) > GRADE_MAX_METADATA_LENGTH:
+        raise LibrusError(ErrorKind.LIMIT)
+    holder = html.Element("span")
+    holder.set("title", re.sub(r"</b>\s*(?=<b[ >])", "</b>\n", title, flags=re.I))
+    fields = markup.tooltip_fields(holder)
+    if any(
+        max(len(key), len(value)) > GRADE_MAX_VALUE_LENGTH
+        for key, value in fields.items()
+    ):
+        raise LibrusError(ErrorKind.LIMIT)
+    period = fields.get("Godzina lekcyjna")
+    if period is not None and not re.fullmatch(r"[0-9]{1,2}", period):
+        raise LibrusError(ErrorKind.PARSE)
+    excursion = fields.get("Czy wycieczka")
+    if excursion is not None and excursion.casefold() not in ("tak", "nie"):
+        raise LibrusError(ErrorKind.PARSE)
+    symbol = markup.text(element)
+    if not symbol:
+        raise LibrusError(ErrorKind.PARSE)
+    return AttendanceRecord(
+        symbol,
+        markup.civil_date(fields.get("Data")),
+        semester,
+        fields.get("Rodzaj"),
+        fields.get("Nauczyciel"),
+        None if period is None else int(period),
+        None if excursion is None else excursion.casefold() == "tak",
+        fields.get("Temat zajęć"),
+        fields.get("Lekcja"),
+        markup.attendance_detail_id(element),
+        tuple(fields.items()),
+    )
+
+
+def _plain_cell_is_layout(cell: html.HtmlElement) -> bool:
+    value = markup.text(cell)
+    if value in ATTENDANCE_EMPTY_MARKERS or re.fullmatch(r"[0-9]{1,2}", value):
+        return True
+    # Civil day labels in grid cells do not create attendance records.
+    if re.fullmatch(r"[0-9]{4}-[0-9]{2}-[0-9]{2}(?: \([^()]+\))?", value):
+        markup.civil_date(value)
+        return True
+    return False
+
+
+def parse_attendance(body: bytes) -> AttendanceRecords:
+    document = parse_page(body)
+    tables = [
+        table
+        for table in document.iter("table")
+        if {"center", "big", "decorated"} <= set(table.get("class", "").split())
+    ]
+    if len(tables) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    table = tables[0]
+    if list(table.iterdescendants("table")):
+        raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+    for anchor in document.iter("a"):
+        if table not in anchor.iterancestors("table") and "Data:" in anchor.get(
+            "title", ""
+        ):
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+    semesters: list[Literal[1, 2]] = []
+    semester: Literal[1, 2] | None = None
+    items: list[AttendanceRecord] = []
+    for row in markup.rows(table):
+        if next(row.iterancestors("thead"), None) is not None:
+            continue
+        cells = markup.cells(row)
+        if not cells or any(c.get("rowspan", "1") != "1" for c in cells):
+            raise LibrusError(ErrorKind.PARSE)
+        headings = [
+            c for c in cells if {"bolded", "center"} <= set(c.get("class", "").split())
+        ]
+        if headings:
+            if len(headings) != 1 or list(row.iter("a")):
+                raise LibrusError(ErrorKind.PARSE)
+            period = ATTENDANCE_SEMESTER_LABELS.get(
+                markup.text(headings[0]).casefold().rstrip(":")
+            )
+            if period is None or period in semesters:
+                raise LibrusError(ErrorKind.PARSE)
+            semester = cast(Literal[1, 2], period)
+            semesters.append(semester)
+            continue
+        for cell in cells:
+            anchors = list(cell.iter("a"))
+            if anchors:
+                if semester is None or "center" not in cell.get("class", "").split():
+                    raise LibrusError(ErrorKind.PARSE)
+                for anchor in anchors:
+                    items.append(_entry(anchor, semester))
+                    if len(items) > ATTENDANCE_MAX_RECORDS:
+                        raise LibrusError(ErrorKind.LIMIT)
+            elif "center" in cell.get(
+                "class", ""
+            ).split() and not _plain_cell_is_layout(cell):
+                raise LibrusError(ErrorKind.PARSE)
+    if not semesters:
+        raise LibrusError(ErrorKind.PARSE)
+    return AttendanceRecords(tuple(items), tuple(semesters))
+
+
+def parse_attendance_detail(body: bytes) -> AttendanceDetailContent:
+    document = parse_page(body)
+    containers = [
+        node
+        for node in document.iter("div")
+        if "container-background" in node.get("class", "").split()
+    ]
+    if len(containers) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    fields: dict[str, str] = {}
+    notes: list[str] = []
+    tables: set[html.HtmlElement] = set()
+    for row in containers[0].iter("tr"):
+        if not {"line0", "line1"}.intersection(row.get("class", "").split()):
+            continue
+        cells = markup.cells(row)
+        table = next(row.iterancestors("table"), None)
+        if table is None:
+            raise LibrusError(ErrorKind.PARSE)
+        tables.add(table)
+        if (
+            fields
+            and len(cells) == 1
+            and cells[0].tag == "td"
+            and cells[0].get("colspan") == "2"
+            and cells[0].get("rowspan", "1") == "1"
+        ):
+            notes.append(markup.text(cells[0]))
+            if len(fields) + len(notes) > ATTENDANCE_DETAIL_MAX_FIELDS:
+                raise LibrusError(ErrorKind.LIMIT)
+            continue
+        if (
+            len(cells) != 2
+            or cells[0].tag != "th"
+            or cells[1].tag != "td"
+            or any(
+                c.get("rowspan", "1") != "1" or c.get("colspan", "1") != "1"
+                for c in cells
+            )
+        ):
+            raise LibrusError(ErrorKind.PARSE)
+        label = markup.text(cells[0]).rstrip(":")
+        if not label or label in fields:
+            raise LibrusError(ErrorKind.PARSE)
+        fields[label] = markup.text(cells[1])
+        if len(fields) + len(notes) > ATTENDANCE_DETAIL_MAX_FIELDS:
+            raise LibrusError(ErrorKind.LIMIT)
+    if not fields or len(tables) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    return AttendanceDetailContent(tuple(fields.items()), tuple(notes))

librus_python_api/attendance_frequency.py

@@ -0,0 +1,112 @@
+"""Original validated gateway parsing and explicit attendance ratio policies."""
+
+from pydantic import ValidationError
+
+from librus_python_api import markup
+from librus_python_api.config import ATTENDANCE_MAX_RECORDS, ATTENDANCE_TYPE_KINDS
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import (
+    AttendanceKind,
+    FrequencyMeasure,
+    GatewayAttendanceRecord,
+    _AttendanceEnvelopeWire,
+    _LessonEnvelopeWire,
+    _SubjectEnvelopeWire,
+)
+from librus_python_api.parsers import decode_json
+
+
+def parse_gateway_attendance(body: bytes) -> tuple[GatewayAttendanceRecord, ...]:
+    data = decode_json(body)
+    if (
+        isinstance(data, dict)
+        and isinstance(data.get("Attendances"), list)
+        and len(data["Attendances"]) > ATTENDANCE_MAX_RECORDS
+    ):
+        raise LibrusError(ErrorKind.LIMIT)
+    failed = False
+    envelope = None
+    try:
+        envelope = _AttendanceEnvelopeWire.model_validate(data)
+    except ValidationError:
+        failed = True
+    if failed or envelope is None:
+        raise LibrusError(ErrorKind.PARSE)
+    seen: set[str] = set()
+    records: list[GatewayAttendanceRecord] = []
+    for row in envelope.Attendances:
+        if row.Id is not None:
+            if row.Id in seen:
+                raise LibrusError(ErrorKind.PARSE)
+            seen.add(row.Id)
+        records.append(
+            GatewayAttendanceRecord(
+                row.Id,
+                markup.civil_date(row.Date),
+                row.Semester,
+                row.Type.Id,
+                AttendanceKind(ATTENDANCE_TYPE_KINDS.get(row.Type.Id, "unknown")),
+                row.Lesson.Id,
+                row.LessonNo,
+            )
+        )
+    return tuple(records)
+
+
+def parse_lesson_subject(body: bytes, identifier: str) -> str:
+    data = decode_json(body)
+    failed = False
+    lesson = None
+    try:
+        lesson = _LessonEnvelopeWire.model_validate(data).Lesson
+    except ValidationError:
+        failed = True
+    if failed or lesson is None or lesson.Id != identifier:
+        raise LibrusError(ErrorKind.PARSE)
+    return lesson.Subject.Id
+
+
+def parse_subject_name(body: bytes, identifier: str) -> str:
+    data = decode_json(body)
+    failed = False
+    subject = None
+    try:
+        subject = _SubjectEnvelopeWire.model_validate(data).Subject
+    except ValidationError:
+        failed = True
+    if (
+        failed
+        or subject is None
+        or subject.Id != identifier
+        or not subject.Name.strip()
+    ):
+        raise LibrusError(ErrorKind.PARSE)
+    return subject.Name.strip()
+
+
+def summarize_frequency(
+    rows: tuple[GatewayAttendanceRecord, ...],
+    *,
+    subject_policy: bool,
+) -> FrequencyMeasure:
+    attended = total = unknown = excluded = 0
+    for row in rows:
+        if row.kind == "unknown":
+            unknown += 1
+        if not subject_policy:
+            total += 1
+            attended += row.kind in ("present", "late", "excursion")
+        elif row.kind in ("present", "late", "absence", "excused", "exemption"):
+            total += 1
+            attended += row.kind in ("present", "late")
+        elif row.kind != "unknown":
+            excluded += 1
+    ratio = attended / total if total and not unknown else None
+    return FrequencyMeasure(
+        attended,
+        total,
+        excluded,
+        unknown,
+        ratio,
+        "subject" if subject_policy else "overall",
+    )

librus_python_api/budget.py

@@ -0,0 +1,79 @@
+"""Caller-shareable operation budgets with no I/O or implicit configuration."""
+
+import asyncio
+import time
+
+from librus_python_api.config import DEFAULT_OPERATION_LIMITS, OperationLimits
+from librus_python_api.exceptions import ErrorKind, LibrusError
+
+
+class RequestBudget:
+    """Single-event-loop request/deadline budget shared across account calls.
+
+    The deadline starts at construction, including admission wait. Every actual
+    dispatch consumes one request; rejected or canceled queued work consumes none.
+    A reserved rate token can still be spent when its waiter is canceled. Budgets
+    are never refunded after dispatch, including connection failure or timeout.
+    """
+
+    def __init__(
+        self,
+        *,
+        max_requests: int = DEFAULT_OPERATION_LIMITS.max_requests,
+        timeout_seconds: float = DEFAULT_OPERATION_LIMITS.timeout_seconds,
+        max_response_bytes: int = DEFAULT_OPERATION_LIMITS.max_response_bytes,
+    ) -> None:
+        limits = OperationLimits(
+            max_requests=max_requests,
+            timeout_seconds=timeout_seconds,
+            max_response_bytes=max_response_bytes,
+        )
+        self._max_requests = limits.max_requests
+        self._deadline = time.monotonic() + limits.timeout_seconds
+        self._requests_dispatched = 0
+        self._max_response_bytes = limits.max_response_bytes
+        self._response_bytes = 0
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    @property
+    def requests_dispatched(self) -> int:
+        return self._requests_dispatched
+
+    @property
+    def response_bytes(self) -> int:
+        return self._response_bytes
+
+    @property
+    def remaining_response_bytes(self) -> int:
+        return max(0, self._max_response_bytes - self._response_bytes)
+
+    def _receive(self, count: int) -> None:
+        self._bind_loop()
+        self.remaining_seconds()
+        self._response_bytes += count
+        if self._response_bytes > self._max_response_bytes:
+            raise LibrusError(ErrorKind.LIMIT)
+
+    def remaining_seconds(self) -> float:
+        remaining = self._deadline - time.monotonic()
+        if remaining <= 0:
+            raise LibrusError(ErrorKind.TIMEOUT)
+        return remaining
+
+    def check(self) -> None:
+        self.remaining_seconds()
+        if self._requests_dispatched >= self._max_requests:
+            raise LibrusError(ErrorKind.LIMIT)
+        if self.remaining_response_bytes == 0:
+            raise LibrusError(ErrorKind.LIMIT)
+
+    def _consume(self) -> None:
+        # Synchronous check/update is atomic on the service's single event loop.
+        self.check()
+        self._requests_dispatched += 1
+
+    def _bind_loop(self) -> None:
+        loop = asyncio.get_running_loop()
+        if self._loop is not None and self._loop is not loop:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        self._loop = loop