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

librus_python_api/detail_fields.py

@@ -0,0 +1,50 @@
+"""Normalize bounded detail records using only established per-family labels."""
+
+from typing import Literal
+
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import DetailField, DetailFieldKey
+
+# School labels are recorded in contracts/school-reads.md. Attendance labels
+# are the narrowly established date/topic fields, not inferred tooltip fields.
+_KEYS: dict[str, dict[str, DetailFieldKey]] = {
+    "agenda": {
+        "data": "date",
+        "nr lekcji": "lesson_number",
+        "nauczyciel": "teacher",
+        "rodzaj": "category",
+        "przedmiot": "subject",
+        "sala": "room",
+        "opis": "description",
+        "data dodania": "published_at",
+    },
+    "homework": {
+        "zajęcia edukacyjne": "subject",
+        "temat": "topic",
+        "kategoria": "category",
+        "data udostępnienia": "published_at",
+        "termin wykonania": "due_at",
+        "treść": "content",
+    },
+    "attendance": {"data": "date", "temat zajęć": "topic"},
+}
+
+
+def normalize_detail_fields(
+    fields: tuple[tuple[str, str], ...],
+    kind: Literal["agenda", "homework", "attendance"],
+) -> tuple[DetailField, ...]:
+    """Run after bounded HTML parsing, before publishing or caching a result."""
+    labels: set[str] = set()
+    keys: set[DetailFieldKey] = set()
+    result = []
+    for label, value in fields:
+        canonical = " ".join(label.split()).rstrip(":").strip().casefold()
+        key = _KEYS[kind].get(canonical)
+        if not canonical or canonical in labels or (key is not None and key in keys):
+            raise LibrusError(ErrorKind.PARSE)
+        labels.add(canonical)
+        if key is not None:
+            keys.add(key)
+        result.append(DetailField(key, label, value))
+    return tuple(result)

librus_python_api/diagnostics.py

@@ -0,0 +1,25 @@
+"""Opt-in allowlisted structured diagnostics; no global logging configuration."""
+
+import logging
+from typing import Protocol
+
+from librus_python_api.models import DiagnosticEvent
+
+
+class DiagnosticSink(Protocol):
+    def __call__(self, event: DiagnosticEvent, /) -> None: ...
+
+
+def logging_sink(event: DiagnosticEvent) -> None:
+    """Emit allowlisted fields via stdlib logging; the application owns handlers."""
+    logging.getLogger("librus_python_api").info(
+        "Librus operation completed",
+        extra={
+            "component": "librus_python_api",
+            "operation": event.operation,
+            "outcome": event.outcome,
+            "elapsed_seconds": event.elapsed_seconds,
+            "budget_requests_dispatched": event.budget_requests_dispatched,
+            "budget_response_bytes": event.budget_response_bytes,
+        },
+    )

librus_python_api/exceptions.py

