librus-python-api 1.0.3__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,
@@ -65,6 +72,9 @@ from librus_python_api.models import (
     MessageTimestamp,
     MessagingBackend,
     ModernAccountData,
+    ModernCorrespondent,
+    ModernCorrespondentReference,
+    ModernCorrespondents,
     ModernIdentity,
     ModernMessageAttachment,
     ModernMessageAttachmentReference,
@@ -82,6 +92,10 @@ from librus_python_api.models import (
     ModernRecipientTypeReference,
     ModernRecipientTypes,
     ModernSendSubmission,
+    ModernTeacherSubject,
+    ModernTeacherSubjects,
+    ModernUnreadCounts,
+    ModernUnreadFolders,
     NotificationCategory,
     NotificationCount,
     NotificationCounts,
@@ -103,6 +117,7 @@ from librus_python_api.models import (
     SchoolAverage,
     SchoolDetail,
     SchoolReference,
+    SchoolYearArchive,
     SendResult,
     SendStatus,
     SendSubmission,
@@ -120,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.0.3"
+__version__ = "1.3.0"
 
 __all__ = [
+    "ArchiveAbsences",
+    "ArchiveAchievement",
+    "ArchiveCounts",
+    "ArchiveDescriptive",
+    "ArchiveMarks",
+    "ArchiveSubject",
+    "ArchiveYear",
+    "SchoolYearArchive",
     "AccountContext",
     "MessagingBackend",
     "ModernAccountData",
@@ -135,6 +158,13 @@ __all__ = [
     "ModernMessageRecipientReceipt",
     "ModernMessages",
     "ModernMessagesCursor",
+    "ModernUnreadCounts",
+    "ModernCorrespondent",
+    "ModernCorrespondentReference",
+    "ModernCorrespondents",
+    "ModernTeacherSubject",
+    "ModernTeacherSubjects",
+    "ModernUnreadFolders",
     "ModernMessagesPage",
     "ModernMessageSummary",
     "ModernRecipient",

librus_python_api/config.py

@@ -207,6 +207,60 @@ ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
                 Evidence.INDEPENDENTLY_OBSERVED,
                 "messages",
             ),
+            Endpoint(
+                "modern_archive_messages_received",
+                "GET",
+                "/api/archive/inbox/messages",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_archive_messages_sent",
+                "GET",
+                "/api/archive/outbox/messages",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_unread_counts",
+                "GET",
+                "/api/inbox/unreadMessagesCount",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_senders",
+                "GET",
+                "/api/inbox/messages/senders",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_receivers",
+                "GET",
+                "/api/outbox/messages/receivers",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_teacher_subjects",
+                "GET",
+                "/api/receivers/student-subjects",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
             Endpoint(
                 "modern_content_received",
                 "GET",
@@ -451,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",
@@ -668,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"}
 )
@@ -878,17 +969,67 @@ def modern_directory_query(
 
 
 def modern_mailbox_query(
-    folder: MessageFolder, page: int, page_size: int
+    folder: MessageFolder,
+    page: int,
+    page_size: int,
+    *,
+    correspondent: str | None = None,
+    unread_only: bool = False,
 ) -> dict[str, str]:
+    """Page selection plus the web app's own sender/receiver/unread filters."""
     if (
         not isinstance(folder, MessageFolder)
         or type(page) is not int
         or not 1 <= page <= 1000
         or type(page_size) is not int
         or not 1 <= page_size <= 50
+        or type(unread_only) is not bool
+        or (unread_only and folder is not MessageFolder.RECEIVED)
+        or (
+            correspondent is not None
+            and (
+                type(correspondent) is not str
+                or re.fullmatch(r"[0-9]{1,64}", correspondent) is None
+            )
+        )
     ):
         raise LibrusError(ErrorKind.INVALID_INPUT)
-    return {"page": str(page), "limit": str(page_size)}
+    query = {}
+    if correspondent is not None:
+        query[MODERN_CORRESPONDENT_FILTERS[folder]] = correspondent
+    if unread_only:
+        query["unreadOnly"] = "1"
+    return query | {"page": str(page), "limit": str(page_size)}
+
+
+MODERN_MAILBOX_OPERATIONS = frozenset(
+    {
+        "modern_messages_received",
+        "modern_messages_sent",
+        "modern_archive_messages_received",
+        "modern_archive_messages_sent",
+    }
+)
+MODERN_CORRESPONDENT_FILTERS = MappingProxyType(
+    {MessageFolder.RECEIVED: "senderId", MessageFolder.SENT: "receiverId"}
+)
+# Filters observed in the web app for the current mailbox only.
+MODERN_MAILBOX_FILTERS = MappingProxyType(
+    {
+        "modern_messages_received": frozenset({"senderId", "unreadOnly"}),
+        "modern_messages_sent": frozenset({"receiverId"}),
+    }
+)
+MODERN_UNREAD_COUNT_FIELDS = (
+    "inbox",
+    "notes",
+    "alerts",
+    "substitutions",
+    "absences",
+    "justifications",
+    "trash",
+)
+MODERN_MAX_UNREAD_COUNT = 1000000
 
 
 def validate_modern_query(operation: str, query: Mapping[str, str]) -> None:
@@ -897,14 +1038,27 @@ def validate_modern_query(operation: str, query: Mapping[str, str]) -> None:
         type(v) is not str for v in query.values()
     ):
         raise LibrusError(ErrorKind.INVALID_INPUT)
-    if operation in {"modern_messages_received", "modern_messages_sent"}:
-        if set(query) != {"page", "limit"} or any(
+    if operation in MODERN_MAILBOX_OPERATIONS:
+        filters = MODERN_MAILBOX_FILTERS.get(operation, frozenset())
+        if not {"page", "limit"} <= set(query) <= {"page", "limit"} | filters or any(
             re.fullmatch(r"[1-9][0-9]{0,3}", query[name]) is None
             for name in ("page", "limit")
         ):
             raise LibrusError(ErrorKind.INVALID_INPUT)
+        folder = (
+            MessageFolder.SENT
+            if operation == "modern_messages_sent"
+            else MessageFolder.RECEIVED
+        )
+        unread = query.get("unreadOnly")
+        if unread not in (None, "1"):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
         modern_mailbox_query(
-            MessageFolder.RECEIVED, int(query["page"]), int(query["limit"])
+            folder,
+            int(query["page"]),
+            int(query["limit"]),
+            correspondent=query.get(MODERN_CORRESPONDENT_FILTERS[folder]),
+            unread_only=unread == "1",
         )
         return
     allowed = [

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",
@@ -48,6 +49,12 @@ type OperationName = Literal[
     "modern_send_message",
     "modern_school_recipients",
     "modern_class_parents",
+    "modern_archive_messages_received",
+    "modern_archive_messages_sent",
+    "modern_unread_counts",
+    "modern_senders",
+    "modern_receivers",
+    "modern_teacher_subjects",
     "modern_messages_received",
     "modern_messages_sent",
     "modern_content_received",
@@ -393,6 +400,46 @@ class ModernMessageReference:
     folder: MessageFolder
     identifier: str = field(repr=False)
     account: str = field(repr=False)
+    # Listed from the archive mailbox. Archived content opens are not supported.
+    archived: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ModernCorrespondentReference:
+    """A sender (received folder) or receiver (sent folder) to filter a list by."""
+
+    folder: MessageFolder
+    identifier: str = field(repr=False)
+    account: str = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ModernCorrespondent:
+    reference: ModernCorrespondentReference = field(repr=False)
+    first_name: str = field(repr=False)
+    last_name: str = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ModernCorrespondents:
+    identity: "Identity" = field(repr=False)
+    folder: MessageFolder
+    items: tuple[ModernCorrespondent, ...] = field(repr=False)
+    observation: "Observation"
+
+
+@dataclass(frozen=True, slots=True)
+class ModernTeacherSubject:
+    # The teacher's modern account ID, as a decimal string.
+    teacher_identifier: str = field(repr=False)
+    subject: str = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ModernTeacherSubjects:
+    identity: "Identity" = field(repr=False)
+    items: tuple[ModernTeacherSubject, ...] = field(repr=False)
+    observation: "Observation"
 
 
 @dataclass(frozen=True, slots=True)
@@ -417,6 +464,11 @@ class ModernMessagesPage:
     items: tuple[ModernMessageSummary, ...] = field(repr=False)
     fingerprint: str = field(repr=False)
     observation: "Observation"
+    archived: bool = False
+    correspondent: ModernCorrespondentReference | None = field(default=None, repr=False)
+    unread_only: bool = False
+    # Archive listings only: the upstream archivingInProgress status flag.
+    archiving_in_progress: bool | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -429,6 +481,9 @@ class ModernMessagesCursor:
     total_count: int
     fingerprint: str = field(repr=False)
     seen_ids: tuple[str, ...] = field(repr=False)
+    archived: bool = False
+    correspondent: str | None = field(default=None, repr=False)
+    unread_only: bool = False
 
 
 @dataclass(frozen=True, slots=True)
@@ -441,6 +496,32 @@ class ModernMessages:
     next_cursor: ModernMessagesCursor | None = field(repr=False)
     truncation_reason: Literal["item_limit", "page_limit"] | None
     observation: "Observation"
+    archived: bool = False
+    correspondent: ModernCorrespondentReference | None = field(default=None, repr=False)
+    unread_only: bool = False
+    # Archive listings only: the upstream archivingInProgress status flag.
+    archiving_in_progress: bool | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ModernUnreadFolders:
+    """Unread counters the modern mailbox shows for one mailbox section."""
+
+    inbox: int
+    notes: int
+    alerts: int
+    substitutions: int
+    absences: int
+    justifications: int
+    trash: int
+
+
+@dataclass(frozen=True, slots=True)
+class ModernUnreadCounts:
+    identity: "Identity" = field(repr=False)
+    current: ModernUnreadFolders
+    archive: ModernUnreadFolders
+    observation: "Observation"
 
 
 @dataclass(frozen=True, slots=True)
@@ -698,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)