Transport¶

Transport-layer abstractions for talking to Moodle.

py-moodle talks to a Moodle instance through three fundamentally different transports:

Webservice / REST API (:mod:py_moodle.transport.webservice) -- POST {base_url}/webservice/rest/server.php with a wstoken, e.g. core_course_get_courses.
Internal AJAX endpoint (:mod:py_moodle.transport.ajax) -- POST {base_url}/lib/ajax/service.php?sesskey=... with a JSON methodname/args payload, used when no webservice token is available or the webservice call fails.
HTML scraping / form submission (:mod:py_moodle.transport.html) -- used where Moodle exposes no webservice or AJAX equivalent at all.

This package formalizes those transports as small, uniform call(...) functions built strictly on top of the shared HTTP client in :mod:py_moodle.http, so a caller can implement "try transport A, on failure fall back to transport B" without knowing the request-building details of either transport.

Transport (webservice vs AJAX vs HTML) is a different, orthogonal axis from Moodle-version compatibility, which remains isolated in :mod:py_moodle.compat.

Modules:

Name	Description
`ajax`	Internal AJAX endpoint transport strategy for talking to Moodle.
`html`	HTML scraping / form-submission transport strategy (interface only).
`webservice`	Webservice (REST API) transport strategy for talking to Moodle.

Classes:

Name	Description
`TransportError`	Base class for transport-layer errors.
`TransportUnavailableError`	Raised when a transport cannot be used for this call.

Classes¶

TransportError ¶

Bases: Exception

Base class for transport-layer errors.

TransportUnavailableError ¶

Bases: TransportError

Raised when a transport cannot be used for this call.

Signals to the caller that it should try the next transport in the fallback chain (e.g. webservice -> AJAX), as opposed to a genuine business-logic failure that should propagate to the user.

Webservice (REST API) transport strategy for talking to Moodle.

Calls {base_url}/webservice/rest/server.php with a wstoken, delegating the actual socket-level request to the shared HTTP client in :mod:py_moodle.http.

Functions:

Name	Description
`call`	Call a Moodle webservice function via the REST API.

Classes¶

Functions:¶

call ¶

call(
    session: Session,
    base_url: str,
    wsfunction: str,
    token: str,
    params: Optional[Dict[str, Any]] = None,
) -> Any

Call a Moodle webservice function via the REST API.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`wsfunction`	`str`	Name of the webservice function to invoke.	required
`token`	`str`	Webservice token (`wstoken`).	required
`params`	`Optional[Dict[str, Any]]`	Additional parameters for the webservice call.	`None`

Returns:

Name	Type	Description
`Any`	`Any`	The parsed JSON response (list or dict) on success.

Raises:

Type	Description
`TransportUnavailableError`	If Moodle reports an invalid/expired token, or a context-validation failure, indicating the caller should fall back to another transport (see :data:`_TRANSPORT_UNAVAILABLE_MARKERS`).
`TransportError`	If the call fails for any other reason (network error, non-token/context Moodle exception, invalid JSON).

Internal AJAX endpoint transport strategy for talking to Moodle.

Calls {base_url}/lib/ajax/service.php?sesskey=... with the [{"index": 0, "methodname": ..., "args": ...}] envelope Moodle expects, delegating the actual socket-level requests to the shared HTTP client in :mod:py_moodle.http.

Functions:

Name	Description
`call`	Call a Moodle method via the internal AJAX endpoint.

Classes¶

Functions:¶

call ¶

call(
    session: Session,
    base_url: str,
    methodname: str,
    sesskey: str,
    args: Optional[Dict[str, Any]] = None,
) -> Any

Call a Moodle method via the internal AJAX endpoint.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`methodname`	`str`	Name of the AJAX method to invoke (as used in `lib/ajax/service.php`).	required
`sesskey`	`str`	Moodle session key required by the AJAX endpoint.	required
`args`	`Optional[Dict[str, Any]]`	Additional method arguments.	`None`

Returns:

Name	Type	Description
`Any`	`Any`	The parsed `data` payload from the first entry of the AJAX JSON-array response, on success.

Raises:

Type	Description
`TransportUnavailableError`	If no usable `sesskey` is supplied.
`TransportError`	If the HTTP call fails, or Moodle's AJAX response reports an error for the requested method.

HTML scraping / form-submission transport strategy (interface only).

This module formalizes the calling convention for a future HtmlTransport that talks to Moodle by scraping HTML pages and submitting HTML forms (e.g. course/edit.php), for the cases where Moodle exposes neither a webservice nor an AJAX equivalent.

No real Moodle interaction is wired up as part of this issue: :func:call only documents the intended signature and always raises :class:NotImplementedError. Migrating existing HTML-based flows (e.g. create_course/delete_course in :mod:py_moodle.course) onto this transport is tracked as follow-up work.

Functions:

Name	Description
`call`	Perform an HTML form-submission/scraping call against Moodle.

Functions:¶

call ¶

call(
    session: Session,
    base_url: str,
    action: str,
    params: Optional[Dict[str, Any]] = None,
) -> Any

Perform an HTML form-submission/scraping call against Moodle.

Parameters:

Name	Type	Description	Default
`session`	`Session`	Authenticated requests session.	required
`base_url`	`str`	Base URL of the Moodle instance.	required
`action`	`str`	Relative path of the HTML page/form to interact with (e.g. `"course/edit.php"`).	required
`params`	`Optional[Dict[str, Any]]`	Form fields or query parameters for the request.	`None`

Returns:

Name	Type	Description
`Any`	`Any`	Parsed result of the HTML interaction, in whatever shape a
	`Any`	future concrete implementation defines.

Raises:

Type	Description
`NotImplementedError`	Always, for this issue. This module only formalizes the transport interface; no real HTML-based Moodle interaction is implemented yet.