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

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

@@ -148,7 +148,10 @@ refunded. Exhaustion raises `LimitError`; deadlines raise `OperationTimeoutError
   allowlisted modern directory and mailbox selections only. Arbitrary query keys,
   routes and modern-to-legacy reference reuse are rejected before dispatch.
 - `diagnostic_sink`: receives `DiagnosticEvent(operation, outcome,
-  elapsed_seconds, budget_requests_dispatched, budget_response_bytes, frames)`.
+  elapsed_seconds, budget_requests_dispatched, budget_response_bytes, frames,
+  http_status)`. `http_status` (1.8.1) is the HTTP status of the operation's
+  last checked read response, or None; statuses the transport turns into
+  errors (4xx, 5xx) are not checked reads, and attachment streams carry none.
   `frames` (1.8.0) holds the code locations of a `LibrusError` outcome, as below;
   it is empty on success and for timeouts, cancellation and replaced
   connection errors. `librus_python_api.diagnostics.logging_sink` emits allowlisted fields
@@ -173,11 +176,17 @@ from the exception's own traceback. Neither raises.
   known tooltip labels (`config.TOOLTIP_LABELS`), known detail-link families and
   lengths. Text and attribute values are masked unless they equal a parser
   constant, so a failing tooltip reads like `[[Data], [Waga], NO-COLON(len=17)]`.
-  Output is bounded. It is meant for a human to review before sharing, not for
+  A whole page held by the failing frame (1.8.1) is summarized after the other
+  elements: body text length, whether the Synergia menu and header are
+  present, title, headings, notices, forms and input types, then the first
+  tables row by row, with known profile labels and notices by name. Output is
+  bounded. It is meant for a human to review before sharing, not for
   automatic upload.
-- `python -m librus_python_api.inspect_page {grades,final-grades} FILE` parses a
-  saved page offline (a whole page or a copied table) and prints counts, or the
-  failure kind, frames and structure. It makes no request and applies the
+- `python -m librus_python_api.inspect_page {grades,final-grades,profile} FILE`
+  parses a saved page offline (a whole page or a copied table) and prints
+  counts, or the failure kind, frames and structure. `profile` (1.8.1) reads the
+  information page. A source view saved as a text document (macOS TextEdit) is
+  named as such instead of being parsed. It makes no request and applies the
   library's parse size limit. Exit status: 0 parsed, 1 failed, 2 unreadable
   file.
 
@@ -192,7 +201,8 @@ arbitrary-URL method.
   reads it, so the first call costs no extra request.
 - `student_information()` returns `StudentInformation` with name, class, register
   number, tutor, school and `lucky_number`. `LuckyNumber.availability` is
-  `UNAVAILABLE` when the page has none; no date is invented.
+  `UNAVAILABLE` when the page has no lucky number, an empty marker or "?" in
+  it; no date is invented. Up to 1.8.0 it was always `UNAVAILABLE`.
 
 Each result carries an `Observation(account, observed_at, session_generation,
 source)` with an aware UTC timestamp.
