librus-python-api 1.4.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

librus_python_api/__init__.py

@@ -35,6 +35,8 @@ from librus_python_api.models import (
     AttendanceView,
     AttendanceWindow,
     Availability,
+    ClassFreeDay,
+    ClassFreeDays,
     CompletedLesson,
     CompletedLessons,
     CompletedLessonsCursor,
@@ -136,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.4.0"
+__version__ = "1.6.0"
 
 __all__ = [
     "ArchiveAbsences",
@@ -216,6 +218,8 @@ __all__ = [
     "AccountClient",
     "AccountCredentials",
     "Availability",
+    "ClassFreeDay",
+    "ClassFreeDays",
     "Attendance",
     "Announcement",
     "Agenda",

librus_python_api/class_free_days.py

@@ -0,0 +1,73 @@
+"""Bounded gateway class free days from independently observed JSON structure."""
+
+import re
+from datetime import date
+from typing import Any
+
+from librus_python_api.config import CLASS_FREE_DAYS_MAX_RECORDS
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import ClassFreeDay
+from librus_python_api.parsers import decode_json
+
+
+def _identifier(value: Any) -> str:
+    if type(value) is not int or value < 0 or len(str(value)) > 64:
+        raise LibrusError(ErrorKind.PARSE)
+    return str(value)
+
+
+def _reference(value: Any) -> str:
+    if not isinstance(value, dict):
+        raise LibrusError(ErrorKind.PARSE)
+    return _identifier(value.get("Id"))
+
+
+def _day(value: Any) -> date:
+    result = None
+    if type(value) is str and re.fullmatch(r"[0-9]{4}-[0-9]{2}-[0-9]{2}", value):
+        try:
+            result = date.fromisoformat(value)
+        except ValueError:
+            pass
+    if result is None:
+        raise LibrusError(ErrorKind.PARSE)
+    return result
+
+
+def parse_class_free_days(body: bytes) -> tuple[ClassFreeDay, ...]:
+    data = decode_json(body)
+    if not isinstance(data, dict) or not isinstance(data.get("ClassFreeDays"), list):
+        raise LibrusError(ErrorKind.PARSE)
+    rows = data["ClassFreeDays"]
+    if len(rows) > CLASS_FREE_DAYS_MAX_RECORDS:
+        raise LibrusError(ErrorKind.LIMIT)
+    items: list[ClassFreeDay] = []
+    seen: set[str] = set()
+    for row in rows:
+        if not isinstance(row, dict):
+            raise LibrusError(ErrorKind.PARSE)
+        identifier = _identifier(row.get("Id"))
+        start, end = _day(row.get("DateFrom")), _day(row.get("DateTo"))
+        first, last = row.get("LessonNoFrom"), row.get("LessonNoTo")
+        if "LessonNoFrom" in row or "LessonNoTo" in row:
+            if (
+                type(first) is not int
+                or type(last) is not int
+                or not 0 <= first <= last <= 99
+            ):
+                raise LibrusError(ErrorKind.PARSE)
+        if identifier in seen or start > end:
+            raise LibrusError(ErrorKind.PARSE)
+        seen.add(identifier)
+        items.append(
+            ClassFreeDay(
+                identifier,
+                _reference(row.get("Class")),
+                _reference(row.get("Type")),
+                start,
+                end,
+                first,
+                last,
+            )
+        )
+    return tuple(items)

librus_python_api/config.py

@@ -449,6 +449,14 @@ ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
                 True,
                 Evidence.INDEPENDENTLY_OBSERVED,
             ),
+            Endpoint(
+                "class_free_days",
+                "GET",
+                "/gateway/api/2.0/ClassFreeDays",
+                SideEffect.NONE,
+                True,
+                Evidence.INDEPENDENTLY_OBSERVED,
+            ),
             Endpoint(
                 "gateway_attendance",
                 "GET",
@@ -855,12 +863,18 @@ WEEKDAY_LABELS = ("pon.", "wt.", "śr.", "czw.", "pt.", "sob.", "ndz.")
 # Observed page-level notices shown instead of the requested content.
 PAGE_NOTICES = MappingProxyType(
     {
+        (
+            "Ten moduł nie jest dostępny w wykorzystywanym przez szkołę wariancie "
+            "rozwiązania LIBRUS Synergia."
+        ): ErrorKind.MODULE_UNAVAILABLE,
         "Ten widok został wyłączony przez administratora szkoły.": (
             ErrorKind.VIEW_DISABLED
         ),
         "Wybrano nieprawidłowy zakres daty.": ErrorKind.INVALID_INPUT,
     }
 )
+MODULE_UNAVAILABLE_PATH = "/modul_niedostepny"
+CLASS_FREE_DAYS_MAX_RECORDS = 4096
 COMPLETED_LESSONS_MAX_WINDOW_DAYS = 371
 COMPLETED_LESSONS_MAX_PAGE_COUNT = 1000
 COMPLETED_LESSONS_MAX_PAGE_ITEMS = 256

librus_python_api/exceptions.py

@@ -14,6 +14,7 @@ __all__ = [
     "LibrusError",
     "LimitError",
     "MaintenanceError",
+    "ModuleUnavailableError",
     "OperationTimeoutError",
     "ParseError",
     "SessionExpiredError",
@@ -36,6 +37,7 @@ class ErrorKind(StrEnum):
     ACCESS_DENIED = "access_denied"
     UNSUPPORTED_CAPABILITY = "unsupported_capability"
     VIEW_DISABLED = "view_disabled"
+    MODULE_UNAVAILABLE = "module_unavailable"
     THROTTLED = "throttled"
     MAINTENANCE = "maintenance"
     CONNECTION = "connection"
@@ -101,6 +103,10 @@ class ViewDisabledError(LibrusError):
     """The school administrator has switched this Synergia view off."""
 
 
+class ModuleUnavailableError(LibrusError):
+    """The school's Synergia product variant does not include this module."""
+
+
 class ThrottledError(LibrusError):
     pass
 
@@ -154,6 +160,7 @@ _ERROR_TYPES: dict[ErrorKind, type[LibrusError]] = {
     ErrorKind.ACCESS_DENIED: AccessDeniedError,
     ErrorKind.UNSUPPORTED_CAPABILITY: UnsupportedCapabilityError,
     ErrorKind.VIEW_DISABLED: ViewDisabledError,
+    ErrorKind.MODULE_UNAVAILABLE: ModuleUnavailableError,
     ErrorKind.THROTTLED: ThrottledError,
     ErrorKind.MAINTENANCE: MaintenanceError,
     ErrorKind.CONNECTION: ConnectionError,

librus_python_api/message_content.py

@@ -57,26 +57,33 @@ def _recipient_receipts(
         raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
     result = []
     total = 0
+    # Rows are recipient/status, or recipient/class/status when the page adds
+    # the class-label column; one table never mixes the two.
+    width = len(cells(table_rows[1]))
     for row in table_rows[1:]:
         columns = cells(row)
-        if len(columns) != 2 or any(
-            c.tag != "td"
-            or c.get("colspan", "1") != "1"
-            or c.get("rowspan", "1") != "1"
-            or next(c.iterdescendants("table"), None) is not None
-            for c in columns
+        if (
+            len(columns) != width
+            or width not in (2, 3)
+            or any(
+                c.tag != "td"
+                or c.get("colspan", "1") != "1"
+                or c.get("rowspan", "1") != "1"
+                or next(c.iterdescendants("table"), None) is not None
+                for c in columns
+            )
         ):
             raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
-        recipient, status = [
-            text(c, MESSAGE_MAX_FIELD_LENGTH, multiline=True) for c in columns
-        ]
+        values = [text(c, MESSAGE_MAX_FIELD_LENGTH, multiline=True) for c in columns]
+        recipient, status = values[0], values[-1]
         if not recipient or not status:
             raise LibrusError(ErrorKind.PARSE)
-        total += len(recipient) + len(status)
+        total += sum(map(len, values))
         if total > MESSAGE_MAX_RECEIPT_TEXT_LENGTH:
             raise LibrusError(ErrorKind.LIMIT)
         stamp = None if status == "NIE" else _timestamp(status)
-        result.append(MessageRecipientReceipt(recipient, status, stamp))
+        label = values[1] if width == 3 and values[1] else None
+        result.append(MessageRecipientReceipt(recipient, status, stamp, label))
     return tuple(result)
 
 

librus_python_api/models.py

@@ -16,6 +16,7 @@ from librus_python_api.exceptions import ErrorKind
 
 type OperationName = Literal[
     "identity",
+    "class_free_days",
     "student_information",
     "final_grades",
     "grades",
@@ -210,6 +211,8 @@ class MessageRecipientReceipt:
     recipient: str = field(repr=False)
     raw_status: str = field(repr=False)
     read_timestamp: MessageTimestamp | None = field(repr=False)
+    # Displayed class label of the optional middle column; None without it.
+    recipient_class: str | None = field(default=None, repr=False)
 
 
 @dataclass(frozen=True, slots=True)
@@ -630,6 +633,24 @@ class CompletedLessons:
     observation: "Observation"
 
 
+@dataclass(frozen=True, slots=True)
+class ClassFreeDay:
+    identifier: str = field(repr=False)
+    class_id: str = field(repr=False)
+    type_id: str = field(repr=False)
+    date_from: date = field(repr=False)
+    date_to: date = field(repr=False)
+    lesson_no_from: int | None = None
+    lesson_no_to: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ClassFreeDays:
+    identity: "Identity" = field(repr=False)
+    items: tuple[ClassFreeDay, ...] = field(repr=False)
+    observation: "Observation"
+
+
 class GradeKind(StrEnum):
     CURRENT = "current"
     PERIOD = "period"

librus_python_api/service.py

@@ -27,6 +27,7 @@ from librus_python_api.attendance_frequency import (
 )
 from librus_python_api.budget import RequestBudget
 from librus_python_api.checkpoint import CHECKPOINT_SERVICE, validate_checkpoint
+from librus_python_api.class_free_days import parse_class_free_days
 from librus_python_api.completed_lessons import (
     parse_completed_lessons,
     validate_selection,
@@ -42,6 +43,7 @@ from librus_python_api.config import (
     GRADE_MAX_WINDOW_DAYS,
     MESSAGE_MAX_CURSOR_IDS,
     MODERN_RECIPIENT_OPERATIONS,
+    MODULE_UNAVAILABLE_PATH,
     NOTIFICATION_COUNTS_ENDPOINT,
     SCHEDULE_RESPONSE_VERSION,
     SESSION_COOKIE,
@@ -83,6 +85,7 @@ from librus_python_api.models import (
     AttendanceFrequency,
     AttendanceView,
     AttendanceWindow,
+    ClassFreeDays,
     CompletedLesson,
     CompletedLessons,
     CompletedLessonsCursor,
@@ -1314,6 +1317,24 @@ class AccountClient:
             ),
         )
 
+    async def class_free_days(
+        self,
+        *,
+        budget: RequestBudget | None = None,
+        max_age_seconds: float = 0.0,
+    ) -> ClassFreeDays:
+        """Read one bounded collection; dates are civil and references stay opaque."""
+
+        async def fetch(budget: RequestBudget, _: bool) -> ClassFreeDays:
+            items = await self._page(
+                "class_free_days", budget, parse_class_free_days, content_type=JSON
+            )
+            return ClassFreeDays(
+                self._session_identity(), items, self._observation("class_free_days")
+            )
+
+        return await self._read(("class_free_days",), fetch, budget, max_age_seconds)
+
     async def attendance(
         self,
         *,
@@ -2438,6 +2459,8 @@ class AccountClient:
         self, response: TransportResponse, content_type: str
     ) -> None:
         if 300 <= response.status < 400:
+            if self._is_module_unavailable_redirect(response):
+                raise LibrusError(ErrorKind.MODULE_UNAVAILABLE)
             # A redirect proves expiry only when it targets a login route.
             # Other redirects must not trigger a new credential submission.
             if self._is_login_redirect(response):
@@ -2446,6 +2469,25 @@ class AccountClient:
         if response.status != 200 or _media_type(response) != content_type:
             raise LibrusError(ErrorKind.PARSE)
 
+    def _is_module_unavailable_redirect(self, response: TransportResponse) -> bool:
+        location = response.headers.get("location", "")
+        if not location or len(location) > 4096:
+            return False
+        try:
+            target = urlsplit(urljoin(response.url, location))
+            source = urlsplit(response.url)
+        except ValueError:
+            return False
+        expected = urlsplit(self._service._connection.origin(ENDPOINTS["identity"]))
+        return (
+            (source.scheme, source.netloc) == (expected.scheme, expected.netloc)
+            and (target.scheme, target.netloc) == (expected.scheme, expected.netloc)
+            and not (
+                target.username or target.password or target.query or target.fragment
+            )
+            and target.path == MODULE_UNAVAILABLE_PATH
+        )
+
     def _is_login_redirect(self, response: TransportResponse) -> bool:
         location = response.headers.get("location", "")
         try:

{librus_python_api-1.4.0.dist-info → librus_python_api-1.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.4.0
+Version: 1.6.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
@@ -42,9 +42,9 @@ 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.4.0` adds formative assessments, including the observation card,
-to grade results. The 1.3.0 archive read passed installed live checks for
-populated and empty archives on two parent logins; see [verification](VERIFICATION.md).
+**Status:** `1.6.0` adds class free days and a typed module-unavailable outcome,
+plus an independent live-check freshness watchdog and targeted mutation/load
+evidence. 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.
@@ -54,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.4.0
+python -m pip install librus-python-api==1.6.0
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -70,7 +70,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.4.0-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.6.0-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.

{librus_python_api-1.4.0.dist-info → librus_python_api-1.6.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-librus_python_api/__init__.py,sha256=Ka6_hAV-fnh3QrjAPyqhWPvaG2eh5w8VT8a5aB_RBNU,6435
+librus_python_api/__init__.py,sha256=DhWaUkE_sGZgqB1aWZh5ZUtyjfIeMJl1KhUPV5WpzLA,6513
 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
@@ -10,11 +10,12 @@ librus_python_api/attendance.py,sha256=HeFAfnIUn4N__yp1zr635Dve55S2jmwtkeIy_6mV5
 librus_python_api/attendance_frequency.py,sha256=SBhED5zuyRIHWdw4urFyTJYykb6EYB7eL4dU3mif1EY,5309
 librus_python_api/budget.py,sha256=8fvqT7eIxyVX2P2OBG27XsYHk_HbtSS4lzuecYpHtgs,2878
 librus_python_api/checkpoint.py,sha256=QBmG9GtpyaGRaFq-FXuGA3yR1BjuMFN9V3RTvvi_FNQ,1930
+librus_python_api/class_free_days.py,sha256=IwoCgr-9ZgEYYQ6717s4cDpyFzbosHMzESMabXJLGqA,2422
 librus_python_api/completed_lessons.py,sha256=sR2oLSGb2q1580l-2upCBv9sQfIcHi7CQfWr1K0EFXI,7635
-librus_python_api/config.py,sha256=zhE2-v3FehMvvsbxMtK1J6iliOp8jYwb4g-e-rFCMEQ,54968
+librus_python_api/config.py,sha256=A5UNZ0oc8Oxt13y0To1REdQLWPgLrH-VRRpcuwodElc,55482
 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
+librus_python_api/exceptions.py,sha256=adVcJuzfB8wGrUlF2SfiyIlE9ZZyTAvGdWRtQIjsA3I,4879
 librus_python_api/files.py,sha256=pQBsIJyfTOZDz83ZB-5fcd-nPMcxR1HJ155h4zTHmsA,9223
 librus_python_api/formative_grades.py,sha256=-F-d1rnFVAIGwg1mN0cryCIBR76OW3v2L4mCWUZ3M7Q,6227
 librus_python_api/grade_parsers.py,sha256=91Kr1-TArzqO-b94ipeIR0a98OV7tRCZQdBWsd9QLZ0,6141
@@ -22,9 +23,9 @@ librus_python_api/grade_records.py,sha256=K0ZzmU1KsA8Jo1MXh30mStApgrigaOKk5ldoBn
 librus_python_api/homework_range.py,sha256=erYfvS6PhHU5XhnR6LkiLNy677hGVflY3UAuHOs-YUw,1663
 librus_python_api/lifecycle.py,sha256=XzA5CEdZFo7iL5IMUrawnRvf2m9BFe0OseP-fpQFaAE,856
 librus_python_api/markup.py,sha256=mjCZf6KJTWUz2vjfXbJ4zM17hnev7a5AFIOW3ip3gsE,5677
-librus_python_api/message_content.py,sha256=sUPuqpjuavqDyn6QGM5aPH4mpoQV62bDLepSSQ2AsUE,8686
+librus_python_api/message_content.py,sha256=v_qoEAoaYS0_9MQBaj57i5XnC7pzv_HHWefgTt4CNyM,9043
 librus_python_api/messages.py,sha256=K9F8XVs1SojfFpdxxLV8gx9E0g81YxEHjigDzLHmDCg,10230
-librus_python_api/models.py,sha256=wWMw2TXmeRWP3yJLSDmdVDYsbXRIztm3mEhCYPH1gco,40310
+librus_python_api/models.py,sha256=Z6eV-ftjaN8YGUW8SntVTLjGCqe1EWRpd0P1Va8EwDs,40991
 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
@@ -41,10 +42,10 @@ librus_python_api/scheduler.py,sha256=3JplYxqvQdFz3aKXcoQUJHE9s3FPw_xRhQ2CPNLuQm
 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=yjdKc4-psMDlIHVLud-WA2YDXafKPuTT-hLdVmdWsIM,94464
+librus_python_api/service.py,sha256=7ioLx-8C-I0Qla8YUyu5UqhjBPlcUvEFpQSYH-9yjzs,96232
 librus_python_api/timetable.py,sha256=tX1QK9fQABxzfLaHHqTe8e6rAgdOkCoTOfAHdPwNmLE,9836
 librus_python_api/transport.py,sha256=QnYXnrv1lW4qToYoTv6HyZw-Lt4rDc-_SMTJpMp6_bc,35297
-librus_python_api-1.4.0.dist-info/METADATA,sha256=VKqlisucgyKpgIO7aGudJPX8-gKpm5mB3ZEm_59jJzE,12031
-librus_python_api-1.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-librus_python_api-1.4.0.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
-librus_python_api-1.4.0.dist-info/RECORD,,
+librus_python_api-1.6.0.dist-info/METADATA,sha256=O_HfTBq306xfvGOiGLwpWeWdHb2G9m_2c2PN9HmY4VY,11994
+librus_python_api-1.6.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+librus_python_api-1.6.0.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
+librus_python_api-1.6.0.dist-info/RECORD,,