Skip to main content

iliasqc

PyPI version conda-forge version Tests License: MIT Dependabot

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:

  1. Create separate zip files for each point value found in your questions
  2. Find all valid combinations that sum to 20 points
  3. Display a table showing the combinations ranked by balance
  4. 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)

Source distribution for iliasqc 0.1.2
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)

Table of built distributions (wheels) for iliasqc 0.1.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page