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

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

@@ -240,6 +240,15 @@ value. The same items stay in `numeric`/`descriptive` unchanged; their
 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).
 
+Point grades (1.7.0) come from the "Oceny punktowe" table that point-grade
+schools show beside, or instead of, the ordinary table. Its entries are
+`NumericGrade`s in `numeric` whose computed `point_grade_id` property holds the
+point-grade detail ID; `raw` is then a score on the scale named by `category`,
+such as `(0-100)`, not a grade symbol. The table's "Wyn." period results are
+`GradeRecords.point_results` (`SchoolAverage`s on the score scale, never mixed
+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).
+
 ## Attendance
 
 - `attendance(view=AttendanceView.ALL)` returns `Attendance` with

{librus_python_api-1.6.4 → librus_python_api-1.7.1}/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 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
+affected school's real point-grade page and a live grade read. Public types
+and signatures are unchanged.
+
+- Grades: a teacher's multi-line `Komentarz` continues on unlabelled tooltip
+  lines and is kept with its line breaks. Every grade read of an account with
+  such a comment failed in all releases up to 1.7.0; any other unlabelled
+  tooltip line still fails.
+- Point grades: a formative entry among the point entries is accepted as the
+  formative mirror it is; the empty footer row wider than the table is
+  skipped; titles that break their own label (`Ocena śródroczna <br> z
+  pierwszego okresu`) name the period columns, so point midterm grades are
+  read. These rules apply to point tables only.
+- Formative assessments: assessment text may contain line breaks. 1.7.0 and
+  earlier failed such a table with `UnsupportedCapabilityError`.
+
+## 1.7.0 (2026-10-27) - Point grades
+
+Reads the "Oceny punktowe" table that point-grade schools show on the grades
+page. Its presence made `grades()`, `grades_window()` and `final_grades()` fail
+with `ParseError` for those accounts. The layout was established offline from
+a relayed screenshot and a public issue report; live qualification on a
+point-grade account is pending.
+
+- Grades: point entries are returned in `numeric` with their raw score, scale
+  category and tooltip fields. The new computed `NumericGrade.point_grade_id`
+  property identifies them. It is not a field, so notification identities are
+  unchanged. A current point entry without its point-grade detail link fails
+  instead of passing as a grade symbol.
+- Grades: the new `GradeRecords.point_results` holds the "Wyn." period
+  results on the score scale. They are never merged into `averages`, which
+  stay the ordinary grade-scale means.
+- Grades: a period grade that both tables show is one record.
+- Final grades: a point table with titled summary columns (midterm, predicted
+  or annual) adds its subjects; a missing column is unavailable. For a subject
+  in both tables, each value is merged on its own: an assigned value fills an
+  unassigned one, equal values are one value and two different assigned values
+  fail.
+- More than one point table, duplicate point subjects, misaligned rows and an
+  ordinary grade table without an annual column fail instead of returning
+  partial output.
+
 ## 1.6.4 (2026-10-26) - Message body rendering security fix
 
 Fixes a denial of service in message body rendering. Public types, signatures

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.6.4
+Version: 1.7.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,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.6.4` renders message bodies in linear time, so a crafted body can
-no longer stall a client, and keeps the 1.6.2 completed-lesson and grade layouts,
-including behaviour points, which are validated and not reported as grades.
+**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
+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
 remain available. See [verification](VERIFICATION.md).
 The stable 1.x API does not guarantee every school layout. School features depend
@@ -56,7 +57,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.4
+python -m pip install librus-python-api==1.7.1
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -72,7 +73,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.6.4-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.7.1-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.

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

@@ -16,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.6.4` renders message bodies in linear time, so a crafted body can
-no longer stall a client, and keeps the 1.6.2 completed-lesson and grade layouts,
-including behaviour points, which are validated and not reported as grades.
+**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
+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
 remain available. See [verification](VERIFICATION.md).
 The stable 1.x API does not guarantee every school layout. School features depend
@@ -30,7 +31,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.4
+python -m pip install librus-python-api==1.7.1
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -46,7 +47,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.6.4-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.7.1-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.

{librus_python_api-1.6.4 → librus_python_api-1.7.1}/pyproject.toml

@@ -41,6 +41,7 @@ dev = [
   "types-pywin32>=312,<400",
   "pre-commit>=4.6,<5",
   "pip-audit>=2.10,<3",
+  "pytest-timeout>=2.3,<3",
 ]
 
 [tool.hatch.version]
