Skip to content

Refresh README for MoodleClient, doctor, ensure, dry-run, and machine-readable output #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
erseco merged 1 commit into from
Jul 7, 2026
Merged

Refresh README for MoodleClient, doctor, ensure, dry-run, and machine-readable output #58

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,11 @@ py-moodle courses list
- **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.
- **High-level `MoodleClient` facade**: A discoverable, object-oriented API (`moodle.courses.list()`, `moodle.scorm.add(...)`) over the function-based library, plus opt-in typed domain models (`Course`, `User`, `Folder`, ...) for IDE autocompletion.
- **Diagnostics**: `py-moodle doctor run` checks base URL reachability, login, sesskey/webservice token availability, and more in one command.
- **Idempotent automation**: `courses ensure` creates a course only if it doesn't already exist, safe to run repeatedly in CI/onboarding scripts.
- **Safe previews**: `--dry-run` on `courses create`, `courses delete`, and `modules add scorm` shows the planned action without touching Moodle.
- **Scripting-friendly output**: `--output table|json|yaml|csv`, plus `--quiet`, `--no-color`, `--verbose`, and `--debug` (with automatic secret redaction) for CI pipelines and shell automation.
- **Extensible**: Designed to be easily extended with new modules and commands. See `AGENTS.md`.
- **English-only codebase**: For clear, global collaboration.

Expand Down Expand Up @@ -207,6 +212,24 @@ for course in courses:
print(course["id"], course["fullname"])
```

### The `MoodleClient` Facade

For scripts that call more than one or two functions, `MoodleClient` collapses
the `session`/`base_url`/`token`/`sesskey` boilerplate into a single object,
with a discoverable `moodle.courses` / `moodle.sections` / `moodle.scorm` /
... API:

```python
from py_moodle import MoodleClient

with MoodleClient.from_env("prod") as moodle:
courses = moodle.courses.list()
course = moodle.courses.create(fullname="My course", shortname="my-course")
moodle.scorm.add(course_id=course["id"], section_id=1, path="package.zip")
```

See the [Client API Reference](https://erseco.github.io/python-moodle/api/client/)
for the full list of resource namespaces.

### How the Example Script Works

Expand Down