edutools-moodle 0.1.0

Python package for Moodle API interactions in educational contexts

Edutools Moodle

Python package for interacting with Moodle Web Services API in educational contexts.

Installation

From source (development mode)

git clone https://github.com/najasoft/edutools-moodle.git
cd edutools-moodle
pip install -e .

From PyPI (when published)

pip install edutools-moodle

Quick Start

from edutools_moodle import MoodleAPI

# Initialize the API client
moodle = MoodleAPI(
    moodle_url="https://your-moodle-instance.com",
    token="your_webservice_token"
)

# Get groups for a course
groups = moodle.get_course_groups(course_id=123)

# Add a user to a group
moodle.add_user_to_group(group_id=1, user_id=42)

# Create a new group
moodle.create_group(course_id=123, group_name="Group A")

Features

• ✅ Groups Management: Create, list, add/remove users
• ✅ Cohorts Management: Check user membership
• ✅ Assignments: Retrieve and manage assignments
• ✅ Grades: Fetch and update grades
• ✅ Base API Client: Extensible for additional Moodle functions

Requirements

• Python 3.8+
• Moodle 3.9+ (recommended, see version compatibility)
• Moodle instance with Web Services enabled
• Valid Moodle API token

Configuration

Generating a Moodle Token

1. Log in to Moodle as administrator
2. Go to Site Administration → Plugins → Web Services → Manage Tokens
3. Create a new token for your user
4. Copy the token string

Checking Moodle Version

from edutools_moodle import MoodleAPI

moodle = MoodleAPI("https://your-moodle.com", "token")

# Get site information
info = moodle.get_site_info()
print(f"Moodle version: {info['release']}")
print(f"Site name: {info['sitename']}")

# Check if version is compatible
if moodle.check_moodle_version("3.9"):
    print("✅ Moodle version is compatible")
else:
    print("⚠️ Moodle 3.9+ recommended")

API Reference

MoodleAPI (Facade)

Main class providing unified access to all modules.

__init__(moodle_url: str, token: str, timeout: int = 30, logger: Optional[Logger] = None)

Initialize the Moodle API client.

Parameters:

• moodle_url - Base URL of Moodle instance
• token - Web service token for authentication
• timeout - Request timeout in seconds (default: 30)
• logger - Optional logger instance (if not provided, uses default logging)

Modules:

• moodle.groups - Groups, groupings, and cohorts
• moodle.users - User management
• moodle.assignments - Assignments and submissions
• moodle.grades - Grade management

get_site_info() -> dict

Get Moodle site information including version.

check_moodle_version(min_version: str) -> bool

Check if Moodle version meets minimum requirement.

Modules:

• moodle.groups - Groups, groupings, and cohorts
• moodle.users - User management
• moodle.assignments - Assignments and submissions
• moodle.grades - Grade management

Groups Module (moodle.groups)

get_course_groups(course_id: int) -> list

Get all groups in a course.

add_user_to_group(group_id: int, user_id: int) -> dict

Add a user to a group.

remove_user_from_group(group_id: int, user_id: int) -> dict

Remove a user from a group.

create_group(course_id: int, group_name: str, description: str = "") -> dict

Create a new group in a course.

is_user_in_cohort(user_id: int, cohort_name: str) -> bool

Check if a user belongs to a specific cohort.

enroll_user_in_cohort(user_id: int, cohort_name: str) -> bool

Enroll a user in a cohort.

Users Module (moodle.users)

create_user(username, password, firstname, lastname, email, ...) -> int

Create a new user account.

check_username_exists(username: str) -> bool

Check if username already exists.

enroll_user_in_course(course_id, user_id, role_id=5) -> bool

Enroll a user in a course.

send_notification(user_id, subject, message) -> bool

Send a notification to a user.

Assignments Module (moodle.assignments)

get_assignments(course_id: int) -> list

Get all assignments in a course.

get_assignment_submissions(assignment_id: int) -> list

Get all submissions for an assignment.

Grades Module (moodle.grades)

update_grade(assignment_id, user_id, grade, feedback="") -> dict

Update a grade for a user's assignment.

Development

Running Tests

pip install pytest
pytest tests/

Project Structure

edutools-moodle/
├── edutools_moodle/
│   ├── __init__.py
│   ├── base.py           # Base API client
│   ├── api.py            # Main MoodleAPI class
│   ├── groups.py         # Groups management
│   ├── assignments.py    # Assignments handling
│   └── grades.py         # Grades management
├── tests/
│   ├── __init__.py
│   └── test_api.py
├── setup.py
├── requirements.txt
└── README.md

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.