Nominations ¶

Returns:

List of active elections.

async get_by_slug(slug)[source]

Get an election by slug.

Parameters:: slug (str) – The slug to search for.
Return type:: Election | None
Returns:: The election if found, None otherwise.

async get_by_status(status, limit=100, offset=0)[source]

Get elections by status.

Parameters:

status (ElectionStatus) – The election status to filter by.
limit (int) – Maximum number of elections to return.
offset (int) – Number of elections to skip.

Return type:

Returns:

List of elections with the specified status.

model_type: alias of Election

class ElectionService[source]

Bases: SQLAlchemyAsyncRepositoryService[Election, Any]

Service for Election business logic.

async create_election(data)[source]

Create a new election.

Parameters:: data (ElectionCreate) – Election creation data.
Return type:: Election
Returns:: The created election instance.

async get_active_elections(limit=100, offset=0)[source]

Get elections that are currently active.

Parameters:

limit (int) – Maximum number of elections to return.
offset (int) – Number of elections to skip.

Return type:

Returns:

List of active elections.

async get_by_slug(slug)[source]

Get an election by slug.

Parameters:: slug (str) – The slug to search for.
Return type:: Election | None
Returns:: The election if found, None otherwise.

async get_by_status(status, limit=100, offset=0)[source]

Get elections by status.

Parameters:

status (ElectionStatus) – The election status to filter by.
limit (int) – Maximum number of elections to return.
offset (int) – Number of elections to skip.

Return type:

Returns:

List of elections with the specified status.

match_fields: ClassVar[Optional[Union[list[str], str]]] = ['slug']: List of dialects that prefer to use field.id = ANY(:1) instead of field.id IN (...).

repository_type: alias of ElectionRepository

class ElectionStatus[source]

Bases: StrEnum

__new__(value)

UPCOMING = 'upcoming'

NOMINATIONS_OPEN = 'nominations_open'

VOTING_OPEN = 'voting_open'

CLOSED = 'closed'

class ElectionUpdate[source]

Bases: BaseModel

Schema for updating an election.

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: Annotated[str, Field(max_length=200)] | None

description: str | None

nominations_open: datetime.date | None

nominations_close: datetime.date | None

voting_open: datetime.date | None

voting_close: datetime.date | None

slug: Annotated[str, Field(max_length=200)] | None

class Nomination[source]

Bases: AuditBase

__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.

endorsement: Mapped[str | None]

id: Mapped[UUID]: UUID Primary key column.

nominator: Mapped[User]

nominator_id: Mapped[UUID]

nominee: Mapped[Nominee]

nominee_id: Mapped[UUID]

updated_at: Mapped[datetime.datetime]: Date/time of instance last update.

class NominationController[source]

Bases: Controller

Controller for Nomination CRUD operations.

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.

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 /.

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.

tags: Sequence[str] | None: A sequence of string tags that will be appended to the schema of all route handlers under the controller.

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.

create_nomination(fn) = <litestar.handlers.http_handlers.decorators.post object>

delete_nomination(fn) = <litestar.handlers.http_handlers.decorators.delete object>

get_nomination(fn) = <litestar.handlers.http_handlers.decorators.get object>

list_nominations(fn) = <litestar.handlers.http_handlers.decorators.get object>

class NominationCreate[source]

Bases: NominationBase

Schema for creating a new nomination.

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class NominationRead[source]

Bases: NominationBase

Schema for reading nomination data.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: UUID

nominator_id: UUID

created_at: datetime.datetime

updated_at: datetime.datetime

class NominationRepository[source]

Bases: SQLAlchemyAsyncRepository[Nomination]

Repository for Nomination database operations.

async count_by_nominee(nominee_id)[source]

Count nominations for a nominee.

Parameters:: nominee_id (UUID) – The nominee ID.
Return type:: int
Returns:: Number of nominations for the nominee.

async get_by_nominator(nominator_id, limit=100, offset=0)[source]

Get nominations by nominator.

Parameters:

nominator_id (UUID) – The nominator user ID.
limit (int) – Maximum number of nominations to return.
offset (int) – Number of nominations to skip.

Return type:

Returns:

List of nominations by the nominator.

async get_by_nominee(nominee_id, limit=100, offset=0)[source]

Get nominations for a nominee.

Parameters:

nominee_id (UUID) – The nominee ID.
limit (int) – Maximum number of nominations to return.
offset (int) – Number of nominations to skip.

Return type:

Returns:

List of nominations for the nominee.

model_type: alias of Nomination

class NominationService[source]

