librus-python-api 1.0.0__py3-none-any.whl

librus_python_api/grade_records.py

@@ -0,0 +1,454 @@
+"""Original bounded parser for inline semester grades and school averages."""
+
+import re
+from dataclasses import dataclass, field
+from typing import Literal, cast
+
+from lxml import html
+
+from librus_python_api import markup
+from librus_python_api.config import (
+    GRADE_AVERAGE_HEADERS,
+    GRADE_BODY_PREFIX_COLUMNS,
+    GRADE_CURRENT_HEADER,
+    GRADE_EMPTY_MARKERS,
+    GRADE_MAX_METADATA_LENGTH,
+    GRADE_MAX_RECORDS,
+    GRADE_MAX_SUBJECTS,
+    GRADE_PERIOD_HEADERS,
+    GRADE_PREDICTED_ANNUAL_HEADER,
+    GRADE_PREDICTED_PERIOD_HEADERS,
+    GRADE_PUBLICATION_DATE_LABEL,
+    GRADE_PUBLICATION_PERIOD_LABELS,
+    GRADE_PUBLICATION_TEACHER_LABEL,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.grade_parsers import _locate, _subject_rows, _summary
+from librus_python_api.models import (
+    Availability,
+    DescriptiveGrade,
+    DescriptiveGradeSummary,
+    GradeKind,
+    GradeRecords,
+    GradeSummaryValue,
+    NumericGrade,
+    SchoolAverage,
+)
+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 _layout(table: html.HtmlElement) -> tuple[list[int], dict[int, int]]:
+    current: list[int] = []
+    averages: dict[int, int] = {}
+    for row in markup.rows(table):
+        if next(row.iterancestors("thead"), None) is None:
+            continue
+        cells = markup.cells(row)
+        if not any(markup.text(c) == GRADE_CURRENT_HEADER for c in cells):
+            continue
+        if current:
+            raise LibrusError(ErrorKind.PARSE)
+        position = GRADE_BODY_PREFIX_COLUMNS
+        for cell in cells:
+            if markup.text(cell) == GRADE_CURRENT_HEADER:
+                if markup.colspan(cell) != 1:
+                    raise LibrusError(ErrorKind.PARSE)
+                current.append(position)
+            period = GRADE_AVERAGE_HEADERS.get(_label(cell.get("title", "")))
+            if period is not None:
+                if period in averages or markup.colspan(cell) != 1:
+                    raise LibrusError(ErrorKind.PARSE)
+                averages[period] = position
+            position += markup.colspan(cell)
+    if len(current) != 2:
+        raise LibrusError(ErrorKind.PARSE)
+    return current, averages
+
+
+def _numeric(
+    element: html.HtmlElement,
+    subject: str,
+    semester: Literal[0, 1, 2],
+    kind: GradeKind = GradeKind.CURRENT,
+) -> NumericGrade:
+    metadata = markup.tooltip_fields(element)
+    counts = metadata.get("Licz do średniej")
+    if counts is not None and counts.casefold() not in ("tak", "nie"):
+        raise LibrusError(ErrorKind.PARSE)
+    weight = metadata.get("Waga")
+    if weight is not None and not re.fullmatch(r"[0-9]{1,4}", weight):
+        raise LibrusError(ErrorKind.PARSE)
+    raw = markup.text(element)
+    if not raw:
+        raise LibrusError(ErrorKind.PARSE)
+    href = element.get("href")
+    if href is not None and len(href) > GRADE_MAX_METADATA_LENGTH:
+        raise LibrusError(ErrorKind.LIMIT)
+    return NumericGrade(
+        subject,
+        raw,
+        markup.civil_date(metadata.get("Data")),
+        semester,
+        None if counts is None else counts.casefold() == "tak",
+        None if weight is None else int(weight),
+        metadata.get("Kategoria"),
+        metadata.get("Nauczyciel"),
+        metadata.get("Komentarz"),
+        href,
+        tuple(metadata.items()),
+        kind,
+    )
+
+
+def _descriptive(
+    box: html.HtmlElement,
+    element: html.HtmlElement,
+    subject: str,
+    semester: Literal[0, 1, 2],
+    kind: GradeKind = GradeKind.CURRENT,
+) -> DescriptiveGrade:
+    metadata = markup.tooltip_fields(box)
+    raw = markup.text(element)
+    if not raw:
+        raise LibrusError(ErrorKind.PARSE)
+    return DescriptiveGrade(
+        subject,
+        raw,
+        markup.civil_date(metadata.get("Data")),
+        semester,
+        metadata.get("Nauczyciel"),
+        metadata.get("Komentarz"),
+        tuple(metadata.items()),
+        kind,
+    )
+
+
+@dataclass(slots=True)
+class _Collection:
+    numeric: list[NumericGrade] = field(default_factory=list, repr=False)
+    descriptive: list[DescriptiveGrade] = field(default_factory=list, repr=False)
+    descriptive_summaries: list[DescriptiveGradeSummary] = field(
+        default_factory=list, repr=False
+    )
+    averages: list[SchoolAverage] = field(default_factory=list, repr=False)
+    subjects: set[tuple[bool, 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)
+
+    def check_size(self) -> None:
+        if (
+            len(self.numeric) + len(self.descriptive) + len(self.descriptive_summaries)
+            > GRADE_MAX_RECORDS
+        ):
+            raise LibrusError(ErrorKind.LIMIT)
+
+    def subject(self, value: str, *, descriptive: bool = False) -> None:
+        key = (descriptive, value)
+        if not value or key in self.subjects:
+            raise LibrusError(ErrorKind.PARSE)
+        self.subjects.add(key)
+        if len(self.subjects) > GRADE_MAX_SUBJECTS:
+            raise LibrusError(ErrorKind.LIMIT)
+
+
+def _boxes(cell: html.HtmlElement) -> list[html.HtmlElement]:
+    return [
+        node
+        for node in cell.iter("span")
+        if "grade-box" in node.get("class", "").split()
+    ]
+
+
+def _entries(
+    cell: html.HtmlElement,
+    subject: str,
+    period: Literal[0, 1, 2],
+    collection: _Collection,
+    *,
+    kind: GradeKind = GradeKind.CURRENT,
+    descriptive: bool = False,
+    require_empty_marker: bool = True,
+) -> None:
+    boxes = _boxes(cell)
+    if (
+        not boxes
+        and require_empty_marker
+        and markup.text(cell) not in GRADE_EMPTY_MARKERS
+    ):
+        if (
+            not descriptive
+            or period == 0
+            or any(isinstance(node.tag, str) for node in cell)
+        ):
+            raise LibrusError(ErrorKind.PARSE)
+        raw = markup.text(cell)
+        if len(raw) > GRADE_MAX_METADATA_LENGTH:
+            raise LibrusError(ErrorKind.LIMIT)
+        collection.descriptive_summaries.append(
+            DescriptiveGradeSummary(subject, period, raw)
+        )
+        collection.check_size()
+    for box in boxes:
+        anchors = [e for e in box if e.tag == "a"]
+        descriptions = [
+            e for e in box if e.tag == "span" and "ocena" in e.get("class", "").split()
+        ]
+        if len(anchors) + len(descriptions) != 1:
+            raise LibrusError(ErrorKind.PARSE)
+        if anchors:
+            record = _numeric(anchors[0], subject, period, kind)
+            if descriptive:
+                href = record.href
+                if href is not None and re.sub(
+                    r"[\x00-\x20]", "", href
+                ).casefold().startswith(("javascript:", "data:", "vbscript:")):
+                    href = None
+                collection.descriptive.append(
+                    DescriptiveGrade(
+                        record.subject,
+                        record.raw,
+                        record.day,
+                        record.semester,
+                        record.teacher,
+                        record.comment,
+                        record.metadata,
+                        kind,
+                        href,
+                    )
+                )
+            else:
+                collection.numeric.append(record)
+        else:
+            collection.descriptive.append(
+                _descriptive(box, descriptions[0], subject, period, kind)
+            )
+        collection.consumed.add(box)
+        collection.check_size()
+
+
+def _descriptive_row(cells: list[html.HtmlElement]) -> bool:
+    return (
+        len(cells) in (4, 6)
+        and {"micro", "center", "screen-only"} <= set(cells[0].get("class", "").split())
+        and all(markup.colspan(cell) == 1 for cell in cells)
+    )
+
+
+def _read_descriptive_row(
+    cells: list[html.HtmlElement], collection: _Collection
+) -> None:
+    subject = markup.text(cells[1])
+    collection.subject(subject, descriptive=True)
+    for period in (1, 2):
+        _entries(cells[period + 1], subject, period, collection, descriptive=True)
+    if len(cells) == 6:
+        for cell in cells[4:]:
+            if _boxes(cell):
+                # These columns have no established semester semantics.
+                raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+
+
+def _period_columns(table: html.HtmlElement) -> dict[tuple[int, GradeKind], int]:
+    result: dict[tuple[int, GradeKind], int] = {}
+    for row in markup.rows(table):
+        cells = markup.cells(row)
+        if next(row.iterancestors("thead"), None) is None or not any(
+            markup.text(c) == GRADE_CURRENT_HEADER for c in cells
+        ):
+            continue
+        position = GRADE_BODY_PREFIX_COLUMNS
+        for cell in cells:
+            label = _label(cell.get("title", ""))
+            period = GRADE_PERIOD_HEADERS.get(label)
+            kind = GradeKind.ANNUAL if period == 0 else GradeKind.PERIOD
+            if label == GRADE_PREDICTED_ANNUAL_HEADER:
+                period, kind = 0, GradeKind.PREDICTED_ANNUAL
+            elif label in GRADE_PREDICTED_PERIOD_HEADERS:
+                period, kind = (
+                    GRADE_PREDICTED_PERIOD_HEADERS[label],
+                    GradeKind.PREDICTED_PERIOD,
+                )
+            if period is not None:
+                if (period, kind) in result or markup.colspan(cell) != 1:
+                    raise LibrusError(ErrorKind.PARSE)
+                result[(period, kind)] = position
+            position += markup.colspan(cell)
+    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):
+        if cells[0].getparent() in collection.publication_rows:
+            continue
+        if _descriptive_row(cells):
+            _read_descriptive_row(cells, collection)
+            continue
+        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)
+            value = (
+                GradeSummaryValue(Availability.UNAVAILABLE, None)
+                if index is None or markup.colspan(columns[index]) != 1
+                else GradeSummaryValue(
+                    Availability.AVAILABLE, markup.text(columns[index])
+                )
+            )
+            collection.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()
+        for period, index in enumerate(current, start=1):
+            if columns[index] not in seen:
+                _entries(
+                    columns[index], subject, cast(Literal[1, 2], period), collection
+                )
+                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)
+            _entries(
+                cell,
+                subject,
+                cast(Literal[0, 1, 2], period),
+                collection,
+                kind=kind,
+                require_empty_marker=False,
+            )
+
+
+def _read_publications(table: html.HtmlElement, collection: _Collection) -> None:
+    rows = list(markup.rows(table))
+    for index, row in enumerate(rows):
+        headers = [
+            cell
+            for cell in markup.cells(row)
+            if cell.tag == "th"
+            and list(cell.iter("strong"))
+            and GRADE_PUBLICATION_DATE_LABEL in cell.text_content()
+        ]
+        if not headers:
+            continue
+        if len(headers) != 1 or index + 1 == len(rows):
+            raise LibrusError(ErrorKind.PARSE)
+        header = headers[0]
+        titles = list(header.iter("strong"))
+        if len(titles) != 1:
+            raise LibrusError(ErrorKind.PARSE)
+        title = markup.text(titles[0])
+        info = markup.text(header)
+        date_info = info.partition(GRADE_PUBLICATION_DATE_LABEL)[2].strip()
+        day = markup.civil_date(date_info[:10])
+        if len(date_info) > 10 and date_info[10] not in (" ", ",", ")"):
+            raise LibrusError(ErrorKind.PARSE)
+        teacher_info = info.partition(GRADE_PUBLICATION_TEACHER_LABEL)[2].strip()
+        teacher = teacher_info.rsplit(")", 1)[0].strip() if teacher_info else None
+        matching = {
+            period
+            for label, period in GRADE_PUBLICATION_PERIOD_LABELS.items()
+            if re.search(r"(?<!\w)" + re.escape(label) + r"(?!\w)", title)
+        }
+        if len(matching) > 1:
+            raise LibrusError(ErrorKind.PARSE)
+        paragraphs = list(rows[index + 1].iter("p"))
+        raw = "\n".join(markup.text(paragraph) for paragraph in paragraphs).strip()
+        if not title or not raw:
+            raise LibrusError(ErrorKind.PARSE)
+        if len(raw) > GRADE_MAX_METADATA_LENGTH:
+            raise LibrusError(ErrorKind.LIMIT)
+        metadata = (("Data", date_info[:10]),)
+        collection.descriptive.append(
+            DescriptiveGrade(
+                title,
+                raw,
+                day,
+                cast(Literal[1, 2] | None, next(iter(matching), None)),
+                teacher,
+                None,
+                metadata,
+                GradeKind.PUBLICATION,
+            )
+        )
+        collection.consumed.add(header)
+        collection.publication_rows.update((row, rows[index + 1]))
+        collection.check_size()
+
+
+def parse_grade_records(body: bytes) -> GradeRecords:
+    document = parse_page(body)
+    collection = _Collection()
+    numeric_tables = []
+    tables = list(document.iter("table"))
+    for table in tables:
+        if not {"decorated", "stretch"} <= set(table.get("class", "").split()):
+            continue
+        if any(
+            next(row.iterancestors("thead"), None) is not None
+            and any(markup.text(c) == GRADE_CURRENT_HEADER for c in markup.cells(row))
+            for row in markup.rows(table)
+        ):
+            numeric_tables.append(table)
+    if len(numeric_tables) > 1:
+        raise LibrusError(ErrorKind.PARSE)
+    for table in tables:
+        _read_publications(table, collection)
+        if table in numeric_tables:
+            _read_numeric_table(table, collection)
+        else:
+            for row in markup.rows(table):
+                cells = markup.cells(row)
+                if _descriptive_row(cells):
+                    _read_descriptive_row(cells, collection)
+                elif (
+                    cells
+                    and cells[0].tag == "td"
+                    and {"micro", "center", "screen-only"}
+                    <= set(cells[0].get("class", "").split())
+                ):
+                    raise LibrusError(ErrorKind.PARSE)
+    for element in document.iter():
+        if not isinstance(element.tag, str) or element in collection.consumed:
+            continue
+        dated_box = "grade-box" in element.get("class", "").split() and any(
+            "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")
+            ):
+                # 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
+                ):
+                    continue
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+    if not collection.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:
+            collection.averages.extend(
+                SchoolAverage(
+                    subject,
+                    period,
+                    GradeSummaryValue(Availability.UNAVAILABLE, None),
+                )
+                for period in (1, 2, 0)
+            )
+    return GradeRecords(
+        tuple(collection.numeric),
+        tuple(collection.descriptive),
+        tuple(collection.averages),
+        tuple(collection.descriptive_summaries),
+    )

