alchemy-filterset 0.1.0__tar.gz

alchemy_filterset-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.3
+Name: alchemy-filterset
+Version: 0.1.0
+Summary: A dynamic, Django-like filterset architecture for SQLAlchemy & Advanced Alchemy.
+Keywords: sqlalchemy,advanced-alchemy,litestar,fastapi,filters,pydantic
+Author: Morteza Karimi
+Author-email: Morteza Karimi <itismortezakarimi@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: advanced-alchemy>=1.11.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: sqlalchemy>=2.0.51
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/MortezaKarimi77/alchemy-filterset
+Project-URL: Repository, https://github.com/MortezaKarimi77/alchemy-filterset.git
+Project-URL: Issues, https://github.com/MortezaKarimi77/alchemy-filterset/issues
+Description-Content-Type: text/markdown
+
+# Alchemy FilterSet 🚀
+
+A powerful, dynamic, and type-safe filtering architecture for **SQLAlchemy 2.0** and **Advanced Alchemy**, heavily inspired by `django-filters`.
+
+## Why Alchemy FilterSet?
+
+While SQLAlchemy and Advanced Alchemy provide excellent tools for querying databases, handling complex HTTP query parameters (like nested relationships, dynamic ordering, and multi-field search) often leads to messy, repetitive, and hard-to-maintain code.
+
+`alchemy-filterset` bridges the gap between your Web Framework (FastAPI, Litestar, etc.) and your Database by providing a declarative, Pydantic-powered filter class that securely translates user requests into efficient SQL `EXISTS` expressions.
+
+## Design Goals
+
+Alchemy FilterSet is designed around a few core principles:
+
+- Declarative API inspired by Django FilterSet while remaining SQLAlchemy-native.
+- No automatic joins; relationship filters are translated into EXISTS expressions.
+- Type-safe query parsing powered by Pydantic v2.
+- Extensible lookup registry for custom operators.
+- Framework agnostic (FastAPI, Litestar, Starlette, etc.).
+
+## Key Features
+
+- 🔗 **Deep Nested Relationships:** Seamlessly filter across infinite layers of relationships (e.g., `province__country__name__icontains="Iran"`).
+- 🚫 **Negation Support:** Easily exclude records using the `not__` prefix (e.g., `not__status="deleted"`).
+- 🗂 **Smart Pagination:** Built-in, declarative pagination controls with frontend limits and backend enforcement.
+- 🔍 **Global Multi-Field Search:** Search across multiple columns and related tables simultaneously with a single `?search=` parameter.
+- ↕️ **Dynamic Ordering:** Sort by any field or nested relationship (e.g., `?ordering=-province__name,created_at`).
+- 🧩 **Association Proxy Support:** Fully supports querying and ordering across SQLAlchemy's `AssociationProxy`.
+- 🛡 **Type-Safe:** Built with Pydantic v2 and Python 3.10+ types.
+
+---
+
+## 📦 Installation
+
+This package requires Python 3.10+ and SQLAlchemy 2.0+.
+
+```bash
+pip install alchemy-filterset
+uv add alchemy-filterset
+poetry add alchemy-filterset
+```
+
+---
+
+## ⚡ Quick Start
+
+Imagine you have two SQLAlchemy models: `Country` and `Province`.
+
+### 1. Define your FilterSet
+
+Inherit from `SQLAlchemyFilterSet` and declare the allowed filters as Pydantic fields.
+
+```python
+from uuid import UUID
+from alchemy_filterset import SQLAlchemyFilterSet
+from my_app.models import Province
+
+class ProvinceFilter(SQLAlchemyFilterSet):
+    # 1. Bind to your SQLAlchemy Model
+    model_cls = Province
+    
+    # 2. Define fields for global search (?search=...)
+    search_fields = {"name", "country__name", "country__code"}
+
+    # 3. Define allowed query parameters using double-underscore syntax
+    name__icontains: str | None = None
+    population__gt: int | None = None
+    is_active: bool | None = None
+    
+    # 4. Filter across relationships seamlessly!
+    country__id: UUID | None = None
+    country__code__in: list[str] | None = None
+```
+
+### 2. Use it in your API (FastAPI / Litestar Example)
+
+Pass the query parameters to the FilterSet, call `to_statement_filters()`, and pass the result to your Advanced Alchemy repository.
+
+```python
+# Example using FastAPI/Litestar dependency injection
+@app.get("/provinces")
+async def get_provinces(
+    filters: ProvinceFilter = Depends(), 
+    repo: ProvinceRepository = Depends()
+):
+    # 1. Translate Pydantic model to SQLAlchemy expressions
+    sql_filters = filters.to_statement_filters()
+    
+    # 2. Pass them to Advanced Alchemy repository
+    provinces = await repo.get_many(*sql_filters)
+    
+    return provinces
+```
+
+Now, your API automatically supports queries like:
+`GET /provinces?country__code__in=IR,US&population__gt=1000000&ordering=-name&page=2`
+
+---
+
+## 📖 Feature Guide & Examples
+
+### 1. Standard Lookups
+
+By default, fields use the exact equality (`eq`) operator. You can append lookups using the `__` syntax.
+
+Supported Lookups:
+
+- **Comparison:** `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `between`
+- **Collection:** `in`, `notin`
+- **Text:** `contains`, `icontains`, `not_contains`, `not_icontains`, `startswith`, `endswith`
+- **Null Check:** `is_null`, `not_null`
+
+```http
+GET /api/users?age__between=18,30
+GET /api/users?status__in=active,pending
+GET /api/users?email__endswith=@gmail.com
+GET /api/users?deleted_at__is_null=true
+```
+
+### 2. Negation / Exclude (The `not__` prefix)
+
+You can negate any standard lookup, nested relationship, or custom filter simply by prefixing it with `not__`.
+This dynamically translates to `!=`, `NOT IN`, or `NOT EXISTS` in SQL.
+
+```python
+class UserFilter(SQLAlchemyFilterSet):
+    model_cls = User
+    
+    # Simple Negation (e.g., status != 'banned')
+    not__status: str | None = None
+    
+    # Nested Negation (Users who DO NOT have a specific role)
+    not__roles__name__icontains: str | None = None
+```
+
+### 3. Deep Nested Relationships (The Magic ✨)
+
+You don't need to write complex `JOIN`s or `EXISTS` subqueries manually. Just chain relationship names separated by `__`.
+
+```python
+class CityFilter(SQLAlchemyFilterSet):
+    model_cls = City
+    
+    # City -> Province -> Country -> name
+    province__country__name__icontains: str | None = None
+```
+
+Under the hood, this generates efficient SQL `EXISTS` queries using SQLAlchemy's `.has()` and `.any()`.
+
+### 4. Global Search
+
+Define `search_fields` on your class. If a user passes the `?search=` parameter, the system will apply an `icontains` filter to all specified fields, joining them with an `OR` operator.
+
+```python
+class PostFilter(SQLAlchemyFilterSet):
+    model_cls = Post
+    search_fields = {"title", "content", "author__username"}
+```
+
+`GET /api/posts?search=python` will search for "python" in the title, content, OR the author's username.
+
+### 5. Dynamic Ordering
+
+Users can sort results using the `ordering` parameter. Prefix with `-` for descending order. Separate multiple fields with commas.
+
+`GET /api/users?ordering=-created_at,last_name`
+
+### 6. Pagination Control
+
+Pagination is enabled by default. If the user does not provide `page` or `page_size`, the defaults are used.
+
+```python
+class HeavyReportFilter(SQLAlchemyFilterSet):
+    model_cls = Report
+    
+    # Customize pagination limits per class
+    default_page_size = 10
+    max_page_size = 50 
+```
+
+**Disabling Pagination:**
+If an API should return all records (e.g., a dropdown list), set `enable_pagination = False`.
+
+```python
+class DropdownFilter(SQLAlchemyFilterSet):
+    model_cls = Category
+    enable_pagination = False # Limits/Offsets are entirely ignored
+```
+
+### 7. Custom Filter Methods
+
+Need complex logic that doesn't fit standard lookups? Write a custom method! Name it `filter_<field_name>`.
+
+```python
+class UserFilter(SQLAlchemyFilterSet):
+    model_cls = User
+    
+    has_avatar: bool | None = None
+
+    def filter_has_avatar(self, value: bool):
+        if value:
+            return User.avatar_url.is_not(None)
+        return User.avatar_url.is_(None)
+```
+
+---
+
+## 🛠 Advanced Usage: Association Proxies
+
+`alchemy-filterset` natively supports SQLAlchemy's `AssociationProxy`. It automatically unpacks the proxy, discovers the underlying tables, and applies the filters or ordering correctly without crashing.
+
+```python
+class Post(Base):
+    __tablename__ = "posts"
+    # ...
+    # Association proxy to tags
+    tags: AssociationProxy[list[str]] = association_proxy("post_tags", "tag_name")
+
+class PostFilter(SQLAlchemyFilterSet):
+    model_cls = Post
+    # Works perfectly!
+    tags__icontains: str | None = None
+```
+
+## License
+
+MIT

alchemy_filterset-0.1.0/README.md

@@ -0,0 +1,227 @@
+# Alchemy FilterSet 🚀
+
+A powerful, dynamic, and type-safe filtering architecture for **SQLAlchemy 2.0** and **Advanced Alchemy**, heavily inspired by `django-filters`.
+
+## Why Alchemy FilterSet?
+
+While SQLAlchemy and Advanced Alchemy provide excellent tools for querying databases, handling complex HTTP query parameters (like nested relationships, dynamic ordering, and multi-field search) often leads to messy, repetitive, and hard-to-maintain code.
+
+`alchemy-filterset` bridges the gap between your Web Framework (FastAPI, Litestar, etc.) and your Database by providing a declarative, Pydantic-powered filter class that securely translates user requests into efficient SQL `EXISTS` expressions.
+
+## Design Goals
+
+Alchemy FilterSet is designed around a few core principles:
+
+- Declarative API inspired by Django FilterSet while remaining SQLAlchemy-native.
+- No automatic joins; relationship filters are translated into EXISTS expressions.
+- Type-safe query parsing powered by Pydantic v2.
+- Extensible lookup registry for custom operators.
+- Framework agnostic (FastAPI, Litestar, Starlette, etc.).
+
+## Key Features
+
+- 🔗 **Deep Nested Relationships:** Seamlessly filter across infinite layers of relationships (e.g., `province__country__name__icontains="Iran"`).
+- 🚫 **Negation Support:** Easily exclude records using the `not__` prefix (e.g., `not__status="deleted"`).
+- 🗂 **Smart Pagination:** Built-in, declarative pagination controls with frontend limits and backend enforcement.
+- 🔍 **Global Multi-Field Search:** Search across multiple columns and related tables simultaneously with a single `?search=` parameter.
+- ↕️ **Dynamic Ordering:** Sort by any field or nested relationship (e.g., `?ordering=-province__name,created_at`).
+- 🧩 **Association Proxy Support:** Fully supports querying and ordering across SQLAlchemy's `AssociationProxy`.
+- 🛡 **Type-Safe:** Built with Pydantic v2 and Python 3.10+ types.
+
+---
+
+## 📦 Installation
+
+This package requires Python 3.10+ and SQLAlchemy 2.0+.
+
+```bash
+pip install alchemy-filterset
+uv add alchemy-filterset
+poetry add alchemy-filterset
+```
+
+---
+
+## ⚡ Quick Start
+
+Imagine you have two SQLAlchemy models: `Country` and `Province`.
+
+### 1. Define your FilterSet
+
+Inherit from `SQLAlchemyFilterSet` and declare the allowed filters as Pydantic fields.
+
+```python
+from uuid import UUID
+from alchemy_filterset import SQLAlchemyFilterSet
+from my_app.models import Province
+
+class ProvinceFilter(SQLAlchemyFilterSet):
+    # 1. Bind to your SQLAlchemy Model
+    model_cls = Province
+    
+    # 2. Define fields for global search (?search=...)
+    search_fields = {"name", "country__name", "country__code"}
+
+    # 3. Define allowed query parameters using double-underscore syntax
+    name__icontains: str | None = None
+    population__gt: int | None = None
+    is_active: bool | None = None
+    
+    # 4. Filter across relationships seamlessly!
+    country__id: UUID | None = None
+    country__code__in: list[str] | None = None
+```
+
+### 2. Use it in your API (FastAPI / Litestar Example)
+
+Pass the query parameters to the FilterSet, call `to_statement_filters()`, and pass the result to your Advanced Alchemy repository.
+
+```python
+# Example using FastAPI/Litestar dependency injection
+@app.get("/provinces")
+async def get_provinces(
+    filters: ProvinceFilter = Depends(), 
+    repo: ProvinceRepository = Depends()
+):
+    # 1. Translate Pydantic model to SQLAlchemy expressions
+    sql_filters = filters.to_statement_filters()
+    
+    # 2. Pass them to Advanced Alchemy repository
+    provinces = await repo.get_many(*sql_filters)
+    
+    return provinces
+```
+
+Now, your API automatically supports queries like:
+`GET /provinces?country__code__in=IR,US&population__gt=1000000&ordering=-name&page=2`
+
+---
+
+## 📖 Feature Guide & Examples
+
+### 1. Standard Lookups
+
+By default, fields use the exact equality (`eq`) operator. You can append lookups using the `__` syntax.
+
+Supported Lookups:
+
+- **Comparison:** `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `between`
+- **Collection:** `in`, `notin`
+- **Text:** `contains`, `icontains`, `not_contains`, `not_icontains`, `startswith`, `endswith`
+- **Null Check:** `is_null`, `not_null`
+
+```http
+GET /api/users?age__between=18,30
+GET /api/users?status__in=active,pending
+GET /api/users?email__endswith=@gmail.com
+GET /api/users?deleted_at__is_null=true
+```
+
+### 2. Negation / Exclude (The `not__` prefix)
+
+You can negate any standard lookup, nested relationship, or custom filter simply by prefixing it with `not__`.
+This dynamically translates to `!=`, `NOT IN`, or `NOT EXISTS` in SQL.
+
+```python
+class UserFilter(SQLAlchemyFilterSet):
+    model_cls = User
+    
+    # Simple Negation (e.g., status != 'banned')
+    not__status: str | None = None
+    
+    # Nested Negation (Users who DO NOT have a specific role)
+    not__roles__name__icontains: str | None = None
+```
+
+### 3. Deep Nested Relationships (The Magic ✨)
+
+You don't need to write complex `JOIN`s or `EXISTS` subqueries manually. Just chain relationship names separated by `__`.
+
+```python
+class CityFilter(SQLAlchemyFilterSet):
+    model_cls = City
+    
+    # City -> Province -> Country -> name
+    province__country__name__icontains: str | None = None
+```
+
+Under the hood, this generates efficient SQL `EXISTS` queries using SQLAlchemy's `.has()` and `.any()`.
+
+### 4. Global Search
+
+Define `search_fields` on your class. If a user passes the `?search=` parameter, the system will apply an `icontains` filter to all specified fields, joining them with an `OR` operator.
+
+```python
+class PostFilter(SQLAlchemyFilterSet):
+    model_cls = Post
+    search_fields = {"title", "content", "author__username"}
+```
+
+`GET /api/posts?search=python` will search for "python" in the title, content, OR the author's username.
+
+### 5. Dynamic Ordering
+
+Users can sort results using the `ordering` parameter. Prefix with `-` for descending order. Separate multiple fields with commas.
+
+`GET /api/users?ordering=-created_at,last_name`
+
+### 6. Pagination Control
+
+Pagination is enabled by default. If the user does not provide `page` or `page_size`, the defaults are used.
+
+```python
+class HeavyReportFilter(SQLAlchemyFilterSet):
+    model_cls = Report
+    
+    # Customize pagination limits per class
+    default_page_size = 10
+    max_page_size = 50 
+```
+
+**Disabling Pagination:**
+If an API should return all records (e.g., a dropdown list), set `enable_pagination = False`.
+
+```python
+class DropdownFilter(SQLAlchemyFilterSet):
+    model_cls = Category
+    enable_pagination = False # Limits/Offsets are entirely ignored
+```
+
+### 7. Custom Filter Methods
+
+Need complex logic that doesn't fit standard lookups? Write a custom method! Name it `filter_<field_name>`.
+
+```python
+class UserFilter(SQLAlchemyFilterSet):
+    model_cls = User
+    
+    has_avatar: bool | None = None
+
+    def filter_has_avatar(self, value: bool):
+        if value:
+            return User.avatar_url.is_not(None)
+        return User.avatar_url.is_(None)
+```
+
+---
+
+## 🛠 Advanced Usage: Association Proxies
+
+`alchemy-filterset` natively supports SQLAlchemy's `AssociationProxy`. It automatically unpacks the proxy, discovers the underlying tables, and applies the filters or ordering correctly without crashing.
+
+```python
+class Post(Base):
+    __tablename__ = "posts"
+    # ...
+    # Association proxy to tags
+    tags: AssociationProxy[list[str]] = association_proxy("post_tags", "tag_name")
+
+class PostFilter(SQLAlchemyFilterSet):
+    model_cls = Post
+    # Works perfectly!
+    tags__icontains: str | None = None
+```
+
+## License
+
+MIT

