Skip to content

HTTP

Centralized HTTP request handling for talking to Moodle.

This module is the single place responsible for:

  • Applying the shared timeout policy from :mod:py_moodle.config by default, with an optional override for callers that need it.
  • Retrying safe, idempotent GET-style requests with a small, bounded backoff on transient network errors (ConnectionError/Timeout), while never retrying POST/mutating requests automatically.
  • Raising typed, normalized exceptions (:class:MoodleHttpError, :class:MoodleTimeoutError, :class:MoodleWebserviceError) instead of letting raw requests exceptions or json.JSONDecodeError escape.
  • Parsing Moodle webservice error payloads (exception/errorcode/ message) into a typed exception with those fields accessible.
  • Redacting known secret-shaped values (webservice token, sesskey, password, cookies, Authorization header) from the URL, params, headers, and response body text used to build any exception message, so secrets never appear in str()/repr() of a raised exception.

Only a handful of call sites are migrated onto this module so far: session.py's MoodleSession.call() and course.py's list_courses()/create_course(). The remaining modules that call session.get/session.post/requests.post directly are left untouched and are tracked as follow-up work; new call sites should prefer the helpers in this module.

Classes:

Name Description
MoodleHttpError

Base exception for HTTP-layer failures talking to Moodle.
MoodleTimeoutError

Raised when a request times out or fails to connect after retries.
MoodleWebserviceError

Raised when Moodle returns a webservice-shaped error payload.

Functions:

Name Description
request_webservice

Call a Moodle webservice REST function and return its parsed payload.
request_html_get

Perform a safe, retryable GET request and return the raw response.
request_form_post

Perform a mutating form POST request; never retried automatically.
request_ajax

Perform a Moodle lib/ajax/service.php call and parse its response.
upload_file

Upload a file via a direct, session-less POST request.

Attributes:

Name Type Description
REDACTED

Attributes

REDACTED module-attribute 

REDACTED = '***REDACTED***'

Classes

MoodleHttpError 

MoodleHttpError(
    message: str,
    *,
    status_code: Optional[int] = None,
    url: Optional[str] = None
)

Bases: Exception

Base exception for HTTP-layer failures talking to Moodle.

Attributes:

Name Type Description
status_code

HTTP status code of the failing response, if any.
url

Redacted URL involved in the failing request, if known.

Initialize the error from an already-redacted message.

Parameters:

Name Type Description Default
message str

Human-readable, already-redacted error message.

 required
status_code Optional[int]

HTTP status code of the failing response, if any.

 None
url Optional[str]

Redacted URL involved in the failing request, if known.

 None

Attributes

status_code instance-attribute 
status_code = status_code
url instance-attribute 
url = url

MoodleTimeoutError 

MoodleTimeoutError(
    message: str,
    *,
    status_code: Optional[int] = None,
    url: Optional[str] = None
)

Bases: MoodleHttpError

Raised when a request times out or fails to connect after retries.

Initialize the error from an already-redacted message.

Parameters:

Name Type Description Default
message str

Human-readable, already-redacted error message.

 required
status_code Optional[int]

HTTP status code of the failing response, if any.

 None
url Optional[str]

Redacted URL involved in the failing request, if known.

 None

Attributes:

Name Type Description
status_code
url

Attributes

status_code instance-attribute 
status_code = status_code
url instance-attribute 
url = url

MoodleWebserviceError 

MoodleWebserviceError(
    message: str,
    *,
    errorcode: Optional[str] = None,
    moodle_exception: Optional[str] = None,
    status_code: Optional[int] = None,
    url: Optional[str] = None
)

Bases: MoodleHttpError

Raised when Moodle returns a webservice-shaped error payload.

Attributes:

Name Type Description
errorcode

Moodle errorcode value from the failed response.
moodle_exception

Moodle exception class name from the failed response (e.g. "invalid_parameter_exception").

Initialize the error with Moodle's error payload fields.

Parameters:

Name Type Description Default
message str

Human-readable, already-redacted error message.

 required
errorcode Optional[str]

Moodle errorcode value from the failed response.

 None
moodle_exception Optional[str]

Moodle exception class name from the failed response.

 None
status_code Optional[int]

HTTP status code of the failing response, if any.

 None
url Optional[str]

Redacted URL involved in the failing request, if known.

 None

Attributes

errorcode instance-attribute 
errorcode = errorcode
moodle_exception instance-attribute 
moodle_exception = moodle_exception
status_code instance-attribute 
status_code = status_code
url instance-attribute 
url = url

Functions:

request_webservice 

request_webservice(
    session: Any,
    base_url: str,
    wsfunction: str,
    params: Optional[Dict[str, Any]] = None,
    *,
    token: Optional[str] = None,
    timeout: Optional[Any] = None,
    method: str = "post"
) -> Any

Call a Moodle webservice REST function and return its parsed payload.

Parameters:

Name Type Description Default
session Any

Authenticated requests.Session-like object.

 required
