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

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

@@ -148,11 +148,47 @@ 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)`.
-  `librus_python_api.diagnostics.logging_sink` emits allowlisted fields through
-  the standard `logging` logger named `librus_python_api`. The application owns
-  handlers and formatting; no logging dependency or global configuration is added. Sink errors
-  never affect results.
+  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
+  through the standard `logging` logger named `librus_python_api`. The
+  application owns handlers and formatting; no logging dependency or global
+  configuration is added. Sink errors never affect results.
+
+### Failure diagnostics (1.8.0)
+
+Errors carry only their kind, so these helpers read where a failure happened
+from the exception's own traceback. Neither raises.
+
+- `diagnostics.failure_frames(error, limit=6, packages=("librus_python_api",))`
+  returns code locations such as `("grade_records:_numeric:100",
+  "markup:tooltip_fields:113")`, the original failure site last. It follows an
+  explicit cause or a context suppressed with `from None`, and skips helpers
+  that only raise. The strings are opaque and change between releases; report
+  them with the library version.
+- `diagnostics.describe_failure(error)` returns the page structure around the
+  failure, or None: the HTML elements held by the innermost library frame that
+  holds any, with their path from the grade table, tags, safe class tokens,
+  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)]`.
+  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,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.
 
 All upstream routes and forms are fixed in `config.py` and documented in
 [contracts/upstream.openapi.yaml](contracts/upstream.openapi.yaml). There is no