alchemy_filterset-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "alchemy-filterset"
+version = "0.1.0"
+description = "A dynamic, Django-like filterset architecture for SQLAlchemy & Advanced Alchemy."
+readme = "README.md"
+authors = [{ name = "Morteza Karimi", email = "itismortezakarimi@gmail.com" }]
+requires-python = ">=3.12"
+license = { text = "MIT" }
+keywords = [
+    "sqlalchemy",
+    "advanced-alchemy",
+    "litestar",
+    "fastapi",
+    "filters",
+    "pydantic",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "advanced-alchemy>=1.11.0",
+    "pydantic>=2.13.4",
+    "sqlalchemy>=2.0.51",
+]
+
+[dependency-groups]
+test = ["pytest>=9.1.1", "pytest-cov>=7.1.0"]
+
+[project.urls]
+Homepage = "https://github.com/MortezaKarimi77/alchemy-filterset"
+Repository = "https://github.com/MortezaKarimi77/alchemy-filterset.git"
+Issues = "https://github.com/MortezaKarimi77/alchemy-filterset/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+
+[tool.pytest.ini_options]
+xfail_strict = true
+testpaths = "tests"
+addopts = ["--strict-config", "--strict-markers", "-s", "-v", "-ra"]
+
+[tool.coverage.run]
+branch = true
+source = ["alchemy_filterset"]
+
+[tool.coverage.paths]
+source = ["src/alchemy_filterset", "*/site-packages/alchemy_filterset"]

