QuestionBankToolkit 0.1.0__py3-none-any.whl

coursebanks/cli.py

@@ -0,0 +1,678 @@
+"""Command-line interface for reusable Canvas question-bank workflows."""
+
+import argparse
+import csv
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+from zipfile import BadZipFile
+
+from .core import build, load_bank, verify_qti
+from .migrate import import_qti, save_bank
+from .models import Bank
+from .rotation import (
+    append_record,
+    choose,
+    multi_term_plan,
+    read_history,
+)
+
+
+class _Arguments(argparse.Namespace):
+    """Describe attributes populated by the CLI argument parser.
+
+    Annotations cover all subcommands, but parsing creates only the attributes
+    registered for the selected command. Handlers must read only those fields.
+    This class supplies typing information, not runtime validation or defaults.
+    Only attributes registered for the selected command are populated.
+
+    Attributes
+    ----------
+    command
+        Selected CLI subcommand.
+    source
+        Input YAML path for commands operating on a question bank.
+    archive
+        Input QTI ZIP path for archive verification or import.
+    out
+        Output directory for build, YAML path for import, or CSV path
+        for plan.
+    course
+    bank_id
+    title
+    metadata_csv
+    force
+        Whether to force the changes even if data is overwritten.
+    history
+        Location of the CSV history file.
+    count
+        Number of questions desired.
+    seed
+        Seed number for random number generator.
+    term
+        Term identifier for question use.
+    ids
+        IDs of questions.
+    terms
+        Terms for questions to be used.
+    assessment
+        Assessment name used by selection and recording.
+    assessments
+        Ordered name/count-text pairs supplied to the plan command.
+        Counts remain strings until the plan handler converts them.
+
+    """
+
+    command: str
+    source: Path
+    archive: Path
+    out: Path
+    course: str
+    bank_id: str
+    title: str
+    metadata_csv: Path | None
+    force: bool
+    history: Path
+    count: int
+    seed: str
+    term: str
+    ids: list[str]
+    terms: list[str]
+    assessment: str
+    assessments: list[list[str]]
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    """Run the CLI using supplied arguments or the process command line.
+
+    Parameters
+    ----------
+    argv
+        Iterable of argument strings, excluding the executable name.
+        None uses the process command line.
+
+    Returns
+    -------
+    status
+        0 after successful execution, or 2 for a handled input, archive,
+        filesystem, or CSV error. Handled errors are printed to standard
+        error with an ``ERROR:`` prefix.
+
+    Raises
+    ------
+    SystemExit
+        When argparse handles help (status 0) or invalid arguments
+        (status 2), before command dispatch.
+
+    Notes
+    -----
+    Command summaries and proposals are printed to standard output.
+    Build, import, record, and plan write their requested outputs.
+    Unexpected programming errors propagate. Expected command failures do
+    not emit a traceback.
+
+    """  # noqa: DOC502
+    args = _build_parser().parse_args(argv, namespace=_Arguments())
+    try:
+        _dispatch(args)
+    except (ValueError, OSError, csv.Error, BadZipFile) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the parser for bank, archive, and rotation commands.
+
+    Returns
+    -------
+    parser
+        New argument parser requiring one subcommand. Path arguments are
+        converted to Path objects; command-specific options and defaults
+        are registered without parsing arguments or accessing files.
+
+    """
+    p = argparse.ArgumentParser(
+        prog="coursebanks",
+        description="Validate YAML, export Canvas QTI 1.2 and plan question "
+        "reuse.",
+    )
+    sp = p.add_subparsers(dest="command", required=True)
+    for cmd in ["validate", "build"]:
+        x = sp.add_parser(cmd)
+        x.add_argument("source", type=Path)
+        if cmd == "build":
+            x.add_argument("--out", default="build", type=Path)
+    x = sp.add_parser(
+        "check-qti",
+        help="Check the structure and scoring of a generated QTI ZIP",
+    )
+    x.add_argument("archive", type=Path)
+    x = sp.add_parser(
+        "import-qti",
+        help="Migrate simple single-answer QTI 1.2 packages to YAML",
+    )
+    x.add_argument("archive", type=Path)
+    x.add_argument("--course", required=True)
+    x.add_argument("--bank-id", required=True)
+    x.add_argument("--title", required=True)
+    x.add_argument("--metadata-csv", type=Path)
+    x.add_argument("--out", type=Path, required=True)
+    x.add_argument("--force", action="store_true")
+    x = sp.add_parser(
+        "select", help="Propose questions but do not record actual usage"
+    )
+    _configure_select(x)
+    x = sp.add_parser(
+        "record",
+        help="Record question IDs actually administered (not proposed)",
+    )
+    _configure_record(x)
+    x = sp.add_parser(
+        "plan",
+        help="Propose a nonrepeating multi-term rotation without "
+        "modifying history",
+    )
+    _configure_plan(x)
+    return p
+
+
+def _configure_select(parser: argparse.ArgumentParser) -> None:
+    """Define arguments for the select command.
+
+    Parameters
+    ----------
+    parser
+        Subcommand parser to configure in place.
+        Register the source, history (default usage.csv), assessment (with
+        the legacy --exam alias), integer count, and seed (default "0").
+
+    Returns
+    -------
+    None
+        Return after registering arguments. No input is parsed and no files
+        are accessed.
+
+    """
+    parser.add_argument("source", type=Path)
+    parser.add_argument("--history", type=Path, default=Path("usage.csv"))
+    parser.add_argument(
+        "--assessment", "--exam", dest="assessment", required=True
+    )
+    parser.add_argument("--count", type=int, required=True)
+    parser.add_argument("--seed", default="0")
+
+
+def _configure_record(parser: argparse.ArgumentParser) -> None:
+    """Define arguments for the record command.
+
+    Parameters
+    ----------
+    parser
+        Subcommand parser to configure in place.
+        Register the source, history (default usage.csv), term, assessment
+        (with the legacy --exam alias), and one or more question IDs.
+
+    Returns
+    -------
+    None
+        Return after registering arguments. No input is parsed and no files
+        are accessed.
+
+    """
+    parser.add_argument("source", type=Path)
+    parser.add_argument("--history", type=Path, default=Path("usage.csv"))
+    parser.add_argument("--term", required=True)
+    parser.add_argument(
+        "--assessment", "--exam", dest="assessment", required=True
+    )
+    parser.add_argument("--ids", nargs="+", required=True)
+
+
+def _configure_plan(parser: argparse.ArgumentParser) -> None:
+    """Define arguments for the plan command.
+
+    Parameters
+    ----------
+    parser
+        Subcommand parser to configure in place.
+        Register the source, history (default usage.csv), one or more terms,
+        repeated --assessment NAME COUNT pairs, seed (default "0"), and
+        required output path. Count text is converted by the plan handler.
+
+    Returns
+    -------
+    None
+        Return after registering arguments. No input is parsed and no files
+        are accessed.
+
+    """
+    parser.add_argument("source", type=Path)
+    parser.add_argument("--history", type=Path, default=Path("usage.csv"))
+    parser.add_argument("--terms", nargs="+", required=True)
+    parser.add_argument(
+        "--assessment",
+        dest="assessments",
+        nargs=2,
+        action="append",
+        metavar=("NAME", "COUNT"),
+        required=True,
+        help="Assessment name and number of questions; may be repeated",
+    )
+    parser.add_argument("--seed", default="0")
+    parser.add_argument("--out", type=Path, required=True)
+
+
+def _dispatch(args: _Arguments) -> None:
+    """Route a parsed command, loading a validated bank when needed.
+
+    Parameters
+    ----------
+    args
+        Namespace produced by the command parser. The command determines
+        which attributes are present and which handler is called.
+
+    Returns
+    -------
+    None
+        Return after the selected handler completes.
+
+    Raises
+    ------
+    ValueError
+        If source validation or command-specific input validation fails.
+    OSError
+        If command file operations fail.
+    csv.Error
+        If command CSV operations fail.
+
+    Notes
+    -----
+    Archive commands use args.archive directly. All other supported commands
+    first load and validate args.source. Handler output and file side effects
+    occur here; exceptions propagate to main for reporting when supported.
+
+    """  # noqa: DOC502
+    if args.command == "check-qti":
+        _run_check_qti(args)
+        return
+    if args.command == "import-qti":
+        _run_import_qti(args)
+        return
+    bank = load_bank(args.source)
+    if args.command == "validate":
+        _run_validate(bank)
+    elif args.command == "build":
+        _run_build(args, bank)
+    elif args.command == "select":
+        _run_select(args, bank)
+    elif args.command == "record":
+        _run_record(args, bank)
+    elif args.command == "plan":
+        _run_plan(args, bank)
+
+
+def _run_check_qti(args: _Arguments) -> None:
+    """Check an archive and print its verified question count.
+
+    Parameters
+    ----------
+    args
+        Parsed check-qti arguments containing the archive path.
+
+    Returns
+    -------
+    None
+        Return after printing the structural validation summary.
+
+    Raises
+    ------
+    ValueError
+        If the archive or one of its members is unreadable, XML is unsafe or
+        malformed, or archive structure or scoring fails verification.
+    OSError
+        If the archive cannot be read.
+
+    Notes
+    -----
+    No files are written. Structural verification does not certify Canvas
+    acceptance or rendered appearance.
+
+    """  # noqa: DOC503
+    try:
+        report = verify_qti(args.archive)
+    except (BadZipFile, RuntimeError, NotImplementedError) as exc:
+        raise ValueError(
+            f"Cannot read QTI archive {args.archive}: {exc}"
+        ) from exc
+    print(f"Valid QTI 1.2 structure: {report['count']} questions")
+
+
+def _run_import_qti(args: _Arguments) -> None:
+    """Import an archive to YAML, protecting existing output unless forced.
+
+    Parameters
+    ----------
+    args
+        Parsed import-qti arguments: archive, course, bank_id, title,
+        optional metadata_csv, out, and force.
+
+    Returns
+    -------
+    None
+        Return after saving the bank and printing its question count and path.
+
+    Raises
+    ------
+    ValueError
+        If output exists without force, the archive or one of its members is
+        unreadable, QTI content is unsupported or invalid, metadata cannot be
+        interpreted, or bank validation fails.
+    OSError
+        If input reads, directory creation, or output writes fail.
+    csv.Error
+        If parsing the optional metadata CSV fails.
+
+    Notes
+    -----
+    Import and validation complete before saving. Saving creates parent
+    directories and overwrites existing output only when force permits it.
+    Other import and serialization exceptions propagate to the caller.
+
+    """  # noqa: DOC503
+    _check_import_output(args.out, force=args.force)
+    try:
+        bank = import_qti(
+            args.archive,
+            args.course,
+            args.bank_id,
+            args.title,
+            args.metadata_csv,
+        )
+    except (BadZipFile, RuntimeError, NotImplementedError) as exc:
+        raise ValueError(
+            f"Cannot read QTI archive {args.archive}: {exc}"
+        ) from exc
+    save_bank(bank, args.out)
+    print(f"Imported {len(bank['questions'])} questions into {args.out}")
+
+
+def _run_validate(bank: Bank) -> None:
+    """Print the identity and question count of an already validated bank.
+
+    Parameters
+    ----------
+    bank
+        Bank validated by the dispatcher before this handler is called.
+
+    Returns
+    -------
+    None
+        Return after printing the course, bank ID, and question count.
+
+    Notes
+    -----
+    This handler only reports success; it does not repeat validation or
+    modify the bank.
+
+    """
+    print(
+        f"Valid: {bank['course']} / {bank['bank_id']}: "
+        f"{len(bank['questions'])} questions"
+    )
+
+
+def _run_build(args: _Arguments, bank: Bank) -> None:
+    """Build QTI and review artifacts and print archive provenance.
+
+    Parameters
+    ----------
+    args
+        Parsed build arguments containing the output-directory path.
+    bank
+        Bank to build. The build function revalidates it before writing.
+
+    Returns
+    -------
+    None
+        Return after printing the archive path, question count, and SHA-256.
+
+    Raises
+    ------
+    ValueError
+        If bank validation or generated-archive verification fails.
+    OSError
+        If creating directories or writing or reading artifacts fails.
+
+    Notes
+    -----
+    Build creates the output directory and overwrites matching artifact
+    filenames. The input bank is unchanged.
+
+    """  # noqa: DOC502
+    artifact, build_report = build(bank, args.out)
+    print(
+        f"Created {artifact}: {build_report['count']} questions; "
+        f"SHA-256 {build_report['sha256']}"
+    )
+
+
+def _run_select(args: _Arguments, bank: Bank) -> None:
+    """Print eligible questions without recording proposed use.
+
+    Parameters
+    ----------
+    args
+        Parsed select arguments containing history, assessment, count,
+        and seed.
+    bank
+        Validated bank from which questions will be selected.
+
+    Returns
+    -------
+    None
+        Return after printing the proposal notice and each selected
+        question's ID, title, area, difficulty, and estimated minutes.
+
+    Raises
+    ------
+    ValueError
+        If history, assessment, or count is invalid, or insufficient eligible
+        unused questions remain.
+    OSError
+        If history cannot be read.
+    csv.Error
+        If history CSV parsing fails.
+
+    Notes
+    -----
+    Prior usage is scoped to the bank's course and bank ID. A missing history
+    file means no prior use. No files are created or changed.
+
+    """  # noqa: DOC502
+    used = {x["id"] for x in read_history(args.history, bank)}
+    selected = choose(bank, args.assessment, args.count, used, args.seed)
+    print(
+        "PROPOSED ONLY — no history written. Record IDs after actually "
+        "administering the assessment.\n"
+    )
+    for q in selected:
+        print(
+            f"{q['id']}: {q['title']} | {q['area']} | "
+            f"{q['difficulty']} | {q['minutes']} min"
+        )
+
+
+def _run_record(args: _Arguments, bank: Bank) -> None:
+    """Record administered question IDs and print the history destination.
+
+    Parameters
+    ----------
+    args
+        Parsed record arguments containing history, term, assessment,
+        and the ordered question IDs.
+    bank
+        Validated bank identifying the course, bank ID, and eligible questions.
+
+    Returns
+    -------
+    None
+        Return after appending records and printing their count and path.
+
+    Raises
+    ------
+    ValueError
+        If history or administration labels are invalid, or IDs are
+        duplicate, unknown, ineligible, or previously recorded.
+    OSError
+        If reading history, creating directories, or writing records fails.
+    csv.Error
+        If reading or writing CSV fails.
+
+    Notes
+    -----
+    Existing history is preserved and new records are appended. A new file
+    receives a header; legacy headers retain their column names and order.
+
+    """  # noqa: DOC502
+    append_record(args.history, bank, args.term, args.assessment, args.ids)
+    print(f"Recorded {len(args.ids)} actual questions in {args.history}")
+
+
+def _run_plan(args: _Arguments, bank: Bank) -> None:
+    """Write a proposed rotation CSV without changing usage history.
+
+    Parameters
+    ----------
+    args
+        Parsed plan arguments containing terms, assessment name/count-text
+        pairs, history, seed, and the output CSV path.
+    bank
+        Validated bank supplying questions for each assessment in each term.
+
+    Returns
+    -------
+    None
+        Return after writing the proposal and printing its row count and path.
+
+    Raises
+    ------
+    ValueError
+        If counts, labels, or history are invalid, or a selection cannot be
+        completed without reusing questions.
+    OSError
+        If reading history, creating directories, or writing the plan fails.
+    csv.Error
+        If reading or writing CSV fails.
+
+    Notes
+    -----
+    Planning completes before the output is opened. Parent directories are
+    created as needed, and an existing output file is overwritten.
+    Rows include course, bank ID, term, assessment, question ID, area, and
+    difficulty. Proposed selections are not appended to usage history.
+
+    """  # noqa: DOC502
+    assessments = [
+        (name, _parse_assessment_count(name, count_text))
+        for name, count_text in args.assessments
+    ]
+
+    used = {x["id"] for x in read_history(args.history, bank)}
+
+    rows = multi_term_plan(bank, args.terms, assessments, used, args.seed)
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    with args.out.open("w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(
+            f,
+            fieldnames=[
+                "course",
+                "bank_id",
+                "term",
+                "assessment",
+                "id",
+                "area",
+                "difficulty",
+            ],
+        )
+        writer.writeheader()
+        writer.writerows(rows)
+    print(
+        f"Wrote proposed, nonbinding rotation of {len(rows)} "
+        f"question uses to {args.out}"
+    )
+
+
+def _check_import_output(path: Path, *, force: bool) -> None:
+    """Reject existing import output unless overwriting is allowed.
+
+    Parameters
+    ----------
+    path
+        Requested destination for the imported YAML bank.
+    force
+        Whether an existing destination may be overwritten.
+
+    Returns
+    -------
+    None
+        Return when the destination does not exist or force is enabled.
+
+    Raises
+    ------
+    ValueError
+        If the destination exists and force is disabled.
+    OSError
+        If checking the destination fails.
+
+    Notes
+    -----
+    This check does not create or reserve the destination, check write
+    permissions, or guarantee that a later write will succeed.
+
+    """  # noqa: DOC503
+    if path.exists() and not force:
+        raise ValueError(
+            f"Refusing to overwrite {path}; use --force if intended"
+        )
+
+
+def _parse_assessment_count(name: str, count_text: str) -> int:
+    """Parse a nonnegative count, identifying the assessment in errors.
+
+    Parameters
+    ----------
+    name
+        Assessment label used in error messages; not validated here.
+    count_text
+        Integer text accepted by int, including surrounding whitespace.
+        Zero is allowed; negative integers and non-integer text are rejected.
+
+    Returns
+    -------
+    count
+        Parsed nonnegative question count.
+
+    Raises
+    ------
+    ValueError
+        If the text cannot be parsed as an integer or the result is negative.
+        Conversion failures retain the original exception as their cause.
+
+    """
+    try:
+        count = int(count_text)
+    except ValueError as exc:
+        raise ValueError(
+            f"Assessment {name!r} count must be a nonnegative "
+            f"integer; got {count_text!r}"
+        ) from exc
+    if count < 0:
+        raise ValueError(
+            f"Assessment {name!r} count must be nonnegative; got {count}"
+        )
+    return count
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())