qti-package-maker


Nameqti-package-maker JSON
Version 0.8.6 PyPI version JSON
download
home_pageNone
SummaryA package to create, manage, and convert QTI packages for quizzes and assessments in Canvas, Blackboard, Moodle, and LibreTexts ADAPT.
upload_time2025-03-29 00:41:38
maintainerNone
docs_urlNone
authorDr. Neil Voss
requires_python>=3.9
licenseNone
keywords qti quiz assessment test package canvas blackboard moodle libretexts adapt e-learning lms question bank quiz converter online learning exam generator qti exporter ims question and test interoperability specification question and test interoperability xml qti v2.1 qti v1.2
VCS
bugtrack_url
requirements lxml crcmod num2words pyyaml tabulate
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # QTI Package Maker

## Introduction

`qti_package_maker` is a Python package designed for generating and converting question and test packages in various formats, including IMS QTI (Question & Test Interoperability) v1.2 and v2.1, Blackboard Question Upload format, human-readable text, and HTML self-test formats.

This package is developed for educators, instructional designers, and e-learning professionals working with LMS platforms such as LibreTexts' ADAPT, Canvas, and Blackboard. It provides a unified interface to create and manage assessments that can be imported into these learning management systems.

The package allows users to:
- Convert and generate question packages in multiple formats, including QTI v1.2 for Canvas/ADAPT and QTI v2.1 for Blackboard.
- Handle various question types, including multiple-choice, matching, numerical, and ordered questions.
- Clean and structure question text to remove formatting inconsistencies.
- Randomize question choices while ensuring the correct answer remains properly mapped.
- Read and write question packages in QTI, human-readable, and Blackboard formats.

This tool is primarily intended for educators and developers who need to convert, migrate, and generate structured assessments across different learning platforms.