alchemy_filterset-0.1.0/src/alchemy_filterset/__init__.py

@@ -0,0 +1,17 @@
+from .exceptions import AttributeNotFoundError, LookupNotFoundError, RelationshipResolverError
+from .filterset import SQLAlchemyFilterSet
+from .registry import LookupRegistry, default_registry
+from .resolver import RelationshipResolver, ResolvedPath
+
+__all__ = (
+    "AttributeNotFoundError",
+    "LookupNotFoundError",
+    "LookupRegistry",
+    "RelationshipResolver",
+    "RelationshipResolverError",
+    "ResolvedPath",
+    "SQLAlchemyFilterSet",
+    "default_registry",
+)
+
+__version__ = "0.1.0"

alchemy_filterset-0.1.0/src/alchemy_filterset/exceptions.py

@@ -0,0 +1,19 @@
+import typing as tp
+
+
+class LookupNotFoundError(KeyError):
+    def __init__(self, lookup: str, available_lookups: tp.Collection[str]) -> None:
+        sorted_lookups = ", ".join(sorted(available_lookups))
+        super().__init__(
+            f"'{lookup}' operator not found in lookup registry.",
+            f"Allowed operators are: [{sorted_lookups}]",
+        )
+
+
+class RelationshipResolverError(Exception):
+    pass
+
+
+class AttributeNotFoundError(RelationshipResolverError):
+    def __init__(self, model: type, attribute_name: str) -> None:
+        super().__init__(f"The '{attribute_name}' attribute was not found on the '{model.__name__}' model.")