Bases: SQLAlchemyAsyncRepositoryService[Nomination, Any]

Service for Nomination business logic.

async count_by_nominee(nominee_id)[source]

Count nominations for a nominee.

Parameters:: nominee_id (UUID) – The nominee ID.
Return type:: int
Returns:: Number of nominations for the nominee.

async create_nomination(nominee_id, nominator_id, endorsement=None)[source]

Create a new nomination.

Parameters:

nominee_id (UUID) – The nominee ID.
nominator_id (UUID) – The nominator user ID.
endorsement (str | None) – Optional endorsement text.

Return type:

Nomination

Returns:

The created nomination instance.

async get_by_nominator(nominator_id, limit=100, offset=0)[source]

Get nominations by nominator.

Parameters:

nominator_id (UUID) – The nominator user ID.
limit (int) – Maximum number of nominations to return.
offset (int) – Number of nominations to skip.

Return type:

Returns:

List of nominations by the nominator.

async get_by_nominee(nominee_id, limit=100, offset=0)[source]

Get nominations for a nominee.

Parameters:

nominee_id (UUID) – The nominee ID.
limit (int) – Maximum number of nominations to return.
offset (int) – Number of nominations to skip.

Return type:

Returns:

List of nominations for the nominee.

repository_type: alias of NominationRepository

class NominationUpdate[source]

Bases: BaseModel

Schema for updating a nomination.

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

endorsement: str | None

class NominationsHTMXController[source]

Bases: Controller

HTMX controller for nominations form submissions.

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.

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 /.

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.

tags: Sequence[str] | None: A sequence of string tags that will be appended to the schema of all route handlers under the controller.

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.

nominate_candidate(fn) = <litestar.handlers.http_handlers.decorators.post object>

class NominationsRenderController[source]

Bases: Controller

Controller for rendering nominations as HTML.

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.

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 /.

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.

tags: Sequence[str] | None: A sequence of string tags that will be appended to the schema of all route handlers under the controller.

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.

get_election_html(fn) = <litestar.handlers.http_handlers.decorators.get object>

list_elections_html(fn) = <litestar.handlers.http_handlers.decorators.get object>

class Nominee[source]

Bases: AuditBase

__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.

accepted: Mapped[bool]

created_at: Mapped[datetime.datetime]: Date/time of instance creation.

election: Mapped[Election]

election_id: Mapped[UUID]

id: Mapped[UUID]: UUID Primary key column.

nominations: Mapped[list[Nomination]]

updated_at: Mapped[datetime.datetime]: Date/time of instance last update.

user: Mapped[User]

user_id: Mapped[UUID]

class NomineeController[source]

Bases: Controller

Controller for Nominee CRUD operations.

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.

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 /.

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.

tags: Sequence[str] | None: A sequence of string tags that will be appended to the schema of all route handlers under the controller.

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.

accept_nomination(fn) = <litestar.handlers.http_handlers.decorators.patch object>

create_nominee(fn) = <litestar.handlers.http_handlers.decorators.post object>

decline_nomination(fn) = <litestar.handlers.http_handlers.decorators.patch object>

delete_nominee(fn) = <litestar.handlers.http_handlers.decorators.delete object>

get_nominee(fn) = <litestar.handlers.http_handlers.decorators.get object>

list_accepted_nominees(fn) = <litestar.handlers.http_handlers.decorators.get object>

list_nominees(fn) = <litestar.handlers.http_handlers.decorators.get object>

class NomineeCreate[source]

Bases: NomineeBase

Schema for creating a new nominee.

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class NomineePublic[source]

Bases: BaseModel

Public nominee schema for listings.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: UUID

election_id: UUID

user_id: UUID

accepted: bool

class NomineeRead[source]

Bases: NomineeBase

Schema for reading nominee data.

model_config: ClassVar[ConfigDict] = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: UUID

accepted: bool

created_at: datetime.datetime

updated_at: datetime.datetime

class NomineeRepository[source]

Bases: SQLAlchemyAsyncRepository[Nominee]

Repository for Nominee database operations.

async get_accepted_nominees(election_id, limit=100, offset=0)[source]

Get accepted nominees for an election.

Parameters:

election_id (UUID) – The election ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of accepted nominees.

async get_by_election(election_id, limit=100, offset=0)[source]

Get nominees for an election.

Parameters:

election_id (UUID) – The election ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of nominees for the election.

async get_by_election_and_user(election_id, user_id)[source]

Get a nominee by election and user.

Parameters:

election_id (UUID) – The election ID.
user_id (UUID) – The user ID.

Return type:

