Categories

Accessed via client.categories.

pycomad.client.CategoriesClient

CategoriesClient(http: _HttpSession)

Methods for the /categories resource.

list

list() -> List[Category]

Return all categories.

Returns:

Type	Description
List[Category]	List of :class:~pycomad.models.Category objects.

Raises:

Type	Description
ComadAuthError	If not authenticated.

create

create(name: str, *, description: Optional[str] = None, parent_id: Optional[Union[UUID, str]] = None, access_level: Optional[Union[AccessLevel, str]] = None, creator: Optional[str] = None) -> Category

Create a category.

Parameters:

Name	Type	Description	Default
name	str	Category name.	required
description	Optional[str]	Optional description.	None
parent_id	Optional[Union[UUID, str]]	UUID of the parent category for a sub-category.	None
access_level	Optional[Union[AccessLevel, str]]	"Private" (default), "Group", or "Global".	None
creator	Optional[str]	Username of the creator (informational).	None

Returns:

Type	Description
Category	The newly created :class:~pycomad.models.Category.

Raises:

Type	Description
ComadAuthError	If not authenticated.
ComadValidationError	On a 400 response (e.g. parent not found).

get

get(category_id: Union[UUID, str]) -> CategoryWithChildren

Fetch a category with its direct sub-categories.

Parameters:

Name	Type	Description	Default
category_id	Union[UUID, str]	UUID of the category.	required

Returns:

Type	Description
CategoryWithChildren	class:~pycomad.models.CategoryWithChildren.

Raises:

Type	Description
ComadNotFoundError	If the category does not exist.
ComadAuthError	If not authenticated.

update

update(category_id: Union[UUID, str], *, name: Optional[str] = None, description: Optional[str] = None, parent_id: Optional[Union[UUID, str]] = None, access_level: Optional[Union[AccessLevel, str]] = None, creator: Optional[str] = None) -> Category

Update a category; only supplied fields are changed.

Parameters:

Name	Type	Description	Default
category_id	Union[UUID, str]	UUID of the category to update.	required
name	Optional[str]	New name.	None
description	Optional[str]	New description.	None
parent_id	Optional[Union[UUID, str]]	New parent category UUID.	None
access_level	Optional[Union[AccessLevel, str]]	New access level.	None
creator	Optional[str]	New creator username.	None

Returns:

Type	Description
Category	The updated :class:~pycomad.models.Category.

Raises:

Type	Description
ComadNotFoundError	If the category does not exist.
ComadValidationError	On a 400 response (e.g. self-referential parent).
ComadAuthError	If not authenticated.

delete

delete(category_id: Union[UUID, str]) -> None

Delete a category.

Parameters:

Name	Type	Description	Default
category_id	Union[UUID, str]	UUID of the category to delete.	required

Raises:

Type	Description
ComadNotFoundError	If the category does not exist.
ComadAuthError	If not authenticated.