Course¶

Course management module for Moodle.

Provides functions to list courses, retrieve course details, and enumerate course sections using AJAX endpoints.

Classes:

Name	Description
`MoodleCourseError`	Exception raised for errors in course operations.
`ConfirmationRequired`	Raised when a mutating operation needs interactive confirmation.

Functions:

Name	Description
`get_course_context_id`	Get the context ID for a course by scraping its main page.
`list_courses`	List all courses visible to the user.
`create_course`	Create a new course using the web form.
`update_course_basic`	Apply a minimal, safe update to a course's name and/or category.
`ensure_course`	Ensure a course with the given shortname exists.
`create_or_update_course`	Create a course, or update it if one with the shortname already exists.
`delete_course`	Delete a course by ID using the web interface.
`get_course`	Get details for a specific course.
`get_course_with_sections_and_modules`	Return full course data with sections and modules.
`list_sections`	Extract a list of sections from course contents.

Attributes¶

EnsureStatus `module-attribute` ¶

EnsureStatus = Literal[
    "created", "reused", "updated", "conflict"
]

Classes¶

MoodleCourseError ¶

Bases: Exception

Exception raised for errors in course operations.

ConfirmationRequired ¶

ConfirmationRequired(course_id: int, course_title: str)

Bases: MoodleCourseError

Raised when a mutating operation needs interactive confirmation.

Attributes:

Name	Type	Description
`course_id`		The course id pending confirmation.
`course_title`		The human-readable title, if it could be determined.

Initialize the exception with the pending course id and title.

Parameters:

Name	Type	Description	Default
`course_id`	`int`	The course id pending confirmation.	required
`course_title`	`str`	The human-readable title, if it could be determined.	required

Attributes¶

course_id `instance-attribute` ¶

course_id = course_id

course_title `instance-attribute` ¶

course_title = course_title

EnsureCourseResult `dataclass` ¶

EnsureCourseResult(
    status: EnsureStatus,
    course: Dict[str, Any],
    differences: Optional[Dict[str, tuple]] = None,
)

Outcome of an :func:ensure_course call.

Attributes:

Name	Type	Description
`status`	`EnsureStatus`	One of `"created"`, `"reused"`, `"updated"`, or `"conflict"`.
`course`	`Dict[str, Any]`	The resulting course dictionary (existing, created, or updated, depending on `status`).
`differences`	`Optional[Dict[str, tuple]]`	Populated only when `status == "conflict"`, mapping each differing field name (`"fullname"` and/or `"categoryid"`) to a `(existing_value, requested_value)` tuple. `None` otherwise.

Attributes¶

status `instance-attribute` ¶

status: EnsureStatus

course `instance-attribute` ¶

course: Dict[str, Any]

differences `class-attribute` `instance-attribute` ¶

differences: Optional[Dict[str, tuple]] = None

Functions:¶

get_course_context_id ¶

get_course_context_id(
    session: Session, base_url: str, course_id: int
) -> int

Get the context ID for a course by scraping its main page.

This mimics how the frontend retrieves the ID, making it the most reliable method.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`course_id`	`int`	Identifier of the course.	required

Returns:

Name	Type	Description
`int`	`int`	Context ID of the course.

Raises:

Type	Description
`MoodleCourseError`	If the context ID cannot be found.

list_courses ¶

list_courses(
    session: Session,
    base_url: str,
    *,
    token: str | None = None,
    sesskey: str | None = None
) -> List[Dict[str, Any]]

List all courses visible to the user.

Uses the core_course_get_courses webservice when a token is available and falls back to the AJAX endpoint otherwise. Internally, each transport is delegated to :mod:py_moodle.transport.webservice and :mod:py_moodle.transport.ajax respectively; their TransportError/TransportUnavailableError exceptions are translated into MoodleCourseError (or used to decide the webservice-to-AJAX fallback) and never leak to callers of this function.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`token`	`str \| None`	Webservice token for REST API (optional, preferred).	`None`
`sesskey`	`str \| None`	Session key for AJAX calls (optional, fallback).	`None`

Returns:

Type	Description
`List[Dict[str, Any]]`	List[Dict[str, Any]]: List of course dictionaries.

Raises:

