edutools-moodle 0.2.0

Python package for Moodle API interactions in educational contexts

Edutools Moodle

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

Version 0.2.0 - Stable release with comprehensive bug fixes and optimizations.

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, update, delete groups; manage members, groupings, and cohorts (20 functions)
• ✅ Users Management: Create users, check existence, enroll in courses, send notifications (7 functions)
• ✅ Assignments Management: Retrieve assignments and submissions with optimized data (4 functions)
• ✅ Grades Management: Add, update, and retrieve grades efficiently (6 functions)
• ✅ Robust Error Handling: Comprehensive validation and detailed error messages
• ✅ Performance Optimized: Reduced response payloads for faster operations
• ✅ Well Documented: Complete API reference with 765 functions documented

What's New in 0.2.0

• 🐛 35+ bug fixes across all modules
• ⚡ Performance improvements - reduced data payload by up to 80%
• 🔄 Updated APIs - migrated from deprecated endpoints
• 📚 Complete documentation - 119 Moodle modules documented
• ✅ Fully tested - all functions systematically validated

See CHANGELOG.md for detailed changes.

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_ids: list) -> list

Get all assignments in specified courses (optimized: returns 11 essential fields).

get_assignment_id_by_cmid(cmid: int, course_id: int) -> int

Get assignment ID from course module ID.

get_user_submission(assignment_id: int, user_id: int) -> dict

Get submission details for a specific user (optimized: returns 8 essential fields).

Grades Module (moodle.grades)

get_grades(course_id: int, group_id: int = None, user_id: int = None) -> list

Get grades for a course, optionally filtered by group or user (optimized: 10 fields per item).

add_grade(assignment_id: int, user_id: int, grade: float, ...) -> dict

Add a grade for a user's assignment submission.

update_grade(assignment_id: int, user_id: int, grade: float, ...) -> dict

Update an existing grade.

get_grades_for_assignment(assignment_id: int, user_ids: list = None) -> list

Get all grades for a specific assignment.

get_course_grades(course_id: int, user_id: int) -> str

Get grades table HTML for a specific user (requires user_id in v0.2.0).

Documentation

• CHANGELOG.md - Version history and migration guide
• docs/api/ - Complete Moodle API reference (119 modules, 765 functions)
• MOODLE_VERSIONS.md - Moodle version compatibility

Important Notes

Breaking Changes in 0.2.0

1. get_course_grades() now requires user_id parameter
2. Removed get_assignment_submissions() - use get_user_submission() instead
3. Removed get_grade_items() - use get_grades() instead

See CHANGELOG.md for complete migration guide.

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.