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

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/_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/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/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/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/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/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()

{librus_python_api-1.0.0.dist-info → librus_python_api-1.0.1.dist-info}/METADATA

@@ -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.dist-info → librus_python_api-1.0.1.dist-info}/RECORD

@@ -1,21 +1,21 @@
-librus_python_api/__init__.py,sha256=ErEyS0CIPgmEIHzURu8MnaZ-rwFiRexLujZnv5cyY_8,5657
+librus_python_api/__init__.py,sha256=YAo4-5FnnoG8Rx29PXJFTCxiQ0Rb6biHI52JCXsdQ0A,5657
 librus_python_api/_notification_bootstrap.py,sha256=18nzH0doXBNaZXCz-_ckIvRrlHTWV5Mm1t5m2-5eYGI,4669
 librus_python_api/_notification_codec.py,sha256=hU6G3zGJ5fR8wfPC6fV2OqBKs-7XpT9eRnKO3FGsTzY,13451
-librus_python_api/_storage.py,sha256=vh6O3X7e5ZNJf2GKU3Cz5PxhHn4D_nv7U7YvcoQV57s,15661
+librus_python_api/_storage.py,sha256=M_6ZAzN4zs7laOdKJBRH1I2rvy3pgqYgC_MZtsd2xtM,15893
 librus_python_api/_windows_filesystem.py,sha256=pQANIGkYrb4Q75gz5mdr5mqYhM_PFblWwTxPGM0bQ78,14063
 librus_python_api/announcements.py,sha256=13FoOR1sq7tt9w6aLf0vclcFKDqLUiIYaO5iYD2QVLA,5928
 librus_python_api/attachment_routes.py,sha256=uSg5wCQqHJiphF0KdI0GatQxZr5SLUx6xWQRsl_U4_U,4123
 librus_python_api/attachments.py,sha256=kyIBpFxeK34Al5_jCkxYKpZnsSLa5DYaGS6vHADpy_g,10921
 librus_python_api/attendance.py,sha256=HeFAfnIUn4N__yp1zr635Dve55S2jmwtkeIy_6mV5B4,6924
-librus_python_api/attendance_frequency.py,sha256=VAXZksSbE_o3fhP9vnN3_y0CCFQATFf6EOYhLQn-Fk8,3426
+librus_python_api/attendance_frequency.py,sha256=SBhED5zuyRIHWdw4urFyTJYykb6EYB7eL4dU3mif1EY,5309
 librus_python_api/budget.py,sha256=8fvqT7eIxyVX2P2OBG27XsYHk_HbtSS4lzuecYpHtgs,2878
 librus_python_api/checkpoint.py,sha256=QBmG9GtpyaGRaFq-FXuGA3yR1BjuMFN9V3RTvvi_FNQ,1930
 librus_python_api/completed_lessons.py,sha256=sR2oLSGb2q1580l-2upCBv9sQfIcHi7CQfWr1K0EFXI,7635
-librus_python_api/config.py,sha256=uXadjaj_CONEt3RJkk6a8ErZAohGVoZRsR9lfMaUtrU,48422
+librus_python_api/config.py,sha256=E3rMMc5qsw_imdpODI09Y6EOv0fcfbuWLPcIkY-ChwQ,49057
 librus_python_api/detail_fields.py,sha256=K10Stx_ehDTttkUI7-G7a2Ko9exYEu5NJpR-3sBnQ60,1789
 librus_python_api/diagnostics.py,sha256=2l7wq6RA3it-Gwj-JRLcw5qbI37fl3xII6GZA2mZj0o,856
 librus_python_api/exceptions.py,sha256=yWWoo0xyrQAk1d13HOJZnQBsq4ulh_P0hRSI6ZiNQOE,4622