@@ -205,7 +215,8 @@ source)` with an aware UTC timestamp.
   `UNAVAILABLE` means the column is absent.
 - `grades(view=GradeView.ALL)` returns `Grades(identity, records, observation,
   view)`. Selecting a view (`ALL`, `WEEK`, `LAST_LOGIN`) is one POST that changes
-  the filter shown in that login's session; it is never replayed. `records` has:
+  the filter shown in that login's session; it is never replayed
+  (except once after Synergia's logged-out page, see [Errors](#errors)). `records` has:
   - `numeric`: `NumericGrade` with subject, raw symbol, civil `day`, semester,
     `kind` (`GradeKind`), and the optional count flag, weight, category, teacher,
     comment and tooltip `metadata`. Unknown weight or count is `None`, not zero.
@@ -301,7 +312,7 @@ school's login. See [gateway descriptive grades](contracts/grades.md#gateway-des
 - `attendance(view=AttendanceView.ALL)` returns `Attendance` with
   `AttendanceRecord`s (symbol, day, semester, type, teacher, period, excursion
   flag, topic, subject, numeric `detail_id`, tooltip metadata) and the semesters
-  shown. The view POST is never replayed.
+  shown. The view POST is never replayed (except once after Synergia's logged-out page, see [Errors](#errors)).
 - `attendance_window(start=None, end=None, view=AttendanceView.ALL)` filters the
   selected collection, with the same optional-date/370-day-difference rules.
   `AttendanceWindow.view` records the selection.
@@ -334,7 +345,8 @@ seven `TimetableDay`s. Each `TimetablePeriod` has a number, a local-time
 `changes` and the reported `next_recess`. A `TimetableChange` keeps the notice
 label (for example "zastępstwo") and its tooltip fields in order. The tooltip
 anchor may wrap the notice or sit inside it. No status is inferred from the
-label. The week selection is a POST that is never replayed.
+label. The week selection is a POST that is never replayed
+(except once after Synergia's logged-out page, see [Errors](#errors)).
 
 ## Announcements
 
@@ -442,7 +454,8 @@ Each `MessageSummary` carries:
 Each text field is bounded to 4,096 characters, total page text to 256 KiB,
 in addition to shared body/parser/request limits. No body or attachment fetch,
 mark-read, delete, send or read-once operation occurs. Pagination changes the
-selected mailbox view, so its POST is never replayed, including after expiry.
+selected mailbox view, so its POST is never replayed, including after expiry
+(except once after Synergia's logged-out page, see [Errors](#errors)).
 Page and batch caches are separate and fresh by default.
 
 In 0.4.11 a full 50-row page without pagination metadata is unsupported, not
@@ -457,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`:
@@ -939,7 +954,8 @@ be a `MessageReference` for the same login with a numeric ID and typed folder.
 Foreign accounts, arbitrary URLs and injected IDs fail before authentication.
 
 - Received opens require `allow_mark_read=True`, even for an already-read
-  selection or warm cache. Opening may mark read before any response or parse
+  selection or warm cache; without it they raise `ConsentRequiredError`
+  (`InvalidInputError` before 1.8.1) before any request. Opening may mark read before any response or parse
   failure. Consent does not assert that upstream actually changed a read flag.
 - `may_mark_read` describes the route, not delivery or mutation confirmation.
   Sent opens do not require the opt-in. Neither folder is automatically replayed,
@@ -1072,7 +1088,7 @@ Limits: 32 group selectors, 2,048 recipients, 1,024 characters per label and
 128 KiB total recipient text, plus shared transport/parser/body limits. Each
 lookup has its own account/type/selection cache key and accepts the common budget and
 freshness parameters. Fresh reads are default. Both selection operations are
