Ensure¶

Idempotent, ensure-style provisioning helpers for sections and content modules. Each helper looks up an existing object by its human-readable natural key and only creates a new one when nothing matches, mirroring ensure_course.

Idempotent ensure-style provisioning helpers for Moodle content.

This module extends the ensure_course pattern (see :mod:py_moodle.course) to sections and content modules. Every helper is idempotent: it first looks up an existing object by its human-readable natural key and only creates a new one when nothing matches, mirroring how ensure_course keys on shortname.

The idempotency keys are:

:func:ensure_module (and its wrappers): (name, modname) within the course.
:func:ensure_section: the section name within the course.

These helpers only ever create or reuse; they never delete or reconcile away extra objects. The heavy lookup (get_course_with_sections_and_modules) and the mutating primitives (add_label/add_resource/add_folder/create_section) are imported lazily inside the functions to avoid import cycles and to keep the module easy to test with monkeypatching.

Classes:

Name	Description
`EnsureModuleResult`	Outcome of an :func:`ensure_module` call.
`EnsureSectionResult`	Outcome of an :func:`ensure_section` call.

Functions:

Name	Description
`ensure_module`	Ensure a module with the given name and type exists in the course.
`ensure_label`	Ensure a `label` module with the given name exists.
`ensure_resource`	Ensure a `resource` (single-file) module with the given name exists.
`ensure_folder`	Ensure a `folder` module with the given name exists.
`ensure_section`	Ensure a section with the given name exists in the course.

Attributes¶

EnsureModuleStatus `module-attribute` ¶

EnsureModuleStatus = Literal['created', 'reused']

EnsureSectionStatus `module-attribute` ¶

EnsureSectionStatus = Literal['created', 'reused']

Classes¶

EnsureModuleResult `dataclass` ¶

EnsureModuleResult(
    status: EnsureModuleStatus,
    cmid: int,
    module: Optional[Dict[str, Any]] = None,
)

Outcome of an :func:ensure_module call.

Attributes:

Name	Type	Description
`status`	`EnsureModuleStatus`	`"created"` when a new module was created, `"reused"` when an existing module matched the `(name, modname)` key.
`cmid`	`int`	The course module ID of the resulting module.
`module`	`Optional[Dict[str, Any]]`	The matched module dictionary when `status == "reused"`, or `None` when a new module was created.

Attributes¶

status `instance-attribute` ¶

status: EnsureModuleStatus

cmid `instance-attribute` ¶

cmid: int

module `class-attribute` `instance-attribute` ¶

module: Optional[Dict[str, Any]] = None

EnsureSectionResult `dataclass` ¶

EnsureSectionResult(
    status: EnsureSectionStatus, section: Dict[str, Any]
)

Outcome of an :func:ensure_section call.

Attributes:

Name	Type	Description
`status`	`EnsureSectionStatus`	`"created"` when a new section was created and renamed, `"reused"` when an existing section matched by `name`.
`section`	`Dict[str, Any]`	The resulting section dictionary. When `status == "reused"` this is the section as returned by `get_course_with_sections_and_modules`; when `status == "created"` it is a minimal `{"id": ..., "name": ...}` mapping.

Attributes¶

status `instance-attribute` ¶

status: EnsureSectionStatus

section `instance-attribute` ¶

section: Dict[str, Any]

Functions:¶

ensure_module ¶

ensure_module(
    session: Session,
    base_url: str,
    sesskey: str,
    course_id: int,
    section_id: int,
    *,
    name: str,
    modname: str,
    create_fn: Callable[[], int],
    token: Optional[str] = None
) -> EnsureModuleResult

Ensure a module with the given name and type exists in the course.

Scans every section of the course for a module whose name and modname both match. If found, the module is reused and create_fn is never called. Otherwise create_fn is invoked exactly once (it must create the module and return its cmid) and the result 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
`course_id`	`int`	ID of the course to search within.	required
`section_id`	`int`	ID of the section the module belongs to (passed by the wrappers to their `create_fn`; not used for the lookup, which is course-wide, mirroring `ensure_course`).	required
`name`	`str`	Human-readable module name used as part of the idempotency key.	required
`modname`	`str`	Moodle module type (e.g. `"label"`) used as part of the idempotency key.	required
`create_fn`	`Callable[[], int]`	Zero-argument callable that creates the module and returns its `cmid`. Only called when no existing module matches.	required
`token`	`Optional[str]`	Optional webservice token forwarded to the course lookup.	`None`

Returns:

Name	Type	Description
`EnsureModuleResult`	`EnsureModuleResult`	Typed result with `status` of `"created"` or
	`EnsureModuleResult`	`"reused"`.

ensure_label ¶

ensure_label(
    session: Session,
    base_url: str,
    sesskey: str,
    course_id: int,
    section_id: int,
    *,
    name: str,
    html: str,
    visible: int = 1,
    token: Optional[str] = None
) -> EnsureModuleResult

