librus-python-api 1.8.3__tar.gz → 1.8.4__tar.gz

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/API.md

@@ -287,12 +287,31 @@ 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
+Behaviour grade symbols (1.8.3): an entry in the behaviour row with a grade
+symbol such as `wz`, linking to a behaviour detail, is a `NumericGrade` in
+`numeric`. As for point grades, `category` is the tooltip's unlabelled first
+line (such as `wzorowe`), `day` is `Data wystawienia`, `teacher` stays `None`
+and `Dodał` is kept only in `metadata`. See [grades](contracts/grades.md).
+
+Schools on the new descriptive grading schema show a subject table
+(`newSchemaGradesByStudentTable`) in one of two layouts. Every view checks it
+the same way (from 1.8.4; before, only the `ALL` view did):
+
+- Empty semester cells (`gradesCell` hooks) that the page script fills from
+  the gateway. In the `ALL` view `grades()` reads those grades from the
+  gateway, as described below. `WEEK` and `LAST_LOGIN` contain none of them.
+- Semester cells holding bare text, such as `5` or `Brak ocen` (1.8.3). The
+  text becomes undated `descriptive_summaries` (`Brak ocen` is empty) and no
+  view makes a gateway request. Undated summaries are not notified.
+- Anything else fails the read: blank cells without hooks, a cell with an
+  attribute or markup, both layouts in one table, a bare-text table that still
+  has `studentGradesDetailsRow` rows (`UnsupportedCapabilityError`), or rows
+  of more than one student (`ParseError`).
+
+Gateway descriptive grades (1.8.0): with the empty layout, the `ALL` view
+reads the 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ść`,
@@ -804,7 +823,11 @@ async with NotificationStore(Path("/absolute/private/notification-state")) as st
   announcements use the ordinary collection. No menu counts, message content,
   detail calls, modern fallback or arbitrary historical catch-up is performed.
 - New `AGENDA` consumption requires explicit `allow_consume_events=True` each
-  time. Complete encoded raw bytes and original metadata commit before parsing.
+  time. Without it, and with no stored raw batch to replay, `poll()` and
+  `consume_schedule_events()` raise `ConsentRequiredError` before any request
+  (from 1.8.4; before, a plain `InvalidInputError`). Other invalid inputs,
+  such as repeated categories, stay `InvalidInputError`.
+  Complete encoded raw bytes and original metadata commit before parsing.
   Existing raw checkpoints replay locally before another consume. Malformed raw
   data remains stored and blocks another consume, even with fresh consent.
 - `NotificationBatch(receipt, context, first_run, categories, items,
@@ -1162,7 +1185,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 |
+| `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. Since 1.8.4 also consuming new calendar events without `allow_consume_events=True` |
 | `CredentialsRejectedError` | Login and password refused |
 | `AccountActionRequiredError` | CAPTCHA, 2FA or another interactive step is required |
 | `SessionExpiredError` | Proven expiry that could not be recovered |

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.8.4 (2026-11-08) - Multi-line formative tooltips, grade checks in every view, calendar consent
+
+Signatures are unchanged.
+
+- Grades: the week and last-login views run the same new-schema descriptive
+  table checks as the all view (#123). They used to return summaries or
+  nothing for a table the all view rejects: blank or classed semester cells,
+  a filled table with gateway detail rows, mixed layouts or rows of more than
+  one student. Notification polls read the last-login view, so such a page
+  now fails the poll instead of passing silently. Only the all view with
+  empty `gradesCell` hooks reads the gateway, as before.
+- Grades: a formative entry in the grade grid whose tooltip carries a
+  multi-line assessment text after `Ocena` no longer fails every grade read of
+  the login with `ParseError`. Found on two of the owner's logins by the live
+  check for this release (2026-11-08); 1.8.3 fails the same way. Unlabelled
+  lines continue `Ocena`, or a teacher-written field, with newlines. Tooltips
+  that already parsed keep the same metadata, so notification identities do
+  not change; the same lines in an ordinary grade's tooltip still fail.
+- Grades: a grade that corrects two earlier grades no longer fails the week
+  view with `ParseError`. Its tooltip lists one `Poprawa oceny` line per
+  corrected grade (seen live on 2026-11-08 in the week view of two owner
+  logins); the values are kept in order in one metadata pair, joined by a
+  newline. Other repeated labels still fail.
+- Notifications (krzysztofbury/librus-mcp#91): polling `AGENDA` without
+  `allow_consume_events=True` when no stored raw batch can be replayed, and
+  `consume_schedule_events()` with
+  `allow_consume_events=False`, raise `ConsentRequiredError` instead of a
+  plain invalid input, so a caller can ask the user. Nothing is requested
+  either way. `except InvalidInputError` still catches it; code comparing
+  `kind` with `INVALID_INPUT` sees the new kind. Repeated categories and a
+  non-boolean flag stay `InvalidInputError`.
+- Docs: `API.md`, the `grades()` docstring and `contracts/grades.md` describe
+  both new-schema table layouts, which views read the gateway, and behaviour
+  grade symbols (#124).
+- The weekly live check also reads the week and last-login grade views.
+
 ## 1.8.3 (2026-11-06) - Reported grade, attendance and announcement layouts
 
 Thank you, @wiktorw and @Witoso, for the reports and the careful synthetic

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.8.3
+Version: 1.8.4
 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,10 @@ 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.3` reads behaviour grade symbols, filled descriptive
+**Status:** `1.8.4` reads multi-line formative assessment text and repeated
+corrections in grade tooltips, checks the new-schema grade table in every grade view and reports
+missing calendar-consumption consent as `ConsentRequiredError`.
+`1.8.3` reads behaviour grade symbols, filled descriptive
 grade tables, the "Aktualnie brak ogłoszeń" page and absences excused
 through e-Usprawiedliwienia. `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
@@ -66,7 +69,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.3
+python -m pip install librus-python-api==1.8.4
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -82,7 +85,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.8.3-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.8.4-py3-none-any.whl
 ```
 
 No console script or background process is installed: import the library in your

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/README.md

@@ -16,7 +16,10 @@ 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.3` reads behaviour grade symbols, filled descriptive
+**Status:** `1.8.4` reads multi-line formative assessment text and repeated
+corrections in grade tooltips, checks the new-schema grade table in every grade view and reports
+missing calendar-consumption consent as `ConsentRequiredError`.
+`1.8.3` reads behaviour grade symbols, filled descriptive
 grade tables, the "Aktualnie brak ogłoszeń" page and absences excused
 through e-Usprawiedliwienia. `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
@@ -40,7 +43,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.3
+python -m pip install librus-python-api==1.8.4
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -56,7 +59,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.8.3-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.8.4-py3-none-any.whl
 ```
 
 No console script or background process is installed: import the library in your

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/src/librus_python_api/__init__.py

@@ -1,7 +1,7 @@
 """Independent bounded async client. General live compatibility is unqualified."""
 
 # Before the imports: config reads it for the User-Agent.
-__version__ = "1.8.3"
+__version__ = "1.8.4"
 
 from librus_python_api.attachments import AttachmentStream, ModernAttachmentStream
 from librus_python_api.budget import RequestBudget

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/src/librus_python_api/config.py

@@ -721,8 +721,12 @@ GRADE_MAX_VALUE_LENGTH = 1024
 GRADE_MERGED_SUBJECTS = frozenset({"Zachowanie"})
 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.
+# multi-line grade comment was observed on 2026-10-27. A formative mirror's
+# assessment text after `Ocena` also spans lines (2026-11-08, markup.py).
 TOOLTIP_MULTILINE_LABELS = frozenset({"Komentarz"})
+# Labels a tooltip may repeat. A grade correcting two earlier grades lists one
+# `Poprawa oceny` line per corrected grade in the week view (2026-11-08).
+TOOLTIP_REPEATABLE_LABELS = frozenset({"Poprawa oceny"})
 # 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(
@@ -744,6 +748,7 @@ TOOLTIP_LABELS = frozenset(
         "Nauczyciel",
         "Obowiązek wyk. zadania",
         "Ocena",
+        "Poprawa oceny",
         "Rodzaj",
         "Suma punktów",
         "Temat zajęć",
@@ -783,8 +788,9 @@ 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.
+# New-schema descriptive grading: the page renders this table either with empty
+# `gradesCell` semester cells, which its script fills from the gateway routes
+# above, or with bare semester text, which needs no gateway read.
 DESCRIPTIVE_TABLE_CLASS = "newSchemaGradesByStudentTable"
 DESCRIPTIVE_ROW_CLASS = "studentRow"
 DESCRIPTIVE_DETAILS_ROW_CLASS = "studentGradesDetailsRow"

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/src/librus_python_api/grade_records.py

@@ -15,6 +15,7 @@ from librus_python_api.config import (
     GRADE_BODY_PREFIX_COLUMNS,
     GRADE_CURRENT_HEADER,
     GRADE_EMPTY_MARKERS,
+    GRADE_INLINE_DETAIL_LABEL,
     GRADE_MAX_METADATA_LENGTH,
     GRADE_MAX_RECORDS,
     GRADE_MAX_SUBJECTS,
@@ -28,6 +29,7 @@ from librus_python_api.config import (
     GRADE_PUBLICATION_PERIOD_LABELS,
     GRADE_PUBLICATION_TEACHER_LABEL,
     TOOLTIP_LABELS,
+    TOOLTIP_MULTILINE_LABELS,
 )
 from librus_python_api.exceptions import ErrorKind, LibrusError
 from librus_python_api.formative_grades import is_formative_table, read_formative_table
@@ -99,7 +101,16 @@ def _numeric(
     semester: Literal[0, 1, 2],
     kind: GradeKind = GradeKind.CURRENT,
 ) -> NumericGrade:
-    metadata = markup.tooltip_fields(element)
+    if markup.detail_id(element.get("href"), FORMATIVE_DETAIL_PATH_PREFIX) is None:
+        metadata = markup.tooltip_fields(element)
+    else:
+        # A formative mirror's assessment text after `Ocena` is free text that
+        # may span lines and hold colons (observed live 2026-11-08).
+        metadata = markup.tooltip_fields(
+            element,
+            multiline=TOOLTIP_MULTILINE_LABELS | {GRADE_INLINE_DETAIL_LABEL},
+            unknown_multiline=True,
+        )
     counts = metadata.get("Licz do średniej")
     if counts is not None and counts.casefold() not in ("tak", "nie"):
         raise LibrusError(ErrorKind.PARSE)

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/src/librus_python_api/inspect_page.py

@@ -31,7 +31,7 @@ NOTICE = (
 
 
 def _grades(body: bytes) -> dict[str, int]:
-    # The all view also checks the new-schema table, as `grades()` does.
+    # Every grade view also checks the new-schema table, as `grades()` does.
     records, table = parse_grade_page(body)
     return {
         "numeric": sum(1 for g in records.numeric if g.point_grade_id is None),

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/src/librus_python_api/markup.py

@@ -13,7 +13,9 @@ from librus_python_api.config import (
     GRADE_MAX_COLUMNS,
     GRADE_MAX_METADATA_FIELDS,
     GRADE_MAX_METADATA_LENGTH,
+    TOOLTIP_LABELS,
     TOOLTIP_MULTILINE_LABELS,
+    TOOLTIP_REPEATABLE_LABELS,
     UPSTREAM_ORIGINS,
 )
 from librus_python_api.exceptions import ErrorKind, LibrusError
@@ -82,14 +84,27 @@ def colspan(cell: html.HtmlElement) -> int:
 
 
 def tooltip_fields(
-    element: html.HtmlElement, heading: list[str] | None = None
+    element: html.HtmlElement,
+    heading: list[str] | None = None,
+    *,
+    multiline: frozenset[str] | None = None,
+    unknown_multiline: bool = False,
 ) -> dict[str, str]:
     """Parse a 'Label: value<br>' title attribute into unique labelled fields.
 
     A free-text field may span lines; an unlabelled line after it continues
     its value. Any other unlabelled line is an unknown layout. With `heading`,
     the first line is taken whole, colon included, and appended to it.
+    `multiline` names the free-text labels (default `Komentarz`); with
+    `unknown_multiline`, a field whose label is not a known one (teacher text
+    holding a colon) is free text too, and inside such free text a line
+    starting with a known label is text unless the tooltip's closing run of
+    known-label lines begins there. Otherwise a known label such as `Data`
+    never continues. A repeatable label (`Poprawa oceny`) adds its value as
+    one more line of the same field.
     """
+    if multiline is None:
+        multiline = TOOLTIP_MULTILINE_LABELS
     title = element.get("title", "")
     if len(title) > GRADE_MAX_METADATA_LENGTH:
         raise LibrusError(ErrorKind.LIMIT)
@@ -98,18 +113,34 @@ def tooltip_fields(
     chunks = re.split(r"<br\s*/?>|\n", title, flags=re.I)
     if len(chunks) > GRADE_MAX_METADATA_FIELDS:
         raise LibrusError(ErrorKind.LIMIT)
-    for chunk in chunks:
-        if not chunk.strip():
-            continue
-        rendered = tooltip_line(chunk)
+    lines = [tooltip_line(chunk) for chunk in chunks if chunk.strip()]
+    # Start of the closing run of known-label lines, such as Kategoria, Data.
+    closing = len(lines)
+    while closing and _known_label(lines[closing - 1]):
+        closing -= 1
+    for index, rendered in enumerate(lines):
         if heading is not None and not heading:
             heading.append(rendered)
             continue
         key, separator, value = rendered.partition(":")
         key, value = key.strip(), value.strip()
-        if not separator and last in TOOLTIP_MULTILINE_LABELS:
+        if (
+            last is not None
+            and (
+                last in multiline or (unknown_multiline and last not in TOOLTIP_LABELS)
+            )
+            and (
+                not separator
+                or (unknown_multiline and index < closing and key in TOOLTIP_LABELS)
+            )
+        ):
             result[last] = f"{result[last]}\n{rendered}".strip()
             continue
+        if separator and key in result and key in TOOLTIP_REPEATABLE_LABELS:
+            # Each repeat keeps its value, in order, as one more line.
+            result[key] = f"{result[key]}\n{value}"
+            last = key
+            continue
         if not separator or not key or key in result:
             raise LibrusError(ErrorKind.PARSE)
         result[key] = value
@@ -117,6 +148,11 @@ def tooltip_fields(
     return result
 
 
+def _known_label(line: str) -> bool:
+    key, separator, _ = line.partition(":")
+    return bool(separator) and key.strip() in TOOLTIP_LABELS
+
+
 def tooltip_line(chunk: str) -> str:
     """One tooltip line's text, whitespace normalized."""
     # Tooltips are HTML inside an attribute; parse markup only where present.

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/src/librus_python_api/notification_workflow.py

@@ -130,7 +130,8 @@ class NotificationWorkflow:
             if uncertain:
                 raise LibrusError(ErrorKind.CHECKPOINT)
             if not consume:
-                raise LibrusError(ErrorKind.INVALID_INPUT)
+                # Nothing is read before the caller agrees to consume new events.
+                raise LibrusError(ErrorKind.CONSENT_REQUIRED)
         state = await store._io(lambda: store._read_state(context.identifier))
         ordinary = await self._ordinary(categories, window, budget)
         # Validate whole ordinary results and state capacity before consuming.

{librus_python_api-1.8.3 → librus_python_api-1.8.4}/src/librus_python_api/service.py

@@ -89,7 +89,6 @@ from librus_python_api.gateway_grades import (
     parse_user_info,
 )
 from librus_python_api.grade_parsers import parse_final_grades
-from librus_python_api.grade_records import parse_grade_records
 from librus_python_api.homework_range import HomeworkAccumulator
 from librus_python_api.lifecycle import join_owned
 from librus_python_api.message_content import parse_message_content, validate_reference
@@ -1084,11 +1083,11 @@ class AccountClient:
         Callback success acknowledges consumer-owned durable storage. Callback
         failure/timeout means acknowledgement unknown, never automatic replay.
         """
-        if (
-            type(allow_consume_events) is not bool
-            or not allow_consume_events
-            or self._consuming_schedule
-        ):
+        if type(allow_consume_events) is not bool:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        if not allow_consume_events:
+            raise LibrusError(ErrorKind.CONSENT_REQUIRED)
+        if self._consuming_schedule:
             raise LibrusError(ErrorKind.INVALID_INPUT)
         validate_checkpoint(checkpoint, checkpoint_timeout_seconds)
         self._consuming_schedule = True
@@ -1324,24 +1323,22 @@ class AccountClient:
         """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
-        view, a page with the new-schema descriptive table adds that table's
+        no POST. Missing inline weight/count data remains unknown.
+
+        Every view checks a new-schema descriptive table the same way. Its
+        semester cells either are empty script hooks or hold bare text, which
+        becomes undated summaries with no extra request; any other layout
+        fails the read. Only the all view with empty hooks adds that table's
         grades from the gateway: three more reads, five when there are grades.
-        Other views do not request them.
         """
         form = grade_view_form(view)
 
         async def fetch(budget: RequestBudget, _: bool) -> Grades:
-            if view is not GradeView.ALL:
-                records = await self._page(
-                    "grades", budget, parse_grade_records, form=form
-                )
-            else:
-                records, table = await self._page(
-                    "grades", budget, parse_grade_page, form=form
-                )
-                if table is not None and not table.filled:
-                    records = await self._gateway_descriptive(records, table, budget)
+            records, table = await self._page(
+                "grades", budget, parse_grade_page, form=form
+            )
+            if view is GradeView.ALL and table is not None and not table.filled:
+                records = await self._gateway_descriptive(records, table, budget)
             return Grades(
                 self._session_identity(), records, self._observation("grades"), view
             )