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

librus_python_api/modern_mailbox.py

@@ -14,11 +14,17 @@ from librus_python_api.config import (
     MESSAGE_MAX_CURSOR_IDS,
     MESSAGE_MAX_FIELD_LENGTH,
     MESSAGE_MAX_TOTAL_TEXT_LENGTH,
+    MODERN_MAX_LABEL,
+    MODERN_MAX_RECIPIENTS,
+    MODERN_MAX_UNREAD_COUNT,
+    MODERN_UNREAD_COUNT_FIELDS,
     modern_mailbox_query,
 )
 from librus_python_api.exceptions import ErrorKind, LibrusError
 from librus_python_api.models import (
     MessageFolder,
+    ModernCorrespondent,
+    ModernCorrespondentReference,
     ModernMessageAttachment,
     ModernMessageAttachmentReference,
     ModernMessageRecipientReceipt,
@@ -26,6 +32,7 @@ from librus_python_api.models import (
     ModernMessagesCursor,
     ModernMessagesPage,
     ModernMessageSummary,
+    ModernUnreadFolders,
 )
 from librus_python_api.modern_body import render_body
 from librus_python_api.parsers import decode_json
@@ -48,6 +55,7 @@ def validate_reference(reference: ModernMessageReference, account: str) -> None:
         not isinstance(reference, ModernMessageReference)
         or not isinstance(reference.folder, MessageFolder)
         or reference.account != account
+        or type(reference.archived) is not bool
         or type(reference.identifier) is not str
         or re.fullmatch(r"[0-9]{1,64}", reference.identifier) is None
     ):
@@ -75,7 +83,9 @@ def _date(value: Any) -> datetime:
     raise LibrusError(ErrorKind.PARSE)
 
 
