dependencies

Dependency management

Application dependency providers.

class byte_bot.server.lib.dependencies.BeforeAfter(field_name: str, before: datetime | None, after: datetime | None)

Bases: StatementFilter

DateTime range filter with exclusive bounds.

This filter creates date/time range conditions using < and > operators, excluding the boundary values.

If either before or after is None, that boundary condition is not applied.

See Also:

OnBeforeAfter : Inclusive datetime range filtering

field_name: str

Name of the model attribute to filter on.

before: datetime | None

Filter results where field is earlier than this value.

after: datetime | None

Filter results where field is later than this value.

append_to_statement(statement: StatementTypeT, model: type[ModelT]) → StatementTypeT

Apply datetime range conditions to statement.

Parameters:

• statement (StatementTypeT) – The SQLAlchemy statement to modify

• model (type[ModelT]) – The SQLAlchemy model class

• Returns

• --------

• StatementTypeT – Modified statement with datetime range conditions

__init__(field_name: str, before: datetime | None, after: datetime | None) → None

class byte_bot.server.lib.dependencies.CollectionFilter(field_name: str, values: Collection[T] | None)

Bases: InAnyFilter, Generic[T]

Data required to construct a WHERE … IN (…) clause.

This filter restricts records based on a field’s presence in a collection of values.

The filter supports both IN and ANY operators for collection membership testing. Use prefer_any=True in append_to_statement to use the ANY operator.

field_name: str

Name of the model attribute to filter on.

values: Collection[T] | None

Values for the IN clause. If this is None, no filter is applied. An empty list will force an empty result set (WHERE 1=-1)

append_to_statement(statement: StatementTypeT, model: type[ModelT], prefer_any: bool = False) → StatementTypeT

Apply a WHERE … IN or WHERE … ANY (…) clause to the statement.

Parameters:

• statement (StatementTypeT) – The SQLAlchemy statement to modify

• model (type[ModelT]) – The SQLAlchemy model class

• prefer_any (bool, optional) – If True, uses the SQLAlchemy any_() operator instead of in_() for the filter condition

• Returns

• --------

• StatementTypeT – Modified statement with the appropriate IN conditions

__init__(field_name: str, values: Collection[T] | None) → None

class byte_bot.server.lib.dependencies.LimitOffset(limit: int, offset: int)

Bases: PaginationFilter

Limit and offset pagination filter.

Implements traditional pagination using SQL LIMIT and OFFSET clauses. Only applies to SELECT statements; other statement types are returned unmodified.

Note

This filter only modifies SELECT statements. For other statement types (UPDATE, DELETE), the statement is returned unchanged.

See also

• sqlalchemy.sql.expression.Select.limit(): SQLAlchemy LIMIT clause

• sqlalchemy.sql.expression.Select.offset(): SQLAlchemy OFFSET clause

limit: int

Maximum number of rows to return.

offset: int

Number of rows to skip before returning results.

append_to_statement(statement: StatementTypeT, model: type[ModelT]) → StatementTypeT

Apply LIMIT/OFFSET pagination to the statement.

Parameters:

• statement – The SQLAlchemy statement to modify

• model – The SQLAlchemy model class

Returns:

Modified statement with limit and offset applied

Return type:

StatementTypeT

Note

Only modifies SELECT statements. Other statement types are returned as-is.

See also

sqlalchemy.sql.expression.Select: SQLAlchemy SELECT statement

__init__(limit: int, offset: int) → None

class byte_bot.server.lib.dependencies.OrderBy(field_name: str, sort_order: Literal['asc', 'desc'] = 'asc')

Bases: StatementFilter

Order by a specific field.

Appends an ORDER BY clause to SELECT statements, sorting records by the specified field in ascending or descending order.

Note

This filter only modifies SELECT statements. For other statement types, the statement is returned unchanged.

See also

• sqlalchemy.sql.expression.Select.order_by(): SQLAlchemy ORDER BY clause

• sqlalchemy.sql.expression.ColumnElement.asc(): Ascending order

• sqlalchemy.sql.expression.ColumnElement.desc(): Descending order

field_name: str

Name of the model attribute to sort on.

sort_order: Literal['asc', 'desc'] = 'asc'