-never replayed, even though group discovery uses GET. No send route, message
+never replayed (except once after Synergia's logged-out page, see [Errors](#errors)), even though group discovery uses GET. No send route, message
    content, mark-read, attachment or read-once access occurs in recipient discovery.
 
 The empty group-option selector is observed. Populated choices, nonzero dispatch,
@@ -1088,7 +1104,8 @@ grades, attendance, messages, announcements, agenda and homework. A shown catego
 without a counter has zero; missing categories are not fabricated. Invalid or
 duplicate counters fail. The menu may be a token-scoped snapshot, not a fresh poll
 or the input for seen-state updates. This ordinary read accepts the common
-budget/freshness arguments and conservatively does not replay on expiry.
+budget/freshness arguments and conservatively does not replay on expiry
+(except once after Synergia's logged-out page, see [Errors](#errors)).
 
 ```python
 batch = await client.consume_schedule_events(
@@ -1145,6 +1162,7 @@ text. `error_for(kind)` builds one.
 | Error | Meaning |
 | --- | --- |
 | `InvalidInputError` | Rejected before any request, or upstream rejected the selection |
+| `ConsentRequiredError` | A subclass of `InvalidInputError` (1.8.1): a call with an effect the user must agree to, such as opening a received message, was made without that consent; nothing was requested |
 | `CredentialsRejectedError` | Login and password refused |
 | `AccountActionRequiredError` | CAPTCHA, 2FA or another interactive step is required |
 | `SessionExpiredError` | Proven expiry that could not be recovered |
@@ -1162,9 +1180,24 @@ text. `error_for(kind)` builds one.
 
 Recovery policy:
 
-- Only a 401, or a redirect to an approved login route, proves expiry.
+- A 401 or a redirect to an approved login route proves expiry. So does
+  (1.8.1) a Synergia page that fails to parse, has no signed-in menu and
+  whose only heading is "Brak dostępu", unless a session that has just signed
+  in gets it. Synergia answers every page read of a session
+  it no longer knows that way, with status 200 (observed 2026-10-29); up to
+  1.8.0 this failed as `ParseError` on every call until the client was
+  recreated.
 - Safe GET reads then log in once more and retry once, within the same budget.
-- View-selection POSTs are never replayed.
+- View-selection POSTs are never replayed after a 401 or login redirect. A
+  read without an account effect answered with the logged-out page, POST
+  included, is repeated once in a fresh session: that page shows the request
+  was not applied to the account. The whole read is repeated, so a
+  multi-page read posts its earlier view selections again (the same views,
+  within the same budget). Opening a received message, which marks it read,
+  is not repeated: it fails as `SessionExpiredError` and the next call signs
+  in. If the fresh session gets the same page, or a session that has just
+  signed in gets it, the read fails as `ParseError` and that operation cools
+  down for 60 seconds, so a page that stays does not sign in on every call.
 - A denial or unrecovered expiry starts a 60-second cooldown for that operation
   on that login; a failed login starts one for the whole login.
 - 429 and 503 pause the whole scheduler, honouring `Retry-After` up to 24 hours.

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

@@ -1,5 +1,56 @@
 # 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.
+
+- Session recovery: for a session it no longer knows, Synergia answers every
+  page read with status 200 and a "Brak dostępu" page instead of a login
+  redirect (observed 2026-10-29). Up to 1.8.0 every read then failed as
+  `ParseError`, and kept failing until the client was recreated: the
+  profile's `parse_profile` failure a tester reported. Such a page now counts
+  as expiry: a read without an account effect signs in again and is repeated
+  once, view-selection POSTs included, since the page shows the request was
+  not applied. Opening a received message (mark-read) is not repeated; it
+  fails as `SessionExpiredError` and the next call signs in. A session that
+  has just signed in and gets the page, or a repeat that gets it again, fails
+  as `ParseError` and cools down for 60 seconds, so a page that stays does
+  not sign in on every call. Verified live by invalidating the session
+  cookies: student information, notification counts, grades, timetable,
+  attendance, homework and legacy messages each recovered with one login.
+- Student information: the lucky number is read from the page header
+  (`span.luckyNumber`). Up to 1.8.0 the parser looked for an element ID the
+  page does not use, so `lucky_number` was always `UNAVAILABLE`. An empty
+  marker or "?" (reported where no number is drawn; neither observed) stays
+  `UNAVAILABLE` instead of failing the read.
+- `describe_failure` summarizes a whole page held by the failing frame, after
+  the elements nearest the failure: body text length, Synergia menu and
+  header presence, title, headings, notices, forms and input types, and the
+  first tables row by row, instead of the start of the page head. Profile
+  labels, the login owner's row labels and known page notices are shown by
+  name, so a login or error page is told apart from a changed layout.
+- `ErrorKind.CONSENT_REQUIRED` and `ConsentRequiredError`, a subclass of
+  `InvalidInputError`: opening a received message without
+  `allow_mark_read=True` raises it instead of a plain invalid input, so a
+  caller can ask the user rather than treat the message as unreadable.
+  `except InvalidInputError` still catches it; code comparing `kind` with
+  `INVALID_INPUT` sees the new kind.
+- `DiagnosticEvent.http_status`: the HTTP status of the operation's last
+  checked read response, also logged by `logging_sink`. A read that fails as
+  `PARSE` at the response check now says whether it was a 2xx other than 200
+  or a 200 of another media type.
+- `inspect_page profile FILE` checks a saved information page. A page source
+  saved as a macOS TextEdit document is named as such.
+
 ## 1.8.0 (2026-10-28) - Failure diagnostics and gateway descriptive grades
 
 Errors still carry only their kind; new helpers say where a failure happened

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.8.0
+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,9 +42,13 @@ 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.0` reports where a failure happened (code locations and a
-redacted page structure, see [failure diagnostics](API.md#failure-diagnostics-180)),
-reads gateway descriptive grades for schools on the new descriptive schema
+**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
+happened (code locations and a redacted page structure, see
+[failure diagnostics](API.md#failure-diagnostics-180)), reads gateway descriptive grades for schools on the new descriptive schema
 (source-informed, first populated read live on one school) and keeps the 1.7.1 point
 grades and multi-line grade comments. It keeps the 1.6.4 linear-time message body
 rendering and the 1.6.2 completed-lesson and grade layouts, including behaviour
@@ -60,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.0
+python -m pip install librus-python-api==1.8.2
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -76,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.0-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
@@ -280,7 +284,10 @@ except LibrusError as error:
 
 To check a saved page offline (a page source saved with Ctrl+U, or a copied
 table), run `python -m librus_python_api.inspect_page grades page.html` (or
-`final-grades`). It prints counts, or the failure's code locations and masked
+`final-grades`, or `profile` for the information page `/informacja`). Save the
+page source itself: in Safari use File > Save As with format Page Source; in
+Chrome on macOS open it with Option+Cmd+U, then Cmd+S. A source view copied
+into TextEdit is a text document, which `inspect_page` rejects. It prints counts, or the failure's code locations and masked
 structure, and makes no request. Pass a `diagnostic_sink` to `LibrusService`
 to receive one `DiagnosticEvent` per operation, with `frames` on failure.
 None of these print page text, values, logins or exception messages.

{librus_python_api-1.8.0 → librus_python_api-1.8.2}/README.md

@@ -16,9 +16,13 @@ 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.0` reports where a failure happened (code locations and a
-redacted page structure, see [failure diagnostics](API.md#failure-diagnostics-180)),
-reads gateway descriptive grades for schools on the new descriptive schema
+**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
+happened (code locations and a redacted page structure, see
+[failure diagnostics](API.md#failure-diagnostics-180)), reads gateway descriptive grades for schools on the new descriptive schema
 (source-informed, first populated read live on one school) and keeps the 1.7.1 point
 grades and multi-line grade comments. It keeps the 1.6.4 linear-time message body
 rendering and the 1.6.2 completed-lesson and grade layouts, including behaviour
@@ -34,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.0
+python -m pip install librus-python-api==1.8.2
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -50,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.0-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
@@ -254,7 +258,10 @@ except LibrusError as error:
 
 To check a saved page offline (a page source saved with Ctrl+U, or a copied
 table), run `python -m librus_python_api.inspect_page grades page.html` (or
-`final-grades`). It prints counts, or the failure's code locations and masked
+`final-grades`, or `profile` for the information page `/informacja`). Save the
+page source itself: in Safari use File > Save As with format Page Source; in
+Chrome on macOS open it with Option+Cmd+U, then Cmd+S. A source view copied
+into TextEdit is a text document, which `inspect_page` rejects. It prints counts, or the failure's code locations and masked
 structure, and makes no request. Pass a `diagnostic_sink` to `LibrusService`
 to receive one `DiagnosticEvent` per operation, with `frames` on failure.
 None of these print page text, values, logins or exception messages.

{librus_python_api-1.8.0 → 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.0"
-
 __all__ = [
     "ArchiveAbsences",
     "ArchiveAchievement",

{librus_python_api-1.8.0 → 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.0 → 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",
@@ -688,6 +689,21 @@ PROFILE_LABELS = MappingProxyType(
         "Szkoła": "school",
     }
 )
+# Rows the information page lists for the login's own user after the
+# student's rows (observed); never read, named by failure diagnostics.
+PROFILE_OWNER_LABELS = ("Imię i nazwisko użytkownika", "Login", "Hasło")
+# The page header shows the lucky number as `span.luckyNumber > b` (observed
+# 2026-10-29). "?" there is reported where no number is drawn, for a school
+# without lucky numbers and possibly on days without a draw; neither it nor
+# an empty marker has been observed.
+PROFILE_LUCKY_NUMBER_CLASS = "luckyNumber"
+# For a session it no longer knows, Synergia answers every page read with 200
+# and a page whose only heading is "Brak dostępu" (`h2.inside`), without the
+# signed-in menu, not with a login redirect (observed 2026-10-29). A signed-in
+# user's timetable page has no menu either, so the heading is required too.
+LOGGED_IN_PAGE_MARKER = "graphic-menu"
+LOGGED_OUT_HEADING = "Brak dostępu"
+PROFILE_LUCKY_NUMBER_DISABLED = "?"
 
 # HTML summary headers omit the two leading body cells: expander and subject.
 # These labels/layout rules are source-informed requirements, not live evidence.
@@ -847,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.0 → librus_python_api-1.8.2}/src/librus_python_api/diagnostics.py

@@ -30,6 +30,16 @@ _ELEMENT_LOCALS = 4
 _DEPTH = 6
 _NODES = 120
 _ELEMENT_BYTES = 8 * 1024
+_PAGE_TABLES = 12
+_PAGE_ROWS = 40
+_PAGE_CELLS = 8
+_PAGE_NOTICES = 4
+# Input types a login, search or settings form uses; others are shown as "?".
+_INPUT_TYPES = frozenset(
+    {"button", "checkbox", "hidden", "password", "radio", "submit", "text"}
+)
+# Element IDs whose presence tells a Synergia page from a login or error page.
+_PAGE_MARKERS = ("graphic-menu", "user-section")
 _REPORT_BYTES = 32 * 1024
 # Markup observed on Synergia pages. Other class tokens, tags and attribute
 # names are shown only as lengths, since they could carry data.
@@ -45,6 +55,7 @@ _CLASSES = frozenset(
         "decorated",
         "detail-grades",
         "double",
+        "form",
         "gradesCell",
         "grade-box",
         "grade-box-mapping",
@@ -53,6 +64,7 @@ _CLASSES = frozenset(
         "legend",
         "line0",
         "line1",
+        "luckyNumber",
         "micro",
         "newSchemaGradesByStudentTable",
         "no-border-left",
@@ -65,6 +77,7 @@ _CLASSES = frozenset(
         "stretch",
         "studentRow",
         "tooltip",
+        "warning-content",
     }
 )
 _TAGS = frozenset(
@@ -164,6 +177,7 @@ def logging_sink(event: DiagnosticEvent) -> None:
             "budget_requests_dispatched": event.budget_requests_dispatched,
             "budget_response_bytes": event.budget_response_bytes,
             "frames": event.frames,
+            "http_status": event.http_status,
         },
     )
 
@@ -242,6 +256,9 @@ def _redaction_vocabulary() -> tuple[
         *config.GRADE_AVERAGE_HEADERS,
     }
     texts |= {label.casefold() for label in config.FORMATIVE_HEADERS}
+    profile = (*config.PROFILE_LABELS, *config.PROFILE_OWNER_LABELS)
+    texts |= set(profile) | {f"{label}:" for label in profile}
+    texts |= set(config.PAGE_NOTICES) | {config.LOGGED_OUT_HEADING}
     prefixes = tuple(
         sorted(
             (
@@ -398,13 +415,91 @@ def _path(element: html.HtmlElement, redactor: _Redactor) -> str:
     return " > ".join(reversed(steps))
 
 
+def _cell(cell: html.HtmlElement, redactor: _Redactor) -> str:
+    spans = "".join(
+        f" {redactor.attribute(name, str(cell.get(name)))}"
+        for name in ("colspan", "rowspan")
+        if cell.get(name, "1") != "1"
+    )
+    text = redactor.text(cell.text_content()) or "EMPTY"
+    return f"{_tag(str(cell.tag))}{spans}[{text}]"
+
+
+def _shown(label: str, texts: list[str]) -> str:
+    return " ".join([f"  {label}: {len(texts)}", *texts[:_PAGE_NOTICES]])
+
+
+def _page_summary(document: html.HtmlElement, redactor: _Redactor) -> list[str]:
+    """A whole page as its markers, forms, notices and tables, row by row.
+
+    A page that fails as a whole (no expected table, an unknown notice, a
+    login or error page) is told apart by these, not by its first elements.
+    Only the first tables, rows and cells are shown.
+    """
+    body = document.find("body")
+    text = " ".join((body if body is not None else document).text_content().split())
+    present = {
+        marker: document.get_element_by_id(marker, None) is not None
+        for marker in _PAGE_MARKERS
+    }
+    markers = " ".join(
+        f"{marker}={'yes' if found else 'no'}" for marker, found in present.items()
+    )
+    lines = [f"  body text len={len(text)} {markers}"]
+    title = document.find(".//title")
+    titles = [] if title is None else [redactor.text(title.text_content()) or "EMPTY"]
+    lines.append(_shown("title", titles))
+    headings = [
+        redactor.text(heading.text_content()) or "EMPTY"
+        for heading in document.iter("h1", "h2", "h3")
+    ]
+    lines.append(_shown("headings", headings))
+    notices = document.xpath(
+        '//div[contains(concat(" ",normalize-space(@class)," ")," warning-content ")]'
+    )
+    shown = [redactor.text(notice.text_content()) or "EMPTY" for notice in notices]
+    lines.append(_shown("notices", shown))
+    forms = [redactor.href(form.get("action", "")) for form in document.iter("form")]
+    inputs: dict[str, int] = {}
+    for field in document.iter("input"):
+        kind = field.get("type", "text").casefold()
+        kind = kind if kind in _INPUT_TYPES else "?"
+        inputs[kind] = inputs.get(kind, 0) + 1
+    counted = " ".join(f"{kind}={count}" for kind, count in sorted(inputs.items()))
+    lines.append(_shown("forms", forms) + (f"; inputs {counted}" if counted else ""))
+    tables = list(document.iter("table"))
+    lines.append(f"  tables: {len(tables)}")
+    for table in tables[:_PAGE_TABLES]:
+        rows = [
+            row
+            for row in table.iter("tr")
+            if next(row.iterancestors("table"), None) is table
+        ]
+        lines.append(f"  {_path(table, redactor)}: {len(rows)} rows")
+        for row in rows[:_PAGE_ROWS]:
+            cells = [cell for cell in row if cell.tag in ("td", "th")]
+            more = " ..." if len(cells) > _PAGE_CELLS else ""
+            rendered = " ".join(_cell(cell, redactor) for cell in cells[:_PAGE_CELLS])
+            lines.append(f"    {rendered}{more}")
+        if len(rows) > _PAGE_ROWS:
+            lines.append("    ...")
+    if len(tables) > _PAGE_TABLES:
+        lines.append("  ...")
+    return lines
+
+
+def _is_page(element: html.HtmlElement) -> bool:
+    return element.getparent() is None and element.tag == "html"
+
+
 def describe_failure(error: BaseException) -> str | None:
     """The page structure around a failure, for a bug report.
 
     Shows the HTML elements held by the innermost library frame that holds
     any: tags, safe class tokens, known tooltip labels, known link families
-    and lengths. Text and attribute values are masked unless they equal a
-    parser constant. Returns None when there is nothing to show; never raises.
+    and lengths. A whole page is summarized last (see _page_summary). Text
+    and attribute values are masked unless they equal a parser constant.
+    Returns None when there is nothing to show; never raises.
     """
     try:
         redactor = _Redactor()
@@ -425,8 +520,15 @@ def describe_failure(error: BaseException) -> str | None:
             if not elements and not sequences:
                 continue
             lines = [f"at {_site(frame, line)}"]
-            for name, value in elements:
+            # The elements nearest the failure first; a page summary last.
+            for name, value in sorted(elements, key=lambda item: _is_page(item[1])):
                 redactor.nodes = 0
+                if _is_page(value):
+                    summary = "\n".join(_page_summary(value, redactor))
+                    if len(summary) > _ELEMENT_BYTES:
+                        summary = summary[:_ELEMENT_BYTES] + "...(truncated)"
+                    lines += [f"{name}: page", summary]
+                    continue
                 lines.append(f"{name}: {_path(value, redactor)}")
                 rendered = redactor.element(value)
                 if len(rendered) > _ELEMENT_BYTES:

{librus_python_api-1.8.0 → librus_python_api-1.8.2}/src/librus_python_api/exceptions.py

@@ -7,6 +7,7 @@ __all__ = [
     "AccountActionRequiredError",
     "ClosedError",
     "CheckpointError",
+    "ConsentRequiredError",
     "ConnectionError",
     "CredentialsRejectedError",
     "ErrorKind",
@@ -31,6 +32,7 @@ __all__ = [
 class ErrorKind(StrEnum):
     CHECKPOINT = "checkpoint"
     INVALID_INPUT = "invalid_input"
+    CONSENT_REQUIRED = "consent_required"
     CREDENTIALS_REJECTED = "credentials_rejected"
     ACCOUNT_ACTION_REQUIRED = "account_action_required"
     SESSION_EXPIRED = "session_expired"
@@ -78,6 +80,13 @@ class InvalidInputError(LibrusError):
     pass
 
 
+class ConsentRequiredError(InvalidInputError):
+    """A call with an effect the user must agree to was made without consent.
+
+    A subclass of InvalidInputError, which these calls raised before 1.8.1.
+    """
+
+
 class CredentialsRejectedError(LibrusError):
     pass
 
@@ -89,6 +98,9 @@ class AccountActionRequiredError(LibrusError):
 class SessionExpiredError(LibrusError):
     # Library-private provenance only; never attach a URL, body or credentials.
     _messages_origin = False
+    # Inferred from a page without the logged-in menu, not from a 401 or a
+    # login redirect; a fresh session getting the same page is a layout.
+    _logged_out_page = False
 
 
 class AccessDeniedError(LibrusError):
@@ -124,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):
@@ -154,6 +168,7 @@ class StorageError(LibrusError):
 _ERROR_TYPES: dict[ErrorKind, type[LibrusError]] = {
     ErrorKind.CHECKPOINT: CheckpointError,
     ErrorKind.INVALID_INPUT: InvalidInputError,
+    ErrorKind.CONSENT_REQUIRED: ConsentRequiredError,
     ErrorKind.CREDENTIALS_REJECTED: CredentialsRejectedError,
     ErrorKind.ACCOUNT_ACTION_REQUIRED: AccountActionRequiredError,
     ErrorKind.SESSION_EXPIRED: SessionExpiredError,

{librus_python_api-1.8.0 → 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