Nominee | None

Returns:

The nominee if found, None otherwise.

async get_by_user(user_id, limit=100, offset=0)[source]

Get nominees by user.

Parameters:

user_id (UUID) – The user ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of nominees for the user.

model_type: alias of Nominee

class NomineeService[source]

Bases: SQLAlchemyAsyncRepositoryService[Nominee, Any]

Service for Nominee business logic.

async accept_nomination(nominee_id)[source]

Accept a nomination.

Parameters:: nominee_id (UUID) – The nominee ID.
Return type:: Nominee
Returns:: The updated nominee instance.
Raises:: ValueError – If nominee is already accepted.

async create_nominee(election_id, user_id)[source]

Create a new nominee.

Parameters:

election_id (UUID) – The election ID.
user_id (UUID) – The user ID to nominate.

Return type:

Nominee

Returns:

The created nominee instance.

Raises:

ValueError – If nominee already exists.

async decline_nomination(nominee_id)[source]

Decline a nomination by deleting the nominee.

Parameters:: nominee_id (UUID) – The nominee ID.
Return type:: None

async get_accepted_nominees(election_id, limit=100, offset=0)[source]

Get accepted nominees for an election.

Parameters:

election_id (UUID) – The election ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of accepted nominees.

async get_by_election(election_id, limit=100, offset=0)[source]

Get nominees for an election.

Parameters:

election_id (UUID) – The election ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of nominees for the election.

async get_by_user(user_id, limit=100, offset=0)[source]

Get nominees by user.

Parameters:

user_id (UUID) – The user ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of nominees for the user.

repository_type: alias of NomineeRepository

class NomineeUpdate[source]

Bases: BaseModel

Schema for updating a nominee.

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

accepted: bool | None

get_nominations_dependencies()[source]

Get all nominations domain dependency providers.

Return type:: dict

Models¶

Nominations domain models.

class ElectionStatus[source]¶

Bases: StrEnum

UPCOMING = 'upcoming'¶

NOMINATIONS_OPEN = 'nominations_open'¶

VOTING_OPEN = 'voting_open'¶

CLOSED = 'closed'¶

__new__(value)¶

class Election[source]¶

Bases: AuditBase, SlugMixin

name: Mapped[str]¶

description: Mapped[str | None]¶

nominations_open: Mapped[datetime.date]¶

nominations_close: Mapped[datetime.date]¶

voting_open: Mapped[datetime.date]¶

voting_close: Mapped[datetime.date]¶

nominees: Mapped[list[Nominee]]¶

property status: ElectionStatus¶

__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.

slug: Mapped[str]¶

updated_at: Mapped[datetime.datetime]¶: Date/time of instance last update.

class Nominee[source]¶

Bases: AuditBase

election_id: Mapped[UUID]¶

user_id: Mapped[UUID]¶

accepted: Mapped[bool]¶

election: Mapped[Election]¶

user: Mapped[User]¶

nominations: Mapped[list[Nomination]]¶

__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 Nomination[source]¶

Bases: AuditBase

nominee_id: Mapped[UUID]¶

nominator_id: Mapped[UUID]¶

endorsement: Mapped[str | None]¶

nominee: Mapped[Nominee]¶

nominator: Mapped[User]¶

__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¶

Nominations domain Pydantic schemas.

class ElectionBase[source]¶

Bases: BaseModel

Base election schema.

name: Annotated[str, Field(max_length=200)]¶

description: str | None¶

nominations_open: datetime.date¶

nominations_close: datetime.date¶

voting_open: datetime.date¶

voting_close: datetime.date¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ElectionCreate[source]¶

Bases: ElectionBase

Schema for creating a new election.

slug: Annotated[str, Field(max_length=200)] | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: Annotated[str, Field(max_length=200)]¶

description: str | None¶

nominations_open: datetime.date¶

nominations_close: datetime.date¶

voting_open: datetime.date¶

voting_close: datetime.date¶

class ElectionUpdate[source]¶

Bases: BaseModel

Schema for updating an election.

name: Annotated[str, Field(max_length=200)] | None¶

description: str | None¶

nominations_open: datetime.date | None¶

nominations_close: datetime.date | None¶

voting_open: datetime.date | None¶

voting_close: datetime.date | None¶

slug: Annotated[str, Field(max_length=200)] | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ElectionRead[source]¶

Bases: ElectionBase

Schema for reading election data.

id: UUID¶

slug: str¶

created_at: datetime.datetime¶

updated_at: datetime.datetime¶

status: ElectionStatus¶

