users

models

User domain models.

class SearchVisibility

Bases: StrEnum

__new__(value)

class EmailPrivacy

Bases: StrEnum

__new__(value)

class MembershipType

Bases: StrEnum

__new__(value)

class UserGroupType

Bases: StrEnum

__new__(value)

class User

Bases: UUIDAuditBase

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at: Mapped[datetime.datetime]

Date/time of instance creation.

id: Mapped[UUID]

UUID Primary key column.

updated_at: Mapped[datetime.datetime]

Date/time of instance last update.

class Membership

Bases: UUIDAuditBase

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at: Mapped[datetime.datetime]

Date/time of instance creation.

id: Mapped[UUID]

UUID Primary key column.

updated_at: Mapped[datetime.datetime]

Date/time of instance last update.

class UserGroup

Bases: UUIDAuditBase

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

created_at: Mapped[datetime.datetime]

Date/time of instance creation.

id: Mapped[UUID]

UUID Primary key column.

updated_at: Mapped[datetime.datetime]

Date/time of instance last update.

schemas

User domain Pydantic schemas.

class UserBase

Bases: BaseModel

Base user schema with common fields.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class UserCreate

Bases: UserBase

Schema for creating a new user.

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'example': {'bio': 'Python creator and BDFL', 'email': 'guido@python.org', 'email_privacy': 'private', 'first_name': 'Guido', 'last_name': 'van Rossum', 'password': 'SecurePass123!', 'public_profile': True, 'search_visibility': 'public', 'username': 'guido_van_rossum'}}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class UserUpdate

Bases: BaseModel

Schema for updating an existing user.

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'example': {'bio': 'Python creator, former BDFL, now retired from leadership but still contributing to Python development', 'email_privacy': 'private', 'first_name': 'Guido', 'last_name': 'van Rossum', 'search_visibility': 'public'}}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class UserRead

Bases: UserBase

Schema for reading user data.

model_config: ClassVar[ConfigDict] = {'from_attributes': True, 'json_schema_extra': {'example': {'bio': 'Python creator and BDFL', 'created_at': '2025-01-15T10:30:00Z', 'date_joined': '2025-01-15T10:30:00Z', 'email': 'guido@python.org', 'email_privacy': 'private', 'first_name': 'Guido', 'id': '550e8400-e29b-41d4-a716-446655440000', 'is_active': True, 'is_staff': False, 'is_superuser': False, 'last_login': '2025-11-29T08:45:00Z', 'last_name': 'van Rossum', 'public_profile': True, 'search_visibility': 'public', 'updated_at': '2025-11-20T14:22:00Z', 'username': 'guido_van_rossum'}}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property full_name: str

Get the user’s full name.

class UserPublic

Bases: BaseModel

Public user schema with limited fields.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property full_name: str

Get the user’s full name.

class MembershipBase

Bases: BaseModel

Base membership schema.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class MembershipCreate

Bases: MembershipBase

Schema for creating a new membership.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class MembershipUpdate

Bases: BaseModel

Schema for updating a membership.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class MembershipRead

Bases: MembershipBase

Schema for reading membership data.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class UserGroupBase

Bases: BaseModel

Base user group schema.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class UserGroupCreate

Bases: UserGroupBase

Schema for creating a new user group.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class UserGroupUpdate

Bases: BaseModel

Schema for updating a user group.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class UserGroupRead

Bases: UserGroupBase

Schema for reading user group data.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class APIKeyCreate

Bases: BaseModel

Schema for creating a new API key.

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'example': {'description': 'API key for automated deployments', 'expires_in_days': 365, 'name': 'CI/CD Pipeline Key'}}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class APIKeyRead

Bases: BaseModel

Schema for reading API key data (without the actual key).

