librus-python-api 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

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,
@@ -110,6 +117,7 @@ from librus_python_api.models import (
     SchoolAverage,
     SchoolDetail,
     SchoolReference,
+    SchoolYearArchive,
     SendResult,
     SendStatus,
     SendSubmission,
@@ -127,9 +135,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.3.0"
 
 __all__ = [
+    "ArchiveAbsences",
+    "ArchiveAchievement",
+    "ArchiveCounts",
+    "ArchiveDescriptive",
+    "ArchiveMarks",
+    "ArchiveSubject",
+    "ArchiveYear",
+    "SchoolYearArchive",
     "AccountContext",
     "MessagingBackend",
     "ModernAccountData",

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",
@@ -722,6 +730,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/models.py

@@ -38,6 +38,7 @@ type OperationName = Literal[
     "attachment_download",
     "recipient_groups",
     "recipients",
+    "school_year_archive",
     "notification_counts",
     "consume_schedule_events",
     "decode_schedule_events",
@@ -778,6 +779,79 @@ class Announcements:
     observation: Observation
 
 
+@dataclass(frozen=True, slots=True)
+class ArchiveCounts:
+    """Counts per period as rendered; the year-end value is not checked as a sum."""
+
+    first_semester: int
+    second_semester: int
+    year_end: int
+
+
+@dataclass(frozen=True, slots=True)
+class ArchiveAbsences:
+    unexcused: ArchiveCounts
+    excused: ArchiveCounts
+    late: ArchiveCounts
+
+
+@dataclass(frozen=True, slots=True)
+class ArchiveMarks:
+    """Rendered marks; "-" and empty text are preserved, never invented.
+
+    `year_end` is the archive's year-end column, not asserted to equal the
+    published annual grade of `SubjectGradeSummary`.
+    """
+
+    first_semester: str = field(repr=False)
+    second_semester: str = field(repr=False)
+    year_end: str = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ArchiveSubject:
+    subject: str = field(repr=False)
+    marks: ArchiveMarks = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ArchiveDescriptive:
+    label: str = field(repr=False)
+    text: str = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ArchiveYear:
+    """One earlier school year. Behaviour cells are raw positional text: the
+    first-semester column and the cell spanning second semester and year end;
+    their populated meaning is not established."""
+
+    class_name: str = field(repr=False)
+    school_year: str = field(repr=False)
+    first_year: int = field(repr=False)
+    subjects: tuple[ArchiveSubject, ...] = field(repr=False)
+    descriptive: tuple[ArchiveDescriptive, ...] = field(repr=False)
+    behaviour_first_semester: str = field(repr=False)
+    behaviour_second_semester_and_year_end: str = field(repr=False)
+    absences: ArchiveAbsences = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ArchiveAchievement:
+    day: date = field(repr=False)
+    class_name: str = field(repr=False)
+    category: str = field(repr=False)
+    text: str = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class SchoolYearArchive:
+    identity: Identity
+    years: tuple[ArchiveYear, ...] = field(repr=False)
+    achievements: tuple[ArchiveAchievement, ...] = field(repr=False)
+    observation: Observation
+
+
 @dataclass(frozen=True, slots=True)
 class AgendaEvent:
     day: date = field(repr=False)

librus_python_api/school_year_archive.py

@@ -0,0 +1,432 @@
+"""The school-year archive page (`/archiwum`), authored from an owner-authorized
+structural observation; every fixture is synthetic.
+
+One table holds every earlier school year: a year header row, a period row,
+grade rows (subject marks or full-year descriptive text), then exactly one
+behaviour section, one absences section and an empty footer, in that order.
+A separate table lists achievements. Unknown layouts are unsupported;
+contradictions inside the known layout are parse errors. The student's name in
+the page header and the chart scripts are never read.
+"""
+
+import re
+from typing import NoReturn
+
+from lxml import html
+
+from librus_python_api import markup
+from librus_python_api.config import (
+    ARCHIVE_ABSENCE_LABELS,
+    ARCHIVE_ABSENCES_HEADING,
+    ARCHIVE_ACHIEVEMENT_HEADERS,
+    ARCHIVE_ACHIEVEMENT_TABLE_CLASSES,
+    ARCHIVE_BEHAVIOUR_HEADING,
+    ARCHIVE_EMPTY_BOX_CLASSES,
+    ARCHIVE_EMPTY_TITLE,
+    ARCHIVE_MAX_ACHIEVEMENTS,
+    ARCHIVE_MAX_DESCRIPTIVE,
+    ARCHIVE_MAX_SUBJECTS,
+    ARCHIVE_MAX_TEXT_LENGTH,
+    ARCHIVE_MAX_TOTAL_TEXT_LENGTH,
+    ARCHIVE_MAX_YEAR_HEADER_LENGTH,
+    ARCHIVE_MAX_YEARS,
+    ARCHIVE_PERIOD_LABELS,
+    ARCHIVE_TABLE_CLASSES,
+    ARCHIVE_YEAR_HEADER_TAGS,
+    ARCHIVE_YEAR_PATTERN,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import (
+    ArchiveAbsences,
+    ArchiveAchievement,
+    ArchiveCounts,
+    ArchiveDescriptive,
+    ArchiveMarks,
+    ArchiveSubject,
+    ArchiveYear,
+)
+from librus_python_api.parsers import parse_page
+
+_YEAR = re.compile(ARCHIVE_YEAR_PATTERN)
+_COUNT = re.compile(r"[0-9]{1,6}")
+
+
+def _fail(kind: ErrorKind) -> NoReturn:
+    raise LibrusError(kind)
+
+
+class _Text:
+    """Rendered cell text under one total budget for the whole page."""
+
+    def __init__(self) -> None:
+        self.used = 0
+
+    def __call__(
+        self,
+        cell: html.HtmlElement,
+        *,
+        multiline: bool = False,
+        limit: int = markup.FIELD_LENGTH,
+    ) -> str:
+        value = markup.text(cell, limit, multiline=multiline)
+        self.used += len(value)
+        if self.used > ARCHIVE_MAX_TOTAL_TEXT_LENGTH:
+            _fail(ErrorKind.LIMIT)
+        return value
+
+
+def _plain(cell: html.HtmlElement, allowed: frozenset[str] = frozenset()) -> None:
+    """Only the observed child vocabulary; other markup is a new layout."""
+    for node in cell.iterdescendants():
+        if isinstance(node.tag, str) and node.tag not in allowed:
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+    for node in cell.iter():
+        if any(name == "title" or name.startswith("on") for name in node.attrib):
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+
+
+def _td(cells: list[html.HtmlElement]) -> None:
+    if any(cell.tag != "td" for cell in cells):
+        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+
+
+def _classes(table: html.HtmlElement) -> set[str]:
+    return set(table.get("class", "").split())
+
+
+def _first_cells(table: html.HtmlElement) -> list[html.HtmlElement]:
+    first = next(markup.rows(table), None)
+    return [] if first is None else markup.cells(first)
+
+
+def _is_archive(table: html.HtmlElement) -> bool:
+    cells = _first_cells(table)
+    return (
+        len(cells) >= 2
+        and markup.text(cells[0]) == ""
+        and all(
+            _YEAR.fullmatch(markup.text(cell, ARCHIVE_MAX_YEAR_HEADER_LENGTH))
+            for cell in cells[1:]
+        )
+    )
+
+
+def _is_achievement_list(table: html.HtmlElement) -> bool:
+    cells = _first_cells(table)
+    return [
+        markup.text(cell, ARCHIVE_MAX_YEAR_HEADER_LENGTH).casefold() for cell in cells
+    ] == list(ARCHIVE_ACHIEVEMENT_HEADERS)
+
+
+def _in_footer(row: html.HtmlElement) -> bool:
+    return next(row.iterancestors("tfoot"), None) is not None
+
+
+def _years(header: html.HtmlElement, text: _Text) -> list[tuple[str, str, int]]:
+    cells = markup.cells(header)
+    _td(cells)
+    _plain(cells[0])
+    if len(cells) - 1 > ARCHIVE_MAX_YEARS:
+        _fail(ErrorKind.LIMIT)
+    if markup.colspan(cells[0]) != 1:
+        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+    years: list[tuple[str, str, int]] = []
+    for cell in cells[1:]:
+        if markup.colspan(cell) != 3:
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+        _plain(cell, ARCHIVE_YEAR_HEADER_TAGS)
+        match = _YEAR.fullmatch(text(cell, limit=ARCHIVE_MAX_YEAR_HEADER_LENGTH))
+        if match is None:
+            _fail(ErrorKind.PARSE)
+        first, second = int(match["first"]), int(match["second"])
+        if len(match["class_name"]) > markup.FIELD_LENGTH:
+            _fail(ErrorKind.LIMIT)
+        if second != first + 1 or any(first == seen for _, _, seen in years):
+            _fail(ErrorKind.PARSE)
+        years.append((match["class_name"], f"{first}/{second}", first))
+    return years
+
+
+def _check_periods(row: html.HtmlElement, count: int, text: _Text) -> None:
+    cells = markup.cells(row)
+    _td(cells)
+    for cell in cells:
+        _plain(cell)
+    if (
+        len(cells) != 1 + 3 * count
+        or any(markup.colspan(cell) != 1 for cell in cells)
+        or text(cells[0])
+        or [text(cell).casefold() for cell in cells[1:]]
+        != list(ARCHIVE_PERIOD_LABELS) * count
+    ):
+        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+
+
+class _Body:
+    """The section order: grades, behaviour, absences, footer."""
+
+    def __init__(self, count: int, text: _Text) -> None:
+        self.count = count
+        self.text = text
+        self.state = "grades"
+        self.labels: set[str] = set()
+        self.subjects: list[tuple[str, list[ArchiveMarks]]] = []
+        self.descriptive: list[tuple[str, list[str]]] = []
+        self.behaviour: list[tuple[str, str]] = []
+        self.absences: dict[str, list[ArchiveCounts]] = {}
+
+    def read(self, row: html.HtmlElement) -> None:
+        cells = markup.cells(row)
+        spans = [markup.colspan(cell) for cell in cells]
+        full = [1 + 3 * self.count]
+        heading = spans == full and "bolded" in row.get("class", "").split()
+        if self.state == "grades":
+            if heading:
+                self._heading(cells, ARCHIVE_BEHAVIOUR_HEADING, "behaviour")
+            else:
+                self._grade(cells, spans)
+        elif self.state == "behaviour":
+            self._behaviour(cells, spans, heading)
+        elif self.state == "absences_heading":
+            if not heading:
+                _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+            self._heading(cells, ARCHIVE_ABSENCES_HEADING, "absences")
+        elif self.state == "absences":
+            if spans == full and not heading:
+                self._footer(cells)
+            else:
+                self._absence(cells, spans)
+        else:
+            _fail(ErrorKind.PARSE)
+
+    def _heading(self, cells: list[html.HtmlElement], label: str, state: str) -> None:
+        _td(cells)
+        _plain(cells[0])
+        if self.text(cells[0]).casefold() != label:
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+        self.state = state
+
+    def _label(self, cells: list[html.HtmlElement]) -> str:
+        if not cells or cells[0].tag != "th":
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+        _plain(cells[0])
+        return self.text(cells[0])
+
+    def _values(
+        self,
+        cells: list[html.HtmlElement],
+        *,
+        multiline: bool = False,
+        limit: int = markup.FIELD_LENGTH,
+    ) -> list[str]:
+        _td(cells)
+        values = []
+        for cell in cells:
+            _plain(cell, frozenset({"br"}) if multiline else frozenset())
+            values.append(self.text(cell, multiline=multiline, limit=limit))
+        return values
+
+    def _grade(self, cells: list[html.HtmlElement], spans: list[int]) -> None:
+        label = self._label(cells)
+        if not label:
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+        if spans == [1] * (1 + 3 * self.count):
+            values = self._values(cells[1:])
+            marks = [
+                ArchiveMarks(*values[3 * i : 3 * i + 3]) for i in range(self.count)
+            ]
+            self.subjects.append((label, marks))
+            limit, size = ARCHIVE_MAX_SUBJECTS, len(self.subjects)
+        elif spans == [1] + [3] * self.count:
+            texts = self._values(
+                cells[1:], multiline=True, limit=ARCHIVE_MAX_TEXT_LENGTH
+            )
+            self.descriptive.append((label, texts))
+            limit, size = ARCHIVE_MAX_DESCRIPTIVE, len(self.descriptive)
+        else:
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+        if label in self.labels:
+            _fail(ErrorKind.PARSE)
+        self.labels.add(label)
+        if size > limit:
+            _fail(ErrorKind.LIMIT)
+
+    def _behaviour(
+        self, cells: list[html.HtmlElement], spans: list[int], heading: bool
+    ) -> None:
+        if heading or spans != [1] + [1, 2] * self.count or self._label(cells):
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+        values = self._values(cells[1:])
+        self.behaviour = [(values[2 * i], values[2 * i + 1]) for i in range(self.count)]
+        self.state = "absences_heading"
+
+    def _absence(self, cells: list[html.HtmlElement], spans: list[int]) -> None:
+        field = ARCHIVE_ABSENCE_LABELS.get(self._label(cells).casefold())
+        if field is None or spans != [1] * (1 + 3 * self.count):
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+        if field in self.absences:
+            _fail(ErrorKind.PARSE)
+        values = self._values(cells[1:])
+        if not all(_COUNT.fullmatch(value) for value in values):
+            _fail(ErrorKind.PARSE)
+        numbers = [int(value) for value in values]
+        self.absences[field] = [
+            ArchiveCounts(*numbers[3 * i : 3 * i + 3]) for i in range(self.count)
+        ]
+
+    def _footer(self, cells: list[html.HtmlElement]) -> None:
+        _td(cells)
+        _plain(cells[0])
+        if self.text(cells[0]) or len(self.absences) != len(ARCHIVE_ABSENCE_LABELS):
+            _fail(ErrorKind.PARSE)
+        self.state = "end"
+
+
+def _archive(table: html.HtmlElement, text: _Text) -> tuple[ArchiveYear, ...]:
+    rows = list(markup.rows(table))
+    if len(rows) < 2:
+        _fail(ErrorKind.PARSE)
+    years = _years(rows[0], text)
+    _check_periods(rows[1], len(years), text)
+    body = _Body(len(years), text)
+    for row in rows[2:]:
+        body.read(row)
+    if body.state != "end":
+        _fail(ErrorKind.PARSE)
+    return tuple(
+        ArchiveYear(
+            class_name=class_name,
+            school_year=school_year,
+            first_year=first_year,
+            subjects=tuple(
+                ArchiveSubject(label, marks[i]) for label, marks in body.subjects
+            ),
+            descriptive=tuple(
+                ArchiveDescriptive(label, texts[i]) for label, texts in body.descriptive
+            ),
+            behaviour_first_semester=body.behaviour[i][0],
+            behaviour_second_semester_and_year_end=body.behaviour[i][1],
+            absences=ArchiveAbsences(
+                unexcused=body.absences["unexcused"][i],
+                excused=body.absences["excused"][i],
+                late=body.absences["late"][i],
+            ),
+        )
+        for i, (class_name, school_year, first_year) in enumerate(years)
+    )
+
+
+def _achievements(
+    table: html.HtmlElement, text: _Text
+) -> tuple[ArchiveAchievement, ...]:
+    items: list[ArchiveAchievement] = []
+    rows = list(markup.rows(table))
+    headers = markup.cells(rows[0])
+    _td(headers)
+    for cell in headers:
+        _plain(cell)
+        if markup.colspan(cell) != 1:
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+        text(cell)
+    finished = False
+    for row in rows[1:]:
+        if finished:
+            _fail(ErrorKind.PARSE)
+        cells = markup.cells(row)
+        _td(cells)
+        if _in_footer(row):
+            if len(cells) != 1 or text(cells[0]):
+                _fail(ErrorKind.PARSE)
+            _plain(cells[0])
+            if markup.colspan(cells[0]) != 4:
+                _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+            finished = True
+            continue
+        if len(cells) != 4 or any(markup.colspan(cell) != 1 for cell in cells):
+            _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+        for i, cell in enumerate(cells):
+            _plain(cell, frozenset({"br"}) if i == 3 else frozenset())
+        items.append(
+            ArchiveAchievement(
+                day=markup.civil_date(text(cells[0])),
+                class_name=text(cells[1]),
+                category=text(cells[2]),
+                text=text(cells[3], multiline=True, limit=ARCHIVE_MAX_TEXT_LENGTH),
+            )
+        )
+        if len(items) > ARCHIVE_MAX_ACHIEVEMENTS:
+            _fail(ErrorKind.LIMIT)
+    return tuple(items)
+
+
+def _explicit_empty(document: html.HtmlElement) -> bool:
+    notices = []
+    for box in document.iter("div"):
+        if not ARCHIVE_EMPTY_BOX_CLASSES <= _classes(box):
+            continue
+        parent = box.getparent()
+        if parent is None or "container-background" not in _classes(parent):
+            continue
+        for head in box:
+            if head.tag != "div" or "warning-head" not in _classes(head):
+                continue
+            for title in head:
+                if title.tag == "span" and "warning-title" in _classes(title):
+                    _plain(title)
+                    if markup.text(title).casefold() != ARCHIVE_EMPTY_TITLE:
+                        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+                    notices.append(title)
+    if len(notices) > 1:
+        _fail(ErrorKind.PARSE)
+    if notices and any("decorated" in _classes(t) for t in document.iter("table")):
+        _fail(ErrorKind.PARSE)
+    return bool(notices)
+
+
+def _check_nesting(table: html.HtmlElement, *, chart_trailer: bool = False) -> None:
+    if next(table.iterancestors("table"), None) is not None:
+        _fail(ErrorKind.PARSE)
+    nested = [node for node in table.iter("table") if node is not table]
+    if not nested:
+        return
+    # Live HTML nests the post-footer charts in a stray opening table. Permit
+    # that single rowless trailing container, never nested tabular data.
+    if not chart_trailer or len(nested) != 1:
+        _fail(ErrorKind.PARSE)
+    trailer = nested[0]
+    previous = trailer.getprevious()
+    if (
+        trailer.getparent() is not table
+        or trailer.getnext() is not None
+        or previous is None
+        or previous.tag != "tfoot"
+        or trailer.attrib
+        or any(
+            node.tag in {"tr", "td", "th", "thead", "tbody", "tfoot"}
+            for node in trailer.iterdescendants()
+        )
+    ):
+        _fail(ErrorKind.PARSE)
+
+
+def parse_school_year_archive(
+    body: bytes,
+) -> tuple[tuple[ArchiveYear, ...], tuple[ArchiveAchievement, ...]]:
+    document = parse_page(body)
+    archives = [t for t in document.iter("table") if _is_archive(t)]
+    lists = [t for t in document.iter("table") if _is_achievement_list(t)]
+    if _explicit_empty(document):
+        if archives or lists:
+            _fail(ErrorKind.PARSE)
+        return (), ()
+    if len(archives) != 1 or len(lists) != 1:
+        _fail(ErrorKind.PARSE)
+    archive, achievements = archives[0], lists[0]
+    _check_nesting(archive)
+    _check_nesting(achievements, chart_trailer=True)
+    if not ARCHIVE_TABLE_CLASSES <= _classes(archive) or not (
+        ARCHIVE_ACHIEVEMENT_TABLE_CLASSES <= _classes(achievements)
+    ):
+        _fail(ErrorKind.UNSUPPORTED_CAPABILITY)
+    text = _Text()
+    return _archive(archive, text), _achievements(achievements, text)

librus_python_api/service.py

@@ -138,6 +138,7 @@ from librus_python_api.models import (
     SchedulerSnapshot,
     SchoolDetail,
     SchoolReference,
+    SchoolYearArchive,
     SendResult,
     SendSubmission,
     StudentInformation,
@@ -196,6 +197,7 @@ from librus_python_api.school_reads import (
     parse_homework,
     parse_school_detail,
 )
+from librus_python_api.school_year_archive import parse_school_year_archive
 from librus_python_api.sending import SendAttempt, parse_send_acknowledgement
 from librus_python_api.timetable import parse_timetable
 from librus_python_api.transport import (
@@ -1486,6 +1488,30 @@ class AccountClient:
 
         return await self._read(("announcements",), fetch, budget, max_age_seconds)
 
+    async def school_year_archive(
+        self, *, budget: RequestBudget | None = None, max_age_seconds: float = 0.0
+    ) -> SchoolYearArchive:
+        """Read every earlier school year's summary and the achievements list.
+
+        One GET with no side effect; the page's student name and charts are
+        never read. A layout other than the observed one is unsupported.
+        """
+
+        async def fetch(budget: RequestBudget, _: bool) -> SchoolYearArchive:
+            years, achievements = await self._page(
+                "school_year_archive", budget, parse_school_year_archive
+            )
+            return SchoolYearArchive(
+                self._session_identity(),
+                years,
+                achievements,
+                self._observation("school_year_archive"),
+            )
+
+        return await self._read(
+            ("school_year_archive",), fetch, budget, max_age_seconds
+        )
+
     async def agenda(
         self,
         year: int,

{librus_python_api-1.2.1.dist-info → librus_python_api-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.2.1
+Version: 1.3.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.3.0` adds a read-only school-year archive.
+Installed live checks passed 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.3.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.3.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,7 +241,7 @@ 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 |
 

{librus_python_api-1.2.1.dist-info → librus_python_api-1.3.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-librus_python_api/__init__.py,sha256=cFnpyZw2vPzTFefw3pbhiP3f-CvFABI4rnGdpLye-LQ,6045
+librus_python_api/__init__.py,sha256=XnV4fql56WvZHQuk3zrUHlQ4mtK0272dM07QFKyINU4,6393
 librus_python_api/_notification_bootstrap.py,sha256=18nzH0doXBNaZXCz-_ckIvRrlHTWV5Mm1t5m2-5eYGI,4669
 librus_python_api/_notification_codec.py,sha256=hU6G3zGJ5fR8wfPC6fV2OqBKs-7XpT9eRnKO3FGsTzY,13451
 librus_python_api/_storage.py,sha256=M_6ZAzN4zs7laOdKJBRH1I2rvy3pgqYgC_MZtsd2xtM,15893
@@ -11,7 +11,7 @@ librus_python_api/attendance_frequency.py,sha256=SBhED5zuyRIHWdw4urFyTJYykb6EYB7
 librus_python_api/budget.py,sha256=8fvqT7eIxyVX2P2OBG27XsYHk_HbtSS4lzuecYpHtgs,2878
 librus_python_api/checkpoint.py,sha256=QBmG9GtpyaGRaFq-FXuGA3yR1BjuMFN9V3RTvvi_FNQ,1930
 librus_python_api/completed_lessons.py,sha256=sR2oLSGb2q1580l-2upCBv9sQfIcHi7CQfWr1K0EFXI,7635
-librus_python_api/config.py,sha256=43tAalNG8_Em7Q-lXs1nmX-GKw7333CKpNAvJtGMg4E,53193
+librus_python_api/config.py,sha256=8DckId5C13QH9KPelZwPfsci8upoqb_SJBtq7XviPPY,54628
 librus_python_api/detail_fields.py,sha256=K10Stx_ehDTttkUI7-G7a2Ko9exYEu5NJpR-3sBnQ60,1789
 librus_python_api/diagnostics.py,sha256=2l7wq6RA3it-Gwj-JRLcw5qbI37fl3xII6GZA2mZj0o,856
 librus_python_api/exceptions.py,sha256=yWWoo0xyrQAk1d13HOJZnQBsq4ulh_P0hRSI6ZiNQOE,4622
@@ -23,7 +23,7 @@ librus_python_api/lifecycle.py,sha256=XzA5CEdZFo7iL5IMUrawnRvf2m9BFe0OseP-fpQFaA
 librus_python_api/markup.py,sha256=GZk7MmBBGB5SIVY_VngmQxQErI3eGHOpJs3mFVlMR3M,5298
 librus_python_api/message_content.py,sha256=sUPuqpjuavqDyn6QGM5aPH4mpoQV62bDLepSSQ2AsUE,8686
 librus_python_api/messages.py,sha256=K9F8XVs1SojfFpdxxLV8gx9E0g81YxEHjigDzLHmDCg,10230
-librus_python_api/models.py,sha256=vqoQAL1IMgnOHRlNWxchMiOdkw7AnYDnyiYEQ2OAHko,36363
+librus_python_api/models.py,sha256=wD4Wg7Jq0dYU2YA8FVztz0EguueN2cue0V0dbvxxJkw,38548
 librus_python_api/modern_body.py,sha256=3L4P_cIrHdIxZqiinFSQrDMhG6iklT1GoA-VEWMJUiI,2682
 librus_python_api/modern_mailbox.py,sha256=2jF9UnJZ5AF6dip-GrMcv_z2kSLpp87dIpVeXk9jMzA,20600
 librus_python_api/modern_messages.py,sha256=qt2CXtrxCZQ-jTt0aQCD6ZaPAJQZXf0BxmvacPo9B0w,10653
@@ -38,11 +38,12 @@ librus_python_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 librus_python_api/recipients.py,sha256=6GQCKo-Zjg3VFSg1J8YXcDsy_U3r6-MUS4VCvz0xdaQ,10033
 librus_python_api/scheduler.py,sha256=3JplYxqvQdFz3aKXcoQUJHE9s3FPw_xRhQ2CPNLuQmA,10729
 librus_python_api/school_reads.py,sha256=PCnZ4lv44j-68FgJpQiMteaPSyfhbX8_3CUyE6zhFcQ,14760
+librus_python_api/school_year_archive.py,sha256=D0A1ywMKgoYgvi-d70__SFreMGvMb_72870Akkbb_m8,15492
 librus_python_api/sending.py,sha256=Nvvk2r-6D6Us53a2fH5GW9PcA6bWEfuOvy6c3M5QVcE,4549
-librus_python_api/service.py,sha256=1hQkDjEIlOwF5_4aSAEkmb1iMdUU51bVyPTVc7BAKJU,93252
+librus_python_api/service.py,sha256=0nu0XEVEnPFZ6gaeDN7Ao9WPmkDfuYbz8nW_Eg-y78I,94275
 librus_python_api/timetable.py,sha256=tX1QK9fQABxzfLaHHqTe8e6rAgdOkCoTOfAHdPwNmLE,9836
 librus_python_api/transport.py,sha256=QnYXnrv1lW4qToYoTv6HyZw-Lt4rDc-_SMTJpMp6_bc,35297
-librus_python_api-1.2.1.dist-info/METADATA,sha256=2EBX-fUeSn5fa9MG7Bgda1npQo-xnBbcgzhuFvnilJ0,11546
-librus_python_api-1.2.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-librus_python_api-1.2.1.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
-librus_python_api-1.2.1.dist-info/RECORD,,
+librus_python_api-1.3.0.dist-info/METADATA,sha256=7LcWlfUprMbkEQZbGWQHxj_p6mhrieVWk30-hAaClQ0,11990
+librus_python_api-1.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+librus_python_api-1.3.0.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
+librus_python_api-1.3.0.dist-info/RECORD,,