Skip to content

A declarative and intuitive way to describe data filtering and sorting in your application.

License

Notifications You must be signed in to change notification settings

so-saf/pydantic-filters

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pydantic-filters

Testing Coverage pypi license versions

Documentation: https://so-saf.github.io/pydantic-filters/

Source Code: https://github.com/so-saf/pydantic-filters


Describe the filters, not implement them! A declarative and intuitive way to describe data filtering and sorting in your application.

Features

  • Filtering by the models themselves as well as by related.
  • Built-in pagination and sorting.
  • Lots of settings and possible customizations.
  • The only required dependency is Pydantic. You can use the basic features without being attached to specific frameworks, or use one of the supported plugins and drivers:
    • Plugins:
      • FastAPI >= 0.100.0
    • Drivers:
      • SQLAlchemy >= 2

Installation

pip install pydantic-filters

A Simple Example

BaseFilter is just a pydantic model, it should be treated similarly

Let's imagine you have a simple user service with the following SQLAlchemy model:

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    age: Mapped[int]

Describe how you would like to filter users using BaseFilter.

from typing import List
from pydantic_filters import BaseFilter


class UserFilter(BaseFilter):
    id: List[int]
    name: List[str]
    name__ilike: str
    age__lt: int
    age__gt: int

BaseFilter is just a pydantic model, it should be treated similarly

Next, you need to apply a filter to some query:

from sqlalchemy import select
from pydantic_filters.drivers.sqlalchemy import append_filter_to_statement

statement = select(User)
filter_ = UserFilter(name__ilike="kate", age__lt=23)

stmt = append_filter_to_statement(
    statement=statement, model=User, filter_=filter_,
)

And get something like:

SELECT users.id, users.name, users.age 
FROM users 
WHERE users.name ILIKE 'kate' AND users.age < 23

The filter can be used in conjunction with one of the supported web frameworks:

from typing import Annotated
from fastapi import FastAPI, APIRouter
from pydantic_filters.plugins.fastapi import FilterDepends


router = APIRouter()


@router.get("/")
async def get_multiple(
    filter_: Annotated[UserFilter, FilterDepends(UserFilter)],
):
    ...


app = FastAPI(title="User Service")
app.include_router(router, prefix="/users", tags=["User"])

fastapi-simple-example.png