@@ -0,0 +1,172 @@
+"""Canonical typed exceptions and the closed, redacted failure factory."""
+
+from enum import StrEnum
+
+__all__ = [
+    "AccessDeniedError",
+    "AccountActionRequiredError",
+    "ClosedError",
+    "CheckpointError",
+    "ConnectionError",
+    "CredentialsRejectedError",
+    "ErrorKind",
+    "InvalidInputError",
+    "LibrusError",
+    "LimitError",
+    "MaintenanceError",
+    "OperationTimeoutError",
+    "ParseError",
+    "SessionExpiredError",
+    "StorageError",
+    "StaleCursorError",
+    "ThrottledError",
+    "UnknownDeliveryError",
+    "UnsupportedCapabilityError",
+    "ViewDisabledError",
+    "error_for",
+]
+
+
+class ErrorKind(StrEnum):
+    CHECKPOINT = "checkpoint"
+    INVALID_INPUT = "invalid_input"
+    CREDENTIALS_REJECTED = "credentials_rejected"
+    ACCOUNT_ACTION_REQUIRED = "account_action_required"
+    SESSION_EXPIRED = "session_expired"
+    ACCESS_DENIED = "access_denied"
+    UNSUPPORTED_CAPABILITY = "unsupported_capability"
+    VIEW_DISABLED = "view_disabled"
+    THROTTLED = "throttled"
+    MAINTENANCE = "maintenance"
+    CONNECTION = "connection"
+    TIMEOUT = "timeout"
+    LIMIT = "limit"
+    PARSE = "parse"
+    STALE_CURSOR = "stale_cursor"
+    UNKNOWN_DELIVERY = "unknown_delivery"
+    CLOSED = "closed"
+    STORAGE = "storage"
+
+
+class LibrusError(Exception):
+    """A failure with no arbitrary upstream message, URL, or response attachment.
+
+    Future transport adapters must suppress raw causes at the public boundary.
+    This type does not sanitize caller-added exception notes or chained errors.
+    """
+
+    def __new__(cls, kind: ErrorKind) -> "LibrusError":
+        if not isinstance(kind, ErrorKind):
+            raise TypeError("kind must be an ErrorKind")
+        # Preserve the foundation constructor while routing all failures through
+        # the same closed factory registry. Callers can catch specific subclasses.
+        concrete = _ERROR_TYPES[kind] if cls is LibrusError else cls
+        if concrete is not _ERROR_TYPES[kind]:
+            raise TypeError("Exception class and kind must agree")
+        return super().__new__(concrete)
+
+    def __init__(self, kind: ErrorKind) -> None:
+        if not isinstance(kind, ErrorKind):
+            raise TypeError("kind must be an ErrorKind")
+        self.kind = kind
+        super().__init__(kind.value)
+
+
+class InvalidInputError(LibrusError):
+    pass
+
+
+class CredentialsRejectedError(LibrusError):
+    pass
+
+
+class AccountActionRequiredError(LibrusError):
+    pass
+
+
+class SessionExpiredError(LibrusError):
+    # Library-private provenance only; never attach a URL, body or credentials.
+    _messages_origin = False
+
+
+class AccessDeniedError(LibrusError):
+    pass
+
+
+class UnsupportedCapabilityError(LibrusError):
+    pass
+
+
+class ViewDisabledError(LibrusError):
+    """The school administrator has switched this Synergia view off."""
+
+
+class ThrottledError(LibrusError):
+    pass
+
+
+class MaintenanceError(LibrusError):
+    pass
+
+
+class ConnectionError(LibrusError):
+    pass
+
+
+class OperationTimeoutError(LibrusError):
+    pass
+
+
+class LimitError(LibrusError):
+    pass
+
+
+class ParseError(LibrusError):
+    pass
+
+
+class StaleCursorError(LibrusError):
+    """Previously valid continuation no longer matches the current page sequence."""
+
+
+class UnknownDeliveryError(LibrusError):
+    pass
+
+
+class ClosedError(LibrusError):
+    pass
+
+
+class CheckpointError(LibrusError):
+    """Durable acknowledgement is unknown; never retry the callback or consume."""
+
+
+class StorageError(LibrusError):
+    """Private durable storage failed; a write may already have committed."""
+
+
+_ERROR_TYPES: dict[ErrorKind, type[LibrusError]] = {
+    ErrorKind.CHECKPOINT: CheckpointError,
+    ErrorKind.INVALID_INPUT: InvalidInputError,
+    ErrorKind.CREDENTIALS_REJECTED: CredentialsRejectedError,
+    ErrorKind.ACCOUNT_ACTION_REQUIRED: AccountActionRequiredError,
+    ErrorKind.SESSION_EXPIRED: SessionExpiredError,
+    ErrorKind.ACCESS_DENIED: AccessDeniedError,
+    ErrorKind.UNSUPPORTED_CAPABILITY: UnsupportedCapabilityError,
+    ErrorKind.VIEW_DISABLED: ViewDisabledError,
+    ErrorKind.THROTTLED: ThrottledError,
+    ErrorKind.MAINTENANCE: MaintenanceError,
+    ErrorKind.CONNECTION: ConnectionError,
+    ErrorKind.TIMEOUT: OperationTimeoutError,
+    ErrorKind.LIMIT: LimitError,
+    ErrorKind.PARSE: ParseError,
+    ErrorKind.STALE_CURSOR: StaleCursorError,
+    ErrorKind.UNKNOWN_DELIVERY: UnknownDeliveryError,
+    ErrorKind.CLOSED: ClosedError,
+    ErrorKind.STORAGE: StorageError,
+}
+
+
+def error_for(kind: ErrorKind) -> LibrusError:
+    """Single redacted factory for every library-owned failure."""
+    return _ERROR_TYPES[kind](kind)

