pages

Pages domain.

class ContentType

Bases: StrEnum

__new__(value)

class DocumentFile

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.

id: Mapped[UUID]

UUID Primary key column.

updated_at: Mapped[datetime.datetime]

Date/time of instance last update.

class DocumentFileController

Bases: Controller

Controller for Document File 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.

class DocumentFileCreate

Bases: DocumentFileBase

Schema for creating a new document file.

model_config: ClassVar[ConfigDict] = {}

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

class DocumentFileRead

Bases: DocumentFileBase

Schema for reading document file data.

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

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

class DocumentFileRepository

Bases: SQLAlchemyAsyncRepository[DocumentFile]

Repository for DocumentFile database operations.

async list_by_page_id(page_id, limit=100, offset=0)

List document files for a specific page.

Parameters:

• page_id (UUID) – The page ID to filter by.

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

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

Return type:

list[DocumentFile]

Returns:

List of document files for the page.

model_type

alias of DocumentFile

class DocumentFileService

Bases: SQLAlchemyAsyncRepositoryService[DocumentFile, Any]

Service for DocumentFile business logic.

async create_document(data)

Create a new document file for a page.

Parameters:

data (DocumentFileCreate) – Document file creation data.

Return type:

DocumentFile

Returns:

The created document file instance.

async list_by_page_id(page_id, limit=100, offset=0)

List document files for a specific page.

Parameters:

• page_id (UUID) – The page ID to filter by.

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

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

Return type:

list[DocumentFile]

Returns:

List of document files for the page.

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

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

repository_type

alias of DocumentFileRepository

class Image

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.

id: Mapped[UUID]

UUID Primary key column.

updated_at: Mapped[datetime.datetime]

Date/time of instance last update.

class ImageController

Bases: Controller

Controller for Image 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.

class ImageCreate

Bases: ImageBase

Schema for creating a new image.

model_config: ClassVar[ConfigDict] = {}

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

class ImageRead

Bases: ImageBase

Schema for reading image data.

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

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

class ImageRepository

Bases: SQLAlchemyAsyncRepository[Image]

Repository for Image database operations.

async list_by_page_id(page_id, limit=100, offset=0)

List images for a specific page.

Parameters:

• page_id (UUID) – The page ID to filter by.

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

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

Return type:

list[Image]

Returns:

List of images for the page.

model_type

alias of Image

class ImageService

Bases: SQLAlchemyAsyncRepositoryService[Image, Any]

Service for Image business logic.

async create_image(data)

Create a new image for a page.

Parameters:

data (ImageCreate) – Image creation data.

Return type:

Image

Returns:

The created image instance.

async list_by_page_id(page_id, limit=100, offset=0)

List images for a specific page.

Parameters:

• page_id (UUID) – The page ID to filter by.

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

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

Return type:

list[Image]

Returns:

List of images for the page.

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

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

repository_type

alias of ImageRepository

class Page

Bases: AuditBase, ContentManageableMixin

__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: Mapped[datetime]

created_at: Mapped[datetime.datetime]

Date/time of instance creation.

creator

creator_id

id: Mapped[UUID]

UUID Primary key column.

last_modified_by

last_modified_by_id

updated: Mapped[datetime]

updated_at: Mapped[datetime.datetime]

Date/time of instance last update.

class PageController

Bases: Controller

Controller for Page 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.

class PageCreate

Bases: PageBase

Schema for creating a new page.

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'example': {'content': '# About Python\n\nPython is a programming language...', 'content_type': 'markdown', 'description': 'Learn about the Python programming language', 'is_published': True, 'keywords': 'python, programming, language', 'path': '/about/', 'template_name': 'pages/default.html', 'title': 'About Python'}}}

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

class PagePublic

Bases: BaseModel

Public page schema for rendering.

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

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

class PageRead

Bases: PageBase

Schema for reading page data.

model_config: ClassVar[ConfigDict] = {'from_attributes': True, 'json_schema_extra': {'example': {'content': '# About Python\n\nPython is a programming language...', 'content_type': 'markdown', 'created': '2025-01-01T00:00:00Z', 'creator_id': '550e8400-e29b-41d4-a716-446655440000', 'description': 'Learn about the Python programming language', 'id': '550e8400-e29b-41d4-a716-446655440001', 'is_published': True, 'keywords': 'python, programming, language', 'last_modified_by_id': None, 'path': '/about/', 'template_name': 'pages/default.html', 'title': 'About Python', 'updated': '2025-01-15T10:00:00Z'}}}

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

class PageRenderController

Bases: Controller

Controller for rendering page templates.

Pages are cached in Redis for 5 minutes (300 seconds) to reduce database load. Cache is automatically invalidated when pages are updated or published/unpublished via the admin interface.

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.

class PageRepository

Bases: SQLAlchemyAsyncRepository[Page]

Repository for Page database operations.

async exists_by_path(path)