Sort direction (“asc” or “desc”).

append_to_statement(statement: StatementTypeT, model: type[ModelT]) → StatementTypeT

Append an ORDER BY clause to the statement.

Parameters:

• statement – The SQLAlchemy statement to modify

• model – The SQLAlchemy model class

Returns:

Modified statement with an ORDER BY clause

Return type:

StatementTypeT

Note

Only modifies SELECT statements. Other statement types are returned as-is.

See also

sqlalchemy.sql.expression.Select.order_by(): SQLAlchemy ORDER BY

__init__(field_name: str, sort_order: Literal['asc', 'desc'] = 'asc') → None

class byte_bot.server.lib.dependencies.SearchFilter(field_name: str | set[str], value: str, ignore_case: bool | None = False)

Bases: StatementFilter

Case-sensitive or case-insensitive substring matching filter.

Implements text search using SQL LIKE or ILIKE operators. Can search across multiple fields using OR conditions.

Note

The search pattern automatically adds wildcards before and after the search value, equivalent to SQL pattern ‘%value%’.

See also

• NotInSearchFilter: Opposite filter using NOT LIKE/ILIKE

• sqlalchemy.sql.expression.ColumnOperators.like(): Case-sensitive LIKE

• sqlalchemy.sql.expression.ColumnOperators.ilike(): Case-insensitive LIKE

field_name: str | set[str]

Name or set of names of model attributes to search on.

value: str

Text to match within the field(s).

ignore_case: bool | None = False

Whether to use case-insensitive matching.

property normalized_field_names: set[str]

Convert field_name to a set if it’s a single string.

Returns:

Set of field names to be searched

Return type:

set[str]

get_search_clauses(model: type[ModelT]) → list[BinaryExpression[bool]]

Generate the LIKE/ILIKE clauses for all specified fields.

Parameters:

model – The SQLAlchemy model class

Returns:

List of text matching expressions

Return type:

list[BinaryExpression[bool]]

See also

sqlalchemy.sql.expression.BinaryExpression: SQLAlchemy expression

append_to_statement(statement: StatementTypeT, model: type[ModelT]) → StatementTypeT

Append a LIKE/ILIKE clause to the statement.

Parameters:

• statement – The SQLAlchemy statement to modify

• model – The SQLAlchemy model class

Returns:

Modified statement with text search clauses

Return type:

StatementTypeT

See also

sqlalchemy.sql.expression.Select.where(): SQLAlchemy WHERE clause

__init__(field_name: str | set[str], value: str, ignore_case: bool | None = False) → None

byte_bot.server.lib.dependencies.create_collection_dependencies() → dict[str, Provide]

Create ORM dependencies.

Creates a dictionary of provides for pagination endpoints.

Returns:

Dictionary of provides.

Return type:

dict[str, Provide]

byte_bot.server.lib.dependencies.provide_created_filter(before: ~datetime.datetime | None = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=None, title=None, description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='createdBefore', required=False), after: ~datetime.datetime | None = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=None, title=None, description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='createdAfter', required=False)) → BeforeAfter

Return type consumed by Repository.filter_on_datetime_field().

Parameters:

• before (datetime | None) – Filter for records created before this date/time.

• after (datetime | None) – Filter for records created after this date/time.

Returns:

BeforeAfter

byte_bot.server.lib.dependencies.provide_filter_dependencies(created_filter: ~advanced_alchemy.filters.BeforeAfter = DependencyKwarg(default=<_EmptyEnum.EMPTY: 0>, skip_validation=True), updated_filter: ~advanced_alchemy.filters.BeforeAfter = DependencyKwarg(default=<_EmptyEnum.EMPTY: 0>, skip_validation=True), id_filter: ~advanced_alchemy.filters.CollectionFilter = DependencyKwarg(default=<_EmptyEnum.EMPTY: 0>, skip_validation=True), limit_offset: ~advanced_alchemy.filters.LimitOffset = DependencyKwarg(default=<_EmptyEnum.EMPTY: 0>, skip_validation=True), search_filter: ~advanced_alchemy.filters.SearchFilter = DependencyKwarg(default=<_EmptyEnum.EMPTY: 0>, skip_validation=True), order_by: ~advanced_alchemy.filters.OrderBy = DependencyKwarg(default=<_EmptyEnum.EMPTY: 0>, skip_validation=True)) → list[BeforeAfter | OnBeforeAfter | CollectionFilter[Any] | LimitOffset | OrderBy | SearchFilter | NotInCollectionFilter[Any] | NotInSearchFilter | ExistsFilter | NotExistsFilter | ComparisonFilter | MultiFilter | FilterGroup]

