Skip to content

Models

Typed domain models for common Moodle entities.

This module provides lightweight, dependency-free dataclasses that give a typed, self-documenting shape to the raw dict/list[dict] payloads returned by the rest of :mod:py_moodle (e.g. course.list_courses(), user.list_course_users(), folder.list_folder_content()).

Each model exposes a from_moodle(data: dict) classmethod that:

  • Raises :class:ModelValidationError when a required field is missing.
  • Defaults missing optional fields to None (or an explicit empty-collection default, e.g. Folder.files).
  • Silently ignores unknown/extra keys, since real-world Moodle payloads routinely carry version- or plugin-specific extra fields.

This module is purely additive: it does not change the return type or signature of any existing public function in the library.

Note on slots: dataclasses.dataclass only accepts the slots keyword argument on Python 3.10+. Since this project supports Python 3.9 as its minimum version, slots=True is applied conditionally (Python 3.10+ only); on Python 3.9 the models remain frozen but without __slots__. This is the documented exception referenced by the issue's acceptance criteria.

Classes:

Name Description
ModelValidationError

Raised when a Moodle response dict is missing a required field.
Course

Typed representation of a Moodle course.
CourseSection

Typed representation of a Moodle course section.
CourseModule

Typed representation of a Moodle course module.
User

Typed representation of a Moodle user.
Folder

Typed representation of a Moodle folder module.
Label

Typed representation of a Moodle label module.
Assignment

Typed representation of a Moodle assignment module.
ScormPackage

Typed representation of a Moodle SCORM package module.
UploadResult

Typed, enriched representation of a file upload result.
DeleteResult

Typed, enriched representation of a delete operation's outcome.

Attributes

T module-attribute 

T = TypeVar('T')

Classes

ModelValidationError

Bases: Exception

Raised when a Moodle response dict is missing a required field.

Course

Typed representation of a Moodle course.

Attributes:

Name Type Description
id int

Unique course identifier (required).
shortname Optional[str]

Course short name, if present.
fullname Optional[str]

Course full name, if present.
categoryid Optional[int]

Category identifier, if present.
summary Optional[str]

Course summary HTML, if present.
format Optional[str]

Course format (e.g. "topics"), if present.
startdate Optional[int]

Unix timestamp of the course start date, if present.
enddate Optional[int]

Unix timestamp of the course end date, if present.
visible Optional[bool]

Whether the course is visible, if present.

Methods:

Name Description
from_moodle

Build a Course from a raw Moodle dict.

Attributes

id instance-attribute 
id: int
shortname class-attribute instance-attribute 
shortname: Optional[str] = None
fullname class-attribute instance-attribute 
fullname: Optional[str] = None
categoryid class-attribute instance-attribute 
categoryid: Optional[int] = None
summary class-attribute instance-attribute 
summary: Optional[str] = None
format class-attribute instance-attribute 
format: Optional[str] = None
startdate class-attribute instance-attribute 
startdate: Optional[int] = None
enddate class-attribute instance-attribute 
enddate: Optional[int] = None
visible class-attribute instance-attribute 
visible: Optional[bool] = None

Methods:

from_moodle classmethod 
from_moodle(data: Dict[str, Any]) -> 'Course'

Build a Course from a raw Moodle dict.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw dict as returned by e.g. list_courses()/get_course().

 required

Returns:

Name Type Description
Course 'Course'

The parsed, typed course.

Raises:

Type Description
ModelValidationError

If the required "id" key is missing.

CourseSection

Typed representation of a Moodle course section.

Modeled after the section entries inside core_courseformat_get_state's response.

Attributes:

Name Type Description
id int

Unique section identifier (required).
name Optional[str]

Section name, if present.
section Optional[int]

Section number, if present.
visible Optional[bool]

Whether the section is visible, if present.
summary Optional[str]

Section summary HTML, if present.
cmlist Optional[List[int]]

List of module ids contained in the section, if present.

Methods:

Name Description
from_moodle

Build a CourseSection from a raw Moodle dict.

Attributes

id instance-attribute 
id: int
name class-attribute instance-attribute 
name: Optional[str] = None
section class-attribute instance-attribute 
section: Optional[int] = None
visible class-attribute instance-attribute 
visible: Optional[bool] = None
summary class-attribute instance-attribute 
summary: Optional[str] = None
cmlist class-attribute instance-attribute 
cmlist: Optional[List[int]] = None

Methods:

from_moodle classmethod 
from_moodle(data: Dict[str, Any]) -> 'CourseSection'