Check if a page exists by path.

Parameters:

path (str) – The path to check.

Return type:

bool

Returns:

True if a page with this path exists, False otherwise.

async get_by_path(path)

Get a page by its URL path.

Parameters:

path (str) – The URL path to search for.

Return type:

Page | None

Returns:

The page if found, None otherwise.

async list_published(limit=100, offset=0)

List published pages.

Parameters:

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

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

Return type:

list[Page]

Returns:

List of published pages.

model_type

alias of Page

class PageService

Bases: SQLAlchemyAsyncRepositoryService[Page, Any]

Service for Page business logic.

async create(data)

Create a new page.

Parameters:

data (dict) – Page creation data.

Return type:

Page

Returns:

The created page instance.

async create_page(data)

Create a new page.

Parameters:

data (PageCreate) – Page creation data.

Return type:

Page

Returns:

The created page instance.

Raises:

ValueError – If path already exists.

async get_by_path(path)

Get a page by its URL path.

Parameters:

path (str) – The URL path to search for.

Return type:

Page | None

Returns:

The page if found, None otherwise.

async list_published(limit=100, offset=0)

List published pages.

Parameters:

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

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

Return type:

list[Page]

Returns:

List of published pages.

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

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

async publish(page_id)

Publish a page.

Parameters:

page_id (UUID) – The ID of the page to publish.

Return type:

Page

Returns:

The updated page instance.

async render_content(page)

Render page content based on content type.

Parameters:

page (Page) – The page to render.

Return type:

str

Returns:

Rendered HTML content.

repository_type

alias of PageRepository

async unpublish(page_id)

Unpublish a page.

Parameters:

page_id (UUID) – The ID of the page to unpublish.

Return type:

Page

Returns:

The updated page instance.

async update(item_id, data)

Update a page.

Parameters:

• item_id (UUID) – The page ID.

• data (dict) – Update data.

Return type:

Page

Returns:

The updated page instance.

class PageUpdate

Bases: BaseModel

Schema for updating an existing page.

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'example': {'content': '# About Python\n\nUpdated content about Python...', 'is_published': True}}}

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

get_page_dependencies()

Get all pages domain dependency providers.

Return type:

dict

models

Pages domain models.

class ContentType

Bases: StrEnum

__new__(value)

class Page

Bases: AuditBase, ContentManageableMixin

__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: Mapped[datetime]

created_at: Mapped[datetime.datetime]

Date/time of instance creation.

creator

creator_id

id: Mapped[UUID]

UUID Primary key column.

last_modified_by

last_modified_by_id

updated: Mapped[datetime]

updated_at: Mapped[datetime.datetime]

Date/time of instance last update.

class Image

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.

id: Mapped[UUID]

UUID Primary key column.

updated_at: Mapped[datetime.datetime]

Date/time of instance last update.

class DocumentFile

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.

id: Mapped[UUID]

UUID Primary key column.

updated_at: Mapped[datetime.datetime]

Date/time of instance last update.

schemas

Pages domain Pydantic schemas.

class PageBase

Bases: BaseModel

Base page schema with common fields.

model_config: ClassVar[ConfigDict] = {}

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

class PageCreate

Bases: PageBase

Schema for creating a new page.

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'example': {'content': '# About Python\n\nPython is a programming language...', 'content_type': 'markdown', 'description': 'Learn about the Python programming language', 'is_published': True, 'keywords': 'python, programming, language', 'path': '/about/', 'template_name': 'pages/default.html', 'title': 'About Python'}}}

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

class PageUpdate

Bases: BaseModel

Schema for updating an existing page.

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'example': {'content': '# About Python\n\nUpdated content about Python...', 'is_published': True}}}

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

class PageRead

Bases: PageBase

Schema for reading page data.

model_config: ClassVar[ConfigDict] = {'from_attributes': True, 'json_schema_extra': {'example': {'content': '# About Python\n\nPython is a programming language...', 'content_type': 'markdown', 'created': '2025-01-01T00:00:00Z', 'creator_id': '550e8400-e29b-41d4-a716-446655440000', 'description': 'Learn about the Python programming language', 'id': '550e8400-e29b-41d4-a716-446655440001', 'is_published': True, 'keywords': 'python, programming, language', 'last_modified_by_id': None, 'path': '/about/', 'template_name': 'pages/default.html', 'title': 'About Python', 'updated': '2025-01-15T10:00:00Z'}}}

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

class PagePublic

Bases: BaseModel

Public page schema for rendering.

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

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

class ImageBase

Bases: BaseModel

Base image schema.

model_config: ClassVar[ConfigDict] = {}

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

class ImageCreate

Bases: ImageBase

Schema for creating a new image.

model_config: ClassVar[ConfigDict] = {}

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

class ImageRead

Bases: ImageBase

Schema for reading image data.

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

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

class DocumentFileBase

Bases: BaseModel