librus_python_api/homework_range.py

@@ -0,0 +1,41 @@
+"""Bounded aggregation by upstream identity, without guessed date-filter semantics."""
+
+from librus_python_api.config import SCHOOL_MAX_TOTAL_TEXT_LENGTH
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import HomeworkItem, SchoolReference
+
+
+class HomeworkAccumulator:
+    def __init__(self, max_items: int) -> None:
+        self.items: list[HomeworkItem] = []
+        self._references: dict[SchoolReference, HomeworkItem] = {}
+        self._max_items = max_items
+        self._text_length = 0
+
+    def extend(self, items: tuple[HomeworkItem, ...]) -> None:
+        for item in items:
+            if item.reference is not None:
+                previous = self._references.get(item.reference)
+                if previous is not None:
+                    if previous != item:
+                        # The selection is not a server-side snapshot. Never
+                        # silently prefer a stale or changed duplicate.
+                        raise LibrusError(ErrorKind.PARSE)
+                    continue
+                self._references[item.reference] = item
+            self._text_length += sum(
+                len(value)
+                for value in (
+                    item.subject,
+                    item.teacher,
+                    item.topic,
+                    item.category,
+                    item.submission_status or "",
+                )
+            )
+            if (
+                len(self.items) >= self._max_items
+                or self._text_length > SCHOOL_MAX_TOTAL_TEXT_LENGTH
+            ):
+                raise LibrusError(ErrorKind.LIMIT)
+            self.items.append(item)