Build a CourseSection from a raw Moodle dict.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw dict as returned by e.g. the section entries of core_courseformat_get_state.

 required

Returns:

Name Type Description
CourseSection 'CourseSection'

The parsed, typed section.

Raises:

Type Description
ModelValidationError

If the required "id" key is missing.

CourseModule

Typed representation of a Moodle course module.

Modeled after the cm entries inside core_courseformat_get_state's response. This acts as the common shape shared by module-specific entities such as :class:Folder, :class:Label, :class:Assignment and :class:ScormPackage.

Attributes:

Name Type Description
id int

Unique course-module identifier (required).
name Optional[str]

Module name, if present.
modname Optional[str]

Module type (e.g. "folder", "assign"), if present.
sectionid Optional[int]

Identifier of the section containing the module, if present.
visible Optional[bool]

Whether the module is visible, if present.
uservisible Optional[bool]

Whether the module is visible to the current user, if present.

Methods:

Name Description
from_moodle

Build a CourseModule from a raw Moodle dict.

Attributes

id instance-attribute 
id: int
name class-attribute instance-attribute 
name: Optional[str] = None
modname class-attribute instance-attribute 
modname: Optional[str] = None
sectionid class-attribute instance-attribute 
sectionid: Optional[int] = None
visible class-attribute instance-attribute 
visible: Optional[bool] = None
uservisible class-attribute instance-attribute 
uservisible: Optional[bool] = None

Methods:

from_moodle classmethod 
from_moodle(data: Dict[str, Any]) -> 'CourseModule'

Build a CourseModule from a raw Moodle dict.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw dict as returned by e.g. the cm entries of core_courseformat_get_state.

 required

Returns:

Name Type Description
CourseModule 'CourseModule'

The parsed, typed module.

Raises:

Type Description
ModelValidationError

If the required "id" key is missing.

User

Typed representation of a Moodle user.

Modeled after core_enrol_get_enrolled_users entries.

Attributes:

Name Type Description
id int

Unique user identifier (required).
username Optional[str]

User's login name, if present.
firstname Optional[str]

User's first name, if present.
lastname Optional[str]

User's last name, if present.
fullname Optional[str]

User's full display name, if present.
email Optional[str]

User's email address, if present.

Methods:

Name Description
from_moodle

Build a User from a raw Moodle dict.

Attributes

id instance-attribute 
id: int
username class-attribute instance-attribute 
username: Optional[str] = None
firstname class-attribute instance-attribute 
firstname: Optional[str] = None
lastname class-attribute instance-attribute 
lastname: Optional[str] = None
fullname class-attribute instance-attribute 
fullname: Optional[str] = None
email class-attribute instance-attribute 
email: Optional[str] = None

Methods:

from_moodle classmethod 
from_moodle(data: Dict[str, Any]) -> 'User'

Build a User from a raw Moodle dict.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw dict as returned by e.g. list_course_users().

 required

Returns:

Name Type Description
User 'User'

The parsed, typed user.

Raises:

Type Description
ModelValidationError

If the required "id" key is missing.

Folder

Typed representation of a Moodle folder module.

Attributes:

Name Type Description
cmid int

Unique course-module identifier of the folder (required).
name Optional[str]

Folder name, if present.
files List[str]

List of filenames contained in the folder. Defaults to an empty list when not present, mirroring the shape returned by list_folder_content().

Methods:

Name Description
from_moodle

Build a Folder from a raw Moodle dict.

Attributes

cmid instance-attribute 
cmid: int
name class-attribute instance-attribute 
name: Optional[str] = None
files class-attribute instance-attribute 
files: List[str] = field(default_factory=list)

Methods:

from_moodle classmethod 
from_moodle(data: Dict[str, Any]) -> 'Folder'

Build a Folder from a raw Moodle dict.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw dict with at least a "cmid" key, plus optionally "name" and "files" (e.g. the filenames from list_folder_content()).

 required

Returns:

Name Type Description
Folder 'Folder'

The parsed, typed folder.

Raises:

Type Description
ModelValidationError

If the required "cmid" key is missing.

Label

Typed representation of a Moodle label module.

Attributes:

Name Type Description
cmid int

Unique course-module identifier of the label (required).
name Optional[str]

Label name, if present.
text Optional[str]

Label HTML content, if present.

Methods:

Name Description
from_moodle

Build a Label from a raw Moodle dict.

Attributes

