iliasqc
Python package to convert structured text files into ILIAS-compatible question pool zip archives. Supports single/multiple choice and gap-fill question types, plus automated quiz combination generation.
This package is based on Kaffeedrache/Tiqi.
Features
- Multiple question types: Single choice, multiple choice, and gap-fill questions
- QTI 1.2 compliant: Generates ILIAS-compatible XML format
- Python API: Use programmatically in your Python code
- CLI tool: Convert files from the command line
- Quiz combinations: Generate multiple pools and find optimal combinations to reach target point totals
Installation
pip
pip install iliasqc
conda / mamba (conda-forge)
conda install -c conda-forge iliasqc
# or
mamba install -c conda-forge iliasqc
Question File Format
Questions are defined in .txt files with special syntax:
# TITLE: My Question Pool
# DESCRIPTION: A collection of questions
[t][s] Single Choice Question @1
Question text goes here.
_ Correct answer
- Incorrect answer
- Another wrong answer
[t][m] Multiple Choice Question @2
Which options are correct?
- Wrong answer
_ Correct answer 1
_ Correct answer 2
- Wrong again
[t][g] Gap-Fill Question @1
The capital of France is [gap]Paris[/gap].
The capital of Germany is [gap]Berlin[/gap].
Syntax Reference
| Marker | Description |
|---|---|
[t] |
Question start marker (required) |
[s] |
Single choice question |
[m] |
Multiple choice question |
[g] |
Gap-fill question |
_ |
Correct answer (for MC questions) |
- |
Incorrect answer (for MC questions) |
[gap]...[/gap] |
Gap to fill |
@N |
Points for the question (e.g., @2) |
# TITLE: |
Pool title metadata |
# DESCRIPTION: |
Pool description metadata |
Usage
Command Line
Convert a question file to ILIAS zip archive:
iliasqc convert questions.txt
Specify custom output path:
iliasqc convert questions.txt -o my_pool.zip
Override title and description:
iliasqc convert questions.txt -t "My Pool" --description "My description"
Filter questions by point value:
iliasqc convert questions.txt -p 2
Quiz Combinations
Generate multiple pools (one per point value) and find combinations to reach a target:
iliasqc combine questions.txt -t 20
This will:
- Create separate zip files for each point value found in your questions
- Find all valid combinations that sum to 20 points
- Display a table showing the combinations ranked by balance
- Export a CSV file with the combinations
Options:
-t, --target: Target total points (required)-o, --output: Output directory (default: same as input file)-c, --combinations: Maximum number of combinations to show (default: 10)--csv-only: Only output CSV, skip the table display
Example output:
Quiz Combinations for 20.0 Points
======================================================================
Available Pools:
- My Pool (5 points): 8 questions
- My Pool (4 points): 12 questions
- My Pool (2 points): 15 questions
──────────────────────────────────────────────────────────────────────
Rank Questions Balance Combination
──────────────────────────────────────────────────────────────────────
1 5 ●●●● 2x My Pool (5 points) + 5x My Pool (2 points)
2 4 ●●●○ 5x My Pool (4 points)
3 6 ●●●○ 3x My Pool (4 points) + 5x My Pool (2 points)
──────────────────────────────────────────────────────────────────────
Tip: Lower balance score = more diverse quiz
Generated 3 pools:
- My Pool_2pt_pool.zip: 15 questions
- My Pool_4pt_pool.zip: 12 questions
- My Pool_5pt_pool.zip: 8 questions
Python API
from iliasqc import txt_to_zip
# Convert to ILIAS zip archive
output_path = txt_to_zip("questions.txt")
print(f"Created: {output_path}")
Quiz Combination API
from iliasqc import (
generate_quiz_combinations,
generate_pools_by_points,
find_combinations,
format_combinations_table,
export_combinations_csv,
)
# Generate pools and find combinations (full pipeline)
pools, combinations = generate_quiz_combinations(
"questions.txt",
target_points=20,
output_dir=".",
)
# Or use individual functions
pools = generate_pools_by_points("questions.txt")
combinations = find_combinations(pools, target_points=20)
# Format as a text table
table = format_combinations_table(combinations, pools, target_points=20)
print(table)
# Export to CSV
csv_path = export_combinations_csv(".", combinations, target_points=20)
Development
git clone https://github.com/famosab/iliasqc.git
cd iliasqc
pip install -e ".[dev]"
Running Tests
Run all tests:
pytest tests/
Run with coverage:
pytest tests/ --cov=iliasqc --cov-report=term-missing
Code Quality
Run linting checks:
ruff check src/ tests/
ruff format --check src/ tests/
Fix linting issues automatically:
ruff check --fix src/ tests/
ruff format src/ tests/
Manual Testing
Create a local Python 3.12+ environment, install the package, and generate sample zip files for manual ILIAS import testing:
conda create -n iliasqc python=3.12 -y
conda activate iliasqc
pip install -e .
python manual_test.py
This generates all sample question pools as .zip files in manual_test_output/, ready to upload to ILIAS. It covers all commands: convert, --title/--description overrides, --points filtering, and combine with different target point totals.
Continuous Integration
The project uses GitHub Actions for automated testing. The CI pipeline runs on every push and pull request, testing against Python 3.12, 3.13, and 3.14.
License
MIT – see LICENSE.
Metadata
Release files for iliasqc 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iliasqc-0.1.2.tar.gz | 22.8 kB | With provenance | Details for iliasqc-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iliasqc-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for iliasqc-0.1.2-py3-none-any.whl |
Total release size: 40.8 kB
Release files / iliasqc-0.1.2.tar.gz
| Download URL | iliasqc-0.1.2.tar.gz |
|---|---|
| Size | 22.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e3a6e1310868cb4263fbd05dd96d6ac4af0bad4f33e05c8cb67d817845812b4d
|
|
BLAKE2b-256 checksum How to use checksums |
1f0e43c9db594c635c465eabbb7e3fe991aab17d11b6b5bf1fe1d5f550f494f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logRelease files / iliasqc-0.1.2-py3-none-any.whl
| Download URL | iliasqc-0.1.2-py3-none-any.whl |
|---|---|
| Size | 18.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cfdd09994e93c243cc2429f9aa2ee71fea1d61560fec65f95db6608f534e8d71
|
|
BLAKE2b-256 checksum How to use checksums |
a553016ac49658c5887d8640a58766d1ff0f5941dc42960944c3b284b3e7a6ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logSecurity for iliasqc 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for iliasqc-0.1.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.