alchemy_filterset-0.1.0/src/alchemy_filterset/filterset.py

@@ -0,0 +1,157 @@
+import typing as tp
+
+import pydantic as pyd
+from advanced_alchemy import filters
+from sqlalchemy import ColumnElement, or_
+from sqlalchemy.ext.associationproxy import AssociationProxyInstance
+from sqlalchemy.orm import DeclarativeBase
+
+from . import exceptions
+from .registry import LookupRegistry, default_registry
+from .resolver import RelationshipResolver
+
+
+class SQLAlchemyFilterSet(pyd.BaseModel):
+    model_config = pyd.ConfigDict(
+        extra="ignore",
+        from_attributes=True,
+        str_strip_whitespace=True,
+        use_enum_values=True,
+        validate_assignment=True,
+        arbitrary_types_allowed=True,
+    )
+
+    model_cls: tp.ClassVar[type[DeclarativeBase]]
+    registry: tp.ClassVar[LookupRegistry] = default_registry
+    search_fields: tp.ClassVar[tp.Collection[str]] = ()
+
+    enable_pagination: tp.ClassVar[bool] = True
+    default_page_size: tp.ClassVar[int] = 30
+    max_page_size: tp.ClassVar[int] = 100
+
+    page: int | None = pyd.Field(default=None, ge=1)
+    page_size: int | None = pyd.Field(default=None, ge=1)
+
+    ordering: str | None = None
+    search: str | None = None
+
+    @pyd.model_validator(mode="after")
+    def validate_pagination_params(self) -> tp.Self:
+        if not self.enable_pagination:
+            if self.page is not None:
+                self.page = None
+            if self.page_size is not None:
+                self.page_size = None
+        else:
+            if self.page is None:
+                self.page = 1
+            if self.page_size is None:
+                self.page_size = self.default_page_size
+            if self.page_size > self.max_page_size:  # noqa: PLR1730
+                self.page_size = self.max_page_size
+
+        return self
+
+    def to_statement_filters(self) -> tp.Sequence[filters.StatementFilter | ColumnElement[bool]]:
+        if not hasattr(self, "model_cls"):
+            raise ValueError(f"The {self.__class__.__name__} class must define the 'model_cls' attribute.")
+
+        query_filters = []
+
+        if self.enable_pagination and self.page and self.page_size:
+            query_filters.append(filters.LimitOffset(limit=self.page_size, offset=(self.page - 1) * self.page_size))
+
+        if ordering_expr := self._build_ordering_filters():
+            query_filters.extend(ordering_expr)
+
+        if (search_expr := self._build_search_filter()) is not None:
+            query_filters.append(search_expr)
+
+        query_filters.extend(self._build_field_filters())
+        return query_filters
+
+    def _build_ordering_filters(self) -> tp.Sequence[filters.OrderBy] | None:
+        if self.ordering is None or not self.ordering.strip():
+            return None
+
+        ordering_filters = []
+        fields = [field.strip() for field in self.ordering.split(",") if field.strip()]
+
+        for field in fields:
+            sort_order = "desc" if field.startswith("-") else "asc"
+            clean_path = field.strip("+-")
+
+            resolved = RelationshipResolver.resolve(self.model_cls, clean_path)
+            if (target_attribute := resolved.target_attribute) is not None:
+                if isinstance(target_attribute, AssociationProxyInstance):
+                    target_attribute = target_attribute.remote_attr
+
+                field_to_order = tp.cast(tp.Any, target_attribute)
+                ordering_filters.append(filters.OrderBy(field_name=field_to_order, sort_order=sort_order))
+
+        return ordering_filters if ordering_filters else None
+
+    def _build_search_filter(self) -> ColumnElement[bool] | None:
+        if not self.search or not self.search_fields:
+            return None
+
+        conditions = []
+        for path in self.search_fields:
+            try:
+                cond = self._build_single_condition(path, lookup="icontains", value=self.search)
+                conditions.append(cond)
+            except (
+                exceptions.RelationshipResolverError,
+                exceptions.LookupNotFoundError,
+                exceptions.AttributeNotFoundError,
+            ):
+                continue
+
+        return or_(*conditions) if conditions else None
+
+    def _build_field_filters(self) -> tp.Sequence[ColumnElement[bool]]:
+        conditions = []
+        reserved_keys = {"page", "page_size", "ordering", "search"}
+
+        query_params: tp.Mapping[str, tp.Any] = self.model_dump(
+            exclude_unset=True, exclude_none=True, exclude=reserved_keys
+        )
+
+        for key, value in query_params.items():
+            is_negated = False
+            if key.startswith("not__"):
+                is_negated = True
+                key = key[len("not__") :]
+
+            if custom_filter_method := getattr(self, f"filter_{key}", None):
+                if (cond := custom_filter_method(value)) is not None:
+                    conditions.append(cond)
+                continue
+
+            parts = key.split("__")
+            lookup = "eq"
+
+            if len(parts) > 1 and self.registry.has_lookup(parts[-1]):
+                lookup = parts.pop()
+
+            clean_path = "__".join(parts)
+
+            cond = self._build_single_condition(clean_path, lookup, value)
+            if is_negated:
+                cond = ~cond
+
+            conditions.append(cond)
+        return conditions
+
+    def _build_single_condition(self, path: str, lookup: str, value: tp.Any) -> ColumnElement[bool]:
+        resolved = RelationshipResolver.resolve(self.model_cls, path)
+        builder_function = self.registry.get(lookup)
+        condition = builder_function(resolved.target_attribute, value)
+
+        for relation, uselist in reversed(resolved.relationship_chain):
+            if uselist:
+                condition = relation.any(condition)
+            else:
+                condition = relation.has(condition)
+
+        return condition

