Schema Conversion & Pagination#

Result conversion, pagination containers, schema helpers, and type variables exported from advanced_alchemy.service.

Conversion & Pagination#

class advanced_alchemy.service.ResultConverter#

Bases: object

Simple mixin to help convert to a paginated response model.

Single objects are transformed to the supplied schema type, and lists of objects are automatically transformed into an OffsetPagination response of the supplied schema type.

Parameters:

data – A database model instance or row mapping. Type: ModelOrRowMappingT

Returns:

The converted schema object.

to_schema(
data,
total=None,
filters=None,
*,
schema_type=None,
pagination_type=None,
)#

Convert the object to a response schema.

When schema_type is None, the model is returned with no conversion.

Parameters:
  • data (Union[ModelOrRowMappingT, Sequence[ModelOrRowMappingT], ModelProtocol, Sequence[ModelProtocol], RowMapping, Sequence[RowMapping], Row[Any], Sequence[Row[Any]], dict[str, Any], Sequence[dict[str, Any]]]) – The return from one of the service calls. Type: ModelOrRowMappingT

  • total (Optional[int]) – The total number of rows in the data.

  • filters (Union[Sequence[Union[StatementFilter, ColumnElement[bool]]], Sequence[StatementFilter], None]) – StatementFilter | ColumnElement collection of route filters.

  • schema_type (Optional[type[ModelDTOT]]) – ModelDTOT Optional schema type to convert the data to

  • pagination_type (Optional[Literal["limit_offset", "cursor"]]) – Pagination container to build. Omitted, a CursorFilter in filters returns a CursorPagination and anything else an OffsetPagination. "cursor" and "limit_offset" require that container and give type checkers its exact type; total is ignored for cursor pages.

Raises:
Returns:

ModelProtocol | RowMapping | OffsetPagination | msgspec.Struct | pydantic.BaseModel | attrs class

Return type:

Union[ModelOrRowMappingT, OffsetPagination[ModelOrRowMappingT], ModelDTOT, OffsetPagination[ModelDTOT], CursorPagination[ModelOrRowMappingT], CursorPagination[ModelDTOT], OffsetPagination[Row[Any]]]

class advanced_alchemy.service.OffsetPagination(items, limit, offset, total)#

Bases: Generic[T]

Container for data returned using limit/offset pagination.

items: Sequence[T]#

List of data being sent as part of the response.

limit: int#

Maximal number of items to send.

offset: int#

Offset from the beginning of the query.

Identical to an index.

total: int#

Total number of items.

class advanced_alchemy.service.CursorPagination(
items,
limit,
next_cursor,
previous_cursor,
has_next,
has_previous,
)#

Bases: Generic[T]

Container for data returned using cursor (keyset) pagination.

items: Sequence[T]#

List of data being sent as part of the response.

limit: int#

Maximal number of items to send.

next_cursor: str | None#

Token for the following page, or None on the last page.

previous_cursor: str | None#

Token for the preceding page, or None on the first page.

has_next: bool#

Whether a page exists after this one.

has_previous: bool#

Whether a page exists before this one.

advanced_alchemy.service.Pagination#
advanced_alchemy.service.find_filter(filter_type, filters)#

Get the filter specified by filter type from the filters.

Parameters:
Returns:

The match filter instance or None

Return type:

Union[FilterTypeT, None]

Schema Helpers#

class advanced_alchemy.service.SchemaDumpConfig(
exclude_unset=True,
exclude_none=False,
exclude_defaults=False,
exclude_sentinels=True,
)#

Bases: object

Configuration for dumping schema-like service input data.

advanced_alchemy.service.schema_dump(data, exclude_unset=True, *, config=None)#

Dump a data object to a dictionary.

Return type:

Union[dict[str, Any], ModelT]

advanced_alchemy.service.fields(cls)#

Return the tuple of attrs attributes for a class or instance.

The tuple also allows accessing the fields by their names (see below for examples).

Parameters:

cls (type) – Class or instance to introspect.

Raises:
  • TypeError – If cls is neither a class nor an attrs instance.

  • attrs.exceptions.NotAnAttrsClassError – If cls is not an attrs class.

Returns:

tuple (with name accessors) of attrs.Attribute

Changed in version 16.2.0: Returned tuple allows accessing the fields by name.

Changed in version 23.1.0: Add support for generic classes.

Changed in version 26.1.0: Add support for instances.

Type Variables & Flags#

advanced_alchemy.service.ModelDTOT#
advanced_alchemy.service.ModelDictT#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

advanced_alchemy.service.ModelDictListT#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to ‘utf-8’. errors defaults to ‘strict’.

advanced_alchemy.service.FilterTypeT#
advanced_alchemy.service.SupportedSchemaModel#
class advanced_alchemy.service.AttrsInstance(*args, **kwargs)#

Bases: Protocol

advanced_alchemy.service.ATTRS_INSTALLED: bool#

Boolean flag indicating whether attrs is installed.