Type	Description
`MoodleCourseError`	If the request fails.

create_course ¶

create_course(
    session: Session,
    base_url: str,
    sesskey: str,
    fullname: str,
    shortname: str,
    categoryid: int = 1,
    visible: int = 1,
    summary: str = "",
    startdate: dict = None,
    enddate: dict = None,
    numsections: int = 4,
) -> Dict[str, Any]

Create a new course using the web form.

Simulates browser behavior by posting to edit.php.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`sesskey`	`str`	Session key for AJAX calls.	required
`fullname`	`str`	Full name of the course.	required
`shortname`	`str`	Short name of the course.	required
`categoryid`	`int`	Category ID.	`1`
`visible`	`int`	Visibility flag (1 for visible, 0 for hidden).	`1`
`summary`	`str`	Course summary.	`''`
`startdate`	`dict`	Dict with keys `day`, `month`, `year`, `hour`, `minute`.	`None`
`enddate`	`dict`	Dict with keys `enabled`, `day`, `month`, `year`, `hour`, `minute`.	`None`
`numsections`	`int`	Number of sections.	`4`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: Created course dictionary with at least `id`, `fullname` and `shortname`.

Raises:

Type	Description
`MoodleCourseError`	If the request fails.

update_course_basic ¶

update_course_basic(
    session: Session,
    base_url: str,
    sesskey: str,
    courseid: int,
    *,
    fullname: str | None = None,
    categoryid: int | None = None
) -> Dict[str, Any]

Apply a minimal, safe update to a course's name and/or category.

Deliberately restricted to fullname and categoryid: this helper fetches the current course/edit.php form, changes only the fields explicitly requested, and resubmits every other field unchanged, so it must never touch summary, visible, sections, or modules.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`sesskey`	`str`	Session key for form calls.	required
`courseid`	`int`	ID of the course to update.	required
`fullname`	`str \| None`	New full name, or None to leave unchanged.	`None`
`categoryid`	`int \| None`	New category ID, or None to leave unchanged.	`None`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: The updated course dictionary, as looked up via
`Dict[str, Any]`	`list_courses` after the update is applied.

Raises:

Type	Description
`MoodleCourseError`	If the update request fails.

ensure_course ¶

ensure_course(
    session: Session,
    base_url: str,
    sesskey: str,
    *,
    shortname: str,
    fullname: str,
    category_id: int,
    token: str | None = None,
    update: bool = False,
    **create_kwargs: Any
) -> EnsureCourseResult

Ensure a course with the given shortname exists.

Looks up an existing course by shortname via list_courses(). If no course with that shortname is found, creates one via create_course(). If a course is found and update is False, the existing course is left untouched: if fullname/category_id match the request the result is "reused"; if they differ the result is "conflict" (nothing is changed, but the caller can inspect differences). If a course is found and update is True, the differing fields among fullname/ category_id are updated via update_course_basic() and the result is "updated".

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`sesskey`	`str`	Session key for AJAX/form calls.	required
`shortname`	`str`	Unique shortname used to look up an existing course.	required
`fullname`	`str`	Desired full name of the course.	required
`category_id`	`int`	Desired category ID of the course.	required
`token`	`str \| None`	Optional webservice token, forwarded to `list_courses`.	`None`
`update`	`bool`	If True and a course is found, apply a safe update to `fullname`/`category_id` instead of leaving it untouched.	`False`
`**create_kwargs`	`Any`	Extra keyword arguments forwarded to `create_course` when a new course must be created (e.g. `visible`, `summary`, `numsections`).	`{}`

Returns:

Name	Type	Description
`EnsureCourseResult`	`EnsureCourseResult`	Typed result with `status` of `"created"`,
	`EnsureCourseResult`	`"reused"`, `"updated"`, or `"conflict"`.

Raises:

Type	Description
`MoodleCourseError`	If listing, creating, or updating fails.

create_or_update_course ¶

create_or_update_course(
    session: Session,
    base_url: str,
    sesskey: str,
    *,
    shortname: str,
    fullname: str,
    category_id: int,
    token: str | None = None,
    **create_kwargs: Any
) -> EnsureCourseResult

Create a course, or update it if one with the shortname already exists.

