User and Role Services

Domain services encapsulating the business logic for User and Role data models.

—

User Service (UserService)

class UserService

Bases: SQLAlchemyAsyncRepositoryService[User, Any]

Handles database operations for users.

default_role: ClassVar[str] = 'application-access'

async authenticate(username: str, password: str) → User

Authenticate a user.

Parameters:

• username (str) – User email.

• password (str) – User password.

Raises:

UnauthorizedException – If the user is not found, not verified, or inactive.

Returns:

The user object.

Return type:

User

async update_password(data: PasswordUpdate, user_id: UUID) → None

Modify the stored user password.

Parameters:

• data (PasswordUpdate) – The Pydantic schema with current and new passwords.

• user_id (UUID) – The unique ID of the target user.

Raises:

UnauthorizedException – If the current password is incorrect.

async get_and_validate_for_role_change(email: str) → User

Retrieve an active user by email for role modification.

Parameters:

email (str) – The email of the user whose role is being modified.

Returns:

The User model object from the database.

Return type:

User

Raises:

• UserNotFound – If no user is found with the given email.

• PermissionDeniedException – If the user is found but their account is inactive.

async get_users_paginated_dto(params: UserFilters) → OffsetPagination[UserDto]

Provide a filtered and paginated list of users with caching.

Role Service (RoleService)

class RoleService

Bases: SQLAlchemyAsyncRepositoryService[Role, Any]

Handles database operations for roles.

async get_id_and_slug_by_slug(slug: str) → Role

Retrieve the role object with column optimization.

async get_default_role(default_role_slug: str) → Role

Retrieve the default role object with column optimization.

Parameters:

default_role_slug (str) – The slug of the default role (e.g., ‘application-access’).

Returns:

A Role object (with id, name, and slug loaded).

Return type:

Role

Raises:

NotFoundError – Signals a critical infrastructure failure. This role is required, and its absence means that the initial database seeding did not complete.