QuestionBankToolkit 0.1.0__py3-none-any.whl

coursebanks/__init__.py

@@ -0,0 +1,15 @@
+"""Validate YAML question banks and exchange Canvas QTI 1.2 archives.
+
+The package supports single-answer multiple-choice questions, instructor
+review artifacts, and assessment selection with usage-history tracking.
+Import workflow functions from the core, migrate, and rotation modules;
+they are not re-exported at package level.
+
+Attributes
+----------
+__version__
+    Package version string.
+
+"""
+
+__version__ = "0.1.0"

coursebanks/__main__.py

@@ -0,0 +1,17 @@
+"""Run the CLI when invoked as ``python -m coursebanks``.
+
+Delegate process arguments to cli.main, the same handler used by the
+installed coursebanks command, and exit with its returned status.
+Successful commands return 0; handled input and file errors return 2.
+Argument parsing handles help and invalid arguments through SystemExit.
+
+Notes
+-----
+Execution occurs at module scope, including when this module is imported.
+Python callers should use cli.main directly to receive its return status.
+
+"""
+
+from .cli import main
+
+raise SystemExit(main())

coursebanks/archive_io.py

@@ -0,0 +1,158 @@
+"""Apply resource limits before reading external QTI ZIP members.
+
+Attributes
+----------
+MAX_QTI_ARCHIVE_MEMBERS
+    Maximum number of central-directory entries in a supported archive.
+MAX_QTI_MEMBER_SIZE
+    Maximum declared and observed uncompressed size of one member, in bytes.
+MAX_QTI_TOTAL_SIZE
+    Maximum total declared uncompressed size of all members, in bytes.
+MAX_QTI_COMPRESSION_RATIO
+    Maximum uncompressed-to-compressed size ratio for a nonempty member.
+
+"""
+
+from __future__ import annotations
+
+from zipfile import ZipFile, ZipInfo
+
+MAX_QTI_ARCHIVE_MEMBERS = 100
+MAX_QTI_MEMBER_SIZE = 16 * 1024 * 1024
+MAX_QTI_TOTAL_SIZE = 32 * 1024 * 1024
+MAX_QTI_COMPRESSION_RATIO = 100.0
+
+
+def validate_archive(archive: ZipFile) -> dict[str, ZipInfo]:
+    """Validate ZIP metadata before any QTI member is decompressed.
+
+    Parameters
+    ----------
+    archive
+        Open ZIP archive whose central-directory entries will be inspected.
+
+    Returns
+    -------
+    members
+        Unique member names mapped to their ``ZipInfo`` records.
+
+    Raises
+    ------
+    ValueError
+        If the archive exceeds the member-count, individual-size,
+        total-size, or compression-ratio limit, or contains a duplicate
+        member name.
+
+    Notes
+    -----
+    Directory entries count toward the member limit. Their zero sizes do not
+    affect the size or compression-ratio checks. This function trusts no
+    member name for lookup until uniqueness has been established and does
+    not decompress member data.
+
+    """
+    entries = archive.infolist()
+    if len(entries) > MAX_QTI_ARCHIVE_MEMBERS:
+        raise ValueError(
+            f"QTI archive contains {len(entries)} members; limit is "
+            f"{MAX_QTI_ARCHIVE_MEMBERS}"
+        )
+
+    members: dict[str, ZipInfo] = {}
+    total_size = 0
+    for entry in entries:
+        if entry.filename in members:
+            raise ValueError(
+                f"QTI archive contains duplicate member name: {entry.filename}"
+            )
+        members[entry.filename] = entry
+        if entry.file_size > MAX_QTI_MEMBER_SIZE:
+            raise ValueError(
+                f"QTI archive member {entry.filename!r} expands to "
+                f"{entry.file_size} bytes; per-member limit is "
+                f"{MAX_QTI_MEMBER_SIZE} bytes"
+            )
+        total_size += entry.file_size
+        if total_size > MAX_QTI_TOTAL_SIZE:
+            raise ValueError(
+                f"QTI archive expands to {total_size} bytes; total limit "
+                f"is {MAX_QTI_TOTAL_SIZE} bytes"
+            )
+        if _exceeds_compression_ratio(entry):
+            ratio = (
+                float("inf")
+                if entry.compress_size == 0
+                else entry.file_size / entry.compress_size
+            )
+            raise ValueError(
+                f"QTI archive member {entry.filename!r} has compression "
+                f"ratio {ratio:.1f}:1; limit is "
+                f"{MAX_QTI_COMPRESSION_RATIO:g}:1"
+            )
+    return members
+
+
+def read_member(archive: ZipFile, member: ZipInfo) -> bytes:
+    """Read one previously validated member with an observed-size bound.
+
+    Parameters
+    ----------
+    archive
+        Open ZIP archive containing ``member``.
+    member
+        Unique member record returned by :func:`validate_archive`.
+
+    Returns
+    -------
+    payload
+        Complete uncompressed member bytes.
+
+    Raises
+    ------
+    ValueError
+        If decompression produces more than the per-member size limit.
+    OSError
+        If the underlying archive cannot be read.
+    zipfile.BadZipFile
+        If member data or its checksum is invalid.
+    RuntimeError
+        If the member is encrypted and no password is available.
+    NotImplementedError
+        If the member uses an unsupported compression method.
+
+    Notes
+    -----
+    The explicit read bound supplements the central-directory metadata check
+    and prevents an unexpectedly larger stream from being accumulated.
+
+    """  # noqa: DOC503
+    with archive.open(member) as stream:
+        payload = stream.read(MAX_QTI_MEMBER_SIZE + 1)
+    if len(payload) > MAX_QTI_MEMBER_SIZE:
+        raise ValueError(
+            f"QTI archive member {member.filename!r} expands beyond the "
+            f"per-member limit of {MAX_QTI_MEMBER_SIZE} bytes"
+        )
+    return payload
+
+
+def _exceeds_compression_ratio(member: ZipInfo) -> bool:
+    """Return whether one nonempty member exceeds the configured ratio.
+
+    Parameters
+    ----------
+    member
+        ZIP metadata containing compressed and uncompressed sizes.
+
+    Returns
+    -------
+    exceeds
+        True for a nonempty member with no compressed bytes or with an
+        uncompressed-to-compressed ratio above the configured maximum.
+
+    """
+    if member.file_size == 0:
+        return False
+    if member.compress_size == 0:
+        return True
+    return member.file_size > MAX_QTI_COMPRESSION_RATIO * member.compress_size