-librus_python_api/files.py,sha256=yVa1wvw2PwAWPix_ZDLokZ-_NTMuG8nStW7I3K6jAo4,8895
+librus_python_api/files.py,sha256=pQBsIJyfTOZDz83ZB-5fcd-nPMcxR1HJ155h4zTHmsA,9223
 librus_python_api/grade_parsers.py,sha256=91Kr1-TArzqO-b94ipeIR0a98OV7tRCZQdBWsd9QLZ0,6141
 librus_python_api/grade_records.py,sha256=HvGHQ8Fyx_1Ne5k6N8cBeTqrDCzM5P6saj8eijDbRA4,16793
 librus_python_api/homework_range.py,sha256=erYfvS6PhHU5XhnR6LkiLNy677hGVflY3UAuHOs-YUw,1663
@@ -23,7 +23,7 @@ librus_python_api/lifecycle.py,sha256=XzA5CEdZFo7iL5IMUrawnRvf2m9BFe0OseP-fpQFaA
 librus_python_api/markup.py,sha256=GZk7MmBBGB5SIVY_VngmQxQErI3eGHOpJs3mFVlMR3M,5298
 librus_python_api/message_content.py,sha256=sUPuqpjuavqDyn6QGM5aPH4mpoQV62bDLepSSQ2AsUE,8686
 librus_python_api/messages.py,sha256=K9F8XVs1SojfFpdxxLV8gx9E0g81YxEHjigDzLHmDCg,10230
-librus_python_api/models.py,sha256=DGbxwDymPjJsqRMtqIe2W9KCBXzNiVPhzeXVjPSC9iQ,33106
+librus_python_api/models.py,sha256=aGPst3eV44w4YB-0HbmskumDz-KAHekTf6J6_CHaRbE,33826
 librus_python_api/modern_body.py,sha256=3L4P_cIrHdIxZqiinFSQrDMhG6iklT1GoA-VEWMJUiI,2682
 librus_python_api/modern_mailbox.py,sha256=nRrmIHb7RfV49xjUTBlDcgtxOdmXEpp4F1L0IvcGQxw,16118
 librus_python_api/modern_messages.py,sha256=9gysqjUkQGtMKmnCL7boRzNDnAhtL5ibAJ2rkNZWCec,9694
@@ -39,10 +39,10 @@ librus_python_api/recipients.py,sha256=6GQCKo-Zjg3VFSg1J8YXcDsy_U3r6-MUS4VCvz0xd
 librus_python_api/scheduler.py,sha256=3JplYxqvQdFz3aKXcoQUJHE9s3FPw_xRhQ2CPNLuQmA,10729
 librus_python_api/school_reads.py,sha256=PCnZ4lv44j-68FgJpQiMteaPSyfhbX8_3CUyE6zhFcQ,14760
 librus_python_api/sending.py,sha256=Nvvk2r-6D6Us53a2fH5GW9PcA6bWEfuOvy6c3M5QVcE,4549
-librus_python_api/service.py,sha256=a8EYBZBihVFe8moY_5SYjCtQSbcDrPwLA7vtcIopsqk,84209
+librus_python_api/service.py,sha256=tPDO0MlbhD6j0PHIZAHGpAVPvCMq2bLLK1HXGR7QQdc,86428
 librus_python_api/timetable.py,sha256=tX1QK9fQABxzfLaHHqTe8e6rAgdOkCoTOfAHdPwNmLE,9836
 librus_python_api/transport.py,sha256=6S5wwBiRkUfKmi6w2t8msxlTSzCo-IbIBE13FeBc7Jw,35357
-librus_python_api-1.0.0.dist-info/METADATA,sha256=_7MctXX2lgQROYs4N-In7q7ZT5vAbKNU3BfQchDQ8Rg,11514
-librus_python_api-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-librus_python_api-1.0.0.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
-librus_python_api-1.0.0.dist-info/RECORD,,
+librus_python_api-1.0.1.dist-info/METADATA,sha256=rwPPhwhdUftJky5wfqstlurtWaiXT93gAPEKi_1oQtY,11514
+librus_python_api-1.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+librus_python_api-1.0.1.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
+librus_python_api-1.0.1.dist-info/RECORD,,