QuestionBankToolkit 0.1.0__tar.gz → 0.1.1__tar.gz

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/CHANGELOG.md

@@ -5,6 +5,17 @@ Changes prepared for the next release are stored as small files in [`newsfragmen
 
 <!-- towncrier release notes start -->
 
+# QuestionBankToolkit 0.1.1 (2026-10-21)
+
+## Bug fixes
+
+- Import supported Canvas Common Cartridge item-bank exports whose questions are stored in a referenced object bank, including correct-only scoring, digit-leading identifiers, and absent feedback.
+
+## Documentation
+
+- Document the live Codeberg Pages site, published PyPI package, and named Twine repository used for future releases.
+
+
 # QuestionBankToolkit 0.1.0 (2026-10-21)
 
 ## Features

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/MANIFEST.in

@@ -6,4 +6,4 @@ recursive-include docs *.md *.py *.rst
 recursive-include examples *.yaml
 recursive-include newsfragments *.md
 recursive-include scripts *.sh
-recursive-include tests *.py *.xml *.yaml
+recursive-include tests *.py *.qti *.xml *.yaml

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: QuestionBankToolkit
-Version: 0.1.0
+Version: 0.1.1
 Summary: Canvas QTI 1.2 question banks from YAML
 Author-email: "David D. Marshall" <ddmarsha@calpoly.edu>
 License-Expression: GPL-3.0-only
@@ -70,7 +70,7 @@ Import a supported QTI 1.2 ZIP package into a new YAML bank with:
 coursebanks import-qti questions.zip --course COURSE123 --bank-id ImportedBank --title "Imported bank" --out imported.yaml
 ```
 
-The importer supports a strict single-answer multiple-choice subset and rejects structures that cannot be represented without loss.
+The importer supports a strict single-answer multiple-choice subset, including Canvas Common Cartridge item-bank exports, and rejects unsupported or ambiguous structures.
 See [the QTI import guide](docs/importing-qti.md) for required package structure, defaults, choice-label normalization, metadata CSV overrides, and the field-by-field compatibility table.
 
 ## Optional: selecting and recording questions

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/README.md

@@ -39,7 +39,7 @@ Import a supported QTI 1.2 ZIP package into a new YAML bank with:
 coursebanks import-qti questions.zip --course COURSE123 --bank-id ImportedBank --title "Imported bank" --out imported.yaml
 ```
 
-The importer supports a strict single-answer multiple-choice subset and rejects structures that cannot be represented without loss.
+The importer supports a strict single-answer multiple-choice subset, including Canvas Common Cartridge item-bank exports, and rejects unsupported or ambiguous structures.
 See [the QTI import guide](docs/importing-qti.md) for required package structure, defaults, choice-label normalization, metadata CSV overrides, and the field-by-field compatibility table.
 
 ## Optional: selecting and recording questions

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/docs/QTI_specification.md

@@ -32,12 +32,12 @@ The XML namespace and resource labels below are compatibility details of the cur
 | Question types | Single-answer multiple choice | No multiple-answer, matching, essay, numeric, or fill-in-the-blank questions |
 | Choices | At least two in YAML/export | Import currently accepts 2-26 choices; labels are reassigned A-Z |
 | Correct answer | Exactly one selected choice | No partial credit or negative marking |
-| Scoring | `SCORE` = 100 for correct, 0 for incorrect | Question points are separately stored in metadata |
+| Scoring | Export writes `SCORE` = 100 for correct and 0 for incorrect | Import also accepts Canvas object-bank items containing only the full-credit rule |
 | Text | Plain text or authored HTML | Does not convert LaTeX to Canvas equation content or package external media |
-| Feedback | One general explanation per question | Not distinct feedback for each wrong choice |
+| Feedback | Export writes one general explanation per question | Import explicitly defaults an explanation when Canvas supplies no feedback |
 | Ordering | Questions and choices retain YAML order in generated XML | Actual display ordering is controlled by the receiving LMS |
 | Metadata | IDs, title, points, topic, area, difficulty, assessment eligibility | Some fields are extensions understood by this toolkit, not portable QTI semantics |
-| Import | Supported subset of QTI 1.2 packages | Unsupported or lossy structures should not be silently converted |
+| Import | Direct QTI resources and Canvas Common Cartridge item-bank wrappers | Unsupported or ambiguous structures are rejected |
 | Question rotation | Managed by local YAML/CSV tooling | Not encoded as a QTI assessment-selection rule |
 | Choice shuffling | Export writes `render_choice/@shuffle` as `Yes` or `No` | A question override takes precedence over the bank default; import stores the effective value per question |
 
@@ -131,11 +131,11 @@ For exam delivery, inspect representative imported questions and confirm the rel
 
 ## 7. Import and round-trip boundaries
 
-`coursebanks import-qti` is intended for compatible **single-answer** items. It reads QTI item IDs, titles, text, ordered choices, one correct score condition, and one general explanation, then builds a validated YAML bank.
+`coursebanks import-qti` is intended for compatible **single-answer** items. It reads QTI item IDs, titles, text, ordered choices, one correct score condition, and available general explanations, then builds a validated YAML bank.
 
-The current importer requires one single-cardinality `response_lid`, `text/plain` or `text/html` stems and choices, 2-26 choices, a valid optional `render_choice/@shuffle` value, one identifiable correct answer, and general feedback. It may use an instructor CSV to recover authoring metadata not present in the QTI package. If the format cannot be represented faithfully, import should fail rather than silently discard meaningful information.
+The current importer requires one single-cardinality `response_lid`, `text/plain` or `text/html` stems and choices, 2-26 choices, a valid optional `render_choice/@shuffle` value, and one identifiable correct answer. It accepts a direct QTI assessment resource or resolves one Canvas Common Cartridge wrapper to its referenced object bank. When feedback is absent, the YAML explanation states that the package provided none rather than inventing instructional content. It may use an instructor CSV to recover authoring metadata not present in the QTI package. If the format cannot otherwise be represented faithfully, import should fail rather than silently discard meaningful information.
 
-Imported options are relabeled `A`, `B`, ... in source order. Thus, the stable question ID is preserved, but original option identifiers are not guaranteed to be preserved on import. Assessment-eligibility metadata is project-specific and cannot be expected from arbitrary third-party exports.
+Imported options are relabeled `A`, `B`, ... in source order. A question ID is preserved when it satisfies the YAML grammar; Canvas hexadecimal IDs beginning with a digit receive a `q_` prefix. Original option identifiers are not guaranteed to be preserved on import. Assessment-eligibility metadata is project-specific and cannot be expected from arbitrary third-party exports.
 
 See the [QTI import guide](importing-qti.md) for the field-by-field compatibility table, metadata defaults, and CSV override precedence.
 
@@ -149,10 +149,10 @@ See the [QTI import guide](importing-qti.md) for the field-by-field compatibilit
 
 `coursebanks check-qti <archive.zip>` currently checks, among other things:
 
-- A root-level `imsmanifest.xml`, a QTI resource of type `imsqti_xmlv1p2`, and a resolvable relative assessment filename.
+- A root-level `imsmanifest.xml`, exactly one QTI resource of type `imsqti_xmlv1p2`, and either a resolvable direct assessment filename or one resolvable Canvas source-bank reference.
 - No more than 100 uniquely named members, 16 MiB per uncompressed member, 32 MiB total declared uncompressed data, and a maximum 100:1 compression ratio per nonempty member.
 - A QTI-namespace `questestinterop` document containing at least one item.
-- Unique, nonempty item IDs, at least two response labels per item, one key matching a response-label identifier, and the expected simple scoring-condition count.
+- Unique, nonempty item IDs, at least two response labels per item, one key matching a response-label identifier, and one or two simple score assignments.
 - XML is parsed using `defusedxml`, rejecting DTD/entity-based constructs.
 
 Verification applies archive limits before XML parsing, and import reapplies them when reopening the package.

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/docs/cleanup-plan.md

@@ -17,13 +17,14 @@ The check script passes when run with the project environment:
 QBT_PYTHON=.venv/bin/python ./scripts/run_checks.sh
 ```
 
-The current result is 406 passing pytest cases with 98% reported coverage and branch measurement enabled, no Ruff lint, format, mypy, BasedPyright, or pydoclint findings.
-Coverage is enabled with branch measurement and reports twelve uncovered source statements and thirteen partially covered branches.
-These numbers are a snapshot from October 20, 2026, rather than release criteria by themselves.
-
-The repository now contains a Codeberg Woodpecker workflow, a local wheel and source-distribution installation check, and a reviewed local release-preparation workflow.
-[Codeberg Woodpecker pipeline 2](https://ci.codeberg.org/repos/18200/pipeline/2) passed on October 20, 2026, using the hosted Python 3.14 environment.
-The project has no recorded Canvas acceptance result yet.
+The current result is 410 passing pytest cases with 98% reported coverage and branch measurement enabled, no Ruff lint, format, mypy, BasedPyright, or pydoclint findings.
+Coverage is enabled with branch measurement and reports fourteen uncovered source statements and fifteen partially covered branches.
+These numbers are a snapshot from October 21, 2026, rather than release criteria by themselves.
+
+The repository now contains a Codeberg Woodpecker workflow, a local wheel and source-distribution installation check, and a reviewed release workflow.
+[Codeberg Woodpecker pipeline 8](https://ci.codeberg.org/repos/18200/pipeline/8) passed the Canvas item-bank import changes on October 21, 2026, using the hosted Python 3.14 environment.
+Version 0.1.1 is published on [PyPI](https://pypi.org/project/QuestionBankToolkit/0.1.1/), and the user documentation is published through [Codeberg Pages](https://ddmarshall.codeberg.page/QuestionBankToolkit/).
+The importer has been exercised against a direct 20-question Canvas item-bank export, but the project has no recorded Canvas re-import result yet.
 Structural QTI verification therefore does not constitute a claim that every supported package has been accepted by Canvas.
 
 ## Completed cleanup
@@ -59,7 +60,7 @@ Structural QTI verification therefore does not constitute a claim that every sup
 - Added shared pre-parse ZIP limits of 100 members, 16 MiB per member, 32 MiB total uncompressed data, and a 100:1 per-member compression ratio.
 - Rejected duplicate archive member names, bounded observed member reads, and reapplied the policy when import reopens an archive.
 - Covered every archive limit at its exact boundary and immediately beyond it through verification, import, and both CLI commands without large fixtures.
-- Rejected unsupported response cardinality, incomplete choices, malformed scoring, ambiguous answers, missing feedback, unsupported text structures, and more than 26 choices.
+- Rejected unsupported response cardinality, incomplete choices, malformed scoring, ambiguous answers, unsupported text structures, and more than 26 choices.
 - Required imported questions to pass the YAML schema before they become validated banks.
 - Added explicit import overwrite protection through `--force` and verified that rejected imports do not create output.
 - Preserved deterministic ZIP bytes and checked the IMS manifest and QTI root namespaces.
@@ -67,6 +68,8 @@ Structural QTI verification therefore does not constitute a claim that every sup
 - Added an independently authored multi-question export fixture and direct assertions for the manifest, metadata, item and choice order, identifiers, plain and HTML text, Unicode, XML escaping, fractional points, shuffling, scoring, and feedback.
 - Verified the exact build artifact set, ZIP members, instructor Markdown, catalog columns and values, validation report, recomputed archive digest, and CLI output for a destination containing spaces.
 - Added a hand-authored third-party-style QTI package and exact import assertions for preserved content, A-through-Z choice normalization, translated answers, current and legacy metadata, importer defaults, shuffling, CSV overrides, and precedence.
+- Added Canvas Common Cartridge item-bank support by resolving wrapper source-bank references, accepting the correct-only scoring form, normalizing digit-leading item IDs, and explicitly marking absent feedback.
+- Imported and validated all 20 questions from a direct Canvas item-bank export on October 21, 2026, including HTML text, four-choice ordering, answer keys, and Canvas-generated identifiers.
 - Published and linked a field-by-field import compatibility table covering preserved, normalized, defaulted, and unsupported data.
 
 ### Code quality and developer documentation
@@ -107,30 +110,24 @@ Structural QTI verification therefore does not constitute a claim that every sup
 - Replaced the release placeholders with active Towncrier and Bump My Version configuration for QuestionBankToolkit.
 - Added news fragments, changelog generation, synchronized version checks, and a release-preparation script that runs all checks without committing, tagging, or publishing.
 - Added [releasing.md](releasing.md) with the fragment, semantic-version, review, commit, and annotated-tag workflow.
+- Published the Sphinx user guide and API reference through the repository's `pages` branch and Codeberg Pages webhook.
+- Released version 0.1.1 with Canvas Common Cartridge item-bank import support, uploaded its checked wheel and source distribution to PyPI, and verified the supported workflows in a clean Python 3.14 environment.
 
 ## Remaining gaps
 
 | Area | Current evidence | Remaining outcome |
 | --- | --- | --- |
-| Release publication | Changelog assembly, version synchronization, release checks, distribution validation, and local commit and tag instructions are tested. PyPI is the selected package index, and the `QuestionBankToolkit` name appeared unregistered when checked on October 21, 2026. | Build and review the Sphinx site, publish it through Codeberg Pages, prepare version 0.1.0, and perform the first PyPI upload with an account token before replacing it with a project-scoped token. |
-| Canvas acceptance | XML structure and toolkit round trips are automated. | Record manual import and export results from the intended Canvas quiz and question-bank workflows. |
+| Canvas acceptance | XML structure and toolkit round trips are automated, and a direct 20-question Canvas item-bank export imports and validates locally. | Import a toolkit-generated package into Canvas, review its behavior, and re-export representative content for a complete bidirectional result. |
 
 Standalone QTI XML is not currently supported input.
-The importer requires a ZIP package containing `imsmanifest.xml` and one referenced QTI assessment resource.
+The importer requires a ZIP package containing `imsmanifest.xml` and either one direct QTI assessment resource or one Canvas wrapper that resolves to an object-bank resource.
 Any future support for standalone XML should be an explicit compatibility decision rather than an incidental parser behavior.
 
-## Next step: Public documentation and PyPI release
-
-Build and review the Sphinx user guide and generated API reference locally.
-Publish the reviewed site to the repository's `pages` branch, configure the Codeberg Pages webhook, and verify the public documentation URL.
-Prepare version 0.1.0 from the current news fragments, review and tag the release, upload the checked wheel and source distribution to PyPI, and verify installation in a clean environment.
-Do not treat an available package name as reserved until the first upload succeeds.
-
-## Canvas acceptance
+## Next step: Canvas acceptance
 
 Perform a manual import of a small synthetic package into the intended Canvas quiz and question-bank destinations.
 Record the Canvas environment and date, question count, text and HTML rendering, choice order, correct answers, grading points, and feedback behavior.
-Export and reimport representative Canvas-produced packages to verify the documented importer scope.
+Import a toolkit-generated package into Canvas and re-export representative content to complete the bidirectional workflow verification.
 Keep automated structural verification and manual Canvas acceptance clearly separate.
 
 Completion means the primary conversion workflows and retained rotation commands pass independent tests, configured checks and packaging tests pass in CI, user documentation matches actual behavior, and the supported Canvas workflow has a dated acceptance record.

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/docs/importing-qti.md

@@ -1,7 +1,7 @@
 # Importing QTI into YAML
 
 QuestionBankToolkit imports a strict subset of QTI 1.2 single-answer multiple-choice packages.
-The input must be a ZIP package containing a root `imsmanifest.xml` whose QTI resource references the assessment XML member.
+The input must be a ZIP package containing a root `imsmanifest.xml` in the supported IMS or Canvas Common Cartridge namespace whose QTI resource either contains the items directly or identifies one Canvas object bank through `sourcebank_ref`.
 Standalone XML, QTI 2.x, and other question types are not supported.
 
 ## Archive safety limits
@@ -51,7 +51,7 @@ Preserved values keep their supported QTI content, normalized values change repr
 | `course` | Defaulted | Taken from the required `--course` argument, not from QTI. |
 | `bank_id` | Defaulted | Taken from the required `--bank-id` argument and validated as a YAML identifier. |
 | Bank `title` | Defaulted | Taken from the required `--title` argument, not from the QTI assessment title. |
-| `id` | Preserved | Taken from `item/@ident`; missing, duplicate, or schema-invalid IDs are rejected. |
+| `id` | Preserved or normalized | Taken from `item/@ident`; a digit-leading identifier is prefixed with `q_`, while missing, duplicate, or otherwise schema-invalid IDs are rejected. |
 | Question `title` | Normalized | Uses `item/@title`, removes an exact leading `<id> ` prefix, and defaults to the item ID. |
 | `area` | Defaulted | Uses CSV `Area`, QTI `area`, QTI `topic`, then `Unclassified`. |
 | `topic` | Defaulted | Uses CSV `Topic`, QTI `topic`, then `Unclassified`. |
@@ -64,7 +64,7 @@ Preserved values keep their supported QTI content, normalized values change repr
 | `choices` | Normalized | Preserves source order and text but replaces source identifiers with `A` through `Z`; 2–26 choices are supported. |
 | `shuffle_choices` | Normalized | QTI `render_choice/@shuffle="Yes"` becomes `true`; `No` or an omitted attribute becomes `false`. |
 | `answer` | Normalized | Translates the source choice identifier from one full-credit score condition to its generated A–Z label. |
-| `explanation` | Preserved | Uses required general feedback `mattext`; a missing explanation is rejected to prevent a lossy import. |
+| `explanation` | Preserved or defaulted | Uses general feedback `mattext`; when the package contains no feedback container, records `No explanation was provided in the imported QTI package.` explicitly, while malformed feedback is rejected. |
 | Additional YAML metadata | Unsupported | QTI fields without a mapping above are not copied into YAML. |
 
 Imported choices deliberately receive new labels.
@@ -93,8 +93,9 @@ The metadata CSV cannot override question text, choices, answers, explanations,
 ## Supported item structure
 
 Each item must contain one single-cardinality `response_lid`, one `render_choice`, 2–26 choices, and consistent `text/plain` or `text/html` content.
-The importer requires one uniquely identifiable choice whose score condition sets `SCORE` to `100` and requires general feedback text.
-Unsupported response types, partial or ambiguous scoring, missing identifiers, inconsistent text formats, missing feedback, media dependencies, and unrepresentable content are rejected rather than silently discarded.
+The importer requires one uniquely identifiable choice whose score condition sets `SCORE` to `100`; it accepts either that single rule or an additional fallback score rule.
+Canvas Common Cartridge exports may place the actual items in a manifest resource referenced by a wrapper assessment's `sourcebank_ref`, and that one level of indirection is resolved explicitly.
+Unsupported response types, partial or ambiguous scoring, missing identifiers, inconsistent text formats, ambiguous source-bank references, media dependencies, and unrepresentable content are rejected rather than silently discarded.
 
 The importer validates the completed bank against [the YAML schema](schema.md).
 Passing import and validation proves compatibility with this toolkit's supported subset, not rendering or acceptance by Canvas.

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/docs/releasing.md

@@ -79,6 +79,7 @@ Do not commit the token or place it in a command argument.
 
 The first upload creates the PyPI project and therefore requires an account-scoped token.
 After the project exists, replace that token with a token scoped only to `QuestionBankToolkit` for later releases.
+Store the project-scoped token under a `QuestionBankToolkit` repository section in `~/.pypirc`, and restrict that file to the current user with `chmod 600 ~/.pypirc`.
 
 From the clean, tagged release commit, build and validate the final files:
 
@@ -89,10 +90,10 @@ python -m twine check dist/*
 ```
 
 Inspect the wheel and source archive names and confirm their version before uploading.
-Then let Twine prompt for the username `__token__` and the API token:
+Upload through the named repository configuration so the token is not included in the command:
 
 ```bash
-python -m twine upload dist/*
+.venv/bin/python -m twine upload --repository QuestionBankToolkit dist/*
 ```
 
 PyPI does not permit replacing a file or reusing a published version after deletion.

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "QuestionBankToolkit"
-version = "0.1.0"
+version = "0.1.1"
 authors = [{ name = "David D. Marshall", email = "ddmarsha@calpoly.edu" }]
 description = "Canvas QTI 1.2 question banks from YAML"
 readme = "README.md"
@@ -255,7 +255,7 @@ name = "Other changes"
 showcontent = true
 
 [tool.bumpversion]
-current_version = "0.1.0"
+current_version = "0.1.1"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 commit = false

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/scripts/check_distribution.sh

@@ -64,6 +64,9 @@ required_source_suffixes = {
     "/scripts/publish_docs.sh",
     "/scripts/prepare_release.sh",
     "/scripts/run_checks.sh",
+    "/tests/fixtures/canvas_item_bank/assessment.xml",
+    "/tests/fixtures/canvas_item_bank/bank.xml.qti",
+    "/tests/fixtures/canvas_item_bank/imsmanifest.xml",
     "/tests/fixtures/import_qti/assessment.xml",
 }
 with tarfile.open(source, "r:gz") as archive:

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/src/QuestionBankToolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: QuestionBankToolkit
-Version: 0.1.0
+Version: 0.1.1
 Summary: Canvas QTI 1.2 question banks from YAML
 Author-email: "David D. Marshall" <ddmarsha@calpoly.edu>
 License-Expression: GPL-3.0-only
@@ -70,7 +70,7 @@ Import a supported QTI 1.2 ZIP package into a new YAML bank with:
 coursebanks import-qti questions.zip --course COURSE123 --bank-id ImportedBank --title "Imported bank" --out imported.yaml
 ```
 
-The importer supports a strict single-answer multiple-choice subset and rejects structures that cannot be represented without loss.
+The importer supports a strict single-answer multiple-choice subset, including Canvas Common Cartridge item-bank exports, and rejects unsupported or ambiguous structures.
 See [the QTI import guide](docs/importing-qti.md) for required package structure, defaults, choice-label normalization, metadata CSV overrides, and the field-by-field compatibility table.
 
 ## Optional: selecting and recording questions

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/src/QuestionBankToolkit.egg-info/SOURCES.txt

@@ -47,6 +47,7 @@ tests/test_archive_limits.py
 tests/test_assessments.py
 tests/test_boundary_failures.py
 tests/test_build_artifacts.py
+tests/test_canvas_qti_import.py
 tests/test_cli_contracts.py
 tests/test_optimized_validation.py
 tests/test_qti_export.py
@@ -59,5 +60,8 @@ tests/test_xml_security.py
 tests/test_yaml_loading.py
 tests/fixtures/export_bank.yaml
 tests/fixtures/sample_bank.yaml
+tests/fixtures/canvas_item_bank/assessment.xml
+tests/fixtures/canvas_item_bank/bank.xml.qti
+tests/fixtures/canvas_item_bank/imsmanifest.xml
 tests/fixtures/import_qti/assessment.xml
 tests/fixtures/import_qti/imsmanifest.xml

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/src/coursebanks/__init__.py

@@ -12,4 +12,4 @@ __version__
 
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/src/coursebanks/core.py

@@ -32,6 +32,7 @@ from .yaml_data import YamlMapping, YamlValue, yaml_value
 
 QTI = "http://www.imsglobal.org/xsd/ims_qtiasiv1p2"
 IMS = "http://www.imsglobal.org/xsd/imscp_v1p1"
+IMS_CC = "http://www.imsglobal.org/xsd/imsccv1p1/imscp_v1p1"
 ET.register_namespace("", QTI)
 SAFE_ID = re.compile(r"^[A-Za-z][A-Za-z0-9_.-]*$")
 DIFFICULTIES = {"Basic", "Moderate", "Challenging"}
@@ -1139,6 +1140,167 @@ def create_qti(
     return dest
 
 
+def _manifest_resource_href(
+    resource: ET.Element, *, allow_file_href: bool
+) -> str | None:
+    """Return a resource's direct href or its first file href.
+
+    Parameters
+    ----------
+    resource
+        Manifest resource element from an IMS or Common Cartridge manifest.
+    allow_file_href
+        Whether a child ``file/@href`` may replace an absent direct href.
+
+    Returns
+    -------
+    href
+        Resource href, or ``None`` when neither supported location supplies
+        one.
+
+    Notes
+    -----
+    Canvas Common Cartridge exports place the wrapper assessment path on a
+    child ``file`` element, while simple QTI packages use ``resource/@href``.
+
+    """
+    href = resource.get("href")
+    if href or not allow_file_href:
+        return href
+    file_node = resource.find("./{*}file")
+    return None if file_node is None else file_node.get("href")
+
+
+def _validated_manifest_href(
+    resource: ET.Element,
+    members: dict[str, ZipInfo],
+    description: str,
+    *,
+    allow_file_href: bool = False,
+) -> str:
+    """Return a safe archive member path declared by a resource.
+
+    Parameters
+    ----------
+    resource
+        Manifest resource containing a direct or child-file href.
+    members
+        Validated archive members keyed by their exact ZIP names.
+    description
+        Resource description included in a rejected-path diagnostic.
+    allow_file_href
+        Whether a child ``file/@href`` may replace an absent direct href.
+
+    Returns
+    -------
+    href
+        Relative path that names an existing unique archive member.
+
+    Raises
+    ------
+    ValueError
+        If the href is absent, absolute, parent-relative, or missing from the
+        validated archive.
+
+    """
+    href = _manifest_resource_href(resource, allow_file_href=allow_file_href)
+    if (
+        not href
+        or href not in members
+        or href.startswith("/")
+        or ".." in Path(href).parts
+    ):
+        raise ValueError(f"{description} href missing or invalid")
+    return href
+
+
+def _resolve_qti_member(
+    archive: ZipFile,
+    members: dict[str, ZipInfo],
+    manifest_root: ET.Element,
+) -> tuple[str, ET.Element]:
+    """Resolve a direct QTI assessment or Canvas-referenced object bank.
+
+    Parameters
+    ----------
+    archive
+        Open archive containing the already parsed manifest.
+    members
+        Validated archive members keyed by exact ZIP names.
+    manifest_root
+        Parsed IMS or Common Cartridge manifest document.
+
+    Returns
+    -------
+    assessment_file
+        Archive member containing the question items.
+    assessment_root
+        Parsed QTI root from that member.
+
+    Raises
+    ------
+    ValueError
+        If the manifest does not contain exactly one QTI resource, its href
+        is invalid, or a Canvas source-bank reference is absent or ambiguous.
+
+    Notes
+    -----
+    Simple packages store items in the QTI resource itself. Canvas item-bank
+    exports instead store a wrapper assessment there; its sourcebank_ref
+    identifies an associated manifest resource containing the actual items.
+
+    """
+    supported_manifest_roots = {
+        f"{{{IMS}}}manifest",
+        f"{{{IMS_CC}}}manifest",
+    }
+    if manifest_root.tag not in supported_manifest_roots:
+        raise ValueError("Incorrect IMS manifest namespace or root")
+    resources = manifest_root.findall(".//{*}resource")
+    qti_resources = [
+        resource
+        for resource in resources
+        if resource.get("type") == "imsqti_xmlv1p2"
+    ]
+    if len(qti_resources) != 1:
+        raise ValueError("Missing/incorrect QTI 1.2 assessment resource")
+
+    common_cartridge = manifest_root.tag == f"{{{IMS_CC}}}manifest"
+    qti_href = _validated_manifest_href(
+        qti_resources[0],
+        members,
+        "Manifest QTI",
+        allow_file_href=common_cartridge,
+    )
+    qti_root = parse_xml(read_member(archive, members[qti_href]))
+    source_refs = {
+        (node.text or "").strip()
+        for node in qti_root.findall(f".//{{{QTI}}}sourcebank_ref")
+        if (node.text or "").strip()
+    }
+    if not source_refs:
+        return qti_href, qti_root
+    if len(source_refs) != 1:
+        raise ValueError("Canvas QTI source bank reference is ambiguous")
+
+    source_ref = next(iter(source_refs))
+    matches = [
+        resource
+        for resource in resources
+        if resource.get("identifier") == source_ref
+    ]
+    if len(matches) != 1:
+        raise ValueError("Canvas QTI source bank reference is missing")
+    bank_href = _validated_manifest_href(
+        matches[0],
+        members,
+        "Manifest source bank",
+        allow_file_href=common_cartridge,
+    )
+    bank_root = parse_xml(read_member(archive, members[bank_href]))
+    return bank_href, bank_root
+
+
 def verify_qti(path: str | Path) -> QTIReport:
     """Check supported archive structure, identifiers, and scoring shape.
 
@@ -1168,12 +1330,13 @@ def verify_qti(path: str | Path) -> QTIReport:
     -----
     Applies the shared QTI archive limits before reading XML. Requires unique
     nonempty item IDs, at least two response labels, one varequal referencing
-    a choice ID, two setvar elements per item, and any supplied render_choice
-    shuffle value to be Yes or No. Checks the first manifest resource and
-    rejects absent, absolute, or parent-relative member paths. XML parsing
-    forbids DTDs and entities. This is not complete QTI validation: score
-    values, supported presentation content, bank schema constraints, and
-    Canvas rendering require other checks.
+    a choice ID, one or two setvar elements per item, and any supplied
+    render_choice shuffle value to be Yes or No. Resolves either a direct QTI
+    resource or one Canvas Common Cartridge source-bank reference and rejects
+    absent, absolute, or parent-relative member paths. XML parsing forbids DTDs
+    and entities. This is not complete QTI validation: score values, supported
+    presentation content, bank schema constraints, and Canvas rendering require
+    other checks.
 
     """  # noqa: DOC503
     with ZipFile(path) as zf:
@@ -1182,18 +1345,7 @@ def verify_qti(path: str | Path) -> QTIReport:
         if manifest is None:
             raise ValueError("QTI package missing root imsmanifest.xml")
         meta = parse_xml(read_member(zf, manifest))
-        resource = meta.find(f".//{{{IMS}}}resource")
-        if resource is None or resource.get("type") != "imsqti_xmlv1p2":
-            raise ValueError("Missing/incorrect QTI 1.2 assessment resource")
-        href = resource.get("href")
-        if (
-            not href
-            or href not in members
-            or href.startswith("/")
-            or ".." in Path(href).parts
-        ):
-            raise ValueError("Manifest QTI href missing or invalid")
-        root = parse_xml(read_member(zf, members[href]))
+        href, root = _resolve_qti_member(zf, members, meta)
     if root.tag != f"{{{QTI}}}questestinterop":
         raise ValueError("Incorrect QTI 1.2 namespace or root")
     items = root.findall(f".//{{{QTI}}}item")
@@ -1223,10 +1375,8 @@ def verify_qti(path: str | Path) -> QTIReport:
         )
         if len(val) != 1 or val[0].text not in {x.get("ident") for x in lids}:
             raise ValueError(f"Missing or invalid correct-answer key for {iid}")
-        if (
-            len(item.findall(f".//{{{QTI}}}respcondition/{{{QTI}}}setvar"))
-            != MIN_CHOICES
-        ):
+        score_rules = item.findall(f".//{{{QTI}}}respcondition/{{{QTI}}}setvar")
+        if len(score_rules) not in {1, MIN_CHOICES}:
             raise ValueError(f"Unexpected scoring rules for {iid}")
     return {
         "count": len(items),

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/src/coursebanks/migrate.py

@@ -15,7 +15,7 @@ from zipfile import ZipFile
 import yaml
 
 from .archive_io import read_member, validate_archive
-from .core import MIN_CHOICES, QTI, parse_bank, verify_qti
+from .core import MIN_CHOICES, QTI, SAFE_ID, parse_bank, verify_qti
 from .models import Bank
 from .xml_io import parse_xml
 from .yaml_data import YamlMapping, YamlValue, yaml_value
@@ -127,7 +127,7 @@ def import_qti(
     Unclassified for area/topic, Moderate for difficulty, unrestricted
     eligibility, 2.5 minutes, 2 points, and unshuffled choices when QTI omits
     the shuffle attribute. CSV overrides and QTI metadata are resolved before
-    schema validation; missing explanations are rejected.
+    schema validation; absent feedback receives an explicit placeholder.
 
     """  # noqa: DOC503
     report = verify_qti(path)
@@ -403,25 +403,28 @@ def _parse_correct_answer(
 
 
 def _parse_explanation(item: Element, ident: str) -> str:
-    """Extract required feedback without silently losing an explanation.
+    """Extract feedback or describe its absence explicitly.
 
     Parameters
     ----------
     item
         Parsed QTI item containing itemfeedback/flow_mat/material/mattext.
     ident
-        Question identifier used in error messages.
+        Question identifier used in malformed-feedback diagnostics.
 
     Returns
     -------
     explanation
-        Text from the first matching feedback element, or an empty string
-        if the element has no text. Bank validation checks for nonempty text.
+        Text from the first matching feedback element. If QTI contains no
+        feedback container, an explicit nonempty placeholder states that the
+        imported package supplied no explanation. An empty feedback text
+        value returns an empty string for bank validation to reject.
 
     Raises
     ------
     ValueError
-        If no matching feedback mattext element exists.
+        If an itemfeedback container exists without the supported nested
+        mattext structure.
 
     """
     feedback = item.find(
@@ -429,12 +432,48 @@ def _parse_explanation(item: Element, ident: str) -> str:
         f"material/{{{QTI}}}mattext"
     )
     if feedback is None:
-        raise ValueError(
-            f"Missing explanation in {ident}; refusing lossy import"
-        )
+        if item.find(f"./{{{QTI}}}itemfeedback") is not None:
+            raise ValueError(f"Missing explanation in {ident}")
+        return "No explanation was provided in the imported QTI package."
     return feedback.text or ""
 
 
+def _normalize_question_id(ident: str) -> str:
+    """Make a digit-leading QTI identifier valid for the YAML schema.
+
+    Parameters
+    ----------
+    ident
+        Nonempty source identifier from the QTI item.
+
+    Returns
+    -------
+    question_id
+        Original identifier when already valid, or the identifier prefixed
+        with ``q_`` when its only schema conflict is a nonletter first
+        character.
+
+    Raises
+    ------
+    ValueError
+        If characters after the optional prefix remain outside the YAML
+        identifier grammar.
+
+    Notes
+    -----
+    Canvas commonly emits hexadecimal item identifiers beginning with a
+    digit. Prefixing preserves every source character and is deterministic.
+    Final bank validation detects any collision with an existing identifier.
+
+    """
+    if SAFE_ID.fullmatch(ident):
+        return ident
+    normalized = f"q_{ident}"
+    if SAFE_ID.fullmatch(normalized):
+        return normalized
+    raise ValueError(f"Unsupported QTI item identifier {ident!r}")
+
+
 def _resolve_eligibility(
     e: dict[str, str], metadata: dict[str, str]
 ) -> YamlMapping:
@@ -560,10 +599,10 @@ def _import_item(
     Returns
     -------
     question
-        Unvalidated YAML mapping containing question content, relabeled
-        choices, effective shuffling, translated answer, feedback, and resolved
-        authoring fields. QTI text/plain and text/html become plain and html
-        respectively.
+        Unvalidated YAML mapping containing normalized identity, question
+        content, relabeled choices, effective shuffling, translated answer,
+        feedback, and resolved authoring fields. QTI text/plain and text/html
+        become plain and html respectively.
 
     Raises
     ------
@@ -590,7 +629,7 @@ def _import_item(
         item, ident, extras.get(ident, {}), metadata
     )
     return {
-        "id": ident,
+        "id": _normalize_question_id(ident),
         **authoring,
         "format": "html"
         if presentation.text_format == "text/html"

{questionbanktoolkit-0.1.0 → questionbanktoolkit-0.1.1}/src/coursebanks/models.py

@@ -117,7 +117,9 @@ class QTIReport(TypedDict):
     ids
         Question identifiers in document order.
     assessment_file
-        Verified ZIP member path referenced by the manifest's QTI resource.
+        Verified ZIP member containing the items. For a Canvas Common
+        Cartridge export, this is the object bank resolved through the QTI
+        wrapper's source-bank reference.
 
     Notes
     -----

questionbanktoolkit-0.1.1/tests/fixtures/canvas_item_bank/assessment.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<questestinterop xmlns="http://www.imsglobal.org/xsd/ims_qtiasiv1p2">
+  <assessment ident="assessment" title="Canvas export">
+    <section ident="root_section">
+      <section ident="bank_section" title="Canvas item bank">
+        <selection_ordering>
+          <selection>
+            <sourcebank_ref>bank_resource</sourcebank_ref>
+          </selection>
+        </selection_ordering>
+      </section>
+    </section>
+  </assessment>
+</questestinterop>

questionbanktoolkit-0.1.1/tests/fixtures/canvas_item_bank/bank.xml.qti

@@ -0,0 +1,51 @@
+<?xml version="1.0"?>
+<questestinterop xmlns="http://www.imsglobal.org/xsd/ims_qtiasiv1p2">
+  <objectbank ident="bank_resource" canvas_item_bank="true">
+    <item ident="03be6638087ef4d5e99c18e8d9c3267e"
+          title="EX18 - Successful Execution">
+      <itemmetadata>
+        <qtimetadata>
+          <qtimetadatafield>
+            <fieldlabel>question_type</fieldlabel>
+            <fieldentry>multiple_choice_question</fieldentry>
+          </qtimetadatafield>
+          <qtimetadatafield>
+            <fieldlabel>points_possible</fieldlabel>
+            <fieldentry/>
+          </qtimetadatafield>
+        </qtimetadata>
+      </itemmetadata>
+      <presentation>
+        <material>
+          <mattext texttype="text/html">What does successful execution establish?</mattext>
+        </material>
+        <response_lid ident="response1" rcardinality="Single">
+          <render_choice>
+            <response_label ident="incorrect-answer">
+              <material>
+                <mattext texttype="text/html">The engineering result is correct.</mattext>
+              </material>
+            </response_label>
+            <response_label ident="correct-answer">
+              <material>
+                <mattext texttype="text/html">The code path completed without an exception.</mattext>
+              </material>
+            </response_label>
+          </render_choice>
+        </response_lid>
+      </presentation>
+      <resprocessing>
+        <outcomes>
+          <decvar maxvalue="100" minvalue="0" varname="SCORE"
+                  vartype="Decimal"/>
+        </outcomes>
+        <respcondition continue="No">
+          <conditionvar>
+            <varequal respident="response1">correct-answer</varequal>
+          </conditionvar>
+          <setvar action="Set" varname="SCORE">100</setvar>
+        </respcondition>
+      </resprocessing>
+    </item>
+  </objectbank>
+</questestinterop>

questionbanktoolkit-0.1.1/tests/fixtures/canvas_item_bank/imsmanifest.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<manifest xmlns="http://www.imsglobal.org/xsd/imsccv1p1/imscp_v1p1"
+          identifier="canvas_export">
+  <resources>
+    <resource identifier="assessment" type="imsqti_xmlv1p2">
+      <file href="assessment/assessment.xml"/>
+      <dependency identifierref="bank_resource"/>
+    </resource>
+    <resource identifier="bank_resource"
+              type="associatedcontent/imscc_xmlv1p1/learning-application-resource"
+              href="non_cc_assessments/bank.xml.qti">
+      <file href="non_cc_assessments/bank.xml.qti"/>
+    </resource>
+  </resources>
+</manifest>

questionbanktoolkit-0.1.1/tests/test_canvas_qti_import.py

@@ -0,0 +1,220 @@
+"""Verify import of Canvas Common Cartridge item-bank exports.
+
+Package a minimal independently authored Canvas-style export and require its
+manifest indirection, scoring, identifiers, and omitted fields to normalize
+into the documented YAML schema.
+
+Attributes
+----------
+FIXTURE_DIR
+    Directory containing the Canvas-style manifest and QTI members.
+MISSING_EXPLANATION
+    Explicit placeholder used when Canvas exports no item feedback.
+
+"""
+
+from copy import deepcopy
+from pathlib import Path
+
+# ElementTree is used only to serialize locally modified test XML.
+from xml.etree import ElementTree as ET  # ruff: ignore[suspicious-xml-etree-import]
+from zipfile import ZipFile
+
+import pytest
+
+from coursebanks.core import QTI, verify_qti
+from coursebanks.migrate import import_qti
+from coursebanks.xml_io import parse_xml
+
+FIXTURE_DIR = Path(__file__).parent / "fixtures" / "canvas_item_bank"
+MISSING_EXPLANATION = "No explanation was provided in the imported QTI package."
+
+
+def _fixture_members() -> dict[str, bytes]:
+    """Return Canvas-style fixture bytes keyed by archive member path.
+
+    Returns
+    -------
+    members
+        Fresh mapping suitable for mutation by one boundary test.
+
+    """
+    return {
+        "imsmanifest.xml": FIXTURE_DIR.joinpath("imsmanifest.xml").read_bytes(),
+        "assessment/assessment.xml": FIXTURE_DIR.joinpath(
+            "assessment.xml"
+        ).read_bytes(),
+        "non_cc_assessments/bank.xml.qti": FIXTURE_DIR.joinpath(
+            "bank.xml.qti"
+        ).read_bytes(),
+    }
+
+
+def _write_archive(path: Path, members: dict[str, bytes]) -> Path:
+    """Write a Canvas-style package with supplied member bytes.
+
+    Parameters
+    ----------
+    path
+        Destination ZIP path, overwritten if already present.
+    members
+        Archive paths mapped to payload bytes.
+
+    Returns
+    -------
+    path
+        Supplied destination after all members have been written.
+
+    """
+    with ZipFile(path, "w") as archive:
+        for name, payload in members.items():
+            archive.writestr(name, payload)
+    return path
+
+
+@pytest.fixture
+def canvas_archive(tmp_path: Path) -> Path:
+    """Package the Canvas-style XML fixtures under their manifest paths.
+
+    Parameters
+    ----------
+    tmp_path
+        Pytest directory receiving the generated Common Cartridge archive.
+
+    Returns
+    -------
+    archive_path
+        ZIP containing a wrapper assessment and referenced object bank.
+
+    """
+    archive_path = tmp_path / "canvas-export.zip"
+    return _write_archive(archive_path, _fixture_members())
+
+
+def test_canvas_item_bank_import(canvas_archive: Path) -> None:
+    """Resolve and import a Canvas object bank through its wrapper.
+
+    Parameters
+    ----------
+    canvas_archive
+        Minimal Canvas Common Cartridge export built by the fixture.
+
+    Notes
+    -----
+    The source item has a digit-leading identifier, one full-credit scoring
+    rule, empty point metadata, no shuffle attribute, and no feedback.
+
+    """
+    report = verify_qti(canvas_archive)
+    assert report == {
+        "count": 1,
+        "ids": ["03be6638087ef4d5e99c18e8d9c3267e"],
+        "assessment_file": "non_cc_assessments/bank.xml.qti",
+    }
+
+    bank = import_qti(
+        canvas_archive,
+        "AERO3300",
+        "Module01",
+        "Canvas item bank",
+    )
+    assert bank["questions"] == [
+        {
+            "id": "q_03be6638087ef4d5e99c18e8d9c3267e",
+            "title": "EX18 - Successful Execution",
+            "area": "Unclassified",
+            "topic": "Unclassified",
+            "difficulty": "Moderate",
+            "assessments": [],
+            "minutes": 2.5,
+            "points": 2,
+            "format": "html",
+            "stem": "What does successful execution establish?",
+            "choices": {
+                "A": "The engineering result is correct.",
+                "B": "The code path completed without an exception.",
+            },
+            "shuffle_choices": False,
+            "answer": "B",
+            "explanation": MISSING_EXPLANATION,
+        }
+    ]
+
+
+def test_canvas_item_bank_rejects_ambiguous_reference(
+    tmp_path: Path,
+) -> None:
+    """Reject a wrapper that identifies more than one source bank.
+
+    Parameters
+    ----------
+    tmp_path
+        Pytest directory receiving the malformed package.
+
+    """
+    members = _fixture_members()
+    root = parse_xml(members["assessment/assessment.xml"])
+    reference = root.find(f".//{{{QTI}}}sourcebank_ref")
+    assert reference is not None
+    duplicate = deepcopy(reference)
+    duplicate.text = "another_bank"
+    reference_parent = root.find(f".//{{{QTI}}}selection")
+    assert reference_parent is not None
+    reference_parent.append(duplicate)
+    members["assessment/assessment.xml"] = ET.tostring(root)
+    archive = _write_archive(tmp_path / "ambiguous.zip", members)
+
+    with pytest.raises(ValueError, match="source bank reference is ambiguous"):
+        verify_qti(archive)
+    with pytest.raises(ValueError, match="source bank reference is ambiguous"):
+        import_qti(archive, "COURSE", "Bank", "Imported")
+
+
+def test_canvas_item_bank_rejects_unsafe_bank_href(tmp_path: Path) -> None:
+    """Reject a parent-relative path on the referenced bank resource.
+
+    Parameters
+    ----------
+    tmp_path
+        Pytest directory receiving the malformed package.
+
+    """
+    members = _fixture_members()
+    root = parse_xml(members["imsmanifest.xml"])
+    bank_resource = next(
+        resource
+        for resource in root.findall(".//{*}resource")
+        if resource.get("identifier") == "bank_resource"
+    )
+    bank_resource.set("href", "../bank.xml.qti")
+    members["../bank.xml.qti"] = members["non_cc_assessments/bank.xml.qti"]
+    members["imsmanifest.xml"] = ET.tostring(root)
+    archive = _write_archive(tmp_path / "unsafe.zip", members)
+
+    with pytest.raises(ValueError, match="source bank href missing or invalid"):
+        verify_qti(archive)
+    with pytest.raises(ValueError, match="source bank href missing or invalid"):
+        import_qti(archive, "COURSE", "Bank", "Imported")
+
+
+def test_canvas_item_bank_rejects_wrong_manifest_namespace(
+    tmp_path: Path,
+) -> None:
+    """Reject resource-like XML outside supported manifest namespaces.
+
+    Parameters
+    ----------
+    tmp_path
+        Pytest directory receiving the malformed package.
+
+    """
+    members = _fixture_members()
+    root = parse_xml(members["imsmanifest.xml"])
+    root.tag = "{urn:unsupported}manifest"
+    members["imsmanifest.xml"] = ET.tostring(root)
+    archive = _write_archive(tmp_path / "wrong-manifest.zip", members)
+
+    with pytest.raises(ValueError, match="manifest namespace or root"):
+        verify_qti(archive)
+    with pytest.raises(ValueError, match="manifest namespace or root"):
+        import_qti(archive, "COURSE", "Bank", "Imported")