@@ -165,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.
@@ -178,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.
@@ -249,12 +287,32 @@ such as `(0-100)`, not a grade symbol. The table's "Wyn." period results are
 into `averages`), and a point table with titled summary columns adds its
 subjects to `final_grades()`. See [point grades](contracts/grades.md#point-grades-170).
 
+Gateway descriptive grades (1.8.0) belong to schools on the new
+descriptive grading schema, whose grades page shows a subject table with empty
+semester cells that the page script fills from the gateway. In the `ALL` view
+only, `grades()` then reads those grades from the gateway with the login's
+session and the call's budget: three more requests, five when there are
+grades. They are `DescriptiveGrade`s in `descriptive` (kind `CURRENT`, no
+`href`), with the page's subject name, the scale value or else the content as
+`raw`, the civil date, semester 1 or 2, the teacher's name when listed, the
+comment and metadata pairs for the present fields only (`Obszar`, `Treść`,
+`Dodał`, `Komentarz`, `Skala`). `grades_window()` filters them like other
+dated records. `WEEK` and `LAST_LOGIN` do not include them, because the page
+narrows those views by a field whose meaning is not established; notifications
+therefore do not report them. A gateway error, an unknown subject, a grade with
+no value, an unexpected shape or a pagination member that shows more items
+fails the whole read instead of returning it without these grades; a refused
+gateway route (403) is `UNSUPPORTED_CAPABILITY`, so it does not put the other
+grade views into the access-denied cooldown. The routes and field names are
+source-informed; a first authorized live read parsed populated records on one
+school's login. See [gateway descriptive grades](contracts/grades.md#gateway-descriptive-grades-180-issue-73).
+
 ## Attendance
 
 - `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.
@@ -287,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
 
@@ -395,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
@@ -892,7 +952,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,
@@ -1025,7 +1086,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,
@@ -1041,7 +1102,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(
@@ -1098,6 +1160,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 |
@@ -1115,9 +1178,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.7.1 → librus_python_api-1.8.1}/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## 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
+without page data. Schools on the new descriptive grading schema get their
+gateway grades.
+
+### Failure diagnostics
+
+- `diagnostics.failure_frames(error)` returns the failure's code locations
+  (`module:function:line`, the original site last) from its traceback, through
+  the parser thread, re-raises and a context suppressed with `from None`.
+- `diagnostics.describe_failure(error)` returns the page structure around the
+  failure: element path, tags, safe class tokens, known tooltip labels and
+  lengths, with every text and attribute value masked unless it equals a parser
+  constant. It names, for example, the unlabelled tooltip line that broke a
+  read.
+- `python -m librus_python_api.inspect_page {grades,final-grades} FILE` parses a
+  saved page or copied table offline and prints counts or the failure report.
+- `DiagnosticEvent.frames` carries the code locations to diagnostic sinks, and
+  `logging_sink` logs them.
+- `config.TOOLTIP_LABELS` lists the tooltip labels diagnostics may show by name.
+
+### Gateway descriptive grades
+
+Reads the grades of schools on the new descriptive grading schema, whose
+grades page renders a subject table with empty semester cells and loads the
+grades from gateway JSON routes. Routes and field names come from public client
+code and the official page script. A first authorized live read on 2026-10-28
+parsed four populated records on one school's login and showed the page
+layout below (issue #73).
+
+- Grades: in the `ALL` view, a page with the new-schema table adds its gateway
+  grades to `GradeRecords.descriptive` as `DescriptiveGrade` records, which
+  grade windows filter by date. The read makes three more requests, or five
+  when there are grades, under the same session and budget. Public types and
+  signatures are unchanged and `DescriptiveGrade` has no new field.
+- Grades: `WEEK` and `LAST_LOGIN` make no gateway request and do not include
+  these grades, so notifications do not report them yet.
+- Grades: a gateway error, unknown subject, grade without a value, malformed
+  or oversized response, unknown table layout or a pagination member showing
+  more items fails the whole all-view read on such a page, instead of
+  returning it without these grades. Pages without the table are unchanged.
+  A refused gateway route (403) is `UnsupportedCapabilityError`, so it does
+  not put the week and last-login views into the access-denied cooldown.
+- Upstream contract: five source-informed gateway operations; the two that
+  take an account identifier accept `[A-Za-z0-9_-]{1,128}`, every other
+  `{id}` route stays numeric.
+- Live check: the weekly grade checks and `scripts/live_capture.py` declare
+  the five gateway routes.
+- The page may hold an unclosed, row-less table of the same class before the
+  real one, and the real table has a period header row, hidden details rows
+  and a footer; only a table with subject rows of its own is read.
+
 ## 1.7.1 (2026-10-27) - Observed point-grade page and multi-line comments
 
 Fixes for layouts 1.7.0 rejected with `ParseError`, established from an

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.7.1
+Version: 1.8.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
@@ -42,8 +42,14 @@ 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.7.1` reads point grades ("Oceny punktowe") as an affected
-school's page shows them, and multi-line grade comments. It keeps the 1.6.4 linear-time message body
+**Status:** `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
 points, which are validated and not reported as grades.
 Class free days, typed capability outcomes and the live-check freshness watchdog
@@ -57,7 +63,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.7.1
+python -m pip install librus-python-api==1.8.1
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -73,10 +79,12 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.7.1-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.8.1-py3-none-any.whl
 ```
 
-No CLI or background process is installed: import the library in your own program.
+No console script or background process is installed: import the library in your
+own program. `python -m librus_python_api.inspect_page` only parses a saved page
+offline for a bug report.
 
 ## First request
 
@@ -254,6 +262,35 @@ unqualified; backend acceptance is not proof of delivery. Tests cover supported
 contracts, not every school or role. Detailed coverage is in the
 [verification log][verification]; open work is tracked in [issues][issues].
 
+## Diagnosing failures
+
+Errors carry only their kind. To see where a failure happened without any page
+data, use the helpers in `librus_python_api.diagnostics` (see
+[API.md](API.md#failure-diagnostics-180)):
+
+```python
+from librus_python_api.diagnostics import describe_failure, failure_frames
+from librus_python_api.exceptions import LibrusError
+
+try:
+    await client.grades()
+except LibrusError as error:
+    print(
+        error.kind, failure_frames(error)
+    )  # ('grade_records:_numeric:100', 'markup:tooltip_fields:113')
+    print(describe_failure(error))  # masked HTML structure around the failure
+```
+
+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`, 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.
+
 ## Development and support
 
 Use a repository checkout for tests and development tools; they are deliberately

{librus_python_api-1.7.1 → librus_python_api-1.8.1}/README.md

@@ -16,8 +16,14 @@ 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.7.1` reads point grades ("Oceny punktowe") as an affected
-school's page shows them, and multi-line grade comments. It keeps the 1.6.4 linear-time message body
+**Status:** `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
 points, which are validated and not reported as grades.
 Class free days, typed capability outcomes and the live-check freshness watchdog
@@ -31,7 +37,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.7.1
+python -m pip install librus-python-api==1.8.1
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -47,10 +53,12 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.7.1-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.8.1-py3-none-any.whl
 ```
 
-No CLI or background process is installed: import the library in your own program.
+No console script or background process is installed: import the library in your
+own program. `python -m librus_python_api.inspect_page` only parses a saved page
+offline for a bug report.
 
 ## First request
 
@@ -228,6 +236,35 @@ unqualified; backend acceptance is not proof of delivery. Tests cover supported
 contracts, not every school or role. Detailed coverage is in the
 [verification log][verification]; open work is tracked in [issues][issues].
 
+## Diagnosing failures
+
+Errors carry only their kind. To see where a failure happened without any page
+data, use the helpers in `librus_python_api.diagnostics` (see
+[API.md](API.md#failure-diagnostics-180)):
+
+```python
+from librus_python_api.diagnostics import describe_failure, failure_frames
+from librus_python_api.exceptions import LibrusError
+
+try:
+    await client.grades()
+except LibrusError as error:
+    print(
+        error.kind, failure_frames(error)
+    )  # ('grade_records:_numeric:100', 'markup:tooltip_fields:113')
+    print(describe_failure(error))  # masked HTML structure around the failure
+```
+
+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`, 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.
+
 ## Development and support
 
 Use a repository checkout for tests and development tools; they are deliberately

{librus_python_api-1.7.1 → librus_python_api-1.8.1}/src/librus_python_api/__init__.py

@@ -138,7 +138,7 @@ from librus_python_api.models import (
 from librus_python_api.sending import SendAttempt
 from librus_python_api.service import AccountClient, LibrusService
 
-__version__ = "1.7.1"
+__version__ = "1.8.1"
 
 __all__ = [
     "ArchiveAbsences",

{librus_python_api-1.7.1 → librus_python_api-1.8.1}/src/librus_python_api/config.py

@@ -433,6 +433,51 @@ ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
                 False,
                 Evidence.INDEPENDENTLY_OBSERVED,
             ),
+            # 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.
+            Endpoint(
+                "descriptive_token_info",
+                "GET",
+                "/gateway/api/2.0/Auth/TokenInfo",
+                SideEffect.NONE,
+                True,
+                Evidence.SOURCE_INFORMED,
+            ),
+            Endpoint(
+                "descriptive_user_info",
+                "GET",
+                "/gateway/api/2.0/Auth/UserInfo/{id}",
+                SideEffect.NONE,
+                True,
+                Evidence.SOURCE_INFORMED,
+            ),
+            # A read sent as POST with the fixed JSON body `{}`; it is never
+            # replayed, although it changes nothing that is known.
+            Endpoint(
+                "descriptive_partial_grades",
+                "POST",
+                "/gateway/api/2.0/Auth/DescriptiveGradingSystem/PartialGrades/Student/{id}",
+                SideEffect.NONE,
+                False,
+                Evidence.SOURCE_INFORMED,
+            ),
+            Endpoint(
+                "descriptive_subjects",
+                "GET",
+                "/gateway/api/3.0/Auth/Subjects",
+                SideEffect.NONE,
+                True,
+                Evidence.SOURCE_INFORMED,
+            ),
+            Endpoint(
+                "descriptive_users",
+                "GET",
+                "/gateway/api/2.0/Users",
+                SideEffect.NONE,
+                True,
+                Evidence.SOURCE_INFORMED,
+            ),
             Endpoint(
                 "attendance",
                 "POST",
@@ -643,6 +688,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.
@@ -662,6 +722,35 @@ GRADE_INLINE_DETAIL_LABEL = "Ocena"
 # Tooltip fields whose free text may continue on unlabelled lines. A teacher's
 # multi-line grade comment was observed on 2026-10-27.
 TOOLTIP_MULTILINE_LABELS = frozenset({"Komentarz"})
+# Tooltip labels observed on grade, attendance and point pages. Diagnostics
+# show only these by name; any other label is masked as teacher-entered text.
+TOOLTIP_LABELS = frozenset(
+    {
+        "Czy wycieczka",
+        "Data",
+        "Data realizacji",
+        "Data wystawienia",
+        "Data zapowiedzi",
+        "Dodał",
+        "Godzina lekcyjna",
+        "Kategoria",
+        "Komentarz",
+        "Lekcja",
+        "Licz do puli",
+        "Licz do wyniku",
+        "Licz do średniej",
+        "Maksymalna ilość punktów",
+        "Nauczyciel",
+        "Obowiązek wyk. zadania",
+        "Ocena",
+        "Rodzaj",
+        "Suma punktów",
+        "Temat zajęć",
+        "Waga",
+        "Zakres do",
+        "Zakres od",
+    }
+)
 # A point-grade ("Oceny punktowe") table marks each subject row's expander image
 # with this ID; ordinary grade rows use `przedmioty_<id>_node`.
 GRADE_POINT_ROW_NODE = re.compile(r"przedmioty_OP_[0-9A-Za-z_]{1,64}_node")
@@ -693,6 +782,21 @@ GRADE_PERIOD_HEADERS = MappingProxyType(
         "Ocena roczna": 0,
     }
 )
+# New-schema descriptive grading: the page renders this table with empty
+# semester cells and its script loads the grades from the gateway routes above.
+DESCRIPTIVE_TABLE_CLASS = "newSchemaGradesByStudentTable"
+DESCRIPTIVE_ROW_CLASS = "studentRow"
+# Gateway account and student identifiers are opaque strings, unlike every
+# other `{id}` route, which takes a numeric ID.
+DESCRIPTIVE_IDENTIFIER = re.compile(r"[A-Za-z0-9_-]{1,128}")
+DESCRIPTIVE_IDENTIFIER_OPERATIONS = frozenset(
+    {"descriptive_user_info", "descriptive_partial_grades"}
+)
+# The PartialGrades read is a POST whose only body is this fixed JSON object.
+DESCRIPTIVE_PARTIAL_GRADES_BODY = b"{}"
+DESCRIPTIVE_MAX_SUBJECTS = 1024
+DESCRIPTIVE_MAX_USERS = 8192
+DESCRIPTIVE_MAX_NAME_LENGTH = 1024
 GRADE_PREDICTED_ANNUAL_HEADER = "Przewidywana ocena roczna"
 GRADE_PREDICTED_PERIOD_HEADERS = MappingProxyType(
     {