-def _summary(data: Any, folder: MessageFolder, account: str) -> ModernMessageSummary:
+def _summary(
+    data: Any, folder: MessageFolder, account: str, archived: bool
+) -> ModernMessageSummary:
     if not isinstance(data, dict):
         raise LibrusError(ErrorKind.PARSE)
     correspondent = (
@@ -98,7 +108,9 @@ def _summary(data: Any, folder: MessageFolder, account: str) -> ModernMessageSum
     read = data.get("readDate")
     read_at = None if read in (None, "") else _date(read)
     return ModernMessageSummary(
-        ModernMessageReference(folder, identifier(data.get("messageId")), account),
+        ModernMessageReference(
+            folder, identifier(data.get("messageId")), account, archived
+        ),
         name,
         subject,
         _date(stamp),
@@ -110,13 +122,23 @@ def _summary(data: Any, folder: MessageFolder, account: str) -> ModernMessageSum
 
 
 def parse_page(
-    body: bytes, folder: MessageFolder, page: int, page_size: int, account: str
-) -> tuple[tuple[ModernMessageSummary, ...], int, str]:
+    body: bytes,
+    folder: MessageFolder,
+    page: int,
+    page_size: int,
+    account: str,
+    archived: bool = False,
+) -> tuple[tuple[ModernMessageSummary, ...], int, str, bool | None]:
     modern_mailbox_query(folder, page, page_size)
     data = decode_json(body)
     if not isinstance(data, dict) or not {"data", "total"} <= set(data):
         raise LibrusError(ErrorKind.PARSE)
-    if data.get("archivingInProgress", False) is not False:
+    in_progress = data.get("archivingInProgress", False)
+    if type(in_progress) is not bool:
+        raise LibrusError(ErrorKind.PARSE)
+    # Live archive pages report true while listing normally; it is a status
+    # flag there. The current mailbox has never shown it.
+    if in_progress and not archived:
         raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
     entries, total = data["data"], data["total"]
     if (
@@ -130,7 +152,7 @@ def parse_page(
     expected = min(page_size, max(0, total - (page - 1) * page_size))
     if len(entries) != expected:
         raise LibrusError(ErrorKind.PARSE)
-    items = tuple(_summary(item, folder, account) for item in entries)
+    items = tuple(_summary(item, folder, account, archived) for item in entries)
     if len({item.reference.identifier for item in items}) != len(items):
         raise LibrusError(ErrorKind.PARSE)
     if (
@@ -155,7 +177,7 @@ def parse_page(
             )
         ).encode()
     ).hexdigest()
-    return items, total, fingerprint
+    return items, total, fingerprint, in_progress if archived else None
 
 
 @dataclass(frozen=True, slots=True, repr=False)
@@ -280,6 +302,7 @@ def parse_content(body: bytes, reference: ModernMessageReference) -> ParsedConte
         content | {"isAnyFileAttached": has_attachment},
         reference.folder,
         reference.account,
+        reference.archived,
     )
     if summary.reference != reference:
         raise LibrusError(ErrorKind.PARSE)
@@ -326,8 +349,15 @@ def validate_selection(
     max_pages: int,
     limit: int,
     account: str,
+    archived: bool = False,
+    correspondent: str | None = None,
+    unread_only: bool = False,
 ) -> None:
-    modern_mailbox_query(folder, 1, page_size)
+    modern_mailbox_query(
+        folder, 1, page_size, correspondent=correspondent, unread_only=unread_only
+    )
+    if type(archived) is not bool:
+        raise LibrusError(ErrorKind.INVALID_INPUT)
     if type(max_pages) is not int or not 1 <= max_pages <= MESSAGE_MAX_BATCH_PAGES:
         raise LibrusError(ErrorKind.INVALID_INPUT)
     if type(limit) is not int or not 1 <= limit <= MESSAGE_MAX_BATCH_ITEMS:
@@ -340,6 +370,9 @@ def validate_selection(
     if (
         cursor.account != account
         or cursor.folder is not folder
+        or cursor.archived is not archived
+        or cursor.correspondent != correspondent
+        or cursor.unread_only is not unread_only
         or cursor.page_size != page_size
         or type(cursor.offset) is not int
         or not 0 <= cursor.offset < page_size
@@ -367,6 +400,9 @@ async def collect(
     page_size: int,
     max_pages: int,
     limit: int,
+    archived: bool = False,
+    correspondent: str | None = None,
+    unread_only: bool = False,
 ) -> tuple[
     tuple[ModernMessageSummary, ...],
     int,
@@ -374,7 +410,17 @@ async def collect(
     ModernMessagesCursor | None,
     Literal["item_limit", "page_limit"] | None,
 ]:
-    validate_selection(folder, cursor, page_size, max_pages, limit, account)
+    validate_selection(
+        folder,
+        cursor,
+        page_size,
+        max_pages,
+        limit,
+        account,
+        archived,
+        correspondent,
+        unread_only,
+    )
     page = cursor.page if cursor else 1
     offset = cursor.offset if cursor else 0
     seen = list(cursor.seen_ids) if cursor else []
@@ -427,6 +473,9 @@ async def collect(
                         total,
                         result.fingerprint,
                         tuple(seen),
+                        archived,
+                        correspondent,
+                        unread_only,
                     ),
                     "item_limit",
                 )
@@ -452,8 +501,87 @@ async def collect(
                     total,
                     result.fingerprint,
                     tuple(seen),
+                    archived,
+                    correspondent,
+                    unread_only,
                 ),
                 "item_limit" if len(items) >= limit else "page_limit",
             )
         page, offset = page + 1, 0
     raise AssertionError("Bounded collector must terminate")
+
+
+def _unread_folders(data: dict[str, Any], prefix: str) -> ModernUnreadFolders:
+    values = []
+    for name in MODERN_UNREAD_COUNT_FIELDS:
+        key = prefix + name[0].upper() + name[1:] if prefix else name
+        value = data.get(key)
+        if type(value) is not int or value < 0:
+            raise LibrusError(ErrorKind.PARSE)
+        if value > MODERN_MAX_UNREAD_COUNT:
+            raise LibrusError(ErrorKind.LIMIT)
+        values.append(value)
+    return ModernUnreadFolders(*values)
+
+
+def parse_unread_counts(
+    body: bytes,
+) -> tuple[ModernUnreadFolders, ModernUnreadFolders]:
+    """Current and archive counters; unknown extra counters stay inert."""
+    data = decode_json(body)
+    counts = data.get("data") if isinstance(data, dict) else None
+    if not isinstance(counts, dict):
+        raise LibrusError(ErrorKind.PARSE)
+    return _unread_folders(counts, ""), _unread_folders(counts, "archive")
+
+
+def validate_correspondent(
+    reference: ModernCorrespondentReference | None, folder: MessageFolder, account: str
+) -> str | None:
+    """The filter value for a correspondent listed for this folder and login."""
+    if reference is None:
+        return None
+    if (
+        not isinstance(reference, ModernCorrespondentReference)
+        or reference.folder is not folder
+        or reference.account != account
+        or type(reference.identifier) is not str
+        or re.fullmatch(r"[0-9]{1,64}", reference.identifier) is None
+    ):
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    return reference.identifier
+
+
+def _name(value: Any) -> str:
+    if type(value) is not str or len(value) > MODERN_MAX_LABEL or "\x00" in value:
+        raise LibrusError(ErrorKind.PARSE)
+    return value
+
+
+def parse_correspondents(
+    body: bytes, folder: MessageFolder, account: str
+) -> tuple[ModernCorrespondent, ...]:
+    """People the folder's messages came from (received) or went to (sent)."""
+    role = "sender" if folder is MessageFolder.RECEIVED else "receiver"
+    data = decode_json(body)
+    entries = data.get("data") if isinstance(data, dict) else None
+    if not isinstance(entries, list):
+        raise LibrusError(ErrorKind.PARSE)
+    if len(entries) > MODERN_MAX_RECIPIENTS:
+        raise LibrusError(ErrorKind.LIMIT)
+    items = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            raise LibrusError(ErrorKind.PARSE)
+        first = _name(entry.get(f"{role}FirstName"))
+        last = _name(entry.get(f"{role}LastName"))
+        # Institutional senders can carry a single name part; never both empty.
+        if not (first.strip() or last.strip()):
+            raise LibrusError(ErrorKind.PARSE)
+        reference = ModernCorrespondentReference(
+            folder, identifier(entry.get(f"{role}Id")), account
+        )
+        items.append(ModernCorrespondent(reference, first, last))
+    if len({item.reference.identifier for item in items}) != len(items):
+        raise LibrusError(ErrorKind.PARSE)
+    return tuple(items)

librus_python_api/modern_messages.py

@@ -23,6 +23,7 @@ from librus_python_api.models import (
     ModernRecipientReference,
     ModernRecipientType,
     ModernRecipientTypeReference,
+    ModernTeacherSubject,
     SendStatus,
 )
 from librus_python_api.parsers import decode_json
@@ -274,3 +275,25 @@ def parse_modern_send_response(body: bytes, status: int) -> SendStatus:
         ):
             return SendStatus.REJECTED
     raise LibrusError(ErrorKind.UNKNOWN_DELIVERY)
+
+
+def parse_teacher_subjects(body: bytes) -> tuple[ModernTeacherSubject, ...]:
+    """Teacher account IDs paired with the subjects they teach the student."""
+    entries = _object(decode_json(body)).get("data")
+    if not isinstance(entries, list):
+        raise LibrusError(ErrorKind.PARSE)
+    if len(entries) > MODERN_MAX_RECIPIENTS:
+        raise LibrusError(ErrorKind.LIMIT)
+    items = []
+    for entry in entries:
+        value = _object(entry)
+        raw = value.get("teacherIdentifier")
+        if type(raw) is int and 0 < raw < 10**64:
+            raw = str(raw)
+        item = ModernTeacherSubject(_identifier(raw), _label(value.get("subject")))
+        # Live lists can repeat an identical pair; the copy adds nothing.
+        if item not in items:
+            items.append(item)
+    if sum(len(item.subject) for item in items) > MODERN_MAX_TOTAL_TEXT:
+        raise LibrusError(ErrorKind.LIMIT)
+    return tuple(items)