Metadata-Version: 2.1
Name: pyexams
Version: 0.2.0
Summary: Generates variants of exam questions using texsurgery, keeps a question database, exports to pdf and moodle
Home-page: https://framagit.org/pang/pyexams
Author: Pablo Angulo
Author-email: pablo.angulo@upm.es
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: texsurgery
Requires-Dist: amc2moodle
Requires-Dist: pydal
Requires-Dist: appdirs

# pyexams

Generates variants of exam questions using [texsurgery](https://framagit.org/pang/texsurgery), keeps a question database, exports to pdf and moodle.

Much like [R exams](https://r-exams.org/), but with the following (main) differences:

 1. R-`exams` requires use of R for both creating exam variants and managing R-`exams` itself, while `pyexams` allows any language for exam creation and is called from a command which can be incorporated into your favorite LaTeX editor.
 2. R-`exams` keeps each question in a separate file, then use a simple R script to compose the whole exam, while `pyexams` use a single LaTeX file for the whole exam.
 3. Both R-`exams` and `pyexams` keep a record of past exam questions, but `pyexams` also keeps a database that can be queried in order to find, for instance, all questions with the tag `derivative` that appeared in exams at least two years ago. The question code is also saved in plain text and managed in a `git` repository, which simplifies the management of a shared question bank, whether group-private or totally open.
 4. Last but not least, R-`exams` is a mature and feature rich project, while `pyexams` is a very young project that still has to deliver.

Other important design decisions involved in `pyexams`:

 - The syntax for the questions is exactly that of [auto-multiple-choice](https://www.auto-multiple-choice.net/)
 - We will use [amc2moodle](https://github.com/nennigb/amc2moodle) (or a custom version of it) to generate the moodle question bank.
 - `pyexams` strives to feel as close to LaTeX as possible to its users, which paradoxically is better done through [texsurgery](https://framagit.org/pang/texsurgery) than through a LaTeX package.

## Warning: Alpha version

This is still an early version. Use with care.

## Installation

    python3 -m pip install pyexams

## Usage

```bash
cd examples
# generates a pdf for the first student in the list (useful for testing)
pyexams amc2moodle.tex
# generates one pdf for each first student in the list (runs in parallel)
pyexams amc2moodle.tex -all
# generates two pdf files for each first student in the list (runs in parallel)
#  one with the exam statement
#  other with the correct answer and an explanation
pyexams amc2moodle.tex -all -both
# generates a moodle question bank
pyexams amc2moodle.tex -moodle  
# generates a moodle question bank with exactly 5 variants of each question
pyexams amc2moodle.tex -moodle -n 5
```

## How to use

### Moodle short questions

  1. Start with a template from the `examples` folder, make a copy, edit it.
  2. Use `pyexams your_source_file.tex` to test quickly if your code works.
  3. When happy with the result, run `pyexams your_source_file.tex -moodle -n 5` to generate a moodle question bank with exactly 5 variants of each question.
  4. Inspect `your_source_file.xml` for obvious errors.
  5. If the file looks fine, try to upload to *moodle*.

### Long written answer
  1. Start with a template from the `examples` folder, make a copy, edit it.
  2. Edit `students.csv` with the real data of your students.
  3. Use `pyexams your_source_file.tex` to test quickly if your code works.
  4. When happy with the results, run `pyexams your_source_file.tex -all -both` to generate two pdf files for each first student in the list:
    - one with the exam statement.
    - other with the correct answer and an explanation.
  5. Distribute the exam statements at the date and time of the exam.
  6. Collect the students' solutions using a *moodle task* or any similar tool.
  7. Distribute the exam solutions at the end of the exam.

We suggest two ways to distribute the exam statements:
  - Through moodle:
    1. Prepare a *moodle folder* activity in advance
    2. Prepare mock pdf files with the same filenames as the real exam statements.
    3. Zip all the mock exams into a single file, which you can upload to moodle and unzip to deliver all the mock exams quickly.
    4. Instruct your students to download the mock exam, as a check.
    5. At the date and time of the exam, upload a zip with the real exam stataments, and unzip it to replace the mock exams.
  - Through email (*coming soon*):
    1. `pyexams -deliver question template_file` will send an email to each student with the exam statement
    2. `pyexams -deliver solution template_file` will send an email to each student with the exam solution
    3. `pyexams -deliver correction template_file` will send an email to each student with an attachment taken from a `correction` folder, with the teacher's comments to each exam (could be any other file).

## Talk at ENSEMAT II

The motivation behind this project and its design decision was presented (in spanish) at a talk at [ENSEMAT II](https://eventos.upm.es/56532/detail/ensemat-2020.-usos-y-avances-en-la-docencia-de-las-matematicas-en-las-ensenanzas-universitarias.html)

 - [Slides for the talk (in spanish)](https://dcain.etsin.upm.es/~pablo/etc/ENSEMATII_sobre_pyexams/pyexams.html)


