Metadata-Version: 2.4
Name: edutools-moodle
Version: 0.2.0
Summary: Python package for Moodle API interactions in educational contexts
Home-page: https://github.com/najasoft/edutools-moodle
Author: Nadiri Abdeljalil
Author-email: nadiri@najasoft.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Edutools Moodle

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/badge/pypi-0.2.0-blue.svg)](https://pypi.org/project/edutools-moodle/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Moodle](https://img.shields.io/badge/moodle-3.9+-orange.svg)](https://moodle.org)

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)

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

### From PyPI (when published)

```bash
pip install edutools-moodle
```

## Quick Start

```python
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](CHANGELOG.md) for detailed changes.

## Requirements

- Python 3.8+
- **Moodle 3.9+** (recommended, see [version compatibility](MOODLE_VERSIONS.md))
- 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

```python
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](CHANGELOG.md)** - Version history and migration guide
- **[docs/api/](docs/api/)** - Complete Moodle API reference (119 modules, 765 functions)
- **[MOODLE_VERSIONS.md](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](CHANGELOG.md) for complete migration guide.

## Development

### Running Tests

```bash
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.
