librus-python-api 1.6.1__tar.gz → 1.6.2__tar.gz

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.6.2 (2026-10-19) - School layout variants and behaviour points
+
+Fixes for completed-lesson and grade pages that 1.6.1 rejected with
+`ParseError`. The layouts were observed offline in owner-provided pages and one
+issue report; the guarded live gate for them is pending. Public types and
+signatures are unchanged.
+
+- Completed lessons: accept the item range after the page count
+  (`Strona 1 z 3 Pozycje 1..20 z 47`) and require it to match the parsed rows;
+  ignore the `decorated filters` date-filter table; locate the optional
+  `e-Tablica` column by its header label (nonempty cells raise
+  `UnsupportedCapabilityError`); skip a blank full-width closing row.
+- Completed lessons: strip whitespace and line breaks around the subject/teacher
+  comma, so `<b>Subject</b>, <br>Teacher` no longer yields the whole cell as the
+  subject with no teacher.
+- Grades: recognize behaviour points in the `Zachowanie` row (a starting-points
+  or running-total tooltip, and point entries linking to behaviour details).
+  They are validated and not returned as grades, so the whole grade read no
+  longer fails on them (#76). Other content beside the points tooltip still
+  fails.
+- Internal: share aiohttp session setup and message send dispatch in the
+  transport, remove an unused recipient constant, orphaned 0.4.x qualification
+  scripts and dead test-support code, and correct stale status sentences in the
+  contracts. Behaviour is unchanged.
+- Development dependencies and pinned GitHub Actions are updated; runtime
+  dependency ranges are unchanged.
+
 ## 1.6.1 (2026-10-12) - Sunday grade dates and calendar closures
 
 - Accept both observed Sunday tooltip labels, `nd.` and `ndz.`, while retaining

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.6.1
+Version: 1.6.2
 Summary: Independent bounded async Librus Synergia client
 Project-URL: Repository, https://github.com/krzysztofbury/librus-python-api
 Project-URL: Issues, https://github.com/krzysztofbury/librus-python-api/issues
@@ -42,7 +42,8 @@ private ACLs. Windows installations include `pywin32` and `tzdata` automatically
 Network paths, reparse-point paths and unsafe storage permissions fail closed.
 See [platform requirements](contracts/persistence.md#windows-disk-boundary-25).
 
-**Status:** `1.6.1` fixes Sunday grade-date labels and calendar closure events.
+**Status:** `1.6.2` accepts more 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
 remain available. See [verification](VERIFICATION.md).
 The stable 1.x API does not guarantee every school layout. School features depend
@@ -54,7 +55,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.6.1
+python -m pip install librus-python-api==1.6.2
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -70,7 +71,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.6.1-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.6.2-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/README.md

@@ -16,7 +16,8 @@ private ACLs. Windows installations include `pywin32` and `tzdata` automatically
 Network paths, reparse-point paths and unsafe storage permissions fail closed.
 See [platform requirements](contracts/persistence.md#windows-disk-boundary-25).
 
-**Status:** `1.6.1` fixes Sunday grade-date labels and calendar closure events.
+**Status:** `1.6.2` accepts more 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
 remain available. See [verification](VERIFICATION.md).
 The stable 1.x API does not guarantee every school layout. School features depend
@@ -28,7 +29,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.6.1
+python -m pip install librus-python-api==1.6.2
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -44,7 +45,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.6.1-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.6.2-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/pyproject.toml

@@ -35,7 +35,7 @@ dev = [
   "openapi-spec-validator>=0.7,<0.10",
   "pytest>=9,<10",
   "pyyaml>=6,<7",
-  "ruff>=0.15,<0.17",
+  "ruff>=0.15,<0.18",
   "types-pyyaml>=6,<7",
   "types-lxml>=2026.2.16,<2027",
   "types-pywin32>=312,<400",

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/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.6.1"
+__version__ = "1.6.2"
 
 __all__ = [
     "ArchiveAbsences",

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/src/librus_python_api/completed_lessons.py

@@ -9,10 +9,12 @@ from lxml import html
 
 from librus_python_api import markup
 from librus_python_api.config import (
+    COMPLETED_LESSONS_COLUMNS,
     COMPLETED_LESSONS_MAX_BATCH_ITEMS,
     COMPLETED_LESSONS_MAX_BATCH_PAGES,
     COMPLETED_LESSONS_MAX_PAGE_COUNT,
     COMPLETED_LESSONS_MAX_PAGE_ITEMS,
+    COMPLETED_LESSONS_OPTIONAL_HEADERS,
     SCHOOL_MAX_CONTENT_LENGTH,
     SCHOOL_MAX_FIELD_LENGTH,
     SCHOOL_MAX_TOTAL_TEXT_LENGTH,
@@ -65,7 +67,8 @@ def validate_selection(
     completed_lessons_form(cursor.start, cursor.end, cursor.page)
 
 
-def _pagination(document: html.HtmlElement, page: int) -> int:
+def _pagination(document: html.HtmlElement, page: int) -> tuple[int, int | None]:
+    """The page count and, when shown, the number of rows the page reports."""
     containers = [
         node
         for node in document.iter("div")
@@ -74,14 +77,19 @@ def _pagination(document: html.HtmlElement, page: int) -> int:
     if not containers:
         if page != 0:
             raise LibrusError(ErrorKind.PARSE)
-        return 1
+        return 1, None
     if len(containers) != 1:
         raise LibrusError(ErrorKind.PARSE)
     spans = [node for node in containers[0] if node.tag == "span"]
     if len(spans) != 1:
         raise LibrusError(ErrorKind.PARSE)
     value = markup.text(spans[0], SCHOOL_MAX_FIELD_LENGTH)
-    match = re.fullmatch(r"(?:Strona\s+)?([0-9]{1,4})\s+z\s+([0-9]{1,4})", value, re.I)
+    match = re.fullmatch(
+        r"(?:Strona\s+)?([0-9]{1,4})\s+z\s+([0-9]{1,4})"
+        r"(?:\s+Pozycje\s+([0-9]{1,6})\.\.([0-9]{1,6})\s+z\s+([0-9]{1,6}))?",
+        value,
+        re.I,
+    )
     if match is None:
         raise LibrusError(ErrorKind.PARSE)
     current, count = int(match[1]), int(match[2])
@@ -89,7 +97,53 @@ def _pagination(document: html.HtmlElement, page: int) -> int:
         raise LibrusError(ErrorKind.LIMIT)
     if not 1 <= current <= count or current != page + 1:
         raise LibrusError(ErrorKind.PARSE)
-    return count
+    if match[3] is None:
+        return count, None
+    # Some schools append the item range: "Pozycje first..last z total".
+    first, last, total = int(match[3]), int(match[4]), int(match[5])
+    if not 1 <= first <= last <= total:
+        raise LibrusError(ErrorKind.PARSE)
+    return count, last - first + 1
+
+
+def _optional_columns(table: html.HtmlElement) -> frozenset[int]:
+    """Row positions of optional columns, located by their header labels."""
+    positions: set[int] = set()
+    for row in markup.rows(table):
+        if not markup.in_header(row):
+            continue
+        position = 0
+        labels = [
+            (cell, markup.text(cell, SCHOOL_MAX_FIELD_LENGTH))
+            for cell in markup.cells(row)
+        ]
+        if not any(label in COMPLETED_LESSONS_OPTIONAL_HEADERS for _, label in labels):
+            continue
+        if positions:
+            raise LibrusError(ErrorKind.PARSE)
+        for cell, label in labels:
+            span = markup.colspan(cell)
+            if label in COMPLETED_LESSONS_OPTIONAL_HEADERS:
+                if span != 1:
+                    raise LibrusError(ErrorKind.PARSE)
+                positions.add(position)
+            position += span
+        # A labelled header must describe exactly the row layout it extends.
+        if position != COMPLETED_LESSONS_COLUMNS + len(positions):
+            raise LibrusError(ErrorKind.PARSE)
+    return frozenset(positions)
+
+
+def _closing_row(row: html.HtmlElement, width: int) -> bool:
+    """A blank full-width row that closes some schools' tables, not a lesson."""
+    cells = markup.cells(row)
+    return (
+        len(cells) == 1
+        and cells[0].tag == "td"
+        and markup.colspan(cells[0]) == width
+        and not any(isinstance(node.tag, str) for node in cells[0])
+        and not markup.text(cells[0], SCHOOL_MAX_FIELD_LENGTH)
+    )
 
 
 def _day(value: str) -> date:
@@ -109,15 +163,24 @@ def _day(value: str) -> date:
     return result
 
 
-def _lesson(row: html.HtmlElement, start: date, end: date) -> CompletedLesson:
+def _lesson(
+    row: html.HtmlElement, start: date, end: date, optional: frozenset[int]
+) -> CompletedLesson:
     cells = markup.cells(row)
-    if len(cells) != 7 or any(
+    if len(cells) != COMPLETED_LESSONS_COLUMNS + len(optional) or any(
         cell.tag != "td"
         or cell.get("rowspan", "1") != "1"
         or cell.get("colspan", "1") != "1"
         for cell in cells
     ):
         raise LibrusError(ErrorKind.PARSE)
+    for index in optional:
+        # Content in an optional column is not modelled; never drop it silently.
+        if any(isinstance(node.tag, str) for node in cells[index]) or markup.text(
+            cells[index], SCHOOL_MAX_FIELD_LENGTH
+        ):
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+    cells = [cell for index, cell in enumerate(cells) if index not in optional]
     date_cells = [
         c for c in cells if {"center", "small"} <= set(c.get("class", "").split())
     ]
@@ -140,7 +203,8 @@ def _lesson(row: html.HtmlElement, start: date, end: date) -> CompletedLesson:
     raw_number, combined, topic, z_value, symbol = values
     if raw_number not in {"", "-"} and re.fullmatch(r"[0-9]{1,2}", raw_number) is None:
         raise LibrusError(ErrorKind.PARSE)
-    names = combined.split(", ")
+    # Some schools render "<b>Subject</b>, <br>Teacher" or pad the comma.
+    names = [name.strip() for name in combined.split(",")]
     subject, teacher = (names[0], names[1]) if len(names) == 2 else (combined, None)
     if not subject or teacher == "":
         raise LibrusError(ErrorKind.PARSE)
@@ -174,9 +238,13 @@ def parse_completed_lessons(
 ) -> tuple[tuple[CompletedLesson, ...], int, str]:
     completed_lessons_form(start, end, page)
     document = parse_page(body)
-    count = _pagination(document, page)
+    count, reported = _pagination(document, page)
+    # A date-filter form table shares the "decorated" class with the data table.
     tables = [
-        t for t in document.iter("table") if "decorated" in t.get("class", "").split()
+        t
+        for t in document.iter("table")
+        if "decorated" in (classes := t.get("class", "").split())
+        and "filters" not in classes
     ]
     empty = [
         n
@@ -190,10 +258,12 @@ def parse_completed_lessons(
     if tables:
         if list(tables[0].iterdescendants("table")):
             raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
-        for row in markup.rows(tables[0]):
-            if next(row.iterancestors("thead"), None) is not None:
-                continue
-            item = _lesson(row, start, end)
+        optional = _optional_columns(tables[0])
+        lines = [row for row in markup.rows(tables[0]) if not markup.in_header(row)]
+        if lines and _closing_row(lines[-1], COMPLETED_LESSONS_COLUMNS + len(optional)):
+            lines.pop()
+        for row in lines:
+            item = _lesson(row, start, end, optional)
             total += sum(len(v) for v in astuple(item) if isinstance(v, str))
             items.append(item)
             if (
@@ -201,6 +271,8 @@ def parse_completed_lessons(
                 or total > SCHOOL_MAX_TOTAL_TEXT_LENGTH
             ):
                 raise LibrusError(ErrorKind.LIMIT)
+    if reported is not None and reported != len(items):
+        raise LibrusError(ErrorKind.PARSE)
     if (items and empty) or (not items and (not empty or count != 1 or page != 0)):
         raise LibrusError(ErrorKind.PARSE)
     # An unrecognized notice next to an empty marker is not a valid empty page.

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/src/librus_python_api/config.py

@@ -731,6 +731,8 @@ ATTENDANCE_MAX_SUBJECTS = 1024
 ATTENDANCE_DETAIL_PATH_PREFIX = "/przegladaj_nb/szczegoly/"
 # Recognition only: formative detail links are classified, never requested.
 FORMATIVE_DETAIL_PATH_PREFIX = "/przegladaj_oceny/szczegoly/ksztaltujace/"
+# Recognition only: behaviour-point detail links are classified, never requested.
+BEHAVIOUR_POINTS_DETAIL_PATH_PREFIX = "/przegladaj_oceny/zachowanie_szczegoly/"
 FORMATIVE_HEADERS = (
     "przedmiot",
     "ocena kształtująca",
@@ -882,6 +884,10 @@ COMPLETED_LESSONS_MAX_PAGE_COUNT = 1000
 COMPLETED_LESSONS_MAX_PAGE_ITEMS = 256
 COMPLETED_LESSONS_MAX_BATCH_PAGES = 8
 COMPLETED_LESSONS_MAX_BATCH_ITEMS = 256
+# Header labels of columns some schools add to the completed-lesson table. Their
+# content is not modelled: such a column must be empty in every lesson row.
+COMPLETED_LESSONS_OPTIONAL_HEADERS = frozenset({"e-Tablica"})
+COMPLETED_LESSONS_COLUMNS = 7
 AGENDA_DETAIL_PATH_PREFIX = "/terminarz/szczegoly/"
 # Recognition only: closure details are not ordinary agenda-detail references.
 AGENDA_CLOSURE_DETAIL_PATH_PREFIX = "/terminarz/szczegoly_wolne/"
@@ -931,7 +937,6 @@ MODERN_DIRECTORY_QUERIES = MappingProxyType(
         "modern_recipients": (("receiverType", "parentsCouncil"),),
     }
 )
-MODERN_SUPPORTED_RECIPIENT_TYPE = "parentsCouncil"
 MODERN_RECIPIENT_OPERATIONS = MappingProxyType(
     {
         **{

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/src/librus_python_api/detail_fields.py

@@ -34,7 +34,6 @@ def normalize_detail_fields(
     fields: tuple[tuple[str, str], ...],
     kind: Literal["agenda", "homework", "attendance"],
 ) -> tuple[DetailField, ...]:
-    """Run after bounded HTML parsing, before publishing or caching a result."""
     labels: set[str] = set()
     keys: set[DetailFieldKey] = set()
     result = []

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/src/librus_python_api/formative_grades.py

@@ -31,7 +31,6 @@ def _fail(kind: ErrorKind) -> NoReturn:
 
 
 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)]

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/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 (
+    BEHAVIOUR_POINTS_DETAIL_PATH_PREFIX,
     FORMATIVE_DETAIL_PATH_PREFIX,
     GRADE_AVERAGE_HEADERS,
     GRADE_BODY_PREFIX_COLUMNS,
@@ -16,6 +17,7 @@ from librus_python_api.config import (
     GRADE_MAX_METADATA_LENGTH,
     GRADE_MAX_RECORDS,
     GRADE_MAX_SUBJECTS,
+    GRADE_MERGED_SUBJECTS,
     GRADE_PERIOD_HEADERS,
     GRADE_PREDICTED_ANNUAL_HEADER,
     GRADE_PREDICTED_PERIOD_HEADERS,
@@ -174,6 +176,50 @@ def _boxes(cell: html.HtmlElement) -> list[html.HtmlElement]:
     ]
 
 
+def _behaviour_points(cell: html.HtmlElement, collection: _Collection) -> bool:
+    """Recognize and validate a behaviour-points cell; points are not grades.
+
+    The cell holds one points tooltip (starting points or a running total; its
+    title is not interpreted) and point entries linking to behaviour details,
+    each with its own unlabelled tooltip. Any other content next to the points
+    tooltip fails instead of being skipped.
+    """
+    tallies = [
+        node
+        for node in cell
+        if node.tag == "span" and "tooltip" in node.get("class", "").split()
+    ]
+    if not tallies:
+        return False
+    elements = [node for node in cell if isinstance(node.tag, str)]
+    boxes = [node for node in elements if node not in tallies]
+    if (
+        len(tallies) != 1
+        or len(tallies[0])
+        or not re.fullmatch(r"-?[0-9]{1,4}", markup.text(tallies[0]))
+        or (cell.text or "").strip()
+        or any((node.tail or "").strip() for node in cell)
+        or _boxes(cell) != boxes
+    ):
+        raise LibrusError(ErrorKind.PARSE)
+    for box in boxes:
+        anchors = [node for node in box if isinstance(node.tag, str)]
+        if (
+            box.getparent() is not cell
+            or len(anchors) != 1
+            or anchors[0].tag != "a"
+            or len(anchors[0])
+            or markup.detail_id(
+                anchors[0].get("href"), BEHAVIOUR_POINTS_DETAIL_PATH_PREFIX
+            )
+            is None
+            or not re.fullmatch(r"[+-]?[0-9]{1,4}", markup.text(anchors[0]))
+        ):
+            raise LibrusError(ErrorKind.PARSE)
+        collection.consumed.add(box)
+    return True
+
+
 def _entries(
     cell: html.HtmlElement,
     subject: str,
@@ -320,9 +366,13 @@ def _read_numeric_table(table: html.HtmlElement, collection: _Collection) -> Non
         seen: set[html.HtmlElement] = set()
         for period, index in enumerate(current, start=1):
             if columns[index] not in seen:
-                _entries(
-                    columns[index], subject, cast(Literal[1, 2], period), collection
-                )
+                if not (
+                    subject in GRADE_MERGED_SUBJECTS
+                    and _behaviour_points(columns[index], collection)
+                ):
+                    _entries(
+                        columns[index], subject, cast(Literal[1, 2], period), collection
+                    )
                 seen.add(columns[index])
         for (period, kind), index in periods.items():
             cell = columns[index]

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/src/librus_python_api/notification_persistence.py

@@ -144,7 +144,6 @@ def _seen_after(
 class NotificationStore(_SQLiteStore):
     """Private native recovery store. No MCP files, auto migration or live access.
 
-    Context locks require POSIX flock. Unsupported platforms fail explicitly.
     Raw checkpoints contain private account/content metadata, never HTTP cookies.
     """
 

{librus_python_api-1.6.1 → librus_python_api-1.6.2}/src/librus_python_api/persistence.py

@@ -1,4 +1,4 @@
-"""Explicit optional durable sending, independent of MCP and core transport."""
+"""Durable sending and the notification store and workflow."""
 
 import hashlib
 import json