librus-python-api 1.0.0__tar.gz → 1.0.1__tar.gz

{librus_python_api-1.0.0 → librus_python_api-1.0.1}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.0.1 (2026-10-06) - Bounded subject frequency and reliability fixes
+
+Compatible patch release. The public library API is unchanged.
+
+- Resolve subject-frequency lesson and subject names from the gateway `Lessons`
+  and `Subjects` collections, read once per login session and cached for the
+  existing one-hour TTL. A cold call now costs three requests regardless of how
+  many lessons and subjects a student has. Before, it cost one request per unique
+  lesson plus one per subject, which exceeded the default 32-request operation
+  budget near 15 subjects and failed with `LIMIT`. References missing from a
+  collection keep the strict per-reference routes. An unavailable, denied,
+  oversized or malformed collection falls back to them; deadlines, budgets and
+  cancellation still propagate.
+- Report a published attachment as published when removing the private temporary
+  name fails after the atomic link commit, instead of raising `STORAGE` for a
+  complete file. The inert temporary file may remain.
+- Wait up to one second, not 100 ms, for another process's SQLite write lock in
+  ordinary store operations. Several local processes commonly share one store;
+  final saves after upstream side effects keep their five-second wait.
+
 ## 1.0.0 (2026-10-05) - Stable native library API
 
 Freeze the documented library API and compatibility policy for consumers moving