model_config: ClassVar[ConfigDict] = {'from_attributes': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: Annotated[str, Field(max_length=200)]¶

description: str | None¶

nominations_open: datetime.date¶

nominations_close: datetime.date¶

voting_open: datetime.date¶

voting_close: datetime.date¶

class NomineeBase[source]¶

Bases: BaseModel

Base nominee schema.

election_id: UUID¶

user_id: UUID¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class NomineeCreate[source]¶

Bases: NomineeBase

Schema for creating a new nominee.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

election_id: UUID¶

user_id: UUID¶

class NomineeUpdate[source]¶

Bases: BaseModel

Schema for updating a nominee.

accepted: bool | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class NomineeRead[source]¶

Bases: NomineeBase

Schema for reading nominee data.

id: UUID¶

accepted: bool¶

created_at: datetime.datetime¶

updated_at: datetime.datetime¶

model_config: ClassVar[ConfigDict] = {'from_attributes': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

election_id: UUID¶

user_id: UUID¶

class NominationBase[source]¶

Bases: BaseModel

Base nomination schema.

nominee_id: UUID¶

endorsement: str | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class NominationCreate[source]¶

Bases: NominationBase

Schema for creating a new nomination.

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

nominee_id: UUID¶

endorsement: str | None¶

class NominationUpdate[source]¶

Bases: BaseModel

Schema for updating a nomination.

endorsement: str | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class NominationRead[source]¶

Bases: NominationBase

Schema for reading nomination data.

id: UUID¶

nominator_id: UUID¶

created_at: datetime.datetime¶

updated_at: datetime.datetime¶

model_config: ClassVar[ConfigDict] = {'from_attributes': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

nominee_id: UUID¶

endorsement: str | None¶

class ElectionPublic[source]¶

Bases: BaseModel

Public election schema for listings.

id: UUID¶

slug: str¶

name: str¶

description: str | None¶

nominations_open: datetime.date¶

nominations_close: datetime.date¶

voting_open: datetime.date¶

voting_close: datetime.date¶

status: ElectionStatus¶

model_config: ClassVar[ConfigDict] = {'from_attributes': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class NomineePublic[source]¶

Bases: BaseModel

Public nominee schema for listings.

id: UUID¶

election_id: UUID¶

user_id: UUID¶

accepted: bool¶

model_config: ClassVar[ConfigDict] = {'from_attributes': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Repositories¶

Nominations domain repositories for database access.

class ElectionRepository[source]¶

Bases: SQLAlchemyAsyncRepository[Election]

Repository for Election database operations.

model_type¶: alias of Election

async get_by_slug(slug)[source]¶

Get an election by slug.

Parameters:: slug (str) – The slug to search for.
Return type:: Election | None
Returns:: The election if found, None otherwise.

async get_active_elections(limit=100, offset=0)[source]¶

Get elections that are currently active.

Parameters:

limit (int) – Maximum number of elections to return.
offset (int) – Number of elections to skip.

Return type:

Returns:

List of active elections.

async get_by_status(status, limit=100, offset=0)[source]¶

Get elections by status.

Parameters:

status (ElectionStatus) – The election status to filter by.
limit (int) – Maximum number of elections to return.
offset (int) – Number of elections to skip.

Return type:

Returns:

List of elections with the specified status.

class NomineeRepository[source]¶

Bases: SQLAlchemyAsyncRepository[Nominee]

Repository for Nominee database operations.

model_type¶: alias of Nominee

async get_by_election(election_id, limit=100, offset=0)[source]¶

Get nominees for an election.

Parameters:

election_id (UUID) – The election ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of nominees for the election.

async get_by_user(user_id, limit=100, offset=0)[source]¶

Get nominees by user.

Parameters:

user_id (UUID) – The user ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of nominees for the user.

async get_accepted_nominees(election_id, limit=100, offset=0)[source]¶

Get accepted nominees for an election.

Parameters:

election_id (UUID) – The election ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of accepted nominees.

async get_by_election_and_user(election_id, user_id)[source]¶

Get a nominee by election and user.

Parameters:

election_id (UUID) – The election ID.
user_id (UUID) – The user ID.

Return type:

Nominee | None

Returns:

The nominee if found, None otherwise.

class NominationRepository[source]¶

Bases: SQLAlchemyAsyncRepository[Nomination]

Repository for Nomination database operations.

model_type¶: alias of Nomination

async get_by_nominee(nominee_id, limit=100, offset=0)[source]¶

Get nominations for a nominee.

Parameters:

nominee_id (UUID) – The nominee ID.
limit (int) – Maximum number of nominations to return.
offset (int) – Number of nominations to skip.

Return type:

Returns:

List of nominations for the nominee.

async get_by_nominator(nominator_id, limit=100, offset=0)[source]¶

Get nominations by nominator.

Parameters:

nominator_id (UUID) – The nominator user ID.
limit (int) – Maximum number of nominations to return.
offset (int) – Number of nominations to skip.

Return type:

Returns:

List of nominations by the nominator.

async count_by_nominee(nominee_id)[source]¶

Count nominations for a nominee.

Parameters:: nominee_id (UUID) – The nominee ID.
Return type:: int
Returns:: Number of nominations for the nominee.

Services¶

Nominations domain services for business logic.

class ElectionService[source]¶

Bases: SQLAlchemyAsyncRepositoryService[Election, Any]

Service for Election business logic.

repository_type¶: alias of ElectionRepository

match_fields: ClassVar[Optional[Union[list[str], str]]] = ['slug']¶: List of dialects that prefer to use field.id = ANY(:1) instead of field.id IN (...).

async create_election(data)[source]¶

Create a new election.

Parameters:: data (ElectionCreate) – Election creation data.
Return type:: Election
Returns:: The created election instance.

async get_by_slug(slug)[source]¶

Get an election by slug.

Parameters:: slug (str) – The slug to search for.
Return type:: Election | None
Returns:: The election if found, None otherwise.

async get_active_elections(limit=100, offset=0)[source]¶

Get elections that are currently active.

Parameters:

limit (int) – Maximum number of elections to return.
offset (int) – Number of elections to skip.

Return type:

Returns:

List of active elections.

async get_by_status(status, limit=100, offset=0)[source]¶

Get elections by status.

Parameters:

status (ElectionStatus) – The election status to filter by.
limit (int) – Maximum number of elections to return.
offset (int) – Number of elections to skip.

Return type:

Returns:

List of elections with the specified status.

class NomineeService[source]¶

Bases: SQLAlchemyAsyncRepositoryService[Nominee, Any]

Service for Nominee business logic.

repository_type¶: alias of NomineeRepository

async create_nominee(election_id, user_id)[source]¶

Create a new nominee.

Parameters:

election_id (UUID) – The election ID.
user_id (UUID) – The user ID to nominate.

Return type:

Nominee

Returns:

The created nominee instance.

Raises:

ValueError – If nominee already exists.

async accept_nomination(nominee_id)[source]¶

Accept a nomination.

Parameters:: nominee_id (UUID) – The nominee ID.
Return type:: Nominee
Returns:: The updated nominee instance.
Raises:: ValueError – If nominee is already accepted.

async decline_nomination(nominee_id)[source]¶

Decline a nomination by deleting the nominee.

Parameters:: nominee_id (UUID) – The nominee ID.
Return type:: None

async get_by_election(election_id, limit=100, offset=0)[source]¶

Get nominees for an election.

Parameters:

election_id (UUID) – The election ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of nominees for the election.

async get_by_user(user_id, limit=100, offset=0)[source]¶

Get nominees by user.

Parameters:

user_id (UUID) – The user ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of nominees for the user.

async get_accepted_nominees(election_id, limit=100, offset=0)[source]¶

Get accepted nominees for an election.

Parameters:

election_id (UUID) – The election ID.
limit (int) – Maximum number of nominees to return.
offset (int) – Number of nominees to skip.

Return type:

Returns:

List of accepted nominees.

class NominationService[source]¶

Bases: SQLAlchemyAsyncRepositoryService[Nomination, Any]

Service for Nomination business logic.

repository_type¶: alias of NominationRepository

async create_nomination(nominee_id, nominator_id, endorsement=None)[source]¶

Create a new nomination.

Parameters:

nominee_id (UUID) – The nominee ID.
nominator_id (UUID) – The nominator user ID.
endorsement (str | None) – Optional endorsement text.

Return type:

Nomination

Returns:

The created nomination instance.

async get_by_nominee(nominee_id, limit=100, offset=0)[source]¶

Get nominations for a nominee.

Parameters:

nominee_id (UUID) – The nominee ID.
limit (int) – Maximum number of nominations to return.
offset (int) – Number of nominations to skip.

Return type:

Returns:

List of nominations for the nominee.

async get_by_nominator(nominator_id, limit=100, offset=0)[source]¶

Get nominations by nominator.

Parameters:

nominator_id (UUID) – The nominator user ID.
limit (int) – Maximum number of nominations to return.
offset (int) – Number of nominations to skip.

Return type: