librus-python-api 1.8.1__tar.gz → 1.8.2__tar.gz

{librus_python_api-1.8.1 → librus_python_api-1.8.2}/API.md

@@ -470,7 +470,9 @@ The initial handoff already includes that GET; subsequent sends cost one GET plu
 one POST. Expiry before dispatch raises `SessionExpiredError` and leaves
 NOT_DISPATCHED. An exact launch-to-native-login redirect is expiry, not denial.
 Messages-origin failures clear only modern binding/cookies/cache; valid legacy
-sessions stay usable. A later explicit modern call can rebind, but no modern
+sessions stay usable. A cancelled mailbox read, or one stopped by a reached limit,
+keeps them, so the next call needs no new launch; a limit that emptied the cookie
+jar does not, and neither does a transport timeout. A later explicit modern call can rebind, but no modern
 read/send is automatically retried. A race after preflight can still yield UNKNOWN.
 
 - `modern_identity(*, budget=None, max_age_seconds=0)` returns `ModernIdentity`:

{librus_python_api-1.8.1 → librus_python_api-1.8.2}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.8.2 (2026-11-01) - Modern session kept across cancels, honest User-Agent
+
+- A cancelled modern mailbox read or a reached limit no longer drops the modern
+  session, so the next call needs no new launch. Other failures still drop it,
+  an unrecognized body and a cookie limit, which empties the jar, included.
+- The `User-Agent` carries the package version; it said 0.4 since that release.
+- `config.ATTENDANCE_RESULT_CACHE_SIZE` is renamed `ACCOUNT_RESULT_CACHE_SIZE`:
+  it caps every cached read of an account.
+
 ## 1.8.1 (2026-10-29) - Session recovery, lucky number, consent error and diagnostics
 
 Signatures are unchanged; one error kind is added.

{librus_python_api-1.8.1 → librus_python_api-1.8.2}/PKG-INFO

@@ -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 → librus_python_api-1.8.2}/README.md

@@ -16,7 +16,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
@@ -37,7 +38,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
@@ -53,7 +54,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 → librus_python_api-1.8.2}/src/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-1.8.1 → librus_python_api-1.8.2}/src/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-1.8.1 → librus_python_api-1.8.2}/src/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-1.8.1 → librus_python_api-1.8.2}/src/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-1.8.1 → librus_python_api-1.8.2}/src/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-1.8.1 → librus_python_api-1.8.2}/src/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-1.8.1 → librus_python_api-1.8.2}/src/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