Convenience wrapper over :func:ensure_course with update=True: if a course with shortname exists it is updated in place (differing fullname/category_id fields are applied) instead of reporting a conflict; otherwise a new course is created.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`sesskey`	`str`	Session key for AJAX/form calls.	required
`shortname`	`str`	Unique shortname used to look up an existing course.	required
`fullname`	`str`	Desired full name of the course.	required
`category_id`	`int`	Desired category ID of the course.	required
`token`	`str \| None`	Optional webservice token, forwarded to `list_courses`.	`None`
`**create_kwargs`	`Any`	Extra keyword arguments forwarded to `create_course` when a new course must be created.	`{}`

Returns:

Name	Type	Description
`EnsureCourseResult`	`EnsureCourseResult`	Typed result with `status` of `"created"`,
	`EnsureCourseResult`	`"reused"`, or `"updated"`.

Raises:

Type	Description
`MoodleCourseError`	If listing, creating, or updating fails.

delete_course ¶

delete_course(
    session: Session,
    base_url: str,
    sesskey: str,
    courseid: int,
    force: bool = False,
) -> None

Delete a course by ID using the web interface.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`sesskey`	`str`	Session key for AJAX calls.	required
`courseid`	`int`	ID of the course to delete.	required
`force`	`bool`	Whether to skip confirmation and delete directly.	`False`

Raises:

Type	Description
`MoodleCourseError`	If the request fails.
`ConfirmationRequired`	If `force` is `False`. Callers must catch this exception and re-invoke with `force=True` after obtaining confirmation themselves; this function performs no stdin/stdout I/O of its own.

get_course ¶

get_course(
    session: Session,
    base_url: str,
    sesskey: str,
    courseid: int,
    token: str = None,
) -> List[Dict[str, Any]]

Get details for a specific course.

Attempts the webservice first and falls back to AJAX if necessary.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`sesskey`	`str`	Session key for AJAX calls.	required
`courseid`	`int`	Identifier of the course to fetch.	required
`token`	`str`	Webservice token (optional).	`None`

Returns:

Type	Description
`List[Dict[str, Any]]`	List[Dict[str, Any]]: Course contents including sections and modules.

Raises:

Type	Description
`MoodleCourseError`	If both webservice and AJAX requests fail.

get_course_with_sections_and_modules ¶

get_course_with_sections_and_modules(
    session: Session,
    base_url: str,
    sesskey: str,
    courseid: int,
    token: str = None,
) -> Dict[str, Any]

Return full course data with sections and modules.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`sesskey`	`str`	Session key for AJAX calls.	required
`courseid`	`int`	Identifier of the course to fetch.	required
`token`	`str`	Webservice token (optional).	`None`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: Course dictionary with keys `id`, `fullname`,
`Dict[str, Any]`	`shortname` and a list of `sections` containing their modules.

list_sections ¶

list_sections(
    course_contents: List[Dict[str, Any]],
) -> List[Dict[str, Any]]

Extract a list of sections from course contents.

Parameters:

Name	Type	Description	Default
`course_contents`	`List[Dict[str, Any]]`	Output from `get_course`.	required

Returns:

Type	Description
`List[Dict[str, Any]]`	List[Dict[str, Any]]: Each dictionary represents a section.

Notes

This function expects the output of get_course.

Course¶

Attributes¶

EnsureStatus module-attribute ¶

Classes¶

MoodleCourseError ¶

ConfirmationRequired ¶

Attributes¶

course_id instance-attribute ¶

course_title instance-attribute ¶

EnsureCourseResult dataclass ¶

Attributes¶

status instance-attribute ¶

course instance-attribute ¶

differences class-attribute instance-attribute ¶

Functions:¶

get_course_context_id ¶

list_courses ¶

create_course ¶

update_course_basic ¶

ensure_course ¶

create_or_update_course ¶

delete_course ¶

get_course ¶

get_course_with_sections_and_modules ¶

list_sections ¶

EnsureStatus `module-attribute` ¶

course_id `instance-attribute` ¶

course_title `instance-attribute` ¶

EnsureCourseResult `dataclass` ¶

status `instance-attribute` ¶

course `instance-attribute` ¶

differences `class-attribute` `instance-attribute` ¶