model_config: ClassVar[ConfigDict] = {'from_attributes': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class APIKeyCreated

Bases: APIKeyRead

Schema returned when creating a new API key (includes the raw key).

model_config: ClassVar[ConfigDict] = {'from_attributes': True, 'json_schema_extra': {'example': {'created_at': '2025-12-13T18:00:00Z', 'description': 'API key for automated deployments', 'expires_at': '2026-12-13T18:00:00Z', 'id': '550e8400-e29b-41d4-a716-446655440000', 'is_active': True, 'key': 'pyorg_abc123xyz789...', 'key_prefix': 'pyorg_abc123', 'last_used_at': None, 'name': 'CI/CD Pipeline Key', 'updated_at': '2025-12-13T18:00:00Z', 'user_id': '550e8400-e29b-41d4-a716-446655440001'}}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

services

User domain services for business logic.

class UserService

Bases: SQLAlchemyAsyncRepositoryService[User, Any]

Service for User business logic.

repository_type

alias of UserRepository

match_fields: ClassVar[Optional[Union[list[str], str]]] = ['email', 'username']

List of dialects that prefer to use field.id = ANY(:1) instead of field.id IN (...).

async create_user(data)

Create a new user with hashed password.

Parameters:

data (UserCreate) – User creation data including plain-text password.

Return type:

User

Returns:

The created user instance.

Raises:

ValueError – If email or username already exists.

async get_by_email(email)

Get a user by email address.

Parameters:

email (str) – The email address to search for.

Return type:

User | None

Returns:

The user if found, None otherwise.

async get_by_username(username)

Get a user by username.

Parameters:

username (str) – The username to search for.

Return type:

User | None

Returns:

The user if found, None otherwise.

async deactivate(user_id)

Deactivate a user account.

Parameters:

user_id (UUID) – The ID of the user to deactivate.

Return type:

User

Returns:

The updated user instance.

async reactivate(user_id)

Reactivate a user account.

Parameters:

user_id (UUID) – The ID of the user to reactivate.

Return type:

User

Returns:

The updated user instance.

class MembershipService

Bases: SQLAlchemyAsyncRepositoryService[Membership, Any]

Service for Membership business logic.

repository_type

alias of MembershipRepository

match_fields: ClassVar[Optional[Union[list[str], str]]] = ['user_id']

List of dialects that prefer to use field.id = ANY(:1) instead of field.id IN (...).

async get_by_user_id(user_id)

Get a membership by user ID.

Parameters:

user_id (UUID) – The user ID to search for.

Return type:

Membership | None

Returns:

The membership if found, None otherwise.

async create_for_user(user_id, membership_data)

Create a membership for a specific user.

Parameters:

• user_id (UUID) – The ID of the user to create membership for.

• membership_data (dict) – The membership data.

Return type:

Membership

Returns:

The created membership instance.

Raises:

ValueError – If user already has a membership.

class UserGroupService

Bases: SQLAlchemyAsyncRepositoryService[UserGroup, Any]

Service for UserGroup business logic.

repository_type

alias of UserGroupRepository

match_fields: ClassVar[Optional[Union[list[str], str]]] = ['name']

List of dialects that prefer to use field.id = ANY(:1) instead of field.id IN (...).

async list_approved(limit=100, offset=0)

List approved user groups.

Parameters:

• limit (int) – Maximum number of groups to return.

• offset (int) – Number of groups to skip.

Return type:

list[UserGroup]

Returns:

List of approved user groups.

async list_trusted(limit=100, offset=0)

List trusted user groups.

Parameters:

• limit (int) – Maximum number of groups to return.

• offset (int) – Number of groups to skip.

Return type:

list[UserGroup]

Returns:

List of trusted user groups.

async approve(group_id)

Approve a user group.

Parameters:

group_id (UUID) – The ID of the group to approve.

Return type:

UserGroup

Returns:

The updated group instance.

async revoke_approval(group_id)

Revoke approval of a user group.

Parameters:

group_id (UUID) – The ID of the group to revoke approval.

Return type:

UserGroup

Returns:

The updated group instance.

async mark_trusted(group_id)

Mark a user group as trusted.

Parameters:

group_id (UUID) – The ID of the group to mark as trusted.

Return type:

UserGroup

Returns:

The updated group instance.

async revoke_trust(group_id)

Revoke trust of a user group.

Parameters:

group_id (UUID) – The ID of the group to revoke trust.

Return type:

UserGroup

Returns:

The updated group instance.

class APIKeyService

Bases: SQLAlchemyAsyncRepositoryService[APIKey, Any]

Service for API key management.

repository_type

alias of APIKeyRepository

match_fields: ClassVar[Optional[Union[list[str], str]]] = ['key_hash']

List of dialects that prefer to use field.id = ANY(:1) instead of field.id IN (...).

async create_key(user_id, data)

Create a new API key for a user.

Parameters:

• user_id (UUID) – The user ID to create the key for.

• data (APIKeyCreate) – API key creation data.

Return type:

tuple[APIKey, str]

Returns:

Tuple of (APIKey instance, raw key string).

async list_by_user(user_id)

List all API keys for a user.

Parameters:

user_id (UUID) – The user ID.

Return type:

list[APIKey]

Returns:

List of API keys.

async list_active_by_user(user_id)

List active API keys for a user.

Parameters:

user_id (UUID) – The user ID.

Return type:

list[APIKey]

Returns:

List of active API keys.

async revoke(key_id)

Revoke an API key.

Parameters:

key_id (UUID) – The API key ID.

Return type:

APIKey

Returns:

The revoked API key.

async revoke_all_for_user(user_id)

Revoke all API keys for a user.

Parameters:

user_id (UUID) – The user ID.

Return type:

int

Returns:

Number of keys revoked.

controllers

User domain API controllers.

class UserController

Bases: Controller

Controller for User CRUD operations.

path: str

A path fragment for the controller.

All route handlers under the controller will have the fragment appended to them. If not set it defaults to /.

tags: Sequence[str] | None

A sequence of string tags that will be appended to the schema of all route handlers under the controller.

after_request: AfterRequestHookHandler | None

A sync or async function executed before a Request is passed to any route handler.

If this function returns a value, the request will not reach the route handler, and instead this value will be used.

after_response: AfterResponseHookHandler | None

A sync or async function called after the response has been awaited.

It receives the Request instance and should not return any values.

before_request: BeforeRequestHookHandler | None

A sync or async function called immediately before calling the route handler.

It receives the Request instance and any non-None return value is used for the response, bypassing the route handler.

cache_control: CacheControlHeader | None

A CacheControlHeader header to add to route handlers of this controller.

Can be overridden by route handlers.

dependencies: Dependencies | None

A string keyed dictionary of dependency Provider instances.

dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for (de)serializing and validation of request data.

etag: ETag | None

An etag header of type ETag to add to route handlers of this controller.

Can be overridden by route handlers.

exception_handlers: ExceptionHandlersMap | None

A map of handler functions to status codes and/or exception types.

guards: Sequence[Guard] | None

A sequence of Guard callables.

include_in_schema: bool | EmptyType

A boolean flag dictating whether the route handler should be documented in the OpenAPI schema

middleware: Sequence[Middleware] | None

A sequence of Middleware.

opt: Mapping[str, Any] | None

A string key mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.

owner: Router

The Router or Litestar app that owns the controller.

This value is set internally by Litestar and it should not be set when subclassing the controller.

parameters: ParametersMap | None

A mapping of Parameter definitions available to all application paths.

request_class: type[Request] | None

A custom subclass of Request to be used as the default request for all route handlers under the controller.

request_max_body_size: int | None | EmptyType

Maximum allowed size of the request body in bytes. If this size is exceeded, a ‘413 - Request Entity Too Large’ error response is returned.

response_class: type[Response] | None

A custom subclass of Response to be used as the default response for all route handlers under the controller.

response_cookies: ResponseCookies | None

A list of Cookie instances.

response_headers: ResponseHeaders | None

A string keyed dictionary mapping ResponseHeader instances.

return_dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for serializing outbound response data.

security: Sequence[SecurityRequirement] | None

A sequence of dictionaries that to the schema of all route handlers under the controller.

signature_namespace: dict[str, Any]

A mapping of names to types for use in forward reference resolution during signature modelling.

signature_types: Sequence[Any]

A sequence of types for use in forward reference resolution during signature modelling.

These types will be added to the signature namespace using their __name__ attribute.

type_decoders: TypeDecodersSequence | None

A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.

type_encoders: TypeEncodersMap | None

A mapping of types to callables that transform them into types supported for serialization.

websocket_class: type[WebSocket] | None

A custom subclass of WebSocket to be used as the default websocket for all route handlers under the controller.

class MembershipController

Bases: Controller

Controller for Membership CRUD operations.

path: str

A path fragment for the controller.

All route handlers under the controller will have the fragment appended to them. If not set it defaults to /.

tags: Sequence[str] | None

A sequence of string tags that will be appended to the schema of all route handlers under the controller.

after_request: AfterRequestHookHandler | None

A sync or async function executed before a Request is passed to any route handler.

If this function returns a value, the request will not reach the route handler, and instead this value will be used.

after_response: AfterResponseHookHandler | None

A sync or async function called after the response has been awaited.

It receives the Request instance and should not return any values.

before_request: BeforeRequestHookHandler | None

A sync or async function called immediately before calling the route handler.

It receives the Request instance and any non-None return value is used for the response, bypassing the route handler.

cache_control: CacheControlHeader | None

A CacheControlHeader header to add to route handlers of this controller.

Can be overridden by route handlers.

dependencies: Dependencies | None

A string keyed dictionary of dependency Provider instances.

dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for (de)serializing and validation of request data.

etag: ETag | None

An etag header of type ETag to add to route handlers of this controller.

Can be overridden by route handlers.

exception_handlers: ExceptionHandlersMap | None

A map of handler functions to status codes and/or exception types.

guards: Sequence[Guard] | None

A sequence of Guard callables.

include_in_schema: bool | EmptyType

A boolean flag dictating whether the route handler should be documented in the OpenAPI schema

middleware: Sequence[Middleware] | None

A sequence of Middleware.

opt: Mapping[str, Any] | None

A string key mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.

owner: Router

The Router or Litestar app that owns the controller.

This value is set internally by Litestar and it should not be set when subclassing the controller.

parameters: ParametersMap | None

A mapping of Parameter definitions available to all application paths.

request_class: type[Request] | None

A custom subclass of Request to be used as the default request for all route handlers under the controller.

request_max_body_size: int | None | EmptyType

Maximum allowed size of the request body in bytes. If this size is exceeded, a ‘413 - Request Entity Too Large’ error response is returned.

response_class: type[Response] | None

A custom subclass of Response to be used as the default response for all route handlers under the controller.

response_cookies: ResponseCookies | None

A list of Cookie instances.

response_headers: ResponseHeaders | None

A string keyed dictionary mapping ResponseHeader instances.

return_dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for serializing outbound response data.

security: Sequence[SecurityRequirement] | None

A sequence of dictionaries that to the schema of all route handlers under the controller.

signature_namespace: dict[str, Any]

A mapping of names to types for use in forward reference resolution during signature modelling.

signature_types: Sequence[Any]

A sequence of types for use in forward reference resolution during signature modelling.

These types will be added to the signature namespace using their __name__ attribute.

type_decoders: TypeDecodersSequence | None

A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.

type_encoders: TypeEncodersMap | None

A mapping of types to callables that transform them into types supported for serialization.

websocket_class: type[WebSocket] | None

A custom subclass of WebSocket to be used as the default websocket for all route handlers under the controller.

class UserGroupController

Bases: Controller

Controller for UserGroup CRUD operations.

path: str

A path fragment for the controller.

All route handlers under the controller will have the fragment appended to them. If not set it defaults to /.

tags: Sequence[str] | None

A sequence of string tags that will be appended to the schema of all route handlers under the controller.

after_request: AfterRequestHookHandler | None

A sync or async function executed before a Request is passed to any route handler.

If this function returns a value, the request will not reach the route handler, and instead this value will be used.

after_response: AfterResponseHookHandler | None

A sync or async function called after the response has been awaited.

It receives the Request instance and should not return any values.

before_request: BeforeRequestHookHandler | None

A sync or async function called immediately before calling the route handler.

It receives the Request instance and any non-None return value is used for the response, bypassing the route handler.

cache_control: CacheControlHeader | None

A CacheControlHeader header to add to route handlers of this controller.

Can be overridden by route handlers.

dependencies: Dependencies | None

A string keyed dictionary of dependency Provider instances.

dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for (de)serializing and validation of request data.

etag: ETag | None

An etag header of type ETag to add to route handlers of this controller.

Can be overridden by route handlers.

exception_handlers: ExceptionHandlersMap | None

A map of handler functions to status codes and/or exception types.

guards: Sequence[Guard] | None

A sequence of Guard callables.

include_in_schema: bool | EmptyType

A boolean flag dictating whether the route handler should be documented in the OpenAPI schema

middleware: Sequence[Middleware] | None

A sequence of Middleware.

opt: Mapping[str, Any] | None

A string key mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.

owner: Router

The Router or Litestar app that owns the controller.

This value is set internally by Litestar and it should not be set when subclassing the controller.

parameters: ParametersMap | None

A mapping of Parameter definitions available to all application paths.

request_class: type[Request] | None

A custom subclass of Request to be used as the default request for all route handlers under the controller.

request_max_body_size: int | None | EmptyType

Maximum allowed size of the request body in bytes. If this size is exceeded, a ‘413 - Request Entity Too Large’ error response is returned.

response_class: type[Response] | None

A custom subclass of Response to be used as the default response for all route handlers under the controller.

response_cookies: ResponseCookies | None

A list of Cookie instances.

response_headers: ResponseHeaders | None

A string keyed dictionary mapping ResponseHeader instances.

return_dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for serializing outbound response data.

security: Sequence[SecurityRequirement] | None

A sequence of dictionaries that to the schema of all route handlers under the controller.

signature_namespace: dict[str, Any]

A mapping of names to types for use in forward reference resolution during signature modelling.

signature_types: Sequence[Any]

A sequence of types for use in forward reference resolution during signature modelling.

These types will be added to the signature namespace using their __name__ attribute.

type_decoders: TypeDecodersSequence | None

A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.

type_encoders: TypeEncodersMap | None

A mapping of types to callables that transform them into types supported for serialization.

websocket_class: type[WebSocket] | None

A custom subclass of WebSocket to be used as the default websocket for all route handlers under the controller.

class APIKeyController

Bases: Controller

Controller for API key management.

API keys allow programmatic access to the API. Users can create multiple keys with optional expiration dates. Keys are shown only once at creation time.

path: str

A path fragment for the controller.

All route handlers under the controller will have the fragment appended to them. If not set it defaults to /.

tags: Sequence[str] | None

A sequence of string tags that will be appended to the schema of all route handlers under the controller.

guards: Sequence[Guard] | None

A sequence of Guard callables.

after_request: AfterRequestHookHandler | None

A sync or async function executed before a Request is passed to any route handler.

If this function returns a value, the request will not reach the route handler, and instead this value will be used.

after_response: AfterResponseHookHandler | None

A sync or async function called after the response has been awaited.

It receives the Request instance and should not return any values.

before_request: BeforeRequestHookHandler | None

A sync or async function called immediately before calling the route handler.

It receives the Request instance and any non-None return value is used for the response, bypassing the route handler.

cache_control: CacheControlHeader | None

A CacheControlHeader header to add to route handlers of this controller.

Can be overridden by route handlers.

dependencies: Dependencies | None

A string keyed dictionary of dependency Provider instances.

dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for (de)serializing and validation of request data.

etag: ETag | None

An etag header of type ETag to add to route handlers of this controller.

Can be overridden by route handlers.

exception_handlers: ExceptionHandlersMap | None

A map of handler functions to status codes and/or exception types.

include_in_schema: bool | EmptyType

A boolean flag dictating whether the route handler should be documented in the OpenAPI schema

middleware: Sequence[Middleware] | None

A sequence of Middleware.

opt: Mapping[str, Any] | None

A string key mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.

owner: Router

The Router or Litestar app that owns the controller.

This value is set internally by Litestar and it should not be set when subclassing the controller.

parameters: ParametersMap | None

A mapping of Parameter definitions available to all application paths.

request_class: type[Request] | None

A custom subclass of Request to be used as the default request for all route handlers under the controller.

request_max_body_size: int | None | EmptyType

Maximum allowed size of the request body in bytes. If this size is exceeded, a ‘413 - Request Entity Too Large’ error response is returned.

response_class: type[Response] | None

A custom subclass of Response to be used as the default response for all route handlers under the controller.

response_cookies: ResponseCookies | None

A list of Cookie instances.

response_headers: ResponseHeaders | None

A string keyed dictionary mapping ResponseHeader instances.

return_dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for serializing outbound response data.

security: Sequence[SecurityRequirement] | None

A sequence of dictionaries that to the schema of all route handlers under the controller.

signature_namespace: dict[str, Any]

A mapping of names to types for use in forward reference resolution during signature modelling.

signature_types: Sequence[Any]

A sequence of types for use in forward reference resolution during signature modelling.

These types will be added to the signature namespace using their __name__ attribute.

type_decoders: TypeDecodersSequence | None

A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.

type_encoders: TypeEncodersMap | None

A mapping of types to callables that transform them into types supported for serialization.

websocket_class: type[WebSocket] | None

A custom subclass of WebSocket to be used as the default websocket for all route handlers under the controller.

repositories

User domain repositories for database access.

class UserRepository

Bases: SQLAlchemyAsyncRepository[User]

Repository for User database operations.

model_type

alias of User

async get_by_email(email)

Get a user by email address.

Parameters:

email (str) – The email address to search for.

Return type:

User | None

Returns:

The user if found, None otherwise.

async get_by_username(username)

Get a user by username.

Parameters:

username (str) – The username to search for.

Return type:

User | None

Returns:

The user if found, None otherwise.

async exists_by_email(email)

Check if a user exists by email.

Parameters:

email (str) – The email address to check.

Return type:

bool

Returns:

True if a user with this email exists, False otherwise.

async exists_by_username(username)

Check if a user exists by username.

Parameters:

username (str) – The username to check.

Return type:

bool

Returns:

True if a user with this username exists, False otherwise.

class MembershipRepository

Bases: SQLAlchemyAsyncRepository[Membership]

Repository for Membership database operations.

model_type

alias of Membership

async get_by_user_id(user_id)

Get a membership by user ID.

Parameters:

user_id (UUID) – The user ID to search for.

Return type:

Membership | None

Returns:

The membership if found, None otherwise.

class UserGroupRepository

Bases: SQLAlchemyAsyncRepository[UserGroup]

Repository for UserGroup database operations.

model_type

alias of UserGroup

async list_approved(limit=100, offset=0)

List approved user groups.

Parameters:

• limit (int) – Maximum number of groups to return.

• offset (int) – Number of groups to skip.

Return type:

list[UserGroup]

Returns:

List of approved user groups.

async list_trusted(limit=100, offset=0)

List trusted user groups.

Parameters:

• limit (int) – Maximum number of groups to return.

• offset (int) – Number of groups to skip.

Return type:

list[UserGroup]

Returns:

List of trusted user groups.

class APIKeyRepository

Bases: SQLAlchemyAsyncRepository[APIKey]

Repository for API key database operations.

model_type

alias of APIKey

async get_by_hash(key_hash)

Get an API key by its hash.

Parameters:

key_hash (str) – The SHA-256 hash of the API key.

Return type:

APIKey | None

Returns:

The API key if found, None otherwise.

async get_by_prefix(key_prefix)

Get an API key by its prefix.

Parameters:

key_prefix (str) – The first 12 characters of the key.

Return type:

APIKey | None

Returns:

The API key if found, None otherwise.

async list_by_user(user_id)

List all API keys for a user.

Parameters:

user_id (UUID) – The user ID.

Return type:

list[APIKey]

Returns:

List of API keys.

async list_active_by_user(user_id)

List active API keys for a user.

Parameters:

user_id (UUID) – The user ID.

Return type:

list[APIKey]

Returns:

List of active API keys.

async revoke_all_for_user(user_id)

Revoke all API keys for a user.

Parameters:

user_id (UUID) – The user ID.

Return type:

int

Returns:

Number of keys revoked.