Base document file schema.

model_config: ClassVar[ConfigDict] = {}

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

class DocumentFileCreate

Bases: DocumentFileBase

Schema for creating a new document file.

model_config: ClassVar[ConfigDict] = {}

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

class DocumentFileRead

Bases: DocumentFileBase

Schema for reading document file data.

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

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

services

Pages domain services for business logic.

class PageService

Bases: SQLAlchemyAsyncRepositoryService[Page, Any]

Service for Page business logic.

repository_type

alias of PageRepository

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

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

async create(data)

Create a new page.

Parameters:

data (dict) – Page creation data.

Return type:

Page

Returns:

The created page instance.

async update(item_id, data)

Update a page.

Parameters:

• item_id (UUID) – The page ID.

• data (dict) – Update data.

Return type:

Page

Returns:

The updated page instance.

async create_page(data)

Create a new page.

Parameters:

data (PageCreate) – Page creation data.

Return type:

Page

Returns:

The created page instance.

Raises:

ValueError – If path already exists.

async get_by_path(path)

Get a page by its URL path.

Parameters:

path (str) – The URL path to search for.

Return type:

Page | None

Returns:

The page if found, None otherwise.

async list_published(limit=100, offset=0)

List published pages.

Parameters:

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

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

Return type:

list[Page]

Returns:

List of published pages.

async publish(page_id)

Publish a page.

Parameters:

page_id (UUID) – The ID of the page to publish.

Return type:

Page

Returns:

The updated page instance.

async unpublish(page_id)

Unpublish a page.

Parameters:

page_id (UUID) – The ID of the page to unpublish.

Return type:

Page

Returns:

The updated page instance.

async render_content(page)

Render page content based on content type.

Parameters:

page (Page) – The page to render.

Return type:

str

Returns:

Rendered HTML content.

class ImageService

Bases: SQLAlchemyAsyncRepositoryService[Image, Any]

Service for Image business logic.

repository_type

alias of ImageRepository

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

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

async list_by_page_id(page_id, limit=100, offset=0)

List images for a specific page.

Parameters:

• page_id (UUID) – The page ID to filter by.

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

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

Return type:

list[Image]

Returns:

List of images for the page.

async create_image(data)

Create a new image for a page.

Parameters:

data (ImageCreate) – Image creation data.

Return type:

Image

Returns:

The created image instance.

class DocumentFileService

Bases: SQLAlchemyAsyncRepositoryService[DocumentFile, Any]

Service for DocumentFile business logic.

repository_type

alias of DocumentFileRepository

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

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

async list_by_page_id(page_id, limit=100, offset=0)

List document files for a specific page.

Parameters:

• page_id (UUID) – The page ID to filter by.

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

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

Return type:

list[DocumentFile]

Returns:

List of document files for the page.

async create_document(data)

Create a new document file for a page.

Parameters:

data (DocumentFileCreate) – Document file creation data.

Return type:

DocumentFile

Returns:

The created document file instance.

controllers

Pages domain API controllers.

class PageController

Bases: Controller

Controller for Page 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 ImageController

Bases: Controller

Controller for Image 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 DocumentFileController

Bases: Controller

Controller for Document File 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 PageRenderController

Bases: Controller

Controller for rendering page templates.

Pages are cached in Redis for 5 minutes (300 seconds) to reduce database load. Cache is automatically invalidated when pages are updated or published/unpublished via the admin interface.

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

include_in_schema: bool | EmptyType

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

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.

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.

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.

repositories

Pages domain repositories for database access.

class PageRepository

Bases: SQLAlchemyAsyncRepository[Page]

Repository for Page database operations.

model_type

alias of Page

async get_by_path(path)

Get a page by its URL path.

Parameters:

path (str) – The URL path to search for.

Return type:

Page | None

Returns:

The page if found, None otherwise.

async list_published(limit=100, offset=0)

List published pages.

Parameters:

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

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

Return type:

list[Page]

Returns:

List of published pages.

async exists_by_path(path)

Check if a page exists by path.

Parameters:

path (str) – The path to check.

Return type:

bool

Returns:

True if a page with this path exists, False otherwise.

class ImageRepository

Bases: SQLAlchemyAsyncRepository[Image]

Repository for Image database operations.

model_type

alias of Image

async list_by_page_id(page_id, limit=100, offset=0)

List images for a specific page.

Parameters:

• page_id (UUID) – The page ID to filter by.

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

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

Return type:

list[Image]

Returns:

List of images for the page.

class DocumentFileRepository

Bases: SQLAlchemyAsyncRepository[DocumentFile]

Repository for DocumentFile database operations.

model_type

alias of DocumentFile

async list_by_page_id(page_id, limit=100, offset=0)

List document files for a specific page.

Parameters:

• page_id (UUID) – The page ID to filter by.

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

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

Return type:

list[DocumentFile]

Returns:

List of document files for the page.