librus_python_api/lifecycle.py

@@ -0,0 +1,24 @@
+"""Joined resource ownership even when callers cancel repeatedly."""
+
+import asyncio
+
+
+async def join_owned[T](future: asyncio.Future[T]) -> bool:
+    """Join without forwarding cancellation; return whether joining was canceled.
+
+    Cleanup must finish before resource/admission slots can be reused. This helper
+    is only for already-owned work, never for ordinary uncancelable operations.
+    """
+    interrupted = False
+    while not future.done():
+        try:
+            # wait() never forwards cancellation to owned work and has no
+            # abandoned shield wrapper that can log an already-handled error.
+            await asyncio.wait((future,))
+        except asyncio.CancelledError:
+            interrupted = True
+        except Exception:
+            break
+    if not future.cancelled():
+        future.exception()
+    return interrupted

librus_python_api/markup.py

@@ -0,0 +1,147 @@
+"""Bounded HTML reading helpers shared by every Synergia page parser."""
+
+import re
+from collections.abc import Iterator
+from datetime import date
+from urllib.parse import urlsplit
+
+from lxml import etree, html
+
+from librus_python_api.config import (
+    ATTENDANCE_DETAIL_PATH_PREFIX,
+    GRADE_MAX_COLUMNS,
+    GRADE_MAX_METADATA_FIELDS,
+    GRADE_MAX_METADATA_LENGTH,
+    UPSTREAM_ORIGINS,
+    WEEKDAY_LABELS,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.parsers import parse_html_document
+
+FIELD_LENGTH = 1024
+_ACTIVE_CONTENT = frozenset({"script", "style", "iframe", "object", "embed", "form"})
+_BLOCKS = frozenset({"br", "p", "div", "li"})
+
+
+def text(
+    element: html.HtmlElement, limit: int = FIELD_LENGTH, *, multiline: bool = False
+) -> str:
+    """Rendered text with block boundaries as line breaks; never truncated.
+
+    Active content inside a data cell is an unsupported layout, not text.
+    """
+    parts: list[str] = []
+    for event, node in etree.iterwalk(element, events=("start", "end", "comment")):
+        if node.tag in _ACTIVE_CONTENT:
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+        if node.tag in _BLOCKS:
+            parts.append("\n")
+        if event == "start" and isinstance(node.tag, str) and node.text:
+            parts.append(re.sub(r"\s+", " ", node.text))
+        if event in ("end", "comment") and node is not element and node.tail:
+            parts.append(re.sub(r"\s+", " ", node.tail))
+    rendered = "".join(parts)
+    value = (
+        "\n".join(
+            line for raw in rendered.splitlines() if (line := " ".join(raw.split()))
+        )
+        if multiline
+        else " ".join(rendered.split())
+    )
+    if len(value) > limit:
+        raise LibrusError(ErrorKind.LIMIT)
+    return value
+
+
+def cells(row: html.HtmlElement) -> list[html.HtmlElement]:
+    return [item for item in row if item.tag in ("td", "th")]
+
+
+def rows(table: html.HtmlElement) -> Iterator[html.HtmlElement]:
+    """Rows of this table only, never rows of a nested table."""
+    for row in table.iter("tr"):
+        if next(row.iterancestors("table"), None) is table:
+            yield row
+
+
+def in_header(row: html.HtmlElement) -> bool:
+    return next(row.iterancestors("thead"), None) is not None
+
+
+def colspan(cell: html.HtmlElement) -> int:
+    value = cell.get("colspan", "1")
+    if not re.fullmatch(r"[1-9][0-9]{0,2}", value):
+        raise LibrusError(ErrorKind.PARSE)
+    span = int(value)
+    if span > GRADE_MAX_COLUMNS:
+        raise LibrusError(ErrorKind.LIMIT)
+    if cell.get("rowspan", "1") != "1":
+        raise LibrusError(ErrorKind.PARSE)
+    return span
+
+
+def tooltip_fields(element: html.HtmlElement) -> dict[str, str]:
+    """Parse a 'Label: value<br>' title attribute into unique labelled fields."""
+    title = element.get("title", "")
+    if len(title) > GRADE_MAX_METADATA_LENGTH:
+        raise LibrusError(ErrorKind.LIMIT)
+    result: dict[str, str] = {}
+    chunks = re.split(r"<br\s*/?>|\n", title, flags=re.I)
+    if len(chunks) > GRADE_MAX_METADATA_FIELDS:
+        raise LibrusError(ErrorKind.LIMIT)
+    for chunk in chunks:
+        if not chunk.strip():
+            continue
+        # Tooltips are HTML inside an attribute; parse markup only where present.
+        rendered = (
+            text(parse_html_document(chunk.encode()))
+            if "<" in chunk
+            else " ".join(chunk.split())
+        )
+        key, separator, value = rendered.partition(":")
+        key, value = key.strip(), value.strip()
+        if not separator or not key or key in result:
+            raise LibrusError(ErrorKind.PARSE)
+        result[key] = value
+    return result
+
+
+def civil_date(value: str | None) -> date:
+    """An ISO date, optionally followed by its weekday label in parentheses."""
+    match = re.fullmatch(r"([0-9]{4}-[0-9]{2}-[0-9]{2})(?: \(([^()]+)\))?", value or "")
+    if match is None or (match[2] is not None and match[2] not in WEEKDAY_LABELS):
+        raise LibrusError(ErrorKind.PARSE)
+    try:
+        return date.fromisoformat(match[1])
+    except ValueError:
+        pass
+    raise LibrusError(ErrorKind.PARSE)
+
+
+def attendance_detail_id(element: html.HtmlElement) -> str | None:
+    """The numeric ID of an inert attendance-detail popup link, if any."""
+    script = element.get("onclick", "")
+    if len(script) > GRADE_MAX_METADATA_LENGTH:
+        raise LibrusError(ErrorKind.LIMIT)
+    match = re.fullmatch(
+        r"\s*otworz_w_nowym_oknie\(\s*(['\"])([^'\"\\\s]+)\1"
+        r"""(?:\s*,\s*(?:'[^'\\\r\n]*'|"[^"\\\r\n]*"|[0-9]{1,6})){1,4}"""
+        r"\s*\)\s*;?\s*",
+        script,
+    )
+    if match is None:
+        return None
+    try:
+        target = urlsplit(match[2])
+    except ValueError:
+        return None
+    if target.query or target.fragment or target.username or target.password:
+        return None
+    if target.scheme or target.netloc:
+        expected = urlsplit(UPSTREAM_ORIGINS["synergia"])
+        if (target.scheme, target.netloc) != (expected.scheme, expected.netloc):
+            return None
+    if not target.path.startswith(ATTENDANCE_DETAIL_PATH_PREFIX):
+        return None
+    identifier = target.path[len(ATTENDANCE_DETAIL_PATH_PREFIX) :]
+    return identifier if re.fullmatch(r"[0-9]{1,64}", identifier) else None