{librus_python_api-1.0.0 → librus_python_api-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.0.0
+Version: 1.0.1
 Summary: Independent bounded async Librus Synergia client
 Project-URL: Repository, https://github.com/krzysztofbury/librus-python-api
 Project-URL: Issues, https://github.com/krzysztofbury/librus-python-api/issues
@@ -40,7 +40,7 @@ private ACLs. Windows installations include `pywin32` and `tzdata` automatically
 Network paths, reparse-point paths and unsafe storage permissions fail closed.
 See [platform requirements](contracts/persistence.md#windows-disk-boundary-25).
 
-**Status:** `1.0.0` freezes the documented native library API. It does not claim
+**Status:** `1.0.x` freezes the documented native library API. It does not claim
 completed MCP cutover, production-state migration or universal live-school
 compatibility. Those consumer/live gates remain separate. School features depend
 on what each account can access. See the [compatibility policy](API.md#compatibility-policy).
@@ -51,7 +51,7 @@ See [limitations](#supported-features-and-limitations) below.
 Install the exact release from PyPI after its gated publication completes:
 
 ```sh
-python -m pip install librus-python-api==1.0.0
+python -m pip install librus-python-api==1.0.1
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -67,7 +67,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.0.0-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.0.1-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.

{librus_python_api-1.0.0 → librus_python_api-1.0.1}/README.md

@@ -14,7 +14,7 @@ private ACLs. Windows installations include `pywin32` and `tzdata` automatically
 Network paths, reparse-point paths and unsafe storage permissions fail closed.
 See [platform requirements](contracts/persistence.md#windows-disk-boundary-25).
 
-**Status:** `1.0.0` freezes the documented native library API. It does not claim
+**Status:** `1.0.x` freezes the documented native library API. It does not claim
 completed MCP cutover, production-state migration or universal live-school
 compatibility. Those consumer/live gates remain separate. School features depend
 on what each account can access. See the [compatibility policy](API.md#compatibility-policy).
@@ -25,7 +25,7 @@ See [limitations](#supported-features-and-limitations) below.
 Install the exact release from PyPI after its gated publication completes:
 
 ```sh
-python -m pip install librus-python-api==1.0.0
+python -m pip install librus-python-api==1.0.1
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -41,7 +41,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.0.0-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.0.1-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.

{librus_python_api-1.0.0 → librus_python_api-1.0.1}/src/librus_python_api/__init__.py

@@ -120,7 +120,7 @@ from librus_python_api.models import (
 from librus_python_api.sending import SendAttempt
 from librus_python_api.service import AccountClient, LibrusService
 
-__version__ = "1.0.0"
+__version__ = "1.0.1"
 
 __all__ = [
     "AccountContext",

{librus_python_api-1.0.0 → librus_python_api-1.0.1}/src/librus_python_api/_storage.py

@@ -26,7 +26,10 @@ if TYPE_CHECKING:
 
 class _StorageLimits(_ValidatedConfig):
     operations: int = Field(default=8, ge=1, le=64)
-    busy_timeout_seconds: float = Field(default=0.1, gt=0, le=5, allow_inf_nan=False)
+    # Several local processes (one per agent host session) commonly share one
+    # store. Each transaction is short, but FULL synchronous commits can exceed
+    # 100 ms on slow disks, so ordinary operations wait up to one second.
+    busy_timeout_seconds: float = Field(default=1.0, gt=0, le=5, allow_inf_nan=False)
     # Final saves follow upstream side effects (a dispatched send or a consumed
     # read-once page), so they wait longer for other contexts' write locks.
     final_busy_timeout_seconds: float = Field(

{librus_python_api-1.0.0 → librus_python_api-1.0.1}/src/librus_python_api/attendance_frequency.py

@@ -1,9 +1,14 @@
 """Original validated gateway parsing and explicit attendance ratio policies."""
 
-from pydantic import ValidationError
+from pydantic import BaseModel, ValidationError
 
 from librus_python_api import markup
-from librus_python_api.config import ATTENDANCE_MAX_RECORDS, ATTENDANCE_TYPE_KINDS
+from librus_python_api.config import (
+    ATTENDANCE_MAX_LESSONS,
+    ATTENDANCE_MAX_RECORDS,
+    ATTENDANCE_MAX_SUBJECTS,
+    ATTENDANCE_TYPE_KINDS,
+)
 from librus_python_api.exceptions import ErrorKind, LibrusError
 from librus_python_api.models import (
     AttendanceKind,
@@ -11,7 +16,9 @@ from librus_python_api.models import (
     GatewayAttendanceRecord,
     _AttendanceEnvelopeWire,
     _LessonEnvelopeWire,
+    _LessonsEnvelopeWire,
     _SubjectEnvelopeWire,
+    _SubjectsEnvelopeWire,
 )
 from librus_python_api.parsers import decode_json
 
@@ -84,6 +91,62 @@ def parse_subject_name(body: bytes, identifier: str) -> str:
     return subject.Name.strip()
 
 
+def _collection[M: BaseModel](data: object, key: str, maximum: int, wire: type[M]) -> M:
+    if (
+        isinstance(data, dict)
+        and isinstance(data.get(key), list)
+        and len(data[key]) > maximum
+    ):
+        raise LibrusError(ErrorKind.LIMIT)
+    failed = False
+    envelope = None
+    try:
+        envelope = wire.model_validate(data)
+    except ValidationError:
+        failed = True
+    if failed or envelope is None:
+        raise LibrusError(ErrorKind.PARSE)
+    return envelope
+
+
+def _unique(pairs: list[tuple[str, str]]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for identifier, value in pairs:
+        # Conflicting rows are never resolved by choosing one of them.
+        if identifier in result and result[identifier] != value:
+            raise LibrusError(ErrorKind.PARSE)
+        result[identifier] = value
+    return result
+
+
+def parse_lesson_subjects(body: bytes) -> dict[str, str]:
+    """Map lesson IDs to subject IDs; rows without a subject are omitted."""
+    envelope = _collection(
+        decode_json(body), "Lessons", ATTENDANCE_MAX_LESSONS, _LessonsEnvelopeWire
+    )
+    return _unique(
+        [
+            (lesson.Id, lesson.Subject.Id)
+            for lesson in envelope.Lessons
+            if lesson.Subject is not None
+        ]
+    )
+
+
+def parse_subject_names(body: bytes) -> dict[str, str]:
+    """Map subject IDs to nonblank names; blank names are omitted."""
+    envelope = _collection(
+        decode_json(body), "Subjects", ATTENDANCE_MAX_SUBJECTS, _SubjectsEnvelopeWire
+    )
+    return _unique(
+        [
+            (subject.Id, subject.Name.strip())
+            for subject in envelope.Subjects
+            if subject.Name is not None and subject.Name.strip()
+        ]
+    )
+
+
 def summarize_frequency(
     rows: tuple[GatewayAttendanceRecord, ...],
     *,

{librus_python_api-1.0.0 → librus_python_api-1.0.1}/src/librus_python_api/config.py

@@ -401,6 +401,22 @@ ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
                 True,
                 Evidence.INDEPENDENTLY_OBSERVED,
             ),
+            Endpoint(
+                "attendance_lessons",
+                "GET",
+                "/gateway/api/2.0/Lessons",
+                SideEffect.NONE,
+                True,
+                Evidence.INDEPENDENTLY_OBSERVED,
+            ),
+            Endpoint(
+                "attendance_subjects",
+                "GET",
+                "/gateway/api/2.0/Subjects",
+                SideEffect.NONE,
+                True,
+                Evidence.INDEPENDENTLY_OBSERVED,
+            ),
             Endpoint(
                 "attendance_lesson",
                 "GET",
@@ -636,6 +652,9 @@ ATTENDANCE_SEMESTER_LABELS = MappingProxyType(
 ATTENDANCE_EMPTY_MARKERS = frozenset({"", "-", "Brak nieobecności"})
 ATTENDANCE_MAX_RECORDS = 2048
 ATTENDANCE_MAX_WINDOW_DAYS = 371
+# Whole-school gateway collections resolve attendance metadata in two requests.
+ATTENDANCE_MAX_LESSONS = 4096
+ATTENDANCE_MAX_SUBJECTS = 1024
 # Collection recognition and detail retrieval share this central path family.
 ATTENDANCE_DETAIL_PATH_PREFIX = "/przegladaj_nb/szczegoly/"
 ATTENDANCE_DETAIL_MAX_FIELDS = 32

{librus_python_api-1.0.0 → librus_python_api-1.0.1}/src/librus_python_api/files.py

@@ -166,6 +166,7 @@ async def publish_attachment(
     size = 0
     digest = hashlib.sha256()
     failed = False
+    published: PublishedAttachment | None = None
     try:
         if sys.platform == "win32":
             from librus_python_api._windows_filesystem import (
@@ -206,9 +207,10 @@ async def publish_attachment(
             final = await _disk(
                 lambda: _publish(directory_fd, descriptor, temporary, name)
             )
-        return PublishedAttachment(
+        published = PublishedAttachment(
             directory / final, size, digest.hexdigest(), content_type
         )
+        return published
     except OSError:
         failed = True
     finally:
@@ -237,6 +239,9 @@ async def publish_attachment(
                     windows_directory.close()
                 except OSError:
                     failed = True
-        if failed:
+        # The atomic link is the commit point. Failing to remove our random
+        # temporary name afterwards leaves an inert private file, but must not
+        # report a complete, published attachment as a failed transfer.
+        if failed and published is None:
             raise LibrusError(ErrorKind.STORAGE) from None
     raise LibrusError(ErrorKind.STORAGE)

{librus_python_api-1.0.0 → librus_python_api-1.0.1}/src/librus_python_api/models.py

@@ -1104,6 +1104,26 @@ class _SubjectEnvelopeWire(BaseModel):
     Subject: _SubjectWire
 
 
+class _CollectionLessonWire(_NumericReferenceWire):
+    # Collection rows may omit a subject; such lessons resolve individually.
+    Subject: _NumericReferenceWire | None = None
+
+
+class _LessonsEnvelopeWire(BaseModel):
+    model_config = ConfigDict(strict=True, extra="ignore", hide_input_in_errors=True)
+    Lessons: list[_CollectionLessonWire]
+
+
+class _CollectionSubjectWire(_NumericReferenceWire):
+    # Blank names resolve individually, where the strict subject contract applies.
+    Name: Annotated[str | None, Field(max_length=1024)] = None
+
+
+class _SubjectsEnvelopeWire(BaseModel):
+    model_config = ConfigDict(strict=True, extra="ignore", hide_input_in_errors=True)
+    Subjects: list[_CollectionSubjectWire]
+
+
 @dataclass(frozen=True, slots=True)
 class ProfileFields:
     name: str = field(repr=False)

{librus_python_api-1.0.0 → librus_python_api-1.0.1}/src/librus_python_api/service.py

@@ -10,7 +10,7 @@ import time
 from collections.abc import Awaitable, Callable, Hashable, Mapping
 from dataclasses import dataclass
 from datetime import UTC, date, datetime
-from types import TracebackType
+from types import MappingProxyType, TracebackType
 from typing import Any, Literal, Self, cast
 from urllib.parse import urljoin, urlsplit
 
@@ -20,7 +20,9 @@ from librus_python_api.attendance import parse_attendance, parse_attendance_deta
 from librus_python_api.attendance_frequency import (
     parse_gateway_attendance,
     parse_lesson_subject,
+    parse_lesson_subjects,
     parse_subject_name,
+    parse_subject_names,
     summarize_frequency,
 )
 from librus_python_api.budget import RequestBudget
@@ -345,6 +347,11 @@ def _require_dates(*days: date | None, max_days: int | None = None) -> None:
             raise LibrusError(ErrorKind.INVALID_INPUT)
 
 
+_METADATA_MAP_FALLBACK = frozenset(
+    {ErrorKind.ACCESS_DENIED, ErrorKind.CONNECTION, ErrorKind.LIMIT, ErrorKind.PARSE}
+)
+
+
 class AccountClient:
     """Service-owned account context. Fresh reads are the default.
 
@@ -388,6 +395,7 @@ class AccountClient:
         self._identity: Identity | None = None
         self._cache: dict[Hashable, tuple[float, Any]] = {}
         self._metadata: dict[tuple[str, str], tuple[float, str]] = {}
+        self._metadata_maps: dict[str, tuple[float, Mapping[str, str]]] = {}
         self._cooldowns: dict[str, tuple[float, ErrorKind]] = {}
         self._consuming_schedule = False
         self._modern_account: ModernAccountData | None = None
@@ -1910,6 +1918,7 @@ class AccountClient:
         self._modern_account = None
         self._cache.clear()
         self._metadata.clear()
+        self._metadata_maps.clear()
         self._transport.clear_auth()
 
     def _invalidate_modern(self) -> None:
@@ -2132,6 +2141,36 @@ class AccountClient:
             del self._metadata[next(iter(self._metadata))]
         return value
 
+    async def _metadata_map(
+        self, endpoint: str, budget: RequestBudget
+    ) -> Mapping[str, str]:
+        """One login-scoped collection read replaces per-reference lookups."""
+        cached = self._metadata_maps.get(endpoint)
+        if cached and time.monotonic() - cached[0] <= ATTENDANCE_METADATA_TTL_SECONDS:
+            return cached[1]
+        parser = (
+            parse_lesson_subjects
+            if endpoint == "attendance_lessons"
+            else parse_subject_names
+        )
+        try:
+            value: Mapping[str, str] = MappingProxyType(
+                await self._page(endpoint, budget, parser, content_type=JSON)
+            )
+        except LibrusError as error:
+            # An unavailable or unexpected collection degrades to the original
+            # per-reference lookups. Deadlines, budgets, cancellation and session
+            # failures still propagate. Only deterministic outcomes are cached.
+            if error.kind not in _METADATA_MAP_FALLBACK:
+                raise
+            if error.kind is ErrorKind.LIMIT:
+                budget.check()  # An exhausted caller budget is not a large collection.
+            if error.kind is ErrorKind.CONNECTION:
+                return MappingProxyType({})
+            value = MappingProxyType({})
+        self._metadata_maps[endpoint] = time.monotonic(), value
+        return value
+
     async def _subject_frequencies(
         self, budget: RequestBudget, start: date | None, end: date | None
     ) -> SubjectFrequencies:
@@ -2147,8 +2186,15 @@ class AccountClient:
         lessons = dict.fromkeys(row.lesson_id for row in rows)
         if len(lessons) > ATTENDANCE_METADATA_CACHE_SIZE:
             raise LibrusError(ErrorKind.LIMIT)
+        # Two collection reads keep the request count independent of how many
+        # lessons and subjects a student has. References absent from a
+        # collection keep the strict per-reference contract.
+        lesson_map = (
+            await self._metadata_map("attendance_lessons", budget) if lessons else {}
+        )
         lesson_subjects = {
-            lesson: await self._metadata_value("attendance_lesson", lesson, budget)
+            lesson: lesson_map.get(lesson)
+            or await self._metadata_value("attendance_lesson", lesson, budget)
             for lesson in lessons
         }
         subjects: dict[str, list[GatewayAttendanceRecord]] = {}
@@ -2156,10 +2202,14 @@ class AccountClient:
             subjects.setdefault(lesson_subjects[row.lesson_id], []).append(row)
         if len(subjects) > ATTENDANCE_METADATA_CACHE_SIZE:
             raise LibrusError(ErrorKind.LIMIT)
+        subject_map = (
+            await self._metadata_map("attendance_subjects", budget) if subjects else {}
+        )
         items = [
             SubjectFrequency(
                 subject,
-                await self._metadata_value("attendance_subject", subject, budget),
+                subject_map.get(subject)
+                or await self._metadata_value("attendance_subject", subject, budget),
                 summarize_frequency(tuple(records), subject_policy=True),
             )
             for subject, records in subjects.items()