pypaginate.domain.specs

User-facing specification objects for filtering, sorting, and search.

Specs are immutable Pydantic models that users construct to describe what they want. Engines consume specs to execute the operations.

Attributes

`FilterInput`	Type alias for filter input accepted by engines and pipelines.
`FilterOperator`	Supported filter operator names (type-checked at definition time).

Classes

`FilterGroup`	Composite filter for nested AND/OR expressions.
`FilterSpec`	Declarative filter specification.
`SearchSpec`	Declarative search specification.
`SortSpec`	Declarative sort specification.

Functions

`And`(→ FilterGroup)	Create an AND group of filter conditions.
`Or`(→ FilterGroup)	Create an OR group of filter conditions.

Module Contents

class pypaginate.domain.specs.FilterGroup(/, **data: Any)

Bases: pydantic.BaseModel

Composite filter for nested AND/OR expressions.

Use And() and Or() builder functions instead of constructing directly.

Example:

And(
    Or(FilterSpec(field="a", value=1), FilterSpec(field="b", value=2)),
    Or(FilterSpec(field="c", value=3), FilterSpec(field="d", value=4)),
)
# = (a=1 OR b=2) AND (c=3 OR d=4)

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

class pypaginate.domain.specs.FilterSpec(/, **data: Any)

Bases: pydantic.BaseModel

Declarative filter specification.

Example:

FilterSpec(field="age", operator="gte", value=18)
FilterSpec(field="name", operator="contains", value="john")

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

class pypaginate.domain.specs.SearchSpec(/, **data: Any)

Bases: pydantic.BaseModel

Declarative search specification.

Example:

SearchSpec(query="john doe", fields=("name", "email"))
SearchSpec(query="jhn", fields=("name",), fuzzy=FuzzyMode.FUZZY)
SearchSpec(query="alice", fields=("name", "bio"), weights={"name": 2.0})

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

class pypaginate.domain.specs.SortSpec(/, **data: Any)

Bases: pydantic.BaseModel

Declarative sort specification.

Example:

SortSpec(field="name")
SortSpec(field="created_at", direction=SortDirection.DESC)

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

pypaginate.domain.specs.And(*conditions: FilterSpec | FilterGroup) → FilterGroup: Create an AND group of filter conditions.

pypaginate.domain.specs.Or(*conditions: FilterSpec | FilterGroup) → FilterGroup: Create an OR group of filter conditions.

pypaginate.domain.specs.FilterInput: Type alias for filter input accepted by engines and pipelines.

pypaginate.domain.specs.FilterOperator: Supported filter operator names (type-checked at definition time).