@@ -56,8 +57,10 @@ include = ["/src", "/pyproject.toml", "/uv.lock", "/README.md", "/SECURITY.md",
 testpaths = ["tests"]
 pythonpath = ["."]
 addopts = "--import-mode=importlib -ra -m 'not performance'"
-# Dump every thread's stack if one test runs this long, so a hang names itself.
-faulthandler_timeout = 300
+# A hung test dumps every thread's stack, then fails with its id instead of
+# holding the job until its timeout (#64, #98). The slowest test takes 9 s.
+faulthandler_timeout = 100
+timeout = 120
 markers = [
   "performance: opt-in hardware-sensitive resource measurements",
 ]

{librus_python_api-1.6.4 → librus_python_api-1.7.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.6.4"
+__version__ = "1.7.1"
 
 __all__ = [
     "ArchiveAbsences",

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

@@ -659,6 +659,12 @@ GRADE_MAX_SUBJECTS = 128
 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.
+TOOLTIP_MULTILINE_LABELS = frozenset({"Komentarz"})
+# 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")
 GRADE_VIEW_FIELDS = MappingProxyType(
     {
         "all": "zmiany_logowanie_wszystkie",
@@ -671,6 +677,11 @@ GRADE_EMPTY_MARKERS = frozenset({"", "-", "Brak ocen"})
 GRADE_AVERAGE_HEADERS = MappingProxyType(
     {"Średnia ocen": 1, "Średnia ocen z drugiego okresu": 2, "Średnia roczna": 0}
 )
+# Point tables label their period results by visible text, not by title. Only
+# "Wyn.I" was observed (owner-relayed screenshot, 2026-10-27); the others
+# follow the same period naming as the ordinary I/II/R summary columns.
+GRADE_POINT_RESULT_HEADER = re.compile(r"Wyn\.\s?(I|II|R)")
+GRADE_POINT_RESULT_PERIODS = MappingProxyType({"I": 1, "II": 2, "R": 0})
 GRADE_MAX_RECORDS = 2048
 GRADE_MAX_METADATA_LENGTH = 8192
 GRADE_MAX_METADATA_FIELDS = 32
@@ -733,6 +744,8 @@ ATTENDANCE_DETAIL_PATH_PREFIX = "/przegladaj_nb/szczegoly/"
 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/"
+# Recognition only: point-grade detail links are classified, never requested.
+POINT_GRADE_DETAIL_PATH_PREFIX = "/przegladaj_oceny_punktowe/szczegoly/"
 FORMATIVE_HEADERS = (
     "przedmiot",
     "ocena kształtująca",

{librus_python_api-1.6.4 → librus_python_api-1.7.1}/src/librus_python_api/formative_grades.py

@@ -58,7 +58,8 @@ 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.
+    `span.grade-box` marker, followed by the text, which may contain empty
+    line breaks (2026-10-27). Anything else is new markup.
     """
     _single(cell)
     anchors = [node for node in cell if isinstance(node.tag, str)]
@@ -66,6 +67,10 @@ def _link(cell: html.HtmlElement) -> tuple[str, str]:
         _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
     anchor = anchors[0]
     children = [node for node in anchor.iterdescendants() if isinstance(node.tag, str)]
+    breaks = [node for node in children if node.tag == "br"]
+    if any(node.getparent() is not anchor or len(node) for node in breaks):
+        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+    children = [node for node in children if node.tag != "br"]
     if children:
         marker = children[0]
         if (

librus_python_api-1.7.1/src/librus_python_api/grade_parsers.py

@@ -0,0 +1,297 @@
+"""Original bounded HTML summary parsing from source-informed requirements."""
+
+import re
+from collections.abc import Iterator
+
+from lxml import html
+
+from librus_python_api import markup
+from librus_python_api.config import (
+    GRADE_BODY_PREFIX_COLUMNS,
+    GRADE_CURRENT_HEADER,
+    GRADE_EMPTY_MARKERS,
+    GRADE_INLINE_DETAIL_LABEL,
+    GRADE_MAX_COLUMNS,
+    GRADE_MAX_SUBJECTS,
+    GRADE_MAX_VALUE_LENGTH,
+    GRADE_MERGED_SUBJECTS,
+    GRADE_POINT_ROW_NODE,
+    GRADE_SUMMARY_HEADERS,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import (
+    Availability,
+    GradeSummaryValue,
+    SubjectGradeSummary,
+)
+from librus_python_api.parsers import parse_page
+
+
+def title_label(title: str, *, points: bool = False) -> str:
+    """A header title's label: its first line, or for a point table all of it.
+
+    Ordinary titles append an explanation after a line break. Point tables
+    break the label itself ("Ocena śródroczna <br> z pierwszego okresu").
+    """
+    if points:
+        return " ".join(re.sub(r"<br\s*/?>", " ", title, flags=re.I).split())
+    return " ".join(re.split(r"<br\s*/?>", title, flags=re.I)[0].split())
+
+
+def _summary_field(cell: html.HtmlElement, *, points: bool = False) -> str | None:
+    title = cell.get("title", "")
+    if len(title) > GRADE_MAX_VALUE_LENGTH:
+        raise LibrusError(ErrorKind.LIMIT)
+    return GRADE_SUMMARY_HEADERS.get(title_label(title, points=points))
+
+
+def _header(
+    row: html.HtmlElement, *, points: bool = False
+) -> tuple[dict[str, int], int]:
+    fields: dict[str, int] = {}
+    position = GRADE_BODY_PREFIX_COLUMNS
+    for cell in markup.cells(row):
+        span = markup.colspan(cell)
+        if position + span > GRADE_MAX_COLUMNS:
+            raise LibrusError(ErrorKind.LIMIT)
+        field = _summary_field(cell, points=points)
+        if field is not None:
+            if field in fields:
+                raise LibrusError(ErrorKind.PARSE)
+            fields[field] = position
+        position += span
+    return fields, position
+
+
+def is_point_table(table: html.HtmlElement) -> bool:
+    """A grade table whose subject rows carry point-grade expander images."""
+    if not {"decorated", "stretch"} <= set(table.get("class", "").split()):
+        return False
+    return any(
+        GRADE_POINT_ROW_NODE.fullmatch(image.get("id", ""))
+        for row in markup.rows(table)
+        for cell in markup.cells(row)[:1]
+        for image in cell.iter("img")
+    )
+
+
+def _current_header(table: html.HtmlElement) -> bool:
+    """A grade table: decorated, with a current-grade header row."""
+    return {"decorated", "stretch"} <= set(table.get("class", "").split()) and any(
+        next(row.iterancestors("thead"), None) is not None
+        and any(markup.text(cell) == GRADE_CURRENT_HEADER for cell in markup.cells(row))
+        for row in markup.rows(table)
+    )
+
+
+def point_layout(table: html.HtmlElement) -> tuple[dict[str, int], int]:
+    """Summary fields and width from the point table's current-grade header row.
+
+    Point tables are not required to have an annual column, so the row with
+    the two current-grade headers defines the body alignment instead.
+    """
+    headers = [
+        row
+        for row in markup.rows(table)
+        if next(row.iterancestors("thead"), None) is not None
+        and any(markup.text(cell) == GRADE_CURRENT_HEADER for cell in markup.cells(row))
+    ]
+    if len(headers) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    return _header(headers[0], points=True)
+
+
+def _candidates(
+    document: html.HtmlElement,
+) -> list[tuple[html.HtmlElement, dict[str, int], int]]:
+    candidates: list[tuple[html.HtmlElement, dict[str, int], int]] = []
+    for table in document.iter("table"):
+        if not {"decorated", "stretch"} <= set(table.get("class", "").split()):
+            continue
+        if is_point_table(table):
+            continue
+        for row in markup.rows(table):
+            if next(row.iterancestors("thead"), None) is None:
+                continue
+            # Group-heading rows can span the entire table. Only the row with
+            # an annual summary title defines the body alignment contract.
+            if not any(_summary_field(cell) == "annual" for cell in markup.cells(row)):
+                continue
+            fields, width = _header(row)
+            candidates.append((table, fields, width))
+    return candidates
+
+
+def _locate(
+    document: html.HtmlElement,
+) -> tuple[html.HtmlElement, dict[str, int], int]:
+    candidates = _candidates(document)
+    if len(candidates) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    return candidates[0]
+
+
+def _outside_nested_tables(row: html.HtmlElement) -> str:
+    """Reject a subject row masquerading as an expanded-detail wrapper."""
+    parts: list[str] = []
+    pending = [row]
+    while pending:
+        element = pending.pop()
+        if element.tail:
+            parts.append(element.tail)
+        if element.tag == "table":
+            continue
+        if element.text:
+            parts.append(element.text)
+        pending.extend(element)
+    return " ".join(parts).strip()
+
+
+def _subject_columns(
+    cells: list[html.HtmlElement], width: int
+) -> tuple[str, list[html.HtmlElement]]:
+    if len(cells) < GRADE_BODY_PREFIX_COLUMNS:
+        raise LibrusError(ErrorKind.PARSE)
+    subject = markup.text(cells[1])
+    if not subject or markup.colspan(cells[0]) != 1 or markup.colspan(cells[1]) != 1:
+        raise LibrusError(ErrorKind.PARSE)
+    columns: list[html.HtmlElement] = []
+    for cell in cells:
+        span = markup.colspan(cell)
+        if span > 1 and subject not in GRADE_MERGED_SUBJECTS:
+            raise LibrusError(ErrorKind.PARSE)
+        if len(columns) + span > GRADE_MAX_COLUMNS:
+            raise LibrusError(ErrorKind.LIMIT)
+        columns.extend([cell] * span)
+    if len(columns) != width:
+        raise LibrusError(ErrorKind.PARSE)
+    return subject, columns
+
+
+def _summary(
+    cells: list[html.HtmlElement],
+    fields: dict[str, int],
+    width: int,
+) -> SubjectGradeSummary:
+    subject, columns = _subject_columns(cells, width)
+    selected = [columns[index] for index in fields.values()]
+    if len({id(cell) for cell in selected}) != len(selected):
+        # A single merged value cannot mean two different summary fields.
+        raise LibrusError(ErrorKind.PARSE)
+    values = {
+        name: GradeSummaryValue(Availability.AVAILABLE, markup.text(columns[index]))
+        for name, index in fields.items()
+    }
+    absent = GradeSummaryValue(Availability.UNAVAILABLE, None)
+    return SubjectGradeSummary(
+        subject,
+        values.get("midterm", absent),
+        values.get("predicted_annual", absent),
+        # Only a point table may lack the annual column.
+        values.get("annual", absent),
+    )
+
+
+def _subject_rows(
+    table: html.HtmlElement, width: int, *, points: bool = False
+) -> Iterator[list[html.HtmlElement]]:
+    for row in markup.rows(table):
+        if next(row.iterancestors("thead"), None) is not None:
+            continue
+        cells = markup.cells(row)
+        if not cells:
+            raise LibrusError(ErrorKind.PARSE)
+        # The observed point table closes with an empty footer cell wider than
+        # the table; only an empty footer row is skipped.
+        if (
+            points
+            and next(row.iterancestors("tfoot"), None) is not None
+            and not any(markup.text(cell) for cell in cells)
+        ):
+            continue
+        if list(row.iter("table")):
+            if _outside_nested_tables(row):
+                raise LibrusError(ErrorKind.PARSE)
+            continue
+        # An empty full-width layout spacer is not an unassigned subject. Keep
+        # this exception narrow: content or a different width remains malformed.
+        if (
+            len(cells) == 1
+            and markup.colspan(cells[0]) == width
+            and not markup.text(cells[0])
+        ):
+            continue
+        # Expanded inline detail labels are not subjects. Recognize this narrow
+        # source-informed variant, never discard arbitrary malformed subject rows.
+        if len(cells) > 1 and markup.text(cells[1]) == GRADE_INLINE_DETAIL_LABEL:
+            continue
+        yield cells
+
+
+def merge_value(
+    first: GradeSummaryValue, other: GradeSummaryValue
+) -> GradeSummaryValue:
+    """One subject's value shown by both grade tables.
+
+    An assigned value fills an unassigned one and equal values are one value;
+    two different assigned values are ambiguous.
+    """
+    first_set, other_set = (
+        value.raw is not None and value.raw not in GRADE_EMPTY_MARKERS
+        for value in (first, other)
+    )
+    if first_set and other_set and first.raw != other.raw:
+        raise LibrusError(ErrorKind.PARSE)
+    if other_set and not first_set:
+        return other
+    # An unassigned shown column still says more than an absent one.
+    return other if first.availability is Availability.UNAVAILABLE else first
+
+
+def parse_final_grades(body: bytes) -> tuple[SubjectGradeSummary, ...]:
+    document = parse_page(body)
+    point_tables = [table for table in document.iter("table") if is_point_table(table)]
+    if len(point_tables) > 1:
+        raise LibrusError(ErrorKind.PARSE)
+    # A point-grade school may show the ordinary table or omit it. An ordinary
+    # grade table without an annual column is still an unknown layout.
+    sources = _candidates(document)
+    if len(sources) > 1 or not (sources or point_tables):
+        raise LibrusError(ErrorKind.PARSE)
+    if point_tables:
+        located = {id(table) for table, _, _ in sources}
+        if any(
+            _current_header(table) and id(table) not in located
+            for table in document.iter("table")
+            if table not in point_tables
+        ):
+            raise LibrusError(ErrorKind.PARSE)
+        fields, width = point_layout(point_tables[0])
+        if fields:
+            sources.append((point_tables[0], fields, width))
+    items: dict[str, SubjectGradeSummary] = {}
+    for table, fields, width in sources:
+        family_subjects: set[str] = set()
+        for cells in _subject_rows(table, width, points=table in point_tables):
+            item = _summary(cells, fields, width)
+            if item.subject in family_subjects:
+                raise LibrusError(ErrorKind.PARSE)
+            family_subjects.add(item.subject)
+            previous = items.get(item.subject)
+            items[item.subject] = (
+                item
+                if previous is None
+                else SubjectGradeSummary(
+                    item.subject,
+                    merge_value(previous.midterm, item.midterm),
+                    merge_value(previous.predicted_annual, item.predicted_annual),
+                    merge_value(previous.annual, item.annual),
+                )
+            )
+            if len(items) > GRADE_MAX_SUBJECTS:
+                raise LibrusError(ErrorKind.LIMIT)
+    # No evidenced no-subject marker exists. Missing rows are not empty success;
+    # a valid all-unassigned page still lists its subjects with raw '-' values.
+    if not items:
+        raise LibrusError(ErrorKind.PARSE)
+    return tuple(items.values())

{librus_python_api-1.6.4 → librus_python_api-1.7.1}/src/librus_python_api/grade_records.py

@@ -19,6 +19,8 @@ from librus_python_api.config import (
     GRADE_MAX_SUBJECTS,
     GRADE_MERGED_SUBJECTS,
     GRADE_PERIOD_HEADERS,
+    GRADE_POINT_RESULT_HEADER,
+    GRADE_POINT_RESULT_PERIODS,
     GRADE_PREDICTED_ANNUAL_HEADER,
     GRADE_PREDICTED_PERIOD_HEADERS,
     GRADE_PUBLICATION_DATE_LABEL,
@@ -27,7 +29,15 @@ from librus_python_api.config import (
 )
 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.grade_parsers import (
+    _locate,
+    _subject_columns,
+    _subject_rows,
+    _summary,
+    is_point_table,
+    point_layout,
+    title_label,
+)
 from librus_python_api.models import (
     Availability,
     DescriptiveGrade,
@@ -42,11 +52,13 @@ from librus_python_api.models import (
 from librus_python_api.parsers import parse_page
 
 
-def _label(title: str) -> str:
-    return " ".join(re.split(r"<br\s*/?>", title, flags=re.I)[0].split())
+def _label(title: str, *, points: bool = False) -> str:
+    return title_label(title, points=points)
 
 
-def _layout(table: html.HtmlElement) -> tuple[list[int], dict[int, int]]:
+def _layout(
+    table: html.HtmlElement, *, points: bool = False
+) -> tuple[list[int], dict[int, int]]:
     current: list[int] = []
     averages: dict[int, int] = {}
     for row in markup.rows(table):
@@ -63,7 +75,12 @@ def _layout(table: html.HtmlElement) -> tuple[list[int], dict[int, int]]:
                 if markup.colspan(cell) != 1:
                     raise LibrusError(ErrorKind.PARSE)
                 current.append(position)
-            period = GRADE_AVERAGE_HEADERS.get(_label(cell.get("title", "")))
+            period = GRADE_AVERAGE_HEADERS.get(
+                _label(cell.get("title", ""), points=points)
+            )
+            result = GRADE_POINT_RESULT_HEADER.fullmatch(markup.text(cell))
+            if points and period is None and result is not None:
+                period = GRADE_POINT_RESULT_PERIODS[result.group(1)]
             if period is not None:
                 if period in averages or markup.colspan(cell) != 1:
                     raise LibrusError(ErrorKind.PARSE)
@@ -140,7 +157,9 @@ class _Collection:
         default_factory=list, repr=False
     )
     averages: list[SchoolAverage] = field(default_factory=list, repr=False)
+    point_results: list[SchoolAverage] = field(default_factory=list, repr=False)
     subjects: set[tuple[bool, str]] = field(default_factory=set, repr=False)
+    point_subjects: set[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
@@ -164,7 +183,15 @@ class _Collection:
         if not value or key in self.subjects:
             raise LibrusError(ErrorKind.PARSE)
         self.subjects.add(key)
-        if len(self.subjects) > GRADE_MAX_SUBJECTS:
+        if len(self.subjects) + len(self.point_subjects) > GRADE_MAX_SUBJECTS:
+            raise LibrusError(ErrorKind.LIMIT)
+
+    def point_subject(self, value: str) -> None:
+        # A subject can appear in both the ordinary and the point table.
+        if not value or value in self.point_subjects:
+            raise LibrusError(ErrorKind.PARSE)
+        self.point_subjects.add(value)
+        if len(self.subjects) + len(self.point_subjects) > GRADE_MAX_SUBJECTS:
             raise LibrusError(ErrorKind.LIMIT)
 
 
@@ -309,7 +336,9 @@ def _read_descriptive_row(
                 raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
 
 
-def _period_columns(table: html.HtmlElement) -> dict[tuple[int, GradeKind], int]:
+def _period_columns(
+    table: html.HtmlElement, *, points: bool = False
+) -> dict[tuple[int, GradeKind], int]:
     result: dict[tuple[int, GradeKind], int] = {}
     for row in markup.rows(table):
         cells = markup.cells(row)
@@ -319,7 +348,7 @@ def _period_columns(table: html.HtmlElement) -> dict[tuple[int, GradeKind], int]
             continue
         position = GRADE_BODY_PREFIX_COLUMNS
         for cell in cells:
-            label = _label(cell.get("title", ""))
+            label = _label(cell.get("title", ""), points=points)
             period = GRADE_PERIOD_HEADERS.get(label)
             kind = GradeKind.ANNUAL if period == 0 else GradeKind.PERIOD
             if label == GRADE_PREDICTED_ANNUAL_HEADER:
@@ -337,19 +366,32 @@ def _period_columns(table: html.HtmlElement) -> dict[tuple[int, GradeKind], int]
     return result
 
 
-def _read_numeric_table(table: html.HtmlElement, collection: _Collection) -> None:
-    # Preserve the established full-row and summary alignment validation.
-    _, fields, width = _locate(table)
-    current, means = _layout(table)
-    periods = _period_columns(table)
-    for cells in _subject_rows(table, width):
+def _read_numeric_table(
+    table: html.HtmlElement, collection: _Collection, *, points: bool = False
+) -> None:
+    # Preserve the established full-row and summary alignment validation. A
+    # point table aligns on its current-grade header row and may lack summaries.
+    if points:
+        fields, width = point_layout(table)
+    else:
+        _, fields, width = _locate(table)
+    current, means = _layout(table, points=points)
+    periods = _period_columns(table, points=points)
+    averages = collection.point_results if points else collection.averages
+    # Period grades shown by both tables are one record, kept from the first.
+    prior = set(collection.numeric) if points else set()
+    for cells in _subject_rows(table, width, points=points):
         if cells[0].getparent() in collection.publication_rows:
             continue
-        if _descriptive_row(cells):
+        if points:
+            subject = _subject_columns(cells, width)[0]
+            collection.point_subject(subject)
+        elif _descriptive_row(cells):
             _read_descriptive_row(cells, collection)
             continue
-        subject = _summary(cells, fields, width).subject
-        collection.subject(subject)
+        else:
+            subject = _summary(cells, fields, width).subject
+            collection.subject(subject)
         columns = [cell for cell in cells for _ in range(markup.colspan(cell))]
         for period in (1, 2, 0):
             index = means.get(period)
@@ -360,7 +402,7 @@ def _read_numeric_table(table: html.HtmlElement, collection: _Collection) -> Non
                     Availability.AVAILABLE, markup.text(columns[index])
                 )
             )
-            collection.averages.append(SchoolAverage(subject, period, value))
+            averages.append(SchoolAverage(subject, period, value))
         if columns[current[0]] is columns[current[1]] and _boxes(columns[current[0]]):
             raise LibrusError(ErrorKind.PARSE)
         seen: set[html.HtmlElement] = set()
@@ -370,14 +412,24 @@ def _read_numeric_table(table: html.HtmlElement, collection: _Collection) -> Non
                     subject in GRADE_MERGED_SUBJECTS
                     and _behaviour_points(columns[index], collection)
                 ):
+                    start = len(collection.numeric)
                     _entries(
                         columns[index], subject, cast(Literal[1, 2], period), collection
                     )
+                    # A point entry without its detail link would pass as a
+                    # grade symbol; an unseen link layout fails instead. The
+                    # observed point table also shows formative entries.
+                    if points and any(
+                        record.point_grade_id is None and record.formative_id is None
+                        for record in collection.numeric[start:]
+                    ):
+                        raise LibrusError(ErrorKind.PARSE)
                 seen.add(columns[index])
         for (period, kind), index in periods.items():
             cell = columns[index]
             if cell in seen and _boxes(cell):
                 raise LibrusError(ErrorKind.PARSE)
+            start = len(collection.numeric)
             _entries(
                 cell,
                 subject,
@@ -386,6 +438,9 @@ def _read_numeric_table(table: html.HtmlElement, collection: _Collection) -> Non
                 kind=kind,
                 require_empty_marker=False,
             )
+            collection.numeric[start:] = [
+                record for record in collection.numeric[start:] if record not in prior
+            ]
 
 
 def _read_publications(table: html.HtmlElement, collection: _Collection) -> None:
@@ -450,8 +505,13 @@ def parse_grade_records(body: bytes) -> GradeRecords:
     collection = _Collection()
     numeric_tables = []
     tables = list(document.iter("table"))
+    point_tables = [table for table in tables if is_point_table(table)]
+    if len(point_tables) > 1:
+        raise LibrusError(ErrorKind.PARSE)
     for table in tables:
-        if not {"decorated", "stretch"} <= set(table.get("class", "").split()):
+        if not {"decorated", "stretch"} <= set(
+            table.get("class", "").split()
+        ) or is_point_table(table):
             continue
         if any(
             next(row.iterancestors("thead"), None) is not None
@@ -472,6 +532,8 @@ def parse_grade_records(body: bytes) -> GradeRecords:
         _read_publications(table, collection)
         if table in numeric_tables:
             _read_numeric_table(table, collection)
+        elif table in point_tables:
+            _read_numeric_table(table, collection, points=True)
         else:
             for row in markup.rows(table):
                 cells = markup.cells(row)
@@ -484,6 +546,7 @@ def parse_grade_records(body: bytes) -> GradeRecords:
                     <= set(cells[0].get("class", "").split())
                 ):
                     raise LibrusError(ErrorKind.PARSE)
+    grade_tables = numeric_tables + point_tables
     for element in document.iter():
         if not isinstance(element.tag, str) or element in collection.consumed:
             continue
@@ -491,27 +554,29 @@ def parse_grade_records(body: bytes) -> GradeRecords:
             "Data:" in (node.get("title") or "") for node in element.iter()
         )
         if dated_box:
-            if any(
-                parent in numeric_tables for parent in element.iterancestors("table")
-            ):
+            if any(parent in grade_tables for parent in element.iterancestors("table")):
                 # Expanded full-row detail mirrors were intentionally excluded.
                 cell = next(element.iterancestors("td", "th"), None)
                 if (
                     cell is not None
-                    and next(cell.iterancestors("table"), None) not in numeric_tables
+                    and next(cell.iterancestors("table"), None) not in grade_tables
                 ):
                     continue
             raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
     for anchor in document.iter("a"):
-        # A formative link outside both known tables is a new layout.
+        # A formative link outside the 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
+            parent in grade_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:
+    if (
+        not collection.subjects
+        and not collection.point_subjects
+        and not collection.descriptive
+    ):
         raise LibrusError(ErrorKind.PARSE)
     for descriptive, subject in sorted(collection.subjects):
         if descriptive and (False, subject) not in collection.subjects:
@@ -529,4 +594,5 @@ def parse_grade_records(body: bytes) -> GradeRecords:
         tuple(collection.averages),
         tuple(collection.descriptive_summaries),
         formative,
+        tuple(collection.point_results),
     )

{librus_python_api-1.6.4 → librus_python_api-1.7.1}/src/librus_python_api/markup.py

@@ -13,6 +13,7 @@ from librus_python_api.config import (
     GRADE_MAX_COLUMNS,
     GRADE_MAX_METADATA_FIELDS,
     GRADE_MAX_METADATA_LENGTH,
+    TOOLTIP_MULTILINE_LABELS,
     UPSTREAM_ORIGINS,
 )
 from librus_python_api.exceptions import ErrorKind, LibrusError
@@ -81,11 +82,16 @@ def colspan(cell: html.HtmlElement) -> int:
 
 
 def tooltip_fields(element: html.HtmlElement) -> dict[str, str]:
-    """Parse a 'Label: value<br>' title attribute into unique labelled fields."""
+    """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.
+    """
     title = element.get("title", "")
     if len(title) > GRADE_MAX_METADATA_LENGTH:
         raise LibrusError(ErrorKind.LIMIT)
     result: dict[str, str] = {}
+    last: str | None = None
     chunks = re.split(r"<br\s*/?>|\n", title, flags=re.I)
     if len(chunks) > GRADE_MAX_METADATA_FIELDS:
         raise LibrusError(ErrorKind.LIMIT)
@@ -100,9 +106,13 @@ def tooltip_fields(element: html.HtmlElement) -> dict[str, str]:
         )
         key, separator, value = rendered.partition(":")
         key, value = key.strip(), value.strip()
+        if not separator and last in TOOLTIP_MULTILINE_LABELS:
+            result[last] = f"{result[last]}\n{rendered}".strip()
+            continue
         if not separator or not key or key in result:
             raise LibrusError(ErrorKind.PARSE)
         result[key] = value
+        last = key
     return result
 
 

{librus_python_api-1.6.4 → librus_python_api-1.7.1}/src/librus_python_api/models.py

@@ -1053,6 +1053,19 @@ class NumericGrade:
 
         return detail_id(self.href, FORMATIVE_DETAIL_PATH_PREFIX)
 
+    @property
+    def point_grade_id(self) -> str | None:
+        """The point-grade ID when `href` is a point-grade detail link.
+
+        `raw` is then a score on the scale its category names, such as
+        `(0-100)`, not a grade symbol. Computed for the same identity reason
+        as `formative_id`.
+        """
+        from librus_python_api.config import POINT_GRADE_DETAIL_PATH_PREFIX
+        from librus_python_api.markup import detail_id
+
+        return detail_id(self.href, POINT_GRADE_DETAIL_PATH_PREFIX)
+
 
 @dataclass(frozen=True, slots=True)
 class DescriptiveGrade:
@@ -1123,6 +1136,9 @@ class GradeRecords:
         default=(), repr=False
     )
     formative: tuple[FormativeGrade, ...] = field(default=(), repr=False)
+    # A point table's period results, on its score scale; never merged into
+    # `averages`, whose values are the ordinary grade-scale means.
+    point_results: tuple[SchoolAverage, ...] = field(default=(), repr=False)
 
 
 @dataclass(frozen=True, slots=True)

{librus_python_api-1.6.4 → librus_python_api-1.7.1}/uv.lock

@@ -921,6 +921,7 @@ dev = [
     { name = "pip-audit" },
     { name = "pre-commit" },
     { name = "pytest" },
+    { name = "pytest-timeout" },
     { name = "pyyaml" },
     { name = "ruff" },
     { name = "twine" },
@@ -947,6 +948,7 @@ dev = [
     { name = "pip-audit", specifier = ">=2.10,<3" },
     { name = "pre-commit", specifier = ">=4.6,<5" },
     { name = "pytest", specifier = ">=9,<10" },
+    { name = "pytest-timeout", specifier = ">=2.3,<3" },
     { name = "pyyaml", specifier = ">=6,<7" },
     { name = "ruff", specifier = ">=0.15,<0.18" },
     { name = "twine", specifier = ">=7,<8" },
@@ -1797,6 +1799,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" },
 ]
 
+[[package]]
+name = "pytest-timeout"
+version = "2.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ac/82/4c9ecabab13363e72d880f2fb504c5f750433b2b6f16e99f4ec21ada284c/pytest_timeout-2.4.0.tar.gz", hash = "sha256:7e68e90b01f9eff71332b25001f85c75495fc4e3a836701876183c4bcfd0540a", size = 17973, upload-time = "2025-05-05T19:44:34.99Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl", hash = "sha256:c42667e5cdadb151aeb5b26d114aff6bdf5a907f176a007a30b940d3d865b5c2", size = 14382, upload-time = "2025-05-05T19:44:33.502Z" },
+]
+
 [[package]]
 name = "python-discovery"
 version = "1.6.1"

librus_python_api-1.6.4/src/librus_python_api/grade_parsers.py

@@ -1,169 +0,0 @@
-"""Original bounded HTML summary parsing from source-informed requirements."""
-
-import re
-from collections.abc import Iterator
-
-from lxml import html
-
-from librus_python_api import markup
-from librus_python_api.config import (
-    GRADE_BODY_PREFIX_COLUMNS,
-    GRADE_INLINE_DETAIL_LABEL,
-    GRADE_MAX_COLUMNS,
-    GRADE_MAX_SUBJECTS,
-    GRADE_MAX_VALUE_LENGTH,
-    GRADE_MERGED_SUBJECTS,
-    GRADE_SUMMARY_HEADERS,
-)
-from librus_python_api.exceptions import ErrorKind, LibrusError
-from librus_python_api.models import (
-    Availability,
-    GradeSummaryValue,
-    SubjectGradeSummary,
-)
-from librus_python_api.parsers import parse_page
-
-
-def _summary_field(cell: html.HtmlElement) -> str | None:
-    title = cell.get("title", "")
-    if len(title) > GRADE_MAX_VALUE_LENGTH:
-        raise LibrusError(ErrorKind.LIMIT)
-    label = " ".join(re.split(r"<br\s*/?>", title, flags=re.I)[0].split())
-    return GRADE_SUMMARY_HEADERS.get(label)
-
-
-def _header(row: html.HtmlElement) -> tuple[dict[str, int], int]:
-    fields: dict[str, int] = {}
-    position = GRADE_BODY_PREFIX_COLUMNS
-    for cell in markup.cells(row):
-        span = markup.colspan(cell)
-        if position + span > GRADE_MAX_COLUMNS:
-            raise LibrusError(ErrorKind.LIMIT)
-        field = _summary_field(cell)
-        if field is not None:
-            if field in fields:
-                raise LibrusError(ErrorKind.PARSE)
-            fields[field] = position
-        position += span
-    return fields, position
-
-
-def _locate(
-    document: html.HtmlElement,
-) -> tuple[html.HtmlElement, dict[str, int], int]:
-    candidates: list[tuple[html.HtmlElement, dict[str, int], int]] = []
-    for table in document.iter("table"):
-        if not {"decorated", "stretch"} <= set(table.get("class", "").split()):
-            continue
-        for row in markup.rows(table):
-            if next(row.iterancestors("thead"), None) is None:
-                continue
-            # Group-heading rows can span the entire table. Only the row with
-            # an annual summary title defines the body alignment contract.
-            if not any(_summary_field(cell) == "annual" for cell in markup.cells(row)):
-                continue
-            fields, width = _header(row)
-            candidates.append((table, fields, width))
-    if len(candidates) != 1:
-        raise LibrusError(ErrorKind.PARSE)
-    return candidates[0]
-
-
-def _outside_nested_tables(row: html.HtmlElement) -> str:
-    """Reject a subject row masquerading as an expanded-detail wrapper."""
-    parts: list[str] = []
-    pending = [row]
-    while pending:
-        element = pending.pop()
-        if element.tail:
-            parts.append(element.tail)
-        if element.tag == "table":
-            continue
-        if element.text:
-            parts.append(element.text)
-        pending.extend(element)
-    return " ".join(parts).strip()
-
-
-def _summary(
-    cells: list[html.HtmlElement],
-    fields: dict[str, int],
-    width: int,
-) -> SubjectGradeSummary:
-    if len(cells) < GRADE_BODY_PREFIX_COLUMNS:
-        raise LibrusError(ErrorKind.PARSE)
-    subject = markup.text(cells[1])
-    if not subject or markup.colspan(cells[0]) != 1 or markup.colspan(cells[1]) != 1:
-        raise LibrusError(ErrorKind.PARSE)
-    columns: list[html.HtmlElement] = []
-    for cell in cells:
-        span = markup.colspan(cell)
-        if span > 1 and subject not in GRADE_MERGED_SUBJECTS:
-            raise LibrusError(ErrorKind.PARSE)
-        if len(columns) + span > GRADE_MAX_COLUMNS:
-            raise LibrusError(ErrorKind.LIMIT)
-        columns.extend([cell] * span)
-    if len(columns) != width:
-        raise LibrusError(ErrorKind.PARSE)
-    selected = [columns[index] for index in fields.values()]
-    if len({id(cell) for cell in selected}) != len(selected):
-        # A single merged value cannot mean two different summary fields.
-        raise LibrusError(ErrorKind.PARSE)
-    values = {
-        name: GradeSummaryValue(Availability.AVAILABLE, markup.text(columns[index]))
-        for name, index in fields.items()
-    }
-    absent = GradeSummaryValue(Availability.UNAVAILABLE, None)
-    return SubjectGradeSummary(
-        subject,
-        values.get("midterm", absent),
-        values.get("predicted_annual", absent),
-        values["annual"],
-    )
-
-
-def _subject_rows(
-    table: html.HtmlElement, width: int
-) -> Iterator[list[html.HtmlElement]]:
-    for row in markup.rows(table):
-        if next(row.iterancestors("thead"), None) is not None:
-            continue
-        cells = markup.cells(row)
-        if not cells:
-            raise LibrusError(ErrorKind.PARSE)
-        if list(row.iter("table")):
-            if _outside_nested_tables(row):
-                raise LibrusError(ErrorKind.PARSE)
-            continue
-        # An empty full-width layout spacer is not an unassigned subject. Keep
-        # this exception narrow: content or a different width remains malformed.
-        if (
-            len(cells) == 1
-            and markup.colspan(cells[0]) == width
-            and not markup.text(cells[0])
-        ):
-            continue
-        # Expanded inline detail labels are not subjects. Recognize this narrow
-        # source-informed variant, never discard arbitrary malformed subject rows.
-        if len(cells) > 1 and markup.text(cells[1]) == GRADE_INLINE_DETAIL_LABEL:
-            continue
-        yield cells
-
-
-def parse_final_grades(body: bytes) -> tuple[SubjectGradeSummary, ...]:
-    table, fields, width = _locate(parse_page(body))
-    items: list[SubjectGradeSummary] = []
-    subjects: set[str] = set()
-    for cells in _subject_rows(table, width):
-        item = _summary(cells, fields, width)
-        if item.subject in subjects:
-            raise LibrusError(ErrorKind.PARSE)
-        subjects.add(item.subject)
-        items.append(item)
-        if len(items) > GRADE_MAX_SUBJECTS:
-            raise LibrusError(ErrorKind.LIMIT)
-    # No evidenced no-subject marker exists. Missing rows are not empty success;
-    # a valid all-unassigned page still lists its subjects with raw '-' values.
-    if not items:
-        raise LibrusError(ErrorKind.PARSE)
-    return tuple(items)