python-moodle¶

A modern Pythonic CLI and library to manage Moodle via web sessions, with full session and CAS support.

Experimental

This library is under active development. Use a test Moodle instance and back up data before running commands that create, modify, or delete content.

py-moodle allows you to automate tedious Moodle tasks—like creating courses, uploading content, and managing modules—directly from your terminal or in your Python scripts. It works by simulating a real user's web session, so it doesn't require API tokens or special Moodle plugins.

Features¶

Manage Moodle entities: Courses, sections, users, and modules from the command line.
Rich module support: Includes built-in support for Folders, Labels, Assignments, and SCORM packages.
Session-based: Works with standard Moodle web sessions, avoiding the need for web service tokens.
Authentication: Supports standard Moodle login and SSO/CAS authentication.
Dual Use: Can be used as a powerful CLI or imported as a library into your own Python projects.
Extensible: Designed to be easily extended with new modules and commands. See AGENTS.md.
English-only codebase: For clear, global collaboration.

Installation¶

You will need Python 3.8+ and pip.

Install from PyPI (Recommended)¶

pip install python-moodle

Install from Source¶

Clone the repository and install:

git clone https://github.com/erseco/python-moodle.git
cd python-moodle
pip install .

Configure your environment¶

Copy the example .env.example file to .env and add your Moodle instance credentials.

cp .env.example .env
# Now, edit the .env file with your credentials

Danger

The .env file stores real credentials. Keep it out of version control and share it with no one.

Your .env file should look like this:

# Production environment credentials
MOODLE_PROD_URL=https://your.moodle.site
MOODLE_PROD_USERNAME=your_admin_user
MOODLE_PROD_PASSWORD=your_super_secret_password
# Optional: CAS SSO URL
# MOODLE_PROD_CAS_URL=https://cas.your-institution.org/cas
# Optional: Predefined webservice token (required for CAS)
# MOODLE_PROD_WS_TOKEN=your_webservice_token

Use the --env flag or the MOODLE_ENV variable to select the environment, e.g. py-moodle --env prod courses list.

Note: For local development, you can quickly spin up a Moodle instance using the provided docker-compose.yml: docker-compose up -d.

CLI Usage¶

Once installed, all functionality is available through the py-moodle command. Every command and subcommand includes detailed help with the -h or --help flag.

Common Commands¶

Here are a few examples of common commands:

List all available courses:

py-moodle courses list

Output:

┏━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┓
┃ ID ┃ Shortname          ┃ Fullname           ┃ Category ┃ Visible ┃
┡━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━┩
│ 2  │ my-first-course    │ My first course    │ 1        │ 1       │
│ 4  │ my-second-course   │ My second course   │ 1        │ 1       │
└────┴────────────────────┴────────────────────┴──────────┴─────────┘

Show the structure of a single course:

py-moodle courses show 2

Create a new course:

py-moodle courses create --fullname "My New Automated Course" --shortname "auto-course-01"

Add a label to a course section:

py-moodle modules add label --course-id 2 --section-id 1 --name "Welcome" --intro "<h1>Welcome to the course!</h1>"

Upload a SCORM package to a course:

py-moodle modules add scorm --course-id 2 --section-id 1 --name "My SCORM Package" --path "path/to/your/scorm.zip"

Library Usage (Automation Scripting)¶

You can also import py-moodle's functions into your own Python scripts to automate complex workflows. The example_script.py file provides a comprehensive tutorial.

Quick Example¶

from py_moodle import MoodleSession
from py_moodle.course import list_courses

# Credentials are loaded automatically from your .env file
ms = MoodleSession.get()
courses = list_courses(ms.session, ms.settings.url, token=ms.token)
for course in courses:
    print(course["id"], course["fullname"])

How the Example Script Works¶

The script is a self-contained demonstration that:

Logs into Moodle using the credentials from your .env file.
Creates a new, temporary course.
Populates the course with sections, labels, assignments, and a SCORM package.
Creates a folder and uploads multiple files to it.
Prints a summary of the final course structure.
Automatically cleans up and deletes the course and all its contents.

Running the Example¶

Make sure you have a valid .env file and have installed the dependencies. Then, simply run:

python example_script.py

This script is the best starting point for understanding how to use the library's functions for your own automation needs.

Testing¶

The project uses pytest and provides a Makefile with convenient targets.

Run the default test suite against the local environment:

make test-local

Run tests against the staging environment:

make test-staging

Run all configured environments:

make test

Development¶

Use the Makefile to format code, run linters, or build the documentation:

make format   # run black and isort
make lint     # run static analysis
make docs     # build the MkDocs site

Documentation¶

Documentation is generated with MkDocs using the Read the Docs theme and published automatically to the gh-pages branch. Every push to main builds the API reference and CLI guide from the source code and makes it available via GitHub Pages.

To build the documentation locally:

pip install mkdocs 'mkdocstrings[python]'
mkdocs build --strict

The rendered site will be available under the site/ directory.

Contribution¶

Contributions are welcome! Please follow the guidelines outlined in [AGENTS.md]. Key principles include:

All code, comments, and documentation must be in English.
Code must be formatted with black and linted with flake8.
Docstrings must use the Google style; flake8-docstrings is configured for this convention.
The CLI should be a thin layer over the core library functions.
All new features must be accompanied by tests.

License¶

This project is licensed under the MIT License.