cmid instance-attribute 
cmid: int
name class-attribute instance-attribute 
name: Optional[str] = None
text class-attribute instance-attribute 
text: Optional[str] = None

Methods:

from_moodle classmethod 
from_moodle(data: Dict[str, Any]) -> 'Label'

Build a Label from a raw Moodle dict.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw dict with at least a "cmid" key.

 required

Returns:

Name Type Description
Label 'Label'

The parsed, typed label.

Raises:

Type Description
ModelValidationError

If the required "cmid" key is missing.

Assignment

Typed representation of a Moodle assignment module.

Attributes:

Name Type Description
cmid int

Unique course-module identifier of the assignment (required).
name Optional[str]

Assignment name, if present.
duedate Optional[int]

Unix timestamp of the submission due date, if present.
allowsubmissionsfromdate Optional[int]

Unix timestamp from which submissions are allowed, if present.

Methods:

Name Description
from_moodle

Build an Assignment from a raw Moodle dict.

Attributes

cmid instance-attribute 
cmid: int
name class-attribute instance-attribute 
name: Optional[str] = None
duedate class-attribute instance-attribute 
duedate: Optional[int] = None
allowsubmissionsfromdate class-attribute instance-attribute 
allowsubmissionsfromdate: Optional[int] = None

Methods:

from_moodle classmethod 
from_moodle(data: Dict[str, Any]) -> 'Assignment'

Build an Assignment from a raw Moodle dict.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw dict with at least a "cmid" key.

 required

Returns:

Name Type Description
Assignment 'Assignment'

The parsed, typed assignment.

Raises:

Type Description
ModelValidationError

If the required "cmid" key is missing.

ScormPackage

Typed representation of a Moodle SCORM package module.

Attributes:

Name Type Description
cmid int

Unique course-module identifier of the SCORM package (required).
name Optional[str]

SCORM package name, if present.
reference Optional[str]

Package file path or URL, if present.

Methods:

Name Description
from_moodle

Build a ScormPackage from a raw Moodle dict.

Attributes

cmid instance-attribute 
cmid: int
name class-attribute instance-attribute 
name: Optional[str] = None
reference class-attribute instance-attribute 
reference: Optional[str] = None

Methods:

from_moodle classmethod 
from_moodle(data: Dict[str, Any]) -> 'ScormPackage'

Build a ScormPackage from a raw Moodle dict.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw dict with at least a "cmid" key.

 required

Returns:

Name Type Description
ScormPackage 'ScormPackage'

The parsed, typed SCORM package.

Raises:

Type Description
ModelValidationError

If the required "cmid" key is missing.

UploadResult

Typed, enriched representation of a file upload result.

upload_file_webservice() currently returns a bare int (the itemid); this model exists so future code can build a richer result without requiring any existing function to change today.

Attributes:

Name Type Description
itemid int

Draft area item identifier of the uploaded file (required).
filename Optional[str]

Name of the uploaded file, if present.
filepath Optional[str]

Path of the uploaded file within the draft area, if present.

Methods:

Name Description
from_moodle

Build an UploadResult from a raw dict.

Attributes

itemid instance-attribute 
itemid: int
filename class-attribute instance-attribute 
filename: Optional[str] = None
filepath class-attribute instance-attribute 
filepath: Optional[str] = None

Methods:

from_moodle classmethod 
from_moodle(data: Dict[str, Any]) -> 'UploadResult'

Build an UploadResult from a raw dict.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw dict with at least an "itemid" key.

 required

Returns:

Name Type Description
UploadResult 'UploadResult'

The parsed, typed upload result.

Raises:

Type Description
ModelValidationError

If the required "itemid" key is missing.

DeleteResult

Typed, enriched representation of a delete operation's outcome.

delete_course() currently returns None on success (or raises); this model exists so future code can build a richer result without requiring any existing function to change today.

Attributes:

Name Type Description
success bool

Whether the delete operation succeeded (required).
message Optional[str]

Human-readable outcome message, if present.

Methods:

Name Description
from_moodle

Build a DeleteResult from a raw dict.

Attributes

success instance-attribute 
success: bool
message class-attribute instance-attribute 
message: Optional[str] = None

Methods:

from_moodle classmethod 
from_moodle(data: Dict[str, Any]) -> 'DeleteResult'

Build a DeleteResult from a raw dict.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw dict with at least a "success" key.

 required

Returns:

Name Type Description
DeleteResult 'DeleteResult'

The parsed, typed delete result.

Raises:

Type Description
ModelValidationError

If the required "success" key is missing.