librus-python-api 1.8.1__py3-none-any.whl → 1.8.2__py3-none-any.whl

librus_python_api/__init__.py

@@ -1,5 +1,8 @@
 """Independent bounded async client. General live compatibility is unqualified."""
 
+# Before the imports: config reads it for the User-Agent.
+__version__ = "1.8.2"
+
 from librus_python_api.attachments import AttachmentStream, ModernAttachmentStream
 from librus_python_api.budget import RequestBudget
 from librus_python_api.config import (
@@ -138,8 +141,6 @@ from librus_python_api.models import (
 from librus_python_api.sending import SendAttempt
 from librus_python_api.service import AccountClient, LibrusService
 
-__version__ = "1.8.1"
-
 __all__ = [
     "ArchiveAbsences",
     "ArchiveAchievement",

librus_python_api/attachments.py

@@ -15,7 +15,10 @@ from librus_python_api.attachment_routes import (
 )
 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.exceptions import (
+    ErrorKind,
+    LibrusError,
+)
 from librus_python_api.lifecycle import join_owned
 from librus_python_api.models import (
     AttachmentHeaders,
@@ -283,9 +286,7 @@ class ModernAttachmentStream(AttachmentStream):
                 budget,
             )
         except BaseException as error:
-            client._invalidate_modern()
-            if isinstance(error, SessionExpiredError):
-                error._messages_origin = True
+            client._modern_read_failed(error)
             raise
         await client._transport.stream_download(
             key,

librus_python_api/config.py

@@ -31,6 +31,7 @@ from pydantic import (
     model_validator,
 )
 
+from librus_python_api import __version__
 from librus_python_api.exceptions import ErrorKind, LibrusError
 from librus_python_api.models import (
     AttendanceView,
@@ -113,7 +114,7 @@ UPSTREAM_ORIGINS = MappingProxyType(
 OAUTH_QUERY = (("client_id", "46"),)
 SESSION_COOKIE = "oauth_token"
 AUTH_COOKIES = frozenset({SESSION_COOKIE, "DZIENNIKSID", "SDZIENNIKSID"})
-USER_AGENT = "librus-python-api/0.4 (independent client)"
+USER_AGENT = f"librus-python-api/{__version__} (independent client)"
 ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
     {
         item.operation_id: item
@@ -435,7 +436,7 @@ ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
             ),
             # Gateway reads behind the grades page's new-schema descriptive
             # table. Routes and field names come from public client code and the
-            # official page script, not from an observed populated response.
+            # official page script; one authorized read parsed four records.
             Endpoint(
                 "descriptive_token_info",
                 "GET",
@@ -862,9 +863,11 @@ FORMATIVE_TEMPLATE_ID = "000000"
 FORMATIVE_MAX_TEXT_LENGTH = 65536
 ATTENDANCE_DETAIL_MAX_FIELDS = 32
 ATTENDANCE_METADATA_CACHE_SIZE = 256
-ATTENDANCE_RESULT_CACHE_SIZE = 64
 ATTENDANCE_METADATA_TTL_SECONDS = 3600
 
+# Entries of every cached read of one account, oldest first out.
+ACCOUNT_RESULT_CACHE_SIZE = 64
+
 ANNOUNCEMENT_MAX_ITEMS = 256
 ANNOUNCEMENT_MAX_FIELD_LENGTH = 1024
 ANNOUNCEMENT_MAX_CONTENT_LENGTH = 65536

librus_python_api/exceptions.py

@@ -136,7 +136,9 @@ class OperationTimeoutError(LibrusError):
 
 
 class LimitError(LibrusError):
-    pass
+    # Library-private: the bound was the cookie count and the jar was emptied,
+    # so the session behind it is gone.
+    _cookies_cleared = False
 
 
 class ParseError(LibrusError):

librus_python_api/gateway_grades.py

@@ -3,8 +3,9 @@
 The grades page of a school on the new descriptive grading schema renders a
 subject table whose semester cells are empty; the page script then loads the
 grades from gateway JSON routes. Routes and field names come from public client
-code and the official page script, not from an observed populated response,
-so every unexpected shape fails instead of producing a partial collection.
+code and the official page script. One authorized read on 2026-10-28 parsed four
+PartialGrades records on one school; pagination keys are still unknown, so every
+unexpected shape fails instead of producing a partial collection.
 """
 
 import re

librus_python_api/service.py

@@ -34,11 +34,11 @@ from librus_python_api.completed_lessons import (
     validate_selection,
 )
 from librus_python_api.config import (
+    ACCOUNT_RESULT_CACHE_SIZE,
     ATTACHMENT_MAX_BYTES,
     ATTENDANCE_MAX_WINDOW_DAYS,
     ATTENDANCE_METADATA_CACHE_SIZE,
     ATTENDANCE_METADATA_TTL_SECONDS,
-    ATTENDANCE_RESULT_CACHE_SIZE,
     CHECKPOINT_TIMEOUT_SECONDS,
     ENDPOINTS,
     GRADE_MAX_RECORDS,
@@ -74,6 +74,7 @@ from librus_python_api.diagnostics import DiagnosticSink, failure_frames
 from librus_python_api.exceptions import (
     ErrorKind,
     LibrusError,
+    LimitError,
     ParseError,
     SessionExpiredError,
 )
@@ -1308,7 +1309,7 @@ class AccountClient:
         budget: RequestBudget | None = None,
         max_age_seconds: float = 0.0,
     ) -> Grades:
-        """Select a grade view with one non-replayed view-changing POST.
+        """Select a grade view with one view-changing POST.
 
         Changes the selected grade filter, not school records. A cache hit makes
         no POST. Missing inline weight/count data remains unknown. In the all
@@ -1401,7 +1402,7 @@ class AccountClient:
         budget: RequestBudget | None = None,
         max_age_seconds: float = 0.0,
     ) -> Attendance:
-        """Read a fixed upstream attendance view without replaying its POST."""
+        """Read a fixed upstream attendance view with one view-changing POST."""
         form = attendance_view_form(view)
 
         async def fetch(budget: RequestBudget, _: bool) -> Attendance:
@@ -1540,7 +1541,7 @@ class AccountClient:
         budget: RequestBudget | None = None,
         max_age_seconds: float = 0.0,
     ) -> Timetable:
-        """Select an explicit school civil week; never replay its selection POST."""
+        """Select an explicit school civil week with one view-changing POST."""
         form = timetable_form(monday)
 
         async def fetch(budget: RequestBudget, _: bool) -> Timetable:
@@ -2143,21 +2144,22 @@ class AccountClient:
                 )
             raise
         self._cache[key] = (time.monotonic(), result)
-        if len(self._cache) > ATTENDANCE_RESULT_CACHE_SIZE:
+        if len(self._cache) > ACCOUNT_RESULT_CACHE_SIZE:
             del self._cache[next(iter(self._cache))]
         return result
 
     async def _authenticated[T](
         self, fetch: Fetch[T], budget: RequestBudget, retry_safe: bool
     ) -> T:
-        """Run a read in a session; recover proven expiry once for safe reads.
+        """Run a read in a session; recover expiry once where a repeat is safe.
 
         Initial login is never retried: a failed credential submission must not
-        be replayed. A view-changing POST is never replayed either; expiry only
-        clears the session so a later explicit call can log in again. A
-        logged-out page proves the request was not applied to the account, so
-        a read without an account effect answered with one is repeated once in
-        a fresh session; a session just signed in that gets it fails as PARSE.
+        be replayed. A retry-safe read is repeated once after a new login, and
+        so is a read without an account effect (`NONE` or `SELECT_VIEW`, never
+        mark-read) answered with a logged-out page, which proves the request
+        was not applied. Other expiry only clears the session so a later
+        explicit call can log in again. A session just signed in that gets the
+        logged-out page fails as PARSE.
         """
         fresh_login = self._identity is None
         if fresh_login:
@@ -2231,9 +2233,7 @@ class AccountClient:
                 raise expired from error
         except BaseException as error:
             if ENDPOINTS[endpoint].origin == "messages":
-                self._invalidate_modern()
-                if isinstance(error, SessionExpiredError):
-                    error._messages_origin = True
+                self._modern_read_failed(error)
             raise
 
     def _check_cooldown(self, key: str) -> None:
@@ -2249,6 +2249,22 @@ class AccountClient:
         self._metadata_maps.clear()
         self._transport.clear_auth()
 
+    def _modern_read_failed(self, error: BaseException) -> None:
+        """Drop the modern session unless the failure says nothing about it.
+
+        A cancel or a local bound keeps it. Every other failure drops it, an
+        unrecognized body included: a session the upstream no longer knows may
+        be answered with one, and keeping it would fail every later read, while
+        dropping it costs one launch.
+        """
+        if isinstance(error, asyncio.CancelledError) or (
+            isinstance(error, LimitError) and not error._cookies_cleared
+        ):
+            return
+        self._invalidate_modern()
+        if isinstance(error, SessionExpiredError):
+            error._messages_origin = True
+
     def _invalidate_modern(self) -> None:
         self._modern_account = None
         for key in tuple(self._cache):

librus_python_api/transport.py

@@ -50,7 +50,12 @@ from librus_python_api.config import (
     recipient_form,
     validate_modern_query,
 )
-from librus_python_api.exceptions import ErrorKind, LibrusError, SessionExpiredError
+from librus_python_api.exceptions import (
+    ErrorKind,
+    LibrusError,
+    LimitError,
+    SessionExpiredError,
+)
 from librus_python_api.models import (
     AttachmentHeaders,
     LoginSubmission,
@@ -451,9 +456,7 @@ class AiohttpTransport:
                 proxy=proxy.get_secret_value() if proxy is not None else None,
             ) as response:
                 self._check_headers(response)
-                if len(session.cookie_jar) > self._limits.max_cookies:
-                    session.cookie_jar.clear()
-                    raise LibrusError(ErrorKind.LIMIT)
+                self._check_cookies(session)
                 if not modern or response.status not in (400, 422):
                     self._check_status(response)
                 body = await self._read_body(response, budget)
@@ -542,9 +545,7 @@ class AiohttpTransport:
             proxy=proxy.get_secret_value() if proxy is not None else None,
         ) as response:
             self._check_headers(response)
-            if len(session.cookie_jar) > self._limits.max_cookies:
-                session.cookie_jar.clear()
-                raise LibrusError(ErrorKind.LIMIT)
+            self._check_cookies(session)
             self._check_status(response)
             body = await self._read_payload(response, budget)
             if response.status == 200:
@@ -843,9 +844,7 @@ class AiohttpTransport:
             proxy=proxy.get_secret_value() if proxy is not None else None,
         ) as response:
             self._check_headers(response)
-            if len(session.cookie_jar) > self._limits.max_cookies:
-                session.cookie_jar.clear()
-                raise LibrusError(ErrorKind.LIMIT)
+            self._check_cookies(session)
             self._check_status(response)
             body = await self._read_body(response, budget)
             return TransportResponse(
@@ -863,6 +862,13 @@ class AiohttpTransport:
         ):
             raise LibrusError(ErrorKind.LIMIT)
 
+    def _check_cookies(self, session: aiohttp.ClientSession) -> None:
+        if len(session.cookie_jar) > self._limits.max_cookies:
+            session.cookie_jar.clear()
+            error = LimitError(ErrorKind.LIMIT)
+            error._cookies_cleared = True
+            raise error
+
     def _check_status(self, response: aiohttp.ClientResponse) -> None:
         if response.status in (429, 503):
             pause = self._limits.cooldown_seconds

{librus_python_api-1.8.1.dist-info → librus_python_api-1.8.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.8.1
+Version: 1.8.2
 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
@@ -42,7 +42,8 @@ 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.8.1` recovers a session Synergia no longer knows (it answers
+**Status:** `1.8.2` keeps the modern mailbox session across a cancelled read
+or a reached limit and sends its own version in the `User-Agent`. `1.8.1` recovers a session Synergia no longer knows (it answers
 with a "Brak dostępu" page, not a login redirect), reads the lucky number
 from the page header and summarizes a page that fails as a whole in
 diagnostics. `1.8.0` reports where a failure
@@ -63,7 +64,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.8.1
+python -m pip install librus-python-api==1.8.2
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -79,7 +80,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.8.1-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.8.2-py3-none-any.whl
 ```
 
 No console script or background process is installed: import the library in your

{librus_python_api-1.8.1.dist-info → librus_python_api-1.8.2.dist-info}/RECORD

@@ -1,24 +1,24 @@
-librus_python_api/__init__.py,sha256=KnN3xexlc15CN1XQPtwLNhUHc9Y82MyiQrMZEs4TYl4,6513
+librus_python_api/__init__.py,sha256=CDi6pTko967g3RViVcZCIWhE-Lzof5VN6E4NkQJ4aUU,6571
 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=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/attachments.py,sha256=Iq-ERZWc3gYXu6Lcv6womT2EXCc-c1Q7r_Q6VyaCm2E,10818
 librus_python_api/attendance.py,sha256=HeFAfnIUn4N__yp1zr635Dve55S2jmwtkeIy_6mV5B4,6924
 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/class_free_days.py,sha256=IwoCgr-9ZgEYYQ6717s4cDpyFzbosHMzESMabXJLGqA,2422
 librus_python_api/completed_lessons.py,sha256=ngGfBD6K4B6dR4elPYvNRvp40Q-GlrhUsUKqBbYY1KE,10727
-librus_python_api/config.py,sha256=F4w0F5r6uCObgyzO-cXkUtbz9Okh8HQEyfObAdOysig,61132
+librus_python_api/config.py,sha256=CBMwuuACfrB7TzTVkTP8QAuPz5hv43YOsbto81-uEJc,61248
 librus_python_api/detail_fields.py,sha256=vDDi5sV-e30-42SF0hwAUoldiZ5wvYtb1UlLt03lBHw,1708
 librus_python_api/diagnostics.py,sha256=5YbJB8J8RXMqMTmulcn5mJRF1vpi0Pvx00ETrXn9hUY,19036
-librus_python_api/exceptions.py,sha256=3Bt_1WbW2blSoljGAa00TK2AzU68tgYuRDd2k1onLTc,5392
+librus_python_api/exceptions.py,sha256=x8_z5UTNmuRINTK4buLYiKdYcFA2w6GZP9ZXOL-OnRU,5531
 librus_python_api/files.py,sha256=pQBsIJyfTOZDz83ZB-5fcd-nPMcxR1HJ155h4zTHmsA,9223
 librus_python_api/formative_grades.py,sha256=VykwtGvViZVOJMwPH3Re1RTDCHMr1_m9_xHjZyaXDIQ,6452
-librus_python_api/gateway_grades.py,sha256=HHXJqtC47v2BTP3ufak9i9Q68phOxwtzWjahKdxkyX4,16086
+librus_python_api/gateway_grades.py,sha256=T-G5KN0kpROi6xSGwAUba2qWDGNhg8TeGmQN140iLxc,16163
 librus_python_api/grade_parsers.py,sha256=ROfffkCP8yj5Q708TZdpp0PDTyVmoh6X7m0y2fyJcwg,11202
 librus_python_api/grade_records.py,sha256=YltZ_OQLsfxj0nvK8_xTuv8ifMOu2jJBnVn6TTQKzaY,22722
 librus_python_api/homework_range.py,sha256=erYfvS6PhHU5XhnR6LkiLNy677hGVflY3UAuHOs-YUw,1663
@@ -44,10 +44,10 @@ librus_python_api/scheduler.py,sha256=3JplYxqvQdFz3aKXcoQUJHE9s3FPw_xRhQ2CPNLuQm
 librus_python_api/school_reads.py,sha256=YHta7DmhjS5vSa4Djq8pzp01-2jhVfGOo1Mnc738rV4,15209
 librus_python_api/school_year_archive.py,sha256=D0A1ywMKgoYgvi-d70__SFreMGvMb_72870Akkbb_m8,15492
 librus_python_api/sending.py,sha256=Nvvk2r-6D6Us53a2fH5GW9PcA6bWEfuOvy6c3M5QVcE,4549
-librus_python_api/service.py,sha256=JY-RStBHmNOgGHISaC-pB2La2pdVGlJXXn52_kwkd3U,102316
+librus_python_api/service.py,sha256=34o-EQSuERhSHZAme-RDhVznhd_y1-GT0SPfduJ5LoM,102964
 librus_python_api/timetable.py,sha256=tX1QK9fQABxzfLaHHqTe8e6rAgdOkCoTOfAHdPwNmLE,9836
-librus_python_api/transport.py,sha256=n3goXE34xcsO-bilsLVYEUW3JkJR-9rbgmqPu7ff9J8,35036
-librus_python_api-1.8.1.dist-info/METADATA,sha256=clDgcKIX4m1Q6xagOEeKjRrcTTdonbX5v37tI2Q1_7s,14071
-librus_python_api-1.8.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-librus_python_api-1.8.1.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
-librus_python_api-1.8.1.dist-info/RECORD,,
+librus_python_api/transport.py,sha256=yF-DnFy4xGYS_RWQ9161b9WJXOlYF8cFRgdjXmVVUIk,34988
+librus_python_api-1.8.2.dist-info/METADATA,sha256=78cqj_uSkFU-4NhnUV0FCj3U8-QmJRK51bvIzIRVask,14202
+librus_python_api-1.8.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+librus_python_api-1.8.2.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
+librus_python_api-1.8.2.dist-info/RECORD,,