# 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 © 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 © 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"
}
JSON