## Table of Contents
<!-- md_toc github README.md -->
- [Introduction](#introduction)
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Installation](#installation)
  - [Prerequisites](#prerequisites)
  - [Installing from PyPI](#installing-from-pypi)
  - [Installing from Source](#installing-from-source)
- [Question Types](#question-types)
  - [Multiple Choice (MC)](#multiple-choice-mc)
  - [Multiple Answer (MA)](#multiple-answer-ma)
  - [Matching (MATCH)](#matching-match)
  - [Numerical Entry (NUM)](#numerical-entry-num)
  - [Fill-in-the-Blank (FIB)](#fill-in-the-blank-fib)
  - [Multi-Part Fill-in-the-Blank (MULTI_FIB)](#multi-part-fill-in-the-blank-multi_fib)
  - [Ordered List (ORDER)](#ordered-list-order)
- [Output Engines](#output-engines)
  - [QTI v1.2 Engine (Canvas QTI v1.2)](#qti-v12-engine-canvas-qti-v12)
  - [QTI v2.1 Engine (Blackboard QTI v2.1)](#qti-v21-engine-blackboard-qti-v21)
  - [Human-Readable Engine](#human-readable-engine)
  - [Blackboard Question Upload Engine](#blackboard-question-upload-engine)
  - [HTML Self-Test Engine](#html-self-test-engine)
- [Engines Capabilities](#engines-capabilities)
  - [Read and Write](#read-and-write)
  - [Assessment Item Types](#assessment-item-types)
- [Usage](#usage)
  - [Primary Supported Input Format](#primary-supported-input-format)
  - [BBQ File Format Guidelines](#bbq-file-format-guidelines)
  - [Supported BBQ Question Formats](#supported-bbq-question-formats)
- [BBQ Converter Command Options](#bbq-converter-command-options)
  - [Complete BBQ Converter Options](#complete-bbq-converter-options)
- [Python API Usage](#python-api-usage)
  - [Creating an Assessment Package](#creating-an-assessment-package)
    - [Saving the Package](#saving-the-package)
- [Development & Contribution](#development--contribution)
- [Roadmap and Planned Features](#roadmap-and-planned-features)
- [Related Projects](#related-projects)
- [License](#license)
- [Support this project](#support-this-project)
- [Social Media links](#social-media-links)
- [Acknowledgments](#acknowledgments)

## Features
- Supports Multiple QTI Versions – Generates valid QTI v1.2 (Canvas) and QTI v2.1 (Blackboard).
- Multiple Question Types – MC, MA, FIB, NUM, MATCH, ORDER, and MULTI_FIB.
- Modular Engine System – Easily swap between different export formats.
- Command-line and Python API Support – Use it in scripts or from the command line.

## Installation

### Prerequisites
- Python 3.9 or later
- `pip` installed

### Installing from PyPI
```sh
pip install qti-package-maker
```

### Installing from Source
```sh
git clone https://github.com/vosslab/qti_package_maker.git
cd qti_package_maker
pip install -r requirements.txt
```

## Question Types

QTI Package Maker supports seven essential question types commonly used in assessments. These include Multiple Choice (MC), Multiple Answer (MA), Matching (MATCH), Numerical Entry (NUM), Fill-in-the-Blank (FIB), Multi-Part Fill-in-the-Blank (MULTI_FIB), and Ordered Lists (ORDER). Below is an overview of each type and its required inputs.

### Multiple Choice (MC)
**Inputs:**
- `question_text` (str): The question prompt.
- `choices_list` (list): A list of answer choices.
- `answer_text` (str): The correct answer.

### Multiple Answer (MA)
**Inputs:**
- `question_text` (str)
- `choices_list` (list)
- `answers_list` (list): A list of correct answers.

### Matching (MATCH)
**Inputs:**
- `question_text` (str)
- `prompts_list` (list): Items to be matched.
- `choices_list` (list): Possible matching answers.

### Numerical Entry (NUM)
**Inputs:**
- `question_text` (str)
- `answer_float` (float): The correct numerical answer.
- `tolerance_float` (float): Accepted tolerance range.
- `tolerance_message` (bool, default=True): Message for tolerance handling.

### Fill-in-the-Blank (FIB)
**Inputs:**
- `question_text` (str)
- `answers_list` (list): List of acceptable answers.

### Multi-Part Fill-in-the-Blank (MULTI_FIB)
**Inputs:**
- `question_text` (str)
- `answer_map` (dict): A dictionary mapping blank positions to correct answers.

### Ordered List (ORDER)
**Inputs:**
- `question_text` (str)
- `ordered_answers_list` (list): The correct sequence of answers.

## Output Engines

The package supports multiple output formats via engines. Each engine corresponds to a specific QTI version or alternative export format.

### QTI v1.2 Engine (Canvas QTI v1.2)
- **Engine Name:** `canvas_qti_v1_2`
- **Format Type:** QTI v1.2 (IMS XML format)
- **Compatible LMS:** Canvas, LibreTexts ADAPT
- **File Output:** ZIP file containing QTI v1.2 XML files

### QTI v2.1 Engine (Blackboard QTI v2.1)
- **Engine Name:** `blackboard_qti_v2_1`
- **Format Type:** QTI v2.1 (IMS XML format)
- **Compatible LMS:** Blackboard
- **File Output:** ZIP file containing QTI v2.1 XML files

### Human-Readable Engine
- **Engine Name:** `human_readable`
- **Format Type:** Simple text file
- **Compatible LMS:** Any system that supports plain-text import
- **File Output:** A structured text file listing the questions and answers in a human-readable format
- **Use Case:** Used for reviewing questions before conversion to QTI

### Blackboard Question Upload Engine
- **Engine Name:** `bbq_text_upload`
- **Format Type:** Blackboard-specific TXT upload format
- **Compatible LMS:** Blackboard (Original Course View)
- **Documentation:** https://help.blackboard.com/Learn/Instructor/Original/Tests_Pools_Surveys/Orig_Reuse_Questions/Upload_Questions
- **File Output:** A `.txt` file that Blackboard can directly upload

### HTML Self-Test Engine
- **Engine Name:** `html_selftest`
- **Format Type:** HTML-based self-assessment
- **Compatible LMS:** Any web-based environment
- **File Output:** A self-contained HTML file
- **Use Case:** Used for creating self-assessment quizzes without LMS integration

## Engines Capabilities

### Read and Write

| Engine Name         | Can Read   | Can Write   |
|---------------------|------------|-------------|
| bbq_text_upload     | ✅         | ✅          |
| blackboard_qti_v2_1 | ❌         | ✅          |
| canvas_qti_v1_2     | ❌         | ✅          |
| html_selftest       | ❌         | ✅          |
| human_readable      | ❌         | ✅          |
| text2qti            | ✅         | ✅          |

### Assessment Item Types

| Item Type   | bbq text upload   | blackboard qti v2.1   | canvas qti v1.2   | html selftest   | human readable   | text2qti   |
|-------------|-------------------|-----------------------|-------------------|-----------------|------------------|------------|
| FIB         | ✅                | ✅                    | ❌                | ❌             | ✅               | ✅         |
| MA          | ✅                | ✅                    | ✅                | ✅             | ✅               | ✅         |
| MATCH       | ✅                | ❌                    | ✅                | ✅             | ✅               | ❌         |
| MC          | ✅                | ✅                    | ✅                | ✅             | ✅               | ✅         |
| MULTI_FIB   | ✅                | ❌                    | ❌                | ❌             | ✅               | ❌         |
| NUM         | ✅                | ❌                    | ❌                | ❌             | ✅               | ✅         |
| ORDER       | ✅                | ❌                    | ❌                | ❌             | ✅               | ❌         |

## Usage

### Primary Supported Input Format

The **Blackboard Question Upload (BBQ) text format** is currently the only supported input format for `qti_package_maker`. This format allows users to write questions in a plain text file and upload them into tests, surveys, and question pools on Blackboard. Once uploaded, the questions can be edited and used like those created directly within the LMS.

### BBQ File Format Guidelines
- Must be a **tab-delimited TXT file**.
- Should **not include a header row**.
- Should **not contain blank lines**.
- New lines characters cannot exist within the question.
- Each row must contain **one question**.
- The **first field in each row** defines the question type.
- Fields in a row are **separated by a TAB**.

### Supported BBQ Question Formats

| Question Type        | Format |
|----------------------|--------|
| **Multiple Choice (MC)** | ``MC TAB question text TAB answer text TAB correct\|incorrect TAB answer two text TAB correct\|incorrect`` |
| **Multiple Answer (MA)** | ``MA TAB question text TAB answer text TAB correct\|incorrect TAB answer two text TAB correct\|incorrect`` |
| **Ordering (ORD)** | `ORD TAB question text TAB answer text TAB answer two text` |
| **Matching (MAT)** | `MAT TAB question text TAB answer text TAB matching text TAB answer two text TAB matching two text` |
| **Fill in the Blank (FIB)** | `FIB TAB question text TAB answer text TAB answer two text` |
| **Fill in Multiple Blanks (FIB_PLUS)** | `FIB_PLUS TAB question text TAB variable1 TAB answer1 TAB answer2 TAB TAB variable2 TAB answer3` |
| **Numeric Response (NUM)** | `NUM TAB question text TAB answer TAB [optional]tolerance` |

For more details, refer to the official **[Blackboard documentation](https://help.blackboard.com/Learn/Instructor/Original/Tests_Pools_Surveys/Orig_Reuse_Questions/Upload_Questions)**.

## BBQ Converter Command Options

The `bbq_converter.py` tool allows converting BBQ text files into multiple output formats. Example usage:
```sh
python3 tools/bbq_converter.py -i bbq-my_questions.txt -f qti12
```
To convert into all available formats:
```sh
python3 tools/bbq_converter.py -i bbq-my_questions.txt --all
```

For available options, use:
```sh
python3 tools/bbq_converter.py -h
```

### Complete BBQ Converter Options
```sh
usage: bbq_converter.py [-h] -i INPUT_FILE [-n QUESTION_LIMIT] [--allow-mixed]
                        [-f {canvas_qti_v1_2,blackboard_qti_v2_1,human_readable,bbq_text_upload,html_selftest}] [-a]
                        [-1 [OUTPUT_FORMAT]] [-2 [OUTPUT_FORMAT]] [-r [OUTPUT_FORMAT]] [-b [OUTPUT_FORMAT]] [-s [OUTPUT_FORMAT]]

Convert BBQ file to other formats.

options:
  -h, --help            show this help message and exit
  -i INPUT_FILE, --input INPUT_FILE, --input_file INPUT_FILE
                        Path to the input BBQ text file.
  -n QUESTION_LIMIT, --limit QUESTION_LIMIT, --question_limit QUESTION_LIMIT
                        Limit the number of input items.
  --allow-mixed         Allow mixed question types.
  -f {canvas_qti_v1_2,blackboard_qti_v2_1,human_readable,bbq_text_upload,html_selftest}, --format {canvas_qti_v1_2,blackboard_qti_v2_1,human_readable,bbq_text_upload,html_selftest}
                        Set output format (multiple allowed).
  -a, --all             Enable all output formats.
  -1 [OUTPUT_FORMAT], --qti12 [OUTPUT_FORMAT]
                        Set output format to Canvas QTI v1.2.
  -2 [OUTPUT_FORMAT], --qti21 [OUTPUT_FORMAT]
                        Set output format to Blackboard QTI v2.1.
  -r [OUTPUT_FORMAT], --human [OUTPUT_FORMAT]
                        Set output format to human-readable text.
  -b [OUTPUT_FORMAT], --bbq [OUTPUT_FORMAT]
                        Set output format to Blackboard Question Upload format.
  -s [OUTPUT_FORMAT], --html [OUTPUT_FORMAT]
                        Set output format to HTML self-test.
```

## Python API Usage

### Creating an Assessment Package

```python
from qti_package_maker.package_interface import QTIPackageInterface

# Initialize the package with a name
qti_packer = QTIPackageInterface("example_assessment", verbose=True)

# Add a multiple-choice question
qti_packer.add_item("MC", ("What is your favorite color?", ["blue", "red", "yellow"], "blue"))

# Add a multiple-answer question
qti_packer.add_item("MA", ("Which of these are fruits?", ["apple", "carrot", "banana", "broccoli"], ["apple", "banana"]))
```

#### Saving the Package
```python
# Save as Canvas QTI v1.2
qti_packer.save_package("canvas_qti_v1_2")

# Save as Blackboard QTI v2.1
qti_packer.save_package("blackboard_qti_v2_1")
``````
This will create a Blackboard-compatible QTI v2.1 ZIP file.

## Development & Contribution

Contributions are welcome! Follow these steps to contribute:

1. **Fork** the repository on GitHub.
2. **Clone** your forked repository:
   ```sh
   git clone https://github.com/YOUR_USERNAME/qti_package_maker.git
   cd qti_package_maker
   ```
3. **Create a feature branch** (`feature-my-update`):
   ```sh
   git checkout -b feature-my-update
   ```
4. **Make your changes** and commit them:
   ```sh
   git add .
   git commit -m "Describe your changes here"
   ```
5. **Push** to your fork and open a **Pull Request**:
   ```sh
   git push origin feature-my-update
   ```
   - Navigate to the **Pull Requests** section of the original repository on GitHub.
   - Click **New Pull Request** and select your branch.
   - Provide a clear description of your changes and submit the request.

## Roadmap and Planned Features
- Improve error handling and validation
- Add question randomization and shuffling
- Add unit tests

## Related Projects

- **Moodle Question Format: Canvas**  
  A Moodle plugin that imports questions exported from the Canvas LMS as an XML file into Moodle.  
  GitHub: https://github.com/jmvedrine/moodle-qformat_canvas

- **text2qti**  
  A Python tool that converts Markdown-based plain text files into quizzes in QTI format, compatible with Canvas and other educational software.  
  PyPI: https://pypi.org/project/text2qti/

- **Blackboard Test Question Generator**  
  An online tool that assists in creating test questions for Blackboard by converting plain text into a format suitable for import.  
  Website: https://ed.oc.edu/blackboardquizgenerator/

- **amc2moodle**  
  A Python package that facilitates the conversion of AMC (Auto Multiple Choice) formatted questions into Moodle XML format for easy import.  
  PyPI: https://pypi.org/project/amc2moodle/

- **moodle-questions**  
  A Python library designed for manipulating questions in Moodle XML format, enabling programmatic creation and modification of Moodle quizzes.  
  GitHub: https://github.com/gethvi/moodle-questions

- **pyAssignment**  
  A Python module for authoring and assessing homework assignments, with capabilities to output assignments to LaTeX and Blackboard quiz formats.  
  PyPI: https://pypi.org/project/pyassignment/

## License

Copyright &copy; 2025, Dr. Neil Voss

qti_package_maker is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or any later version.

qti_package_maker is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

See the full license details in the 
[LICENSE file](https://github.com/vosslab/qti_package_maker/blob/main/LICENSE).
If not, see <http://www.gnu.org/licenses/>.

## Support this project

<!-- setup on Feb 28, 2025 -->
- **Bitcoin:** [Donate with Bitcoin](bitcoin:bc1qdexkqwzyet93ret40akqmms2jv99wvsgzdshu8?message=support%20qti_package_maker)
- **Dash:** [Donate with Dash](dash:XdDmwBVecEy9yyXKeD7hScLp7oN8rd4XNV?message=support%20qti_package_maker)
- **Patreon:** [Support on Patreon](https://www.patreon.com/vosslab)
- **Paypal:** [Donate via PayPal](https://paypal.me/vosslab)

## Social Media links

- [YouTube](https://www.youtube.com/neilvosslab)
- [Github](https://github.com/vosslab)
- [Bluesky](https://bsky.app/profile/neilvosslab.bsky.social)
- [Facebook](https://fb.me/neilvosslab)
- [LinkedIn](https://www.linkedin.com/in/vosslab)


## Acknowledgments
- Based on the IMS Global QTI specification
- Inspired by the need for cross-platform assessment portability
- Developed to improve e-learning content interoperability
- Funding for production from Illinois Library OER grant



            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "qti-package-maker",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "QTI, quiz, assessment, test package, Canvas, Blackboard, Moodle, LibreTexts ADAPT, e-learning, LMS, question bank, quiz converter, online learning, exam generator, QTI exporter, IMS Question and Test Interoperability specification, Question and Test Interoperability, XML, QTI v2.1, QTI v1.2",
    "author": "Dr. Neil Voss",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/3c/a8/03390c32a45d23f752822643afd353852b91eae9c84fb1f6084a4cd1b5ee/qti_package_maker-0.8.6.tar.gz",
    "platform": null,
    "description": "# QTI Package Maker\n\n## Introduction\n\n`qti_package_maker` is a Python package designed for generating and converting question and test packages in various formats, including IMS QTI (Question & Test Interoperability) v1.2 and v2.1, Blackboard Question Upload format, human-readable text, and HTML self-test formats.\n\nThis package is developed for educators, instructional designers, and e-learning professionals working with LMS platforms such as LibreTexts' ADAPT, Canvas, and Blackboard. It provides a unified interface to create and manage assessments that can be imported into these learning management systems.\n\nThe package allows users to:\n- Convert and generate question packages in multiple formats, including QTI v1.2 for Canvas/ADAPT and QTI v2.1 for Blackboard.\n- Handle various question types, including multiple-choice, matching, numerical, and ordered questions.\n- Clean and structure question text to remove formatting inconsistencies.\n- Randomize question choices while ensuring the correct answer remains properly mapped.\n- Read and write question packages in QTI, human-readable, and Blackboard formats.\n\nThis tool is primarily intended for educators and developers who need to convert, migrate, and generate structured assessments across different learning platforms.\n\n## Table of Contents\n<!-- md_toc github README.md -->\n- [Introduction](#introduction)\n- [Table of Contents](#table-of-contents)\n- [Features](#features)\n- [Installation](#installation)\n  - [Prerequisites](#prerequisites)\n  - [Installing from PyPI](#installing-from-pypi)\n  - [Installing from Source](#installing-from-source)\n- [Question Types](#question-types)\n  - [Multiple Choice (MC)](#multiple-choice-mc)\n  - [Multiple Answer (MA)](#multiple-answer-ma)\n  - [Matching (MATCH)](#matching-match)\n  - [Numerical Entry (NUM)](#numerical-entry-num)\n  - [Fill-in-the-Blank (FIB)](#fill-in-the-blank-fib)\n  - [Multi-Part Fill-in-the-Blank (MULTI_FIB)](#multi-part-fill-in-the-blank-multi_fib)\n  - [Ordered List (ORDER)](#ordered-list-order)\n- [Output Engines](#output-engines)\n  - [QTI v1.2 Engine (Canvas QTI v1.2)](#qti-v12-engine-canvas-qti-v12)\n  - [QTI v2.1 Engine (Blackboard QTI v2.1)](#qti-v21-engine-blackboard-qti-v21)\n  - [Human-Readable Engine](#human-readable-engine)\n  - [Blackboard Question Upload Engine](#blackboard-question-upload-engine)\n  - [HTML Self-Test Engine](#html-self-test-engine)\n- [Engines Capabilities](#engines-capabilities)\n  - [Read and Write](#read-and-write)\n  - [Assessment Item Types](#assessment-item-types)\n- [Usage](#usage)\n  - [Primary Supported Input Format](#primary-supported-input-format)\n  - [BBQ File Format Guidelines](#bbq-file-format-guidelines)\n  - [Supported BBQ Question Formats](#supported-bbq-question-formats)\n- [BBQ Converter Command Options](#bbq-converter-command-options)\n  - [Complete BBQ Converter Options](#complete-bbq-converter-options)\n- [Python API Usage](#python-api-usage)\n  - [Creating an Assessment Package](#creating-an-assessment-package)\n    - [Saving the Package](#saving-the-package)\n- [Development & Contribution](#development--contribution)\n- [Roadmap and Planned Features](#roadmap-and-planned-features)\n- [Related Projects](#related-projects)\n- [License](#license)\n- [Support this project](#support-this-project)\n- [Social Media links](#social-media-links)\n- [Acknowledgments](#acknowledgments)\n\n## Features\n- Supports Multiple QTI Versions \u2013 Generates valid QTI v1.2 (Canvas) and QTI v2.1 (Blackboard).\n- Multiple Question Types \u2013 MC, MA, FIB, NUM, MATCH, ORDER, and MULTI_FIB.\n- Modular Engine System \u2013 Easily swap between different export formats.\n- Command-line and Python API Support \u2013 Use it in scripts or from the command line.\n\n## Installation\n\n### Prerequisites\n- Python 3.9 or later\n- `pip` installed\n\n### Installing from PyPI\n```sh\npip install qti-package-maker\n```\n\n### Installing from Source\n```sh\ngit clone https://github.com/vosslab/qti_package_maker.git\ncd qti_package_maker\npip install -r requirements.txt\n```\n\n## Question Types\n\nQTI Package Maker supports seven essential question types commonly used in assessments. These include Multiple Choice (MC), Multiple Answer (MA), Matching (MATCH), Numerical Entry (NUM), Fill-in-the-Blank (FIB), Multi-Part Fill-in-the-Blank (MULTI_FIB), and Ordered Lists (ORDER). Below is an overview of each type and its required inputs.\n\n### Multiple Choice (MC)\n**Inputs:**\n- `question_text` (str): The question prompt.\n- `choices_list` (list): A list of answer choices.\n- `answer_text` (str): The correct answer.\n\n### Multiple Answer (MA)\n**Inputs:**\n- `question_text` (str)\n- `choices_list` (list)\n- `answers_list` (list): A list of correct answers.\n\n### Matching (MATCH)\n**Inputs:**\n- `question_text` (str)\n- `prompts_list` (list): Items to be matched.\n- `choices_list` (list): Possible matching answers.\n\n### Numerical Entry (NUM)\n**Inputs:**\n- `question_text` (str)\n- `answer_float` (float): The correct numerical answer.\n- `tolerance_float` (float): Accepted tolerance range.\n- `tolerance_message` (bool, default=True): Message for tolerance handling.\n\n### Fill-in-the-Blank (FIB)\n**Inputs:**\n- `question_text` (str)\n- `answers_list` (list): List of acceptable answers.\n\n### Multi-Part Fill-in-the-Blank (MULTI_FIB)\n**Inputs:**\n- `question_text` (str)\n- `answer_map` (dict): A dictionary mapping blank positions to correct answers.\n\n### Ordered List (ORDER)\n**Inputs:**\n- `question_text` (str)\n- `ordered_answers_list` (list): The correct sequence of answers.\n\n## Output Engines\n\nThe package supports multiple output formats via engines. Each engine corresponds to a specific QTI version or alternative export format.\n\n### QTI v1.2 Engine (Canvas QTI v1.2)\n- **Engine Name:** `canvas_qti_v1_2`\n- **Format Type:** QTI v1.2 (IMS XML format)\n- **Compatible LMS:** Canvas, LibreTexts ADAPT\n- **File Output:** ZIP file containing QTI v1.2 XML files\n\n### QTI v2.1 Engine (Blackboard QTI v2.1)\n- **Engine Name:** `blackboard_qti_v2_1`\n- **Format Type:** QTI v2.1 (IMS XML format)\n- **Compatible LMS:** Blackboard\n- **File Output:** ZIP file containing QTI v2.1 XML files\n\n### Human-Readable Engine\n- **Engine Name:** `human_readable`\n- **Format Type:** Simple text file\n- **Compatible LMS:** Any system that supports plain-text import\n- **File Output:** A structured text file listing the questions and answers in a human-readable format\n- **Use Case:** Used for reviewing questions before conversion to QTI\n\n### Blackboard Question Upload Engine\n- **Engine Name:** `bbq_text_upload`\n- **Format Type:** Blackboard-specific TXT upload format\n- **Compatible LMS:** Blackboard (Original Course View)\n- **Documentation:** https://help.blackboard.com/Learn/Instructor/Original/Tests_Pools_Surveys/Orig_Reuse_Questions/Upload_Questions\n- **File Output:** A `.txt` file that Blackboard can directly upload\n\n### HTML Self-Test Engine\n- **Engine Name:** `html_selftest`\n- **Format Type:** HTML-based self-assessment\n- **Compatible LMS:** Any web-based environment\n- **File Output:** A self-contained HTML file\n- **Use Case:** Used for creating self-assessment quizzes without LMS integration\n\n## Engines Capabilities\n\n### Read and Write\n\n| Engine Name         | Can Read   | Can Write   |\n|---------------------|------------|-------------|\n| bbq_text_upload     | \u2705         | \u2705          |\n| blackboard_qti_v2_1 | \u274c         | \u2705          |\n| canvas_qti_v1_2     | \u274c         | \u2705          |\n| html_selftest       | \u274c         | \u2705          |\n| human_readable      | \u274c         | \u2705          |\n| text2qti            | \u2705         | \u2705          |\n\n### Assessment Item Types\n\n| Item Type   | bbq text upload   | blackboard qti v2.1   | canvas qti v1.2   | html selftest   | human readable   | text2qti   |\n|-------------|-------------------|-----------------------|-------------------|-----------------|------------------|------------|\n| FIB         | \u2705                | \u2705                    | \u274c                | \u274c             | \u2705               | \u2705         |\n| MA          | \u2705                | \u2705                    | \u2705                | \u2705             | \u2705               | \u2705         |\n| MATCH       | \u2705                | \u274c                    | \u2705                | \u2705             | \u2705               | \u274c         |\n| MC          | \u2705                | \u2705                    | \u2705                | \u2705             | \u2705               | \u2705         |\n| MULTI_FIB   | \u2705                | \u274c                    | \u274c                | \u274c             | \u2705               | \u274c         |\n| NUM         | \u2705                | \u274c                    | \u274c                | \u274c             | \u2705               | \u2705         |\n| ORDER       | \u2705                | \u274c                    | \u274c                | \u274c             | \u2705               | \u274c         |\n\n## Usage\n\n### Primary Supported Input Format\n\nThe **Blackboard Question Upload (BBQ) text format** is currently the only supported input format for `qti_package_maker`. This format allows users to write questions in a plain text file and upload them into tests, surveys, and question pools on Blackboard. Once uploaded, the questions can be edited and used like those created directly within the LMS.\n\n### BBQ File Format Guidelines\n- Must be a **tab-delimited TXT file**.\n- Should **not include a header row**.\n- Should **not contain blank lines**.\n- New lines characters cannot exist within the question.\n- Each row must contain **one question**.\n- The **first field in each row** defines the question type.\n- Fields in a row are **separated by a TAB**.\n\n### Supported BBQ Question Formats\n\n| Question Type        | Format |\n|----------------------|--------|\n| **Multiple Choice (MC)** | ``MC TAB question text TAB answer text TAB correct\\|incorrect TAB answer two text TAB correct\\|incorrect`` |\n| **Multiple Answer (MA)** | ``MA TAB question text TAB answer text TAB correct\\|incorrect TAB answer two text TAB correct\\|incorrect`` |\n| **Ordering (ORD)** | `ORD TAB question text TAB answer text TAB answer two text` |\n| **Matching (MAT)** | `MAT TAB question text TAB answer text TAB matching text TAB answer two text TAB matching two text` |\n| **Fill in the Blank (FIB)** | `FIB TAB question text TAB answer text TAB answer two text` |\n| **Fill in Multiple Blanks (FIB_PLUS)** | `FIB_PLUS TAB question text TAB variable1 TAB answer1 TAB answer2 TAB TAB variable2 TAB answer3` |\n| **Numeric Response (NUM)** | `NUM TAB question text TAB answer TAB [optional]tolerance` |\n\nFor more details, refer to the official **[Blackboard documentation](https://help.blackboard.com/Learn/Instructor/Original/Tests_Pools_Surveys/Orig_Reuse_Questions/Upload_Questions)**.\n\n## BBQ Converter Command Options\n\nThe `bbq_converter.py` tool allows converting BBQ text files into multiple output formats. Example usage:\n```sh\npython3 tools/bbq_converter.py -i bbq-my_questions.txt -f qti12\n```\nTo convert into all available formats:\n```sh\npython3 tools/bbq_converter.py -i bbq-my_questions.txt --all\n```\n\nFor available options, use:\n```sh\npython3 tools/bbq_converter.py -h\n```\n\n### Complete BBQ Converter Options\n```sh\nusage: bbq_converter.py [-h] -i INPUT_FILE [-n QUESTION_LIMIT] [--allow-mixed]\n                        [-f {canvas_qti_v1_2,blackboard_qti_v2_1,human_readable,bbq_text_upload,html_selftest}] [-a]\n                        [-1 [OUTPUT_FORMAT]] [-2 [OUTPUT_FORMAT]] [-r [OUTPUT_FORMAT]] [-b [OUTPUT_FORMAT]] [-s [OUTPUT_FORMAT]]\n\nConvert BBQ file to other formats.\n\noptions:\n  -h, --help            show this help message and exit\n  -i INPUT_FILE, --input INPUT_FILE, --input_file INPUT_FILE\n                        Path to the input BBQ text file.\n  -n QUESTION_LIMIT, --limit QUESTION_LIMIT, --question_limit QUESTION_LIMIT\n                        Limit the number of input items.\n  --allow-mixed         Allow mixed question types.\n  -f {canvas_qti_v1_2,blackboard_qti_v2_1,human_readable,bbq_text_upload,html_selftest}, --format {canvas_qti_v1_2,blackboard_qti_v2_1,human_readable,bbq_text_upload,html_selftest}\n                        Set output format (multiple allowed).\n  -a, --all             Enable all output formats.\n  -1 [OUTPUT_FORMAT], --qti12 [OUTPUT_FORMAT]\n                        Set output format to Canvas QTI v1.2.\n  -2 [OUTPUT_FORMAT], --qti21 [OUTPUT_FORMAT]\n                        Set output format to Blackboard QTI v2.1.\n  -r [OUTPUT_FORMAT], --human [OUTPUT_FORMAT]\n                        Set output format to human-readable text.\n  -b [OUTPUT_FORMAT], --bbq [OUTPUT_FORMAT]\n                        Set output format to Blackboard Question Upload format.\n  -s [OUTPUT_FORMAT], --html [OUTPUT_FORMAT]\n                        Set output format to HTML self-test.\n```\n\n## Python API Usage\n\n### Creating an Assessment Package\n\n```python\nfrom qti_package_maker.package_interface import QTIPackageInterface\n\n# Initialize the package with a name\nqti_packer = QTIPackageInterface(\"example_assessment\", verbose=True)\n\n# Add a multiple-choice question\nqti_packer.add_item(\"MC\", (\"What is your favorite color?\", [\"blue\", \"red\", \"yellow\"], \"blue\"))\n\n# Add a multiple-answer question\nqti_packer.add_item(\"MA\", (\"Which of these are fruits?\", [\"apple\", \"carrot\", \"banana\", \"broccoli\"], [\"apple\", \"banana\"]))\n```\n\n#### Saving the Package\n```python\n# Save as Canvas QTI v1.2\nqti_packer.save_package(\"canvas_qti_v1_2\")\n\n# Save as Blackboard QTI v2.1\nqti_packer.save_package(\"blackboard_qti_v2_1\")\n``````\nThis will create a Blackboard-compatible QTI v2.1 ZIP file.\n\n## Development & Contribution\n\nContributions are welcome! Follow these steps to contribute:\n\n1. **Fork** the repository on GitHub.\n2. **Clone** your forked repository:\n   ```sh\n   git clone https://github.com/YOUR_USERNAME/qti_package_maker.git\n   cd qti_package_maker\n   ```\n3. **Create a feature branch** (`feature-my-update`):\n   ```sh\n   git checkout -b feature-my-update\n   ```\n4. **Make your changes** and commit them:\n   ```sh\n   git add .\n   git commit -m \"Describe your changes here\"\n   ```\n5. **Push** to your fork and open a **Pull Request**:\n   ```sh\n   git push origin feature-my-update\n   ```\n   - Navigate to the **Pull Requests** section of the original repository on GitHub.\n   - Click **New Pull Request** and select your branch.\n   - Provide a clear description of your changes and submit the request.\n\n## Roadmap and Planned Features\n- Improve error handling and validation\n- Add question randomization and shuffling\n- Add unit tests\n\n## Related Projects\n\n- **Moodle Question Format: Canvas**  \n  A Moodle plugin that imports questions exported from the Canvas LMS as an XML file into Moodle.  \n  GitHub: https://github.com/jmvedrine/moodle-qformat_canvas\n\n- **text2qti**  \n  A Python tool that converts Markdown-based plain text files into quizzes in QTI format, compatible with Canvas and other educational software.  \n  PyPI: https://pypi.org/project/text2qti/\n\n- **Blackboard Test Question Generator**  \n  An online tool that assists in creating test questions for Blackboard by converting plain text into a format suitable for import.  \n  Website: https://ed.oc.edu/blackboardquizgenerator/\n\n- **amc2moodle**  \n  A Python package that facilitates the conversion of AMC (Auto Multiple Choice) formatted questions into Moodle XML format for easy import.  \n  PyPI: https://pypi.org/project/amc2moodle/\n\n- **moodle-questions**  \n  A Python library designed for manipulating questions in Moodle XML format, enabling programmatic creation and modification of Moodle quizzes.  \n  GitHub: https://github.com/gethvi/moodle-questions\n\n- **pyAssignment**  \n  A Python module for authoring and assessing homework assignments, with capabilities to output assignments to LaTeX and Blackboard quiz formats.  \n  PyPI: https://pypi.org/project/pyassignment/\n\n## License\n\nCopyright &copy; 2025, Dr. Neil Voss\n\nqti_package_maker is free software: you can redistribute it and/or modify it under\nthe terms of the GNU General Public License as published by the Free\nSoftware Foundation, either version 3 of the License, or any later version.\n\nqti_package_maker is distributed in the hope that it will be useful, but WITHOUT\nANY WARRANTY; without even the implied warranty of MERCHANTABILITY or\nFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for\nmore details.\n\nSee the full license details in the \n[LICENSE file](https://github.com/vosslab/qti_package_maker/blob/main/LICENSE).\nIf not, see <http://www.gnu.org/licenses/>.\n\n## Support this project\n\n<!-- setup on Feb 28, 2025 -->\n- **Bitcoin:** [Donate with Bitcoin](bitcoin:bc1qdexkqwzyet93ret40akqmms2jv99wvsgzdshu8?message=support%20qti_package_maker)\n- **Dash:** [Donate with Dash](dash:XdDmwBVecEy9yyXKeD7hScLp7oN8rd4XNV?message=support%20qti_package_maker)\n- **Patreon:** [Support on Patreon](https://www.patreon.com/vosslab)\n- **Paypal:** [Donate via PayPal](https://paypal.me/vosslab)\n\n## Social Media links\n\n- [YouTube](https://www.youtube.com/neilvosslab)\n- [Github](https://github.com/vosslab)\n- [Bluesky](https://bsky.app/profile/neilvosslab.bsky.social)\n- [Facebook](https://fb.me/neilvosslab)\n- [LinkedIn](https://www.linkedin.com/in/vosslab)\n\n\n## Acknowledgments\n- Based on the IMS Global QTI specification\n- Inspired by the need for cross-platform assessment portability\n- Developed to improve e-learning content interoperability\n- Funding for production from Illinois Library OER grant\n\n\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A package to create, manage, and convert QTI packages for quizzes and assessments in Canvas, Blackboard, Moodle, and LibreTexts ADAPT.",
    "version": "0.8.6",
    "project_urls": {
        "Homepage": "https://biologyproblems.org",
        "PyPI": "https://pypi.org/project/qti-package-maker/",
        "Repository": "https://github.com/vosslab/qti_package_maker"
    },
    "split_keywords": [
        "qti",
        " quiz",
        " assessment",
        " test package",
        " canvas",
        " blackboard",
        " moodle",
        " libretexts adapt",
        " e-learning",
        " lms",
        " question bank",
        " quiz converter",
        " online learning",
        " exam generator",
        " qti exporter",
        " ims question and test interoperability specification",
        " question and test interoperability",
        " xml",
        " qti v2.1",
        " qti v1.2"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "3db0c1d22f023877bb369dae6a037bb5f18673fcb2492eaef7a80fb3daef50d1",
                "md5": "cc4028453e4e90debb531e0ae4ba8f42",
                "sha256": "24c410441eb4a7df1a9ef5a439452829a027c2cab37d42d29255d4d4470685bb"
            },
            "downloads": -1,
            "filename": "qti_package_maker-0.8.6-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "cc4028453e4e90debb531e0ae4ba8f42",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 91401,
            "upload_time": "2025-03-29T00:41:36",
            "upload_time_iso_8601": "2025-03-29T00:41:36.921279Z",
            "url": "https://files.pythonhosted.org/packages/3d/b0/c1d22f023877bb369dae6a037bb5f18673fcb2492eaef7a80fb3daef50d1/qti_package_maker-0.8.6-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "3ca803390c32a45d23f752822643afd353852b91eae9c84fb1f6084a4cd1b5ee",
                "md5": "e5ae010e84dc6000deaf6d37ef0d7631",
                "sha256": "ff62666174942b4bfeb8aa0eae5d9ea11cb277933e0e1cc6bdb48ea1c7b9e16a"
            },
            "downloads": -1,
            "filename": "qti_package_maker-0.8.6.tar.gz",
            "has_sig": false,
            "md5_digest": "e5ae010e84dc6000deaf6d37ef0d7631",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 86969,
            "upload_time": "2025-03-29T00:41:38",
            "upload_time_iso_8601": "2025-03-29T00:41:38.295547Z",
            "url": "https://files.pythonhosted.org/packages/3c/a8/03390c32a45d23f752822643afd353852b91eae9c84fb1f6084a4cd1b5ee/qti_package_maker-0.8.6.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-03-29 00:41:38",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "vosslab",
    "github_project": "qti_package_maker",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "requirements": [
        {
            "name": "lxml",
            "specs": []
        },
        {
            "name": "crcmod",
            "specs": []
        },
        {
            "name": "num2words",
            "specs": []
        },
        {
            "name": "pyyaml",
            "specs": []
        },
        {
            "name": "tabulate",
            "specs": []
        }
    ],
    "lcname": "qti-package-maker"
}
        
Elapsed time: 1.94193s