coursebanks/assessments.py

@@ -0,0 +1,114 @@
+"""Shared assessment eligibility rules and legacy YAML migration."""
+
+from .models import Question
+from .yaml_data import YamlMapping
+
+
+def assessment_name(value: object) -> str:
+    """Validate an assessment name without changing its text.
+
+    Parameters
+    ----------
+    value
+        User-defined assessment name. It must be a string containing at
+        least one non-whitespace character.
+
+    Returns
+    -------
+    name
+        Original string with case and leading or trailing whitespace intact.
+
+    Raises
+    ------
+    ValueError
+        If the value is not a string or is empty or whitespace-only.
+
+    Notes
+    -----
+    Names are not limited to a predefined set. Eligibility comparisons use
+    exact string equality; validation does not trim or normalize names.
+
+    """
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError("assessment names must be nonempty strings")
+    return value
+
+
+def question_assessments(data: YamlMapping) -> list[str]:
+    """Validate assessment eligibility or convert a legacy exam field.
+
+    Parameters
+    ----------
+    data
+        Question mapping containing an optional assessments list or legacy
+        exam string. Other fields are ignored by this helper.
+
+    Returns
+    -------
+    names
+        New list of unique, nonblank assessment names. An omitted field or
+        empty list gives unrestricted eligibility. Legacy exam Either also
+        becomes an empty list; any other valid legacy name becomes a
+        single-element list.
+
+    Raises
+    ------
+    ValueError
+        If both eligibility fields are present, assessments is not a list,
+        a name is invalid, or the list contains duplicate names.
+
+    Notes
+    -----
+    Name order, case, and whitespace are preserved. Duplicate checks use
+    exact equality. Either has special meaning only in the legacy exam
+    field; an assessments entry named Either is an ordinary restriction.
+    The input mapping and any contained list are not modified.
+
+    """
+    if "exam" in data:
+        if "assessments" in data:
+            raise ValueError("use assessments or legacy exam, not both")
+        name = assessment_name(data["exam"])
+        return [] if name == "Either" else [name]
+    values = data.get("assessments", [])
+    if not isinstance(values, list):
+        # Schema diagnostics use ValueError, including malformed YAML types.
+        raise ValueError("assessments must be a list of nonempty strings")  # ruff: ignore[type-check-without-type-error]
+    names = [assessment_name(value) for value in values]
+    if len(names) != len(set(names)):
+        raise ValueError("assessments must contain unique names")
+    return names
+
+
+def is_eligible(question: Question, assessment: str) -> bool:
+    """Check whether a validated question allows a named assessment.
+
+    Parameters
+    ----------
+    question
+        Validated question whose assessments list restricts eligibility.
+        An empty list, or an absent key, permits any valid assessment name.
+    assessment
+        Nonblank assessment name to compare using exact string equality.
+
+    Returns
+    -------
+    eligible
+        True if eligibility is unrestricted or the name occurs in the
+        assessments list; otherwise False.
+
+    Raises
+    ------
+    ValueError
+        If the requested assessment name is not a nonblank string.
+
+    Notes
+    -----
+    This helper validates the requested name, not the question's contents.
+    It does not consult usage history or check whether the question has
+    already been selected. Neither input is modified.
+
+    """  # noqa: DOC502
+    name = assessment_name(assessment)
+    names = question.get("assessments", [])
+    return not names or name in names