base_url str

Base URL of the Moodle instance.

 required
wsfunction str

Name of the Moodle webservice function to call.

 required
params Optional[Dict[str, Any]]

Additional parameters for the webservice call.

 None
token Optional[str]

Webservice token, sent as wstoken.

 None
timeout Optional[Any]

Optional timeout override; defaults to DEFAULT_REQUEST_TIMEOUT.

 None
method str

HTTP method to use: "post" (default, never retried, appropriate for most Moodle webservice calls) or "get" (retried with backoff on transient network errors; only use for calls that are safe and idempotent).

 'post'

Returns:

Name Type Description
Any Any

Parsed JSON payload (typically a dict or list).

Raises:

Type Description
MoodleHttpError

On network failures or non-2xx status codes.
MoodleTimeoutError

On repeated timeouts for GET-style calls.
MoodleWebserviceError

When Moodle returns an error payload.

request_html_get 

request_html_get(
    session: Any,
    url: str,
    *,
    timeout: Optional[Any] = None,
    headers: Optional[Dict[str, str]] = None
) -> Any

Perform a safe, retryable GET request and return the raw response.

Parameters:

Name Type Description Default
session Any

Authenticated requests.Session-like object.

 required
url str

Absolute URL to fetch.

 required
timeout Optional[Any]

Optional timeout override; defaults to DEFAULT_SCRAPE_TIMEOUT.

 None
headers Optional[Dict[str, str]]

Optional request headers.

 None

Returns:

Type Description
Any

The response object returned by the underlying session's get.

Raises:

Type Description
MoodleHttpError

On non-2xx status codes.
MoodleTimeoutError

On repeated timeouts after retries.

request_form_post 

request_form_post(
    session: Any,
    url: str,
    *,
    data: Optional[Any] = None,
    headers: Optional[Dict[str, str]] = None,
    timeout: Optional[Any] = None,
    allow_redirects: bool = True,
    raise_for_status: bool = True
) -> Any

Perform a mutating form POST request; never retried automatically.

Parameters:

Name Type Description Default
session Any

Authenticated requests.Session-like object.

 required
url str

Absolute URL to post to.

 required
data Optional[Any]

Form-encoded body (dict or already-encoded string).

 None
headers Optional[Dict[str, str]]

Optional request headers.

 None
timeout Optional[Any]

Optional timeout override; defaults to DEFAULT_REQUEST_TIMEOUT.

 None
allow_redirects bool

Whether to follow redirects (forwarded as-is).

 True
raise_for_status bool

Whether to raise MoodleHttpError for a 4xx/5xx response. Callers that need to inspect Moodle's redirect/form-re-render behavior themselves can pass False and handle the raw response's status code.

 True

Returns:

Type Description
Any

The response object returned by the underlying session's post.

Raises:

Type Description
MoodleHttpError

On network failures (never retried), or on a 4xx/5xx status code when raise_for_status is True.

request_ajax 

request_ajax(
    session: Any,
    url: str,
    payload: Any,
    *,
    headers: Optional[Dict[str, str]] = None,
    timeout: Optional[Any] = None
) -> Any

Perform a Moodle lib/ajax/service.php call and parse its response.

Parameters:

Name Type Description Default
session Any

Authenticated requests.Session-like object.

 required
url str

Absolute AJAX endpoint URL (typically including sesskey).

 required
payload Any

JSON-serializable list of AJAX method-call descriptors.

 required
headers Optional[Dict[str, str]]

Optional request headers; defaults to {"Content-Type": "application/json"}.

 None
timeout Optional[Any]

Optional timeout override; defaults to DEFAULT_REQUEST_TIMEOUT.

 None

Returns:

Name Type Description
Any Any

Parsed JSON payload (typically a list of AJAX response
Any

entries).

Raises:

Type Description
MoodleHttpError

On network failures, non-2xx status codes, a non-JSON body, or an AJAX error entry in the response. Never retried, since AJAX calls may be mutating.

upload_file 

upload_file(
    url: str,
    *,
    params: Optional[Dict[str, Any]] = None,
    files: Optional[Dict[str, Any]] = None,
    timeout: Optional[Any] = None
) -> Any

Upload a file via a direct, session-less POST request.

Mirrors the pattern used by Moodle's webservice file-upload endpoint, which authenticates via a token query parameter rather than session cookies. Never retried, since uploads are mutating requests.

Parameters:

Name Type Description Default
url str

Absolute upload endpoint URL.

 required
params Optional[Dict[str, Any]]

Query parameters (e.g. {"token": ..., "filearea": ...}).

 None
files Optional[Dict[str, Any]]

requests-style files mapping for multipart upload.

 None
timeout Optional[Any]

Optional timeout override; defaults to DEFAULT_UPLOAD_TIMEOUT.

 None

Returns:

Type Description
Any

The raw response returned by requests.post.

Raises:

Type Description
MoodleHttpError

On network failures or non-2xx status codes.