Category

py_moodle.category

Category management module for Moodle CLI.

Provides functions to list, create, and delete course categories using Moodle webservice API or AJAX/form posts for greater compatibility.

All code and comments must be in English.

Classes:

Name	Description
MoodleCategoryError	Exception raised for errors in category operations.

Functions:

Name	Description
list_categories	List all course categories.
get_category	Retrieve a single category by ID using the webservice.
create_category_form	Create a new course category using the form endpoint.
delete_category_form	Delete a category by mimicking the browser flow.
create_category	Create a category using form post or webservice.
delete_category	Delete a category using form post or webservice.

Classes

MoodleCategoryError

Bases: Exception

Exception raised for errors in category operations.

Functions

list_categories

list_categories(
    session: Session, base_url: str, token: str
) -> List[Dict[str, Any]]

List all course categories.

Parameters:

Name	Type	Description	Default
session	Session	Authenticated requests session.	required
base_url	str	Base URL of the Moodle instance.	required
token	str	Webservice token used for the request.	required

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Categories sorted by ID.

Raises:

Type	Description
MoodleCategoryError	If the request fails.

get_category

get_category(
    session: Session,
    base_url: str,
    token: str,
    categoryid: int,
) -> Dict[str, Any]

Retrieve a single category by ID using the webservice.

Parameters:

Name	Type	Description	Default
session	Session	Authenticated requests session.	required
base_url	str	Base URL of the Moodle instance.	required
token	str	Webservice token used for the request.	required
categoryid	int	Identifier of the category to fetch.	required

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Category information.

Raises:

Type	Description
MoodleCategoryError	If the request fails or the category is missing.

create_category_form

create_category_form(
    session: Session,
    base_url: str,
    sesskey: str,
    name: str,
    parent: int = 0,
    description: str = "",
) -> Dict[str, Any]

Create a new course category using the form endpoint.

This method mimics a browser interaction and does not require webservice permissions.

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 submissions.	required
name	str	Name of the category to create.	required
parent	int	ID of the parent category.	0
description	str	Optional HTML description.	''

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Newly created category data.

Raises:

Type	Description
MoodleCategoryError	If the category cannot be created.

delete_category_form

delete_category_form(
    session: Session,
    base_url: str,
    sesskey: str,
    categoryid: int,
) -> bool

Delete a category by mimicking the browser flow.

Uses course/management.php and does not require webservice permissions.

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 submissions.	required
categoryid	int	ID of the category to delete.	required

Returns:

Name	Type	Description
bool	bool	True if the deletion appears successful.

Raises:

Type	Description
MoodleCategoryError	If the deletion fails.

create_category

create_category(
    session: Session,
    base_url: str,
    name: str,
    parent: int = 0,
    token: Optional[str] = None,
    sesskey: Optional[str] = None,
) -> Dict[str, Any]

Create a category using form post or webservice.

Parameters:

Name	Type	Description	Default
session	Session	Authenticated requests session.	required
base_url	str	Base URL of the Moodle instance.	required
name	str	Name of the category.	required
parent	int	ID of the parent category.	0
token	Optional[str]	Webservice token (optional).	None
sesskey	Optional[str]	Session key (optional).	None

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Created category data.

Raises:

Type	Description
ValueError	If neither sesskey nor token is provided.

delete_category

delete_category(
    session: Session,
    base_url: str,
    categoryid: int,
    token: Optional[str] = None,
    sesskey: Optional[str] = None,
) -> bool

Delete a category using form post or webservice.

Parameters:

Name	Type	Description	Default
session	Session	Authenticated requests session.	required
base_url	str	Base URL of the Moodle instance.	required
categoryid	int	ID of the category to delete.	required
token	Optional[str]	Webservice token (optional).	None
sesskey	Optional[str]	Session key (optional).	None

Returns:

Name	Type	Description
bool	bool	True if the deletion appears successful.

Raises:

Type	Description
ValueError	If neither sesskey nor token is provided.