Metadata-Version: 2.4
Name: moodle-tools
Version: 1.0.0
Summary: A collection of tools to simplify working with Moodle quizzes.
Project-URL: Homepage, https://git.tu-berlin.de/dima/moodle-tools
Project-URL: Repository, https://git.tu-berlin.de/dima/moodle-tools
Project-URL: Documentation, https://dima.gitlab-pages.tu-berlin.de/moodle-tools
Project-URL: Bug Tracker, https://git.tu-berlin.de/dima/moodle-tools/-/issues
Author-email: Lennart Behme <lennart.behme@tu-berlin.de>, Gereon Dusella <gereon.dusella@tu-berlin.de>, Ricardo Ernesto Martinez Ramirez <r.martinez.ramirez@tu-berlin.de>, Viktor Rosenfeld <viktor.rosenfeld@tu-berlin.de>
Maintainer-email: The ISDA Team <isda@dima.tu-berlin.de>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: moodle,teaching
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: asteval~=1.0
Requires-Dist: jinja2~=3.1
Requires-Dist: loguru~=0.7.0
Requires-Dist: markdown~=3.4
Requires-Dist: pyyaml~=6.0
Provides-Extra: dev
Requires-Dist: duckdb==1.2.1; extra == 'dev'
Requires-Dist: isda-streaming==1.2.0; extra == 'dev'
Requires-Dist: mypy~=1.13; extra == 'dev'
Requires-Dist: pdoc~=15.0; extra == 'dev'
Requires-Dist: pre-commit~=4.0; extra == 'dev'
Requires-Dist: pytest-cov~=6.0; extra == 'dev'
Requires-Dist: pytest~=8.3; extra == 'dev'
Requires-Dist: sqlparse~=0.5.0; extra == 'dev'
Requires-Dist: types-markdown~=3.4; extra == 'dev'
Requires-Dist: types-pyyaml~=6.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: pdoc~=15.0; extra == 'docs'
Provides-Extra: isda
Requires-Dist: duckdb==1.2.1; extra == 'isda'
Requires-Dist: isda-streaming==1.2.0; extra == 'isda'
Requires-Dist: sqlparse~=0.5.0; extra == 'isda'
Provides-Extra: test
Requires-Dist: duckdb==1.2.1; extra == 'test'
Requires-Dist: isda-streaming==1.2.0; extra == 'test'
Requires-Dist: pytest-cov~=6.0; extra == 'test'
Requires-Dist: pytest~=8.3; extra == 'test'
Requires-Dist: sqlparse~=0.5.0; extra == 'test'
Description-Content-Type: text/markdown

# Moodle Tools

This repository contains a collection of tools to simplify working with Moodle quizzes.

## Tools

- `make-questions`: Generate Moodle quiz questions from simple YAML documents to minimize the use of the web interface.
- `analyze-results`: Analyze the results of a Moodle quiz to improve question quality.

## Installation

`moodle-tools` is distributed as a Python package.
You can install it from PyPI using `pip`:

```bash
pip install moodle-tools
```

### Local Installation

Either clone the repository:

```bash
git clone https://git.tu-berlin.de/dima/moodle-tools
cd moodle-tools
virtualenv venv
source venv/bin/activate
pip install .
```

Or directly install it from GitLab:

```bash
pip install git+https://git.tu-berlin.de/dima/moodle-tools
```

### Optional Question Types

Specialized question types that require additional dependencies are not installed by
default. To use them, you need to install the respective dependency group with
`pip install "moodle-tools[GROUPNAME]"`. The following groups are available:

- `isda`: Adds support for `CoderunnerDDLQuestion`, `CoderunnerDQLQuestion`, and `CoderunnerStreamingQuestion` questions.

For example, to install the `isda` questions execute:

```bash
pip install "moodle-tools[isda]"
```

## Usage

Once installed, you can access the tools as Python modules or via their command line
interface.

```python
from moodle_tools import make_questions, analyze_results
```

```bash
make-questions -h
analyze-results -h
```

## Documentation

The [API documentation](https://dima.gitlab-pages.tu-berlin.de/moodle-tools) of
`moodle-tools` is hosted on GitLab pages.

## Contributing

If you want to contribute a bug fix or feature to `moodle-tools`, please open an issue
first to ensure that your intended contribution aligns with the project.

Different to a user installation, you also need to install the `dev` requirements and
activate `pre-commit` in your copy of the repository before making a commit.

```bash
# Activate your virtual environment first
pip install -e ".[dev]"
pre-commit install
```

The source code for Moodle's XML parser is located [here](https://github.com/moodle/moodle/tree/main/question/format/xml)
in case we need to reverse engineer behavior changes.