Provide common collection route filtering dependencies.

Add all filters to any route by including this function as a dependency, e.g.:

@get
def get_collection_handler(filters: Filters) -> ...: ...

The dependency is provided in the application layer, so only need to inject the dependency where necessary.

Parameters:

• created_filter (BeforeAfter) – Filter for records created before/after a certain date/time.

• updated_filter (BeforeAfter) – Filter for records updated before/after a certain date/time.

• id_filter (CollectionFilter) – Filter for records with a certain ID.

• limit_offset (LimitOffset) – Pagination filter.

• search_filter (SearchFilter) – Search filter.

• order_by (OrderBy) – Order by filter.

Returns:

List of filters to apply to query.

Return type:

list[repository.FilterTypes]

byte_bot.server.lib.dependencies.provide_id_filter(ids: list[~uuid.UUID] | None = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=None, title=None, description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='ids', required=False)) → CollectionFilter[UUID]

Return type consumed by Repository.filter_in_collection().

Parameters:

ids (list[UUID] | None) – List of IDs to filter on.

Returns:

CollectionFilter[UUID]

byte_bot.server.lib.dependencies.provide_limit_offset_pagination(current_page: int = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=1, title=None, description=None, const=None, gt=None, ge=1, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='currentPage', required=False), page_size: int = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=20, title=None, description=None, const=None, gt=None, ge=1, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='pageSize', required=False)) → LimitOffset

Add offset/limit pagination.

Return type consumed by Repository.apply_limit_offset_pagination().

Parameters:

• current_page (int) – Current page of results.

• page_size (int) – Number of results per page.

Returns:

LimitOffset

byte_bot.server.lib.dependencies.provide_order_by(field_name: str | None = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=None, title='Order by field', description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='orderBy', required=False), sort_order: ~typing.Literal['asc', 'desc'] | None = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default='desc', title='Field to search', description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='sortOrder', required=False)) → OrderBy

Add offset/limit pagination.

Return type consumed by Repository.apply_order_by().

Parameters:

• field_name (int) – LIMIT to apply to select.

• sort_order (int) – OFFSET to apply to select.

Returns:

OrderBy

byte_bot.server.lib.dependencies.provide_search_filter(field: str | None = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=None, title='Field to search', description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='searchField', required=False), search: str | None = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=None, title='Field to search', description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='searchString', required=False), ignore_case: bool | None = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=None, title='Search should be case sensitive', description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<class 'bool'>, header=None, cookie=None, query='searchIgnoreCase', required=False)) → SearchFilter

Add offset/limit pagination.

Return type consumed by Repository.apply_search_filter().

Parameters:

• field (str | None) – Field to search.

• search (str | None) – String to search for.

• ignore_case (bool | None) – Whether to ignore case when searching.

byte_bot.server.lib.dependencies.provide_updated_filter(before: ~datetime.datetime | None = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=None, title=None, description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='updatedBefore', required=False), after: ~datetime.datetime | None = ParameterKwarg(examples=None, external_docs=None, content_encoding=None, default=None, title=None, description=None, const=None, gt=None, ge=None, lt=None, le=None, multiple_of=None, min_items=None, max_items=None, min_length=None, max_length=None, pattern=None, lower_case=None, upper_case=None, format=None, enum=None, read_only=None, schema_extra=None, schema_component_key=None, annotation=<_EmptyEnum.EMPTY: 0>, header=None, cookie=None, query='updatedAfter', required=False)) → BeforeAfter

Add updated filter.

Return type consumed by Repository.filter_on_datetime_field().

Parameters:

• before (datetime | None) – Filter for records updated before this date/time.

• after (datetime | None) – Filter for records updated after this date/time.

Returns:

BeforeAfter