alchemy_filterset-0.1.0/src/alchemy_filterset/registry.py

@@ -0,0 +1,92 @@
+import typing as tp
+from dataclasses import dataclass, field
+
+import sqlalchemy as sa
+
+from .exceptions import LookupNotFoundError
+
+type FilterBuilder = tp.Callable[[tp.Any, tp.Any], sa.ColumnElement[bool]]
+
+
+@dataclass(slots=True)
+class LookupRegistry:
+    _builders: tp.MutableMapping[str, FilterBuilder] = field(default_factory=dict)
+
+    @tp.overload
+    def register(self, lookup: str | tp.Collection[str]) -> tp.Callable[[FilterBuilder], FilterBuilder]: ...
+
+    @tp.overload
+    def register(self, lookup: str | tp.Collection[str], builder: FilterBuilder) -> FilterBuilder: ...
+
+    def register(
+        self, lookup: str | tp.Collection[str], builder: FilterBuilder | None = None
+    ) -> FilterBuilder | tp.Callable[[FilterBuilder], FilterBuilder]:
+        def decorator(builder_function: FilterBuilder) -> FilterBuilder:
+            lookups = (lookup,) if isinstance(lookup, str) else lookup
+
+            for lookup_ in lookups:
+                lookup_ = lookup_.strip().casefold()
+                self._builders[lookup_] = builder_function
+
+            return builder_function
+
+        return decorator if builder is None else decorator(builder)
+
+    def get(self, lookup: str) -> FilterBuilder:
+        lookup = lookup.strip().casefold()
+        if lookup not in self._builders:
+            raise LookupNotFoundError(lookup, self._builders.keys())
+        return self._builders[lookup]
+
+    def has_lookup(self, lookup: str) -> bool:
+        return lookup.strip().casefold() in self._builders
+
+    @property
+    def registered_lookups(self) -> set[str]:
+        return set(self._builders.keys())
+
+
+def register_default_lookups(registry: LookupRegistry) -> None:
+    # Register comparison lookups
+    registry.register(lookup="eq", builder=lambda col, val: col == val)
+    registry.register(lookup="ne", builder=lambda col, val: col != val)
+    registry.register(lookup="gt", builder=lambda col, val: col > val)
+    registry.register(lookup="ge", builder=lambda col, val: col >= val)
+    registry.register(lookup="lt", builder=lambda col, val: col < val)
+    registry.register(lookup="le", builder=lambda col, val: col <= val)
+    registry.register(
+        lookup="between",
+        builder=lambda col, val: (
+            col.between(val[0], val[1]) if isinstance(val, (list, tuple)) and len(val) == 2 else sa.false()
+        ),
+    )
+
+    # Register collection lookups
+    registry.register(
+        lookup="in",
+        builder=lambda col, val: col.in_(val if isinstance(val, (list, tuple, set)) else [val]) if val else sa.false(),
+    )
+    registry.register(
+        lookup="notin",
+        builder=lambda col, val: (
+            col.not_in(val if isinstance(val, (list, tuple, set)) else [val]) if val else sa.true()
+        ),
+    )
+
+    # Register text search lookups
+    registry.register(lookup="contains", builder=lambda col, val: sa.cast(col, sa.String).like(f"%{val}%"))
+    registry.register(lookup="icontains", builder=lambda col, val: sa.cast(col, sa.String).ilike(f"%{val}%"))
+    registry.register(lookup="not_contains", builder=lambda col, val: sa.cast(col, sa.String).not_like(f"%{val}%"))
+    registry.register(lookup="not_icontains", builder=lambda col, val: sa.cast(col, sa.String).not_ilike(f"%{val}%"))
+    registry.register(lookup="startswith", builder=lambda col, val: sa.cast(col, sa.String).like(f"{val}%"))
+    registry.register(lookup="istartswith", builder=lambda col, val: sa.cast(col, sa.String).ilike(f"{val}%"))
+    registry.register(lookup="endswith", builder=lambda col, val: sa.cast(col, sa.String).like(f"%{val}"))
+    registry.register(lookup="iendswith", builder=lambda col, val: sa.cast(col, sa.String).ilike(f"%{val}"))
+
+    # Register null lookups
+    registry.register(lookup="is_null", builder=lambda col, val: col.is_(None) if val else col.is_not(None))
+    registry.register(lookup="not_null", builder=lambda col, val: col.is_not(None) if val else col.is_(None))
+
+
+default_registry = LookupRegistry()
+register_default_lookups(default_registry)