librus_python_api/files.py

@@ -0,0 +1,242 @@
+"""Optional local attachment publication; no implicit destination or network client."""
+
+import asyncio
+import hashlib
+import os
+import secrets
+import stat
+import sys
+import unicodedata
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import partial
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from librus_python_api.attachment_routes import validate_max_bytes
+from librus_python_api.attachments import AttachmentStream
+from librus_python_api.config import ATTACHMENT_MAX_BYTES
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.lifecycle import join_owned
+
+if TYPE_CHECKING:
+    from librus_python_api._windows_filesystem import WindowsDirectory
+
+MAX_FILENAME_BYTES = 180
+MAX_FILENAME_ATTEMPTS = 100
+_RESERVED = (
+    {"CON", "PRN", "AUX", "NUL"}
+    | {f"{prefix}{i}" for prefix in ("COM", "LPT") for i in range(1, 10)}
+    | {f"{prefix}{i}" for prefix in ("COM", "LPT") for i in "¹²³"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class PublishedAttachment:
+    path: Path = field(repr=False)
+    size_bytes: int
+    sha256: str = field(repr=False)
+    content_type: str | None = field(repr=False)
+
+
+def safe_attachment_filename(filename: str) -> str:
+    """Treat upstream names as untrusted display data, never as a relative path."""
+    if type(filename) is not str or len(filename) > 4096:
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    name = filename.replace("\\", "/").rsplit("/", 1)[-1]
+    name = "".join(
+        "_" if unicodedata.category(c).startswith("C") or c in '<>:"|?*' else c
+        for c in name
+    ).strip(" .")
+    if name.split(".", 1)[0].upper() in _RESERVED:
+        name = "_" + name
+    # Truncate on UTF-8 codepoint boundaries, leaving room for collision suffixes.
+    name = name.encode()[:MAX_FILENAME_BYTES].decode("utf-8", errors="ignore")
+    return name.rstrip(" .") or "attachment"
+
+
+async def _disk[T](function: Callable[[], T]) -> T:
+    task = asyncio.create_task(asyncio.to_thread(function))
+    interrupted = await join_owned(task)
+    if interrupted:
+        raise asyncio.CancelledError
+    return task.result()
+
+
+def _write_all(descriptor: int, chunk: bytes) -> None:
+    view = memoryview(chunk)
+    while view:
+        count = os.write(descriptor, view)
+        if count <= 0:
+            raise OSError("Local write made no progress")
+        view = view[count:]
+
+
+async def prepare_attachment_directory(directory: Path) -> None:
+    """Explicitly create/validate a caller-selected private local directory.
+
+    Parent must exist. Never change an existing directory's permissions or ACL.
+    Cancellation may leave the complete empty directory, never an unjoined worker.
+    """
+    if not isinstance(directory, Path) or not directory.is_absolute():
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+
+    def prepare() -> None:
+        if sys.platform == "win32":
+            from librus_python_api._windows_filesystem import WindowsDirectory
+
+            WindowsDirectory(directory, create=True).close()
+        elif (
+            os.name == "posix"
+            and hasattr(os, "O_NOFOLLOW")
+            and hasattr(os, "O_DIRECTORY")
+        ):
+            directory.mkdir(mode=0o700, exist_ok=True)
+            descriptor = os.open(
+                directory, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+            )
+            try:
+                status = os.fstat(descriptor)
+                if (
+                    status.st_uid != os.geteuid()
+                    or stat.S_IMODE(status.st_mode) & 0o077
+                ):
+                    raise LibrusError(ErrorKind.STORAGE)
+                os.fsync(descriptor)
+            finally:
+                os.close(descriptor)
+        else:
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+
+    try:
+        await _disk(prepare)
+    except OSError:
+        raise LibrusError(ErrorKind.STORAGE) from None
+
+
+def _publish(directory: int, descriptor: int, temporary: str, name: str) -> str:
+    os.fsync(descriptor)
+    path = Path(name)
+    for index in range(MAX_FILENAME_ATTEMPTS):
+        candidate = name if index == 0 else f"{path.stem} ({index}){path.suffix}"
+        try:
+            # A same-directory hard link is atomic and fails if any target exists,
+            # including a dangling symlink. There is no check-then-replace race.
+            os.link(
+                temporary,
+                candidate,
+                src_dir_fd=directory,
+                dst_dir_fd=directory,
+                follow_symlinks=False,
+            )
+        except FileExistsError:
+            continue
+        os.fsync(directory)
+        return candidate
+    raise LibrusError(ErrorKind.LIMIT)
+
+
+async def publish_attachment(
+    stream: AttachmentStream,
+    directory: Path,
+    *,
+    filename: str,
+    max_bytes: int = ATTACHMENT_MAX_BYTES,
+) -> PublishedAttachment:
+    """Publish only a complete bounded stream to an existing caller-selected directory.
+
+    Files are owner-only. Failed/cancelled reads remove only this call's temporary
+    file. Cancellation during the atomic commit may leave a complete final file;
+    it never overwrites or removes an existing final path. All disk workers are
+    joined before closing descriptors or removing their temporary file.
+    """
+    if not isinstance(stream, AttachmentStream) or not isinstance(directory, Path):
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    validate_max_bytes(max_bytes)
+    # POSIX requires no-follow directory-relative opens; Windows uses pinned
+    # private NTFS handles instead, without emulating these flags by path checks.
+    if sys.platform != "win32" and (
+        not hasattr(os, "O_DIRECTORY") or not hasattr(os, "O_NOFOLLOW")
+    ):
+        raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+    name = safe_attachment_filename(filename)
+    directory_fd = descriptor = None
+    windows_directory: WindowsDirectory | None = None
+    temporary = ".librus-attachment-" + secrets.token_hex(16)
+    size = 0
+    digest = hashlib.sha256()
+    failed = False
+    try:
+        if sys.platform == "win32":
+            from librus_python_api._windows_filesystem import (
+                WindowsDirectory as Directory,
+            )
+
+            windows_directory = Directory(directory, create=False)
+            descriptor = windows_directory.open_file(temporary, exclusive=True)
+        else:
+            directory_fd = os.open(
+                directory, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+            )
+            descriptor = os.open(
+                temporary,
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW,
+                0o600,
+                dir_fd=directory_fd,
+            )
+        async with stream:
+            async for chunk in stream:
+                size += len(chunk)
+                if size > max_bytes:
+                    raise LibrusError(ErrorKind.LIMIT)
+                await _disk(partial(_write_all, descriptor, chunk))
+                digest.update(chunk)
+            if not stream.complete:
+                raise LibrusError(ErrorKind.PARSE)
+            content_type = stream.metadata.headers.content_type
+        if windows_directory is not None:
+            from librus_python_api._windows_filesystem import publish_file
+
+            final = await _disk(
+                lambda: publish_file(
+                    windows_directory, descriptor, name, MAX_FILENAME_ATTEMPTS
+                )
+            )
+        else:
+            final = await _disk(
+                lambda: _publish(directory_fd, descriptor, temporary, name)
+            )
+        return PublishedAttachment(
+            directory / final, size, digest.hexdigest(), content_type
+        )
+    except OSError:
+        failed = True
+    finally:
+        # Local cleanup has no outstanding worker and targets only our random name.
+        try:
+            if descriptor is not None:
+                os.close(descriptor)
+                if windows_directory is not None:
+                    try:
+                        os.unlink(directory / temporary)
+                    except FileNotFoundError:
+                        pass  # A completed rename removed only our temporary name.
+                else:
+                    assert directory_fd is not None
+                    os.unlink(temporary, dir_fd=directory_fd)
+        except OSError:
+            failed = True
+        finally:
+            if directory_fd is not None:
+                try:
+                    os.close(directory_fd)
+                except OSError:
+                    failed = True
+            if windows_directory is not None:
+                try:
+                    windows_directory.close()
+                except OSError:
+                    failed = True
+        if failed:
+            raise LibrusError(ErrorKind.STORAGE) from None
+    raise LibrusError(ErrorKind.STORAGE)

librus_python_api/grade_parsers.py

@@ -0,0 +1,169 @@
+"""Original bounded HTML summary parsing from source-informed requirements."""
+
+import re
+from collections.abc import Iterator
+
+from lxml import html
+
+from librus_python_api import markup
+from librus_python_api.config import (
+    GRADE_BODY_PREFIX_COLUMNS,
+    GRADE_INLINE_DETAIL_LABEL,
+    GRADE_MAX_COLUMNS,
+    GRADE_MAX_SUBJECTS,
+    GRADE_MAX_VALUE_LENGTH,
+    GRADE_MERGED_SUBJECTS,
+    GRADE_SUMMARY_HEADERS,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import (
+    Availability,
+    GradeSummaryValue,
+    SubjectGradeSummary,
+)
+from librus_python_api.parsers import parse_page
+
+
+def _summary_field(cell: html.HtmlElement) -> str | None:
+    title = cell.get("title", "")
+    if len(title) > GRADE_MAX_VALUE_LENGTH:
+        raise LibrusError(ErrorKind.LIMIT)
+    label = " ".join(re.split(r"<br\s*/?>", title, flags=re.I)[0].split())
+    return GRADE_SUMMARY_HEADERS.get(label)
+
+
+def _header(row: html.HtmlElement) -> tuple[dict[str, int], int]:
+    fields: dict[str, int] = {}
+    position = GRADE_BODY_PREFIX_COLUMNS
+    for cell in markup.cells(row):
+        span = markup.colspan(cell)
+        if position + span > GRADE_MAX_COLUMNS:
+            raise LibrusError(ErrorKind.LIMIT)
+        field = _summary_field(cell)
+        if field is not None:
+            if field in fields:
+                raise LibrusError(ErrorKind.PARSE)
+            fields[field] = position
+        position += span
+    return fields, position
+
+
+def _locate(
+    document: html.HtmlElement,
+) -> tuple[html.HtmlElement, dict[str, int], int]:
+    candidates: list[tuple[html.HtmlElement, dict[str, int], int]] = []
+    for table in document.iter("table"):
+        if not {"decorated", "stretch"} <= set(table.get("class", "").split()):
+            continue
+        for row in markup.rows(table):
+            if next(row.iterancestors("thead"), None) is None:
+                continue
+            # Group-heading rows can span the entire table. Only the row with
+            # an annual summary title defines the body alignment contract.
+            if not any(_summary_field(cell) == "annual" for cell in markup.cells(row)):
+                continue
+            fields, width = _header(row)
+            candidates.append((table, fields, width))
+    if len(candidates) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    return candidates[0]
+
+
+def _outside_nested_tables(row: html.HtmlElement) -> str:
+    """Reject a subject row masquerading as an expanded-detail wrapper."""
+    parts: list[str] = []
+    pending = [row]
+    while pending:
+        element = pending.pop()
+        if element.tail:
+            parts.append(element.tail)
+        if element.tag == "table":
+            continue
+        if element.text:
+            parts.append(element.text)
+        pending.extend(element)
+    return " ".join(parts).strip()
+
+
+def _summary(
+    cells: list[html.HtmlElement],
+    fields: dict[str, int],
+    width: int,
+) -> SubjectGradeSummary:
+    if len(cells) < GRADE_BODY_PREFIX_COLUMNS:
+        raise LibrusError(ErrorKind.PARSE)
+    subject = markup.text(cells[1])
+    if not subject or markup.colspan(cells[0]) != 1 or markup.colspan(cells[1]) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    columns: list[html.HtmlElement] = []
+    for cell in cells:
+        span = markup.colspan(cell)
+        if span > 1 and subject not in GRADE_MERGED_SUBJECTS:
+            raise LibrusError(ErrorKind.PARSE)
+        if len(columns) + span > GRADE_MAX_COLUMNS:
+            raise LibrusError(ErrorKind.LIMIT)
+        columns.extend([cell] * span)
+    if len(columns) != width:
+        raise LibrusError(ErrorKind.PARSE)
+    selected = [columns[index] for index in fields.values()]
+    if len({id(cell) for cell in selected}) != len(selected):
+        # A single merged value cannot mean two different summary fields.
+        raise LibrusError(ErrorKind.PARSE)
+    values = {
+        name: GradeSummaryValue(Availability.AVAILABLE, markup.text(columns[index]))
+        for name, index in fields.items()
+    }
+    absent = GradeSummaryValue(Availability.UNAVAILABLE, None)
+    return SubjectGradeSummary(
+        subject,
+        values.get("midterm", absent),
+        values.get("predicted_annual", absent),
+        values["annual"],
+    )
+
+
+def _subject_rows(
+    table: html.HtmlElement, width: int
+) -> Iterator[list[html.HtmlElement]]:
+    for row in markup.rows(table):
+        if next(row.iterancestors("thead"), None) is not None:
+            continue
+        cells = markup.cells(row)
+        if not cells:
+            raise LibrusError(ErrorKind.PARSE)
+        if list(row.iter("table")):
+            if _outside_nested_tables(row):
+                raise LibrusError(ErrorKind.PARSE)
+            continue
+        # An empty full-width layout spacer is not an unassigned subject. Keep
+        # this exception narrow: content or a different width remains malformed.
+        if (
+            len(cells) == 1
+            and markup.colspan(cells[0]) == width
+            and not markup.text(cells[0])
+        ):
+            continue
+        # Expanded inline detail labels are not subjects. Recognize this narrow
+        # source-informed variant, never discard arbitrary malformed subject rows.
+        if len(cells) > 1 and markup.text(cells[1]) == GRADE_INLINE_DETAIL_LABEL:
+            continue
+        yield cells
+
+
+def parse_final_grades(body: bytes) -> tuple[SubjectGradeSummary, ...]:
+    table, fields, width = _locate(parse_page(body))
+    items: list[SubjectGradeSummary] = []
+    subjects: set[str] = set()
+    for cells in _subject_rows(table, width):
+        item = _summary(cells, fields, width)
+        if item.subject in subjects:
+            raise LibrusError(ErrorKind.PARSE)
+        subjects.add(item.subject)
+        items.append(item)
+        if len(items) > GRADE_MAX_SUBJECTS:
+            raise LibrusError(ErrorKind.LIMIT)
+    # No evidenced no-subject marker exists. Missing rows are not empty success;
+    # a valid all-unassigned page still lists its subjects with raw '-' values.
+    if not items:
+        raise LibrusError(ErrorKind.PARSE)
+    return tuple(items)