librus-python-api 1.2.1__tar.gz → 1.4.0__tar.gz

{librus_python_api-1.2.1 → librus_python_api-1.4.0}/API.md

@@ -191,8 +191,54 @@ source)` with an aware UTC timestamp.
   selection. It reuses only that view's cache; averages and undated summaries
   remain outside the window.
 
-The observation card ("Karta spostrzeżeń") shown on some grades pages is not
-read yet.
+### School-year archive (1.3.0)
+
+`school_year_archive(*, budget=None, max_age_seconds=0.0)` returns
+`SchoolYearArchive(identity, years, achievements, observation)`. It performs one
+read-only GET for all earlier years, with the same per-login cache, coalescing,
+budgets and safe-read session recovery as `announcements()`. There is no year
+selection or chart request. This is separate from the modern message archive.
+
+- `years` contains `ArchiveYear` in page order: `class_name`, `school_year`,
+  `first_year`, `subjects`, `descriptive`, two raw behaviour fields and `absences`.
+- Each `ArchiveSubject(subject, marks)` has `ArchiveMarks(first_semester,
+  second_semester, year_end)`. Empty text and `-` remain distinct. `year_end` is
+  not asserted to equal `SubjectGradeSummary.annual`.
+- `ArchiveDescriptive(label, text)` keeps whole-year text, with explicit BR
+  boundaries as newlines. Source whitespace is normalized.
+- `behaviour_first_semester` and `behaviour_second_semester_and_year_end` retain
+  positional text. Populated behaviour semantics have not been observed.
+- `ArchiveAbsences(unexcused, excused, late)` contains `ArchiveCounts` with the
+  same three period names. Counts are rendered integers, never summed or repaired.
+- `achievements` contains `ArchiveAchievement(day, class_name, category, text)`;
+  `day` is a civil `date`. A header-only achievements table yields an empty tuple.
+
+All archive types are root exports. School text and record containers are omitted
+from reprs; the page's student-name header does not enter archive records.
+Limits: 16 unique consecutive school-year pairs, 128 subject rows, 32 descriptive
+rows, 256 achievements, 1024 characters per short field, 65536 per long text
+cell and 262144 total rendered characters, plus the shared transport/tree bounds.
+
+The observed `Brak danych` information notice returns empty `years` and
+`achievements`. Missing tables without that explicit marker still raise `PARSE`;
+an empty notice combined with data tables is rejected. Repeated school years
+(including a class-change layout) are ambiguous and raise `PARSE`. Unknown
+geometry/markup raises `UNSUPPORTED_CAPABILITY`; bounds raise `LIMIT`, never
+partial success. Consumers must handle these states before exposing the read.
+See [archive evidence and limitations](contracts/grades.md#school-year-archive-130).
+
+The observed grade-detail page added no fields beyond the list tooltip, so
+there is no separate per-grade detail request. This finding is limited to the
+observed layout.
+
+Formative assessments (1.4.0) come from the same page with no extra request.
+`grades().records.formative` and `grades_window(...).formative` hold
+`FormativeGrade(subject, text, category, semester, day, assessment_type,
+detail_id)`; the observation card ("KARTA SPOSTRZEŻEŃ") appears as a subject
+value. The same items stay in `numeric`/`descriptive` unchanged; their
+`formative_id` property (computed, not a field, so stored notification
+identities are unchanged) links them to `detail_id`. A page without the
+section returns `()`. See [formative grades](contracts/grades.md#formative-grades-and-the-observation-card-140).
 
 ## Attendance
 

{librus_python_api-1.2.1 → librus_python_api-1.4.0}/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 1.4.0 (2026-10-08) - Formative assessments and the observation card
+
+Compatible minor release. Existing fields, results and stored notification
+identities are unchanged. One new failure mode: a page whose formative table
+is recognised but uses unknown markup (for example an empty-state row, markup
+inside the assessment text or a stray formative link) now fails the grades
+read instead of being ignored, rather than returning partial output.
+
+- Add `GradeRecords.formative` and `GradeWindow.formative`: `FormativeGrade`
+  records from the grades page's "Oceny kształtujące" table, including the
+  "KARTA SPOSTRZEŻEŃ" observation card, read from the page `grades()` already
+  fetches. No request is added; formative detail links are never followed.
+- Add the computed `formative_id` property to `NumericGrade` and
+  `DescriptiveGrade`, identifying grid records that mirror a formative item.
+  It is not a dataclass field, so grade notification identities stay stable.
+- Reject unknown formative markup and stray formative links instead of
+  dropping them; a page without the section has no formative items.
+- The weekly live check reports formative counts for the grades step.
+
+## 1.3.0 (2026-10-07) - School-year archive read
+
+Compatible minor release. Existing calls and results are unchanged.
+
+- Add `AccountClient.school_year_archive()` and frozen per-year records for
+  subject marks, descriptive text, raw behaviour cells, absence counts and
+  dated achievements. One read-only GET covers all earlier years without year
+  selection, chart requests or fetching grade-detail links.
+- Apply the shared account-isolated cache, coalescing, recovery and budgets.
+  Reject ambiguous tables, unknown markup and exceeded bounds without partial
+  output. Preserve empty marks and school-provided year-end values.
+- Add guarded weekly archive coverage with redacted year counts. Older pinned
+  libraries without the method skip this check. Installed live checks passed
+  on two parent logins, covering populated and explicit empty archives with
+  unchanged notification counters. Broader school-layout support is unqualified.
+- Recognize the observed `Brak danych` empty notice and the malformed HTML
+  chart container after the achievements footer. Nested tabular data still fails.
+- Record the #40 grade-detail finding: the observed page added no fields beyond
+  the list tooltip, so no separate grade-detail read is introduced.
+
 ## 1.2.1 (2026-10-06) - Live fixes for archive listing and teacher subjects
 
 Compatible patch release found by the new pre-publication live check. 1.1.0 and

{librus_python_api-1.2.1 → librus_python_api-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.2.1
+Version: 1.4.0
 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
@@ -26,6 +26,8 @@ Description-Content-Type: text/markdown
 
 # librus-python-api
 
+[![Weekly live check](https://github.com/krzysztofbury/librus-python-api/actions/workflows/live-check.yml/badge.svg?branch=main)](https://github.com/krzysztofbury/librus-python-api/actions/workflows/live-check.yml)
+
 Read grades, attendance, homework, timetables and messages from **Librus Synergia**
 in Python. This independent, asynchronous client handles login, session recovery,
 pagination and request limits, returning typed Python objects rather than HTML.
@@ -40,9 +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.0.x` freezes the documented native library API. It does not claim
-completed MCP cutover, production-state migration or universal live-school
-compatibility. Those consumer/live gates remain separate. School features depend
+**Status:** `1.4.0` adds formative assessments, including the observation card,
+to grade results. The 1.3.0 archive read passed installed live checks for
+populated and empty archives on two parent logins; see [verification](VERIFICATION.md).
+The stable 1.x API does not guarantee every school layout. School features depend
 on what each account can access. See the [compatibility policy](API.md#compatibility-policy).
 See [limitations](#supported-features-and-limitations) below.
 
@@ -51,7 +54,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.2.1
+python -m pip install librus-python-api==1.4.0
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -67,7 +70,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.2.1-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.4.0-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.
@@ -148,6 +151,11 @@ attendance = await client.attendance_window(today.replace(day=1), today)
 
 # Permit reuse of this account's cached result for up to 60 seconds.
 announcements = await client.announcements(max_age_seconds=60)
+
+# Earlier school years, separate from the message archive (1.3.0).
+archive = await client.school_year_archive()
+for year in archive.years:
+    print(year.school_year, year.subjects)
 ```
 
 Collections expose named record tuples, for example `homework.items`, rather than
@@ -233,12 +241,12 @@ removed in 0.7.
 
 | Area | Available |
 | --- | --- |
-| School data | Profile, grades, attendance, timetable, announcements, agenda, homework and completed lessons |
+| School data | Profile, grades, school-year archive, attendance, timetable, announcements, agenda, homework and completed lessons |
 | Communication | Legacy/modern message lists and content, recipient discovery, bounded attachment streams and explicit sending |
 | Application workflows | Shared multi-account limits, caching, notification checkpoints, optional durable send/notification stores |
 
-Completed lessons may be disabled by the school. Behaviour notes and observation
-cards are not implemented. Some recipient, archive and receipt layouts remain
+Completed lessons may be disabled by the school. Behaviour notes are not
+implemented. Some recipient, archive and receipt layouts remain
 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] and [roadmap][roadmap].

{librus_python_api-1.2.1 → librus_python_api-1.4.0}/README.md

@@ -1,5 +1,7 @@
 # librus-python-api
 
+[![Weekly live check](https://github.com/krzysztofbury/librus-python-api/actions/workflows/live-check.yml/badge.svg?branch=main)](https://github.com/krzysztofbury/librus-python-api/actions/workflows/live-check.yml)
+
 Read grades, attendance, homework, timetables and messages from **Librus Synergia**
 in Python. This independent, asynchronous client handles login, session recovery,
 pagination and request limits, returning typed Python objects rather than HTML.
@@ -14,9 +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.0.x` freezes the documented native library API. It does not claim
-completed MCP cutover, production-state migration or universal live-school
-compatibility. Those consumer/live gates remain separate. School features depend
+**Status:** `1.4.0` adds formative assessments, including the observation card,
+to grade results. The 1.3.0 archive read passed installed live checks for
+populated and empty archives on two parent logins; see [verification](VERIFICATION.md).
+The stable 1.x API does not guarantee every school layout. School features depend
 on what each account can access. See the [compatibility policy](API.md#compatibility-policy).
 See [limitations](#supported-features-and-limitations) below.
 
@@ -25,7 +28,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.2.1
+python -m pip install librus-python-api==1.4.0
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -41,7 +44,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.2.1-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.4.0-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.
@@ -122,6 +125,11 @@ attendance = await client.attendance_window(today.replace(day=1), today)
 
 # Permit reuse of this account's cached result for up to 60 seconds.
 announcements = await client.announcements(max_age_seconds=60)
+
+# Earlier school years, separate from the message archive (1.3.0).
+archive = await client.school_year_archive()
+for year in archive.years:
+    print(year.school_year, year.subjects)
 ```
 
 Collections expose named record tuples, for example `homework.items`, rather than
@@ -207,12 +215,12 @@ removed in 0.7.
 
 | Area | Available |
 | --- | --- |
-| School data | Profile, grades, attendance, timetable, announcements, agenda, homework and completed lessons |
+| School data | Profile, grades, school-year archive, attendance, timetable, announcements, agenda, homework and completed lessons |
 | Communication | Legacy/modern message lists and content, recipient discovery, bounded attachment streams and explicit sending |
 | Application workflows | Shared multi-account limits, caching, notification checkpoints, optional durable send/notification stores |
 
-Completed lessons may be disabled by the school. Behaviour notes and observation
-cards are not implemented. Some recipient, archive and receipt layouts remain
+Completed lessons may be disabled by the school. Behaviour notes are not
+implemented. Some recipient, archive and receipt layouts remain
 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] and [roadmap][roadmap].

{librus_python_api-1.2.1 → librus_python_api-1.4.0}/src/librus_python_api/__init__.py

@@ -16,6 +16,13 @@ from librus_python_api.models import (
     AgendaEvent,
     Announcement,
     Announcements,
+    ArchiveAbsences,
+    ArchiveAchievement,
+    ArchiveCounts,
+    ArchiveDescriptive,
+    ArchiveMarks,
+    ArchiveSubject,
+    ArchiveYear,
     AttachmentHeaders,
     AttachmentMetadata,
     Attendance,
@@ -37,6 +44,7 @@ from librus_python_api.models import (
     DetailField,
     DetailFieldKey,
     FinalGrades,
+    FormativeGrade,
     FrequencyMeasure,
     GatewayAttendance,
     GatewayAttendanceRecord,
@@ -110,6 +118,7 @@ from librus_python_api.models import (
     SchoolAverage,
     SchoolDetail,
     SchoolReference,
+    SchoolYearArchive,
     SendResult,
     SendStatus,
     SendSubmission,
@@ -127,9 +136,17 @@ from librus_python_api.models import (
 from librus_python_api.sending import SendAttempt
 from librus_python_api.service import AccountClient, LibrusService
 
-__version__ = "1.2.1"
+__version__ = "1.4.0"
 
 __all__ = [
+    "ArchiveAbsences",
+    "ArchiveAchievement",
+    "ArchiveCounts",
+    "ArchiveDescriptive",
+    "ArchiveMarks",
+    "ArchiveSubject",
+    "ArchiveYear",
+    "SchoolYearArchive",
     "AccountContext",
     "MessagingBackend",
     "ModernAccountData",
@@ -235,6 +252,7 @@ __all__ = [
     "DescriptiveGrade",
     "DescriptiveGradeSummary",
     "FinalGrades",
+    "FormativeGrade",
     "GradeKind",
     "GradeRecords",
     "Grades",

{librus_python_api-1.2.1 → librus_python_api-1.4.0}/src/librus_python_api/config.py

@@ -505,6 +505,14 @@ ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
                 True,
                 Evidence.INDEPENDENTLY_OBSERVED,
             ),
+            Endpoint(
+                "school_year_archive",
+                "GET",
+                "/archiwum",
+                SideEffect.NONE,
+                True,
+                Evidence.INDEPENDENTLY_OBSERVED,
+            ),
             Endpoint(
                 "agenda",
                 "POST",
@@ -713,6 +721,18 @@ ATTENDANCE_MAX_LESSONS = 4096
 ATTENDANCE_MAX_SUBJECTS = 1024
 # Collection recognition and detail retrieval share this central path family.
 ATTENDANCE_DETAIL_PATH_PREFIX = "/przegladaj_nb/szczegoly/"
+# Recognition only: formative detail links are classified, never requested.
+FORMATIVE_DETAIL_PATH_PREFIX = "/przegladaj_oceny/szczegoly/ksztaltujace/"
+FORMATIVE_HEADERS = (
+    "przedmiot",
+    "ocena kształtująca",
+    "kategoria",
+    "okres",
+    "data",
+    "typ",
+)
+FORMATIVE_TEMPLATE_ID = "000000"
+FORMATIVE_MAX_TEXT_LENGTH = 65536
 ATTENDANCE_DETAIL_MAX_FIELDS = 32
 ATTENDANCE_METADATA_CACHE_SIZE = 256
 ATTENDANCE_RESULT_CACHE_SIZE = 64
@@ -722,6 +742,35 @@ ANNOUNCEMENT_MAX_ITEMS = 256
 ANNOUNCEMENT_MAX_FIELD_LENGTH = 1024
 ANNOUNCEMENT_MAX_CONTENT_LENGTH = 65536
 ANNOUNCEMENT_MAX_TOTAL_TEXT_LENGTH = 262144
+
+# School-year archive (/archiwum): labels as rendered upstream, including the
+# absence spellings. Matching is case-insensitive and exact otherwise.
+ARCHIVE_TABLE_CLASSES = frozenset({"decorated"})
+ARCHIVE_ACHIEVEMENT_TABLE_CLASSES = frozenset({"decorated", "big", "center"})
+ARCHIVE_YEAR_PATTERN = (
+    r"Klasa: (?P<class_name>\S(?:.*\S)?) Rok: (?P<first>[0-9]{4})/(?P<second>[0-9]{4})"
+)
+ARCHIVE_PERIOD_LABELS = ("okres 1", "okres 2", "koniec roku")
+ARCHIVE_BEHAVIOUR_HEADING = "zachowanie"
+ARCHIVE_ABSENCES_HEADING = "nieobecności"
+ARCHIVE_ABSENCE_LABELS = MappingProxyType(
+    {
+        "nieusprawiedlione": "unexcused",
+        "usprawiedlione": "excused",
+        "spóźnienia": "late",
+    }
+)
+ARCHIVE_ACHIEVEMENT_HEADERS = ("data", "klasa", "kategoria", "osiągnięcie")
+ARCHIVE_YEAR_HEADER_TAGS = frozenset({"span", "b"})
+ARCHIVE_MAX_YEARS = 16
+ARCHIVE_MAX_SUBJECTS = 128
+ARCHIVE_MAX_DESCRIPTIVE = 32
+ARCHIVE_MAX_ACHIEVEMENTS = 256
+ARCHIVE_MAX_TEXT_LENGTH = 65536
+ARCHIVE_MAX_TOTAL_TEXT_LENGTH = 262144
+ARCHIVE_MAX_YEAR_HEADER_LENGTH = 1024 + len("Klasa:  Rok: 0000/0000")
+ARCHIVE_EMPTY_TITLE = "brak danych"
+ARCHIVE_EMPTY_BOX_CLASSES = frozenset({"warning-box", "information", "medium"})
 ANNOUNCEMENT_TABLE_CLASSES = frozenset(
     {"decorated", "big", "center", "printable", "margin-top"}
 )

librus_python_api-1.4.0/src/librus_python_api/formative_grades.py

@@ -0,0 +1,173 @@
+"""The grades page's formative-assessment table ("Oceny kształtujące").
+
+Authored from an owner-authorized structural observation; fixtures are
+synthetic. The table sits on the page `grades()` already reads, so no request
+is added. Its subject may be the pseudo-subject "KARTA SPOSTRZEŻEŃ". Unknown
+markup is unsupported; contradictions inside the known layout are parse errors.
+"""
+
+import re
+from collections.abc import Callable
+from typing import Literal, NoReturn, cast
+
+from lxml import html
+
+from librus_python_api import markup
+from librus_python_api.config import (
+    FORMATIVE_DETAIL_PATH_PREFIX,
+    FORMATIVE_HEADERS,
+    FORMATIVE_MAX_TEXT_LENGTH,
+    FORMATIVE_TEMPLATE_ID,
+    GRADE_MAX_RECORDS,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import FormativeGrade
+
+_SPAN = re.compile(r"[1-9][0-9]{0,5}")
+
+
+def _fail(kind: ErrorKind) -> NoReturn:
+    raise LibrusError(kind)
+
+
+def is_formative_table(table: html.HtmlElement) -> bool:
+    # Cheap structural gates first: other tables' header text is never read.
+    if not {"stretch", "decorated"} <= set(table.get("class", "").split()):
+        return False
+    heads = [row for row in markup.rows(table) if markup.in_header(row)]
+    if len(heads) != 1:
+        return False
+    cells = markup.cells(heads[0])
+    return len(cells) == len(FORMATIVE_HEADERS) and [
+        markup.text(cell).casefold() for cell in cells
+    ] == list(FORMATIVE_HEADERS)
+
+
+def _single(cell: html.HtmlElement) -> None:
+    if cell.get("colspan", "1") != "1" or cell.get("rowspan", "1") != "1":
+        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+
+
+def _plain(cell: html.HtmlElement) -> str:
+    _single(cell)
+    if any(isinstance(node.tag, str) for node in cell.iterdescendants()):
+        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+    return markup.text(cell)
+
+
+def _link(cell: html.HtmlElement) -> tuple[str, str]:
+    """The detail ID and full text of the assessment cell.
+
+    Observed: one link whose optional first child is an empty coloured
+    `span.grade-box` marker, followed by the text. Anything else is new markup.
+    """
+    _single(cell)
+    anchors = [node for node in cell if isinstance(node.tag, str)]
+    if len(anchors) != 1 or anchors[0].tag != "a":
+        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+    anchor = anchors[0]
+    children = [node for node in anchor.iterdescendants() if isinstance(node.tag, str)]
+    if children:
+        marker = children[0]
+        if (
+            len(children) != 1
+            or marker.getparent() is not anchor
+            or anchor.index(marker) != 0
+            or marker.tag != "span"
+            or "grade-box" not in marker.get("class", "").split()
+            or markup.text(marker)
+        ):
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+    identifier = markup.detail_id(anchor.get("href"), FORMATIVE_DETAIL_PATH_PREFIX)
+    if identifier is None:
+        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+    return identifier, markup.text(anchor, FORMATIVE_MAX_TEXT_LENGTH)
+
+
+def _template(row: html.HtmlElement) -> bool:
+    """A hidden, empty template entry (ID 000000) rendered for scripts.
+
+    Not observed inside this table (the page's observed template is an ordinary
+    grade link in a separate hidden table); kept narrow on purpose.
+    """
+    hidden = "display:none" in row.get("style", "").replace(" ", "").casefold()
+    links = [
+        markup.detail_id(anchor.get("href"), FORMATIVE_DETAIL_PATH_PREFIX)
+        for anchor in row.iter("a")
+    ]
+    if not hidden or links != [FORMATIVE_TEMPLATE_ID]:
+        return False
+    if any(markup.text(anchor) for anchor in row.iter("a")):
+        _fail(ErrorKind.PARSE)
+    return True
+
+
+def _item(subject: str, cells: list[html.HtmlElement]) -> FormativeGrade:
+    if len(cells) != 5:
+        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+    identifier, text = _link(cells[0])
+    category = _plain(cells[1])
+    period = _plain(cells[2])
+    day = markup.civil_date(_plain(cells[3]))
+    kind = _plain(cells[4])
+    if not text or period not in ("1", "2") or identifier == FORMATIVE_TEMPLATE_ID:
+        _fail(ErrorKind.PARSE)
+    return FormativeGrade(
+        subject,
+        text,
+        category,
+        cast(Literal[1, 2], int(period)),
+        day,
+        kind,
+        identifier,
+    )
+
+
+def read_formative_table(
+    table: html.HtmlElement, check_size: Callable[[int], None]
+) -> tuple[FormativeGrade, ...]:
+    """Rows in page order; a subject TH may span the rows of its group."""
+    if any(nested is not table for nested in table.iter("table")):
+        _fail(ErrorKind.PARSE)
+    items: list[FormativeGrade] = []
+    seen: set[str] = set()
+    subject, remaining = "", 0
+    for row in markup.rows(table):
+        if markup.in_header(row):
+            continue
+        cells = markup.cells(row)
+        if next(row.iterancestors("tfoot"), None) is not None:
+            if len(cells) != 1 or markup.text(cells[0]):
+                _fail(ErrorKind.PARSE)
+            continue
+        if _template(row):
+            continue
+        if remaining == 0:
+            if not cells or cells[0].tag != "th":
+                _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+            head = cells[0]
+            span = head.get("rowspan", "1")
+            if head.get("colspan", "1") != "1" or not _SPAN.fullmatch(span):
+                _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+            remaining = int(span)
+            if remaining > GRADE_MAX_RECORDS:
+                _fail(ErrorKind.LIMIT)
+            if any(isinstance(node.tag, str) for node in head.iterdescendants()):
+                _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+            subject = markup.text(head)
+            if not subject:
+                _fail(ErrorKind.PARSE)
+            cells = cells[1:]
+        elif cells and cells[0].tag == "th":
+            # A new subject before the spanning group ended.
+            _fail(ErrorKind.PARSE)
+        remaining -= 1
+        item = _item(subject, cells)
+        if item.detail_id in seen:
+            _fail(ErrorKind.PARSE)
+        seen.add(item.detail_id)
+        items.append(item)
+        check_size(len(items))
+    if remaining:
+        _fail(ErrorKind.PARSE)
+    return tuple(items)

{librus_python_api-1.2.1 → librus_python_api-1.4.0}/src/librus_python_api/grade_records.py

@@ -8,6 +8,7 @@ from lxml import html
 
 from librus_python_api import markup
 from librus_python_api.config import (
+    FORMATIVE_DETAIL_PATH_PREFIX,
     GRADE_AVERAGE_HEADERS,
     GRADE_BODY_PREFIX_COLUMNS,
     GRADE_CURRENT_HEADER,
@@ -23,11 +24,13 @@ from librus_python_api.config import (
     GRADE_PUBLICATION_TEACHER_LABEL,
 )
 from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.formative_grades import is_formative_table, read_formative_table
 from librus_python_api.grade_parsers import _locate, _subject_rows, _summary
 from librus_python_api.models import (
     Availability,
     DescriptiveGrade,
     DescriptiveGradeSummary,
+    FormativeGrade,
     GradeKind,
     GradeRecords,
     GradeSummaryValue,
@@ -138,14 +141,22 @@ class _Collection:
     subjects: set[tuple[bool, str]] = field(default_factory=set, repr=False)
     consumed: set[html.HtmlElement] = field(default_factory=set, repr=False)
     publication_rows: set[html.HtmlElement] = field(default_factory=set, repr=False)
+    formative: int = 0
 
     def check_size(self) -> None:
         if (
-            len(self.numeric) + len(self.descriptive) + len(self.descriptive_summaries)
+            len(self.numeric)
+            + len(self.descriptive)
+            + len(self.descriptive_summaries)
+            + self.formative
             > GRADE_MAX_RECORDS
         ):
             raise LibrusError(ErrorKind.LIMIT)
 
+    def count_formative(self, count: int) -> None:
+        self.formative = count
+        self.check_size()
+
     def subject(self, value: str, *, descriptive: bool = False) -> None:
         key = (descriptive, value)
         if not value or key in self.subjects:
@@ -400,7 +411,14 @@ def parse_grade_records(body: bytes) -> GradeRecords:
             numeric_tables.append(table)
     if len(numeric_tables) > 1:
         raise LibrusError(ErrorKind.PARSE)
+    formative_tables = [table for table in tables if is_formative_table(table)]
+    if len(formative_tables) > 1:
+        raise LibrusError(ErrorKind.PARSE)
+    formative: tuple[FormativeGrade, ...] = ()
     for table in tables:
+        if table in formative_tables:
+            formative = read_formative_table(table, collection.count_formative)
+            continue
         _read_publications(table, collection)
         if table in numeric_tables:
             _read_numeric_table(table, collection)
@@ -434,6 +452,15 @@ def parse_grade_records(body: bytes) -> GradeRecords:
                 ):
                     continue
             raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+    for anchor in document.iter("a"):
+        # A formative link outside both known tables is a new layout.
+        if markup.detail_id(
+            anchor.get("href"), FORMATIVE_DETAIL_PATH_PREFIX
+        ) and not any(
+            parent in numeric_tables or parent in formative_tables
+            for parent in anchor.iterancestors("table")
+        ):
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
     if not collection.subjects and not collection.descriptive:
         raise LibrusError(ErrorKind.PARSE)
     for descriptive, subject in sorted(collection.subjects):
@@ -451,4 +478,5 @@ def parse_grade_records(body: bytes) -> GradeRecords:
         tuple(collection.descriptive),
         tuple(collection.averages),
         tuple(collection.descriptive_summaries),
+        formative,
     )

{librus_python_api-1.2.1 → librus_python_api-1.4.0}/src/librus_python_api/markup.py

@@ -131,8 +131,19 @@ def attendance_detail_id(element: html.HtmlElement) -> str | None:
     )
     if match is None:
         return None
+    return detail_id(match[2], ATTENDANCE_DETAIL_PATH_PREFIX)
+
+
+def detail_id(link: str | None, prefix: str) -> str | None:
+    """The numeric ID of a relative or same-origin Synergia detail link.
+
+    Recognition only: the link is never followed. Queries, fragments, other
+    origins, credentials and non-digit IDs are not detail links.
+    """
+    if link is None or len(link) > GRADE_MAX_METADATA_LENGTH:
+        return None
     try:
-        target = urlsplit(match[2])
+        target = urlsplit(link)
     except ValueError:
         return None
     if target.query or target.fragment or target.username or target.password:
@@ -141,7 +152,7 @@ def attendance_detail_id(element: html.HtmlElement) -> str | None:
         expected = urlsplit(UPSTREAM_ORIGINS["synergia"])
         if (target.scheme, target.netloc) != (expected.scheme, expected.netloc):
             return None
-    if not target.path.startswith(ATTENDANCE_DETAIL_PATH_PREFIX):
+    if not target.path.startswith(prefix):
         return None
-    identifier = target.path[len(ATTENDANCE_DETAIL_PATH_PREFIX) :]
+    identifier = target.path[len(prefix) :]
     return identifier if re.fullmatch(r"[0-9]{1,64}", identifier) else None