alchemy_filterset-0.1.0/src/alchemy_filterset/resolver.py

@@ -0,0 +1,91 @@
+import typing as tp
+from dataclasses import dataclass, field
+
+from sqlalchemy import ColumnElement
+from sqlalchemy.ext.associationproxy import AssociationProxyInstance
+from sqlalchemy.orm import DeclarativeBase, InstrumentedAttribute
+
+from . import exceptions
+
+type QueryableAttribute = InstrumentedAttribute[tp.Any] | AssociationProxyInstance[tp.Any] | ColumnElement[tp.Any]
+
+
+@dataclass(slots=True)
+class ResolvedPath:
+    root_model: type[DeclarativeBase]
+    target_model: type[DeclarativeBase]
+    target_attribute: QueryableAttribute | None
+    attribute_name: str
+    relationship_chain: list[tuple[InstrumentedAttribute[tp.Any], bool]] = field(default_factory=list)
+    remaining_parts: list[str] = field(default_factory=list)
+
+    @property
+    def is_nested(self) -> bool:
+        return len(self.relationship_chain) > 0
+
+
+class RelationshipResolver:
+    @classmethod
+    def resolve(cls, root_model: type[DeclarativeBase], path: str | tp.Sequence[str], sep: str = "__") -> ResolvedPath:
+        paths = (path,) if isinstance(path, str) else path
+        parts = [part.strip() for path in paths for part in path.split(sep) if part.strip()]
+
+        if not parts:
+            raise exceptions.RelationshipResolverError("The entered path for navigation is empty.")
+
+        current_model = root_model
+        relationship_chain: list[tuple[InstrumentedAttribute[tp.Any], bool]] = []
+        remaining_parts: list[str] = []
+
+        for index, part in enumerate(parts):
+            if (attribute := getattr(current_model, part, None)) is None:
+                raise exceptions.AttributeNotFoundError(current_model, part)
+
+            if cls._is_relationship(attribute):
+                uselist = attribute.property.uselist
+                relationship_chain.append((attribute, uselist))
+                current_model = attribute.property.mapper.class_
+
+            elif isinstance(attribute, AssociationProxyInstance):
+                local_attr = attribute.local_attr
+                relationship_chain.append((local_attr, local_attr.property.uselist))
+
+                remote_attr = attribute.remote_attr
+                if cls._is_relationship(remote_attr):
+                    relationship_chain.append((remote_attr, remote_attr.property.uselist))
+                    current_model = remote_attr.property.mapper.class_
+                else:
+                    remaining_parts = parts[index + 1 :]
+                    return ResolvedPath(
+                        root_model=root_model,
+                        target_model=local_attr.property.mapper.class_,
+                        target_attribute=attribute,
+                        attribute_name=part,
+                        relationship_chain=relationship_chain,
+                        remaining_parts=remaining_parts,
+                    )
+
+            else:
+                remaining_parts = parts[index + 1 :]
+                return ResolvedPath(
+                    root_model=root_model,
+                    target_model=current_model,
+                    target_attribute=attribute,
+                    attribute_name=part,
+                    relationship_chain=relationship_chain,
+                    remaining_parts=remaining_parts,
+                )
+
+        last_attribute = relationship_chain[-1][0] if relationship_chain else None
+        return ResolvedPath(
+            root_model=root_model,
+            target_model=current_model,
+            target_attribute=last_attribute,
+            attribute_name=last_attribute.key if last_attribute else "",
+            relationship_chain=relationship_chain,
+            remaining_parts=remaining_parts,
+        )
+
+    @staticmethod
+    def _is_relationship(attribute: tp.Any) -> bool:
+        return hasattr(attribute, "property") and hasattr(attribute.property, "mapper")