Ensure a label module with the given name exists.

Thin wrapper over :func:ensure_module binding modname="label" and delegating creation to :func:py_moodle.label.add_label.

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
`course_id`	`int`	ID of the course.	required
`section_id`	`int`	ID of the section to create the label in when missing.	required
`name`	`str`	Label name (idempotency key together with the module type).	required
`html`	`str`	HTML content of the label.	required
`visible`	`int`	Whether the label is visible (`1`) or hidden (`0`).	`1`
`token`	`Optional[str]`	Optional webservice token forwarded to the course lookup.	`None`

Returns:

Name	Type	Description
`EnsureModuleResult`	`EnsureModuleResult`	Result of the create-or-reuse operation.

ensure_resource ¶

ensure_resource(
    session: Session,
    base_url: str,
    sesskey: str,
    course_id: int,
    section_id: int,
    *,
    name: str,
    file_path: str,
    intro: str = "",
    visible: int = 1,
    token: Optional[str] = None
) -> EnsureModuleResult

Ensure a resource (single-file) module with the given name exists.

Thin wrapper over :func:ensure_module binding modname="resource" and delegating creation to :func:py_moodle.resource.add_resource.

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
`course_id`	`int`	ID of the course.	required
`section_id`	`int`	ID of the section to create the resource in when missing.	required
`name`	`str`	Resource name (idempotency key together with the module type).	required
`file_path`	`str`	Local path to the file to upload when creating.	required
`intro`	`str`	Optional HTML introduction for the resource.	`''`
`visible`	`int`	Whether the resource is visible (`1`) or hidden (`0`).	`1`
`token`	`Optional[str]`	Optional webservice token forwarded to the course lookup.	`None`

Returns:

Name	Type	Description
`EnsureModuleResult`	`EnsureModuleResult`	Result of the create-or-reuse operation.

ensure_folder ¶

ensure_folder(
    session: Session,
    base_url: str,
    sesskey: str,
    course_id: int,
    section_id: int,
    *,
    name: str,
    files_itemid: int,
    intro_html: str = "",
    visible: int = 1,
    token: Optional[str] = None
) -> EnsureModuleResult

Ensure a folder module with the given name exists.

Thin wrapper over :func:ensure_module binding modname="folder" and delegating creation to :func:py_moodle.folder.add_folder.

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
`course_id`	`int`	ID of the course.	required
`section_id`	`int`	ID of the section to create the folder in when missing.	required
`name`	`str`	Folder name (idempotency key together with the module type).	required
`files_itemid`	`int`	Draft-area itemid holding the folder's files.	required
`intro_html`	`str`	Optional HTML introduction for the folder.	`''`
`visible`	`int`	Whether the folder is visible (`1`) or hidden (`0`).	`1`
`token`	`Optional[str]`	Optional webservice token forwarded to the course lookup.	`None`

Returns:

Name	Type	Description
`EnsureModuleResult`	`EnsureModuleResult`	Result of the create-or-reuse operation.

ensure_section ¶

ensure_section(
    session: Session,
    base_url: str,
    sesskey: str,
    course_id: int,
    *,
    name: str,
    token: Optional[str] = None
) -> EnsureSectionResult

Ensure a section with the given name exists in the course.

Looks up an existing section by name via get_course_with_sections_and_modules. If found, it is reused. Otherwise a new section is created with create_section and then renamed to name (see :func:_rename_section for the renaming mechanism and its limitations).

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
`course_id`	`int`	ID of the course.	required
`name`	`str`	Section name used as the idempotency key.	required
`token`	`Optional[str]`	Optional webservice token forwarded to the course lookup.	`None`

Returns:

Name	Type	Description
`EnsureSectionResult`	`EnsureSectionResult`	Typed result with `status` of `"created"` or
	`EnsureSectionResult`	`"reused"`.

Ensure¶

Attributes¶

EnsureModuleStatus module-attribute ¶

EnsureSectionStatus module-attribute ¶

Classes¶

EnsureModuleResult dataclass ¶

Attributes¶

status instance-attribute ¶

cmid instance-attribute ¶

module class-attribute instance-attribute ¶

EnsureSectionResult dataclass ¶

Attributes¶

status instance-attribute ¶

section instance-attribute ¶

Functions:¶

ensure_module ¶

ensure_label ¶

ensure_resource ¶

ensure_folder ¶

ensure_section ¶

EnsureModuleStatus `module-attribute` ¶

EnsureSectionStatus `module-attribute` ¶

EnsureModuleResult `dataclass` ¶

status `instance-attribute` ¶

cmid `instance-attribute` ¶

module `class-attribute` `instance-attribute` ¶

EnsureSectionResult `dataclass` ¶

status `instance-attribute` ¶

section `instance-attribute` ¶