Merge pull request #317 from eadwinCode/pagination_with_filter

feat: Added Django Ninja FilterSchema support to Pagination Decorator And Model Controller

Author: eadwinCode

docs/api_controller/model_controller/02_model_configuration.md

@@ -128,6 +128,84 @@ class EventModelController(ModelControllerBase):
     )
 ```
 
+### **Pagination with Filtering**
+
+You can combine pagination with Django Ninja's `FilterSchema` to automatically add filtering capabilities to your Model Controller's list endpoint:
+
+```python
+from typing import Optional
+from ninja import FilterSchema
+from ninja_extra import ModelConfig, ModelPagination
+from ninja_extra.pagination import PageNumberPaginationExtra
+
+# Define a FilterSchema for your model
+class EventFilterSchema(FilterSchema):
+    title: Optional[str] = None
+    category: Optional[str] = None
+    start_date__gte: Optional[str] = None
+
+@api_controller("/events")
+class EventModelController(ModelControllerBase):
+    model_config = ModelConfig(
+        model=Event,
+        pagination=ModelPagination(
+            klass=PageNumberPaginationExtra,
+            filter_schema=EventFilterSchema,  # Add filtering support
+            paginator_kwargs={"page_size": 25}
+        )
+    )
+```
+
+This configuration automatically applies the `FilterSchema` to the list endpoint, allowing users to filter results:
+
+```
+GET /api/events/?title=Conference&category=Tech&page=1&page_size=25
+```
+
+### **Advanced Filtering with Custom Lookups**
+
+Use Django Ninja's `FilterLookup` annotation for more sophisticated filtering:
+
+```python
+from typing import Annotated, Optional
+from ninja import FilterSchema, FilterLookup
+
+class AdvancedEventFilterSchema(FilterSchema):
+    # Case-insensitive search
+    title: Annotated[Optional[str], FilterLookup("title__icontains")] = None
+    
+    # Date range filtering
+    start_date_after: Annotated[Optional[str], FilterLookup("start_date__gte")] = None
+    start_date_before: Annotated[Optional[str], FilterLookup("start_date__lte")] = None
+    
+    # Related field filtering
+    category: Annotated[Optional[str], FilterLookup("category__name__iexact")] = None
+    
+    # Multiple field search
+    search: Annotated[
+        Optional[str],
+        FilterLookup([
+            "title__icontains",
+            "description__icontains",
+            "location__icontains"
+        ])
+    ] = None
+
+@api_controller("/events")
+class EventModelController(ModelControllerBase):
+    model_config = ModelConfig(
+        model=Event,
+        pagination=ModelPagination(
+            klass=PageNumberPaginationExtra,
+            filter_schema=AdvancedEventFilterSchema,
+            paginator_kwargs={"page_size": 50}
+        )
+    )
+```
+
+!!! info "Learn More About FilterSchema"
+    For comprehensive documentation on FilterSchema features, custom expressions, combining filters, and advanced filtering techniques, visit: [https://django-ninja.dev/guides/input/filtering/](https://django-ninja.dev/guides/input/filtering/)
+
 ## **Route Configuration**
 
 You can customize individual route behavior using route info dictionaries. Each route type (`create_route_info`, `list_route_info`, `find_one_route_info`, `update_route_info`, `patch_route_info`, `delete_route_info`) accepts various configuration parameters.
@@ -316,7 +394,13 @@ class EventModelController(ModelControllerBase):
     - Consider your data size when choosing pagination class
     - Use appropriate page sizes for your use case
 
-4. **Async Support**:
+4. **Filtering**:
+    - Use `FilterSchema` to provide flexible filtering on list endpoints
+    - Leverage `FilterLookup` for complex database lookups (e.g., `__icontains`, `__gte`)
+    - Consider indexing filtered fields in your database for performance
+    - Document available filters in your API documentation
+
+5. **Async Support**:
     - Enable `async_routes` when using async database operations
     - Implement custom async services for complex operations
     - Consider performance implications of async operations 

docs/tutorial/pagination.md

@@ -4,9 +4,10 @@
 
 ## **Properties**
 
-`def paginate(func_or_pgn_class: Any = NOT_SET, **paginator_params: Any) -> Callable[..., Any]:`
+`def paginate(func_or_pgn_class: Any = NOT_SET, filter_schema: Optional[Type[FilterSchema]] = None, **paginator_params: Any) -> Callable[..., Any]:`
 
 - func_or_pgn_class: Defines a route function or a Pagination Class. default: `ninja_extra.pagination.LimitOffsetPagination`
+- filter_schema: Optional FilterSchema class from Django Ninja for filtering querysets before pagination
 - paginator_params: extra parameters for initialising Pagination Class
 
 ### **Using Ninja LimitOffsetPagination**
@@ -75,3 +76,127 @@ api.register_controllers(UserController)
 ```
 
 ![Preview](../images/pagination_example.gif)
+
+## **Pagination with Filtering**
+
+You can combine pagination with Django Ninja's `FilterSchema` to provide both filtering and pagination capabilities. Filters are applied to the queryset **before** pagination.
+
+!!! info "Learn More About FilterSchema"
+    For comprehensive information about FilterSchema features, custom expressions, combining filters, and advanced filtering techniques, see the official Django Ninja documentation: [https://django-ninja.dev/guides/input/filtering/](https://django-ninja.dev/guides/input/filtering/)
+
+### **Basic Filtering Example**
+
+```python
+from typing import Optional
+from ninja import FilterSchema
+from ninja_extra.pagination import paginate, PageNumberPaginationExtra, PaginatedResponseSchema
+from ninja_extra import api_controller, route, NinjaExtraAPI
+from ninja import ModelSchema
+from myapp.models import Book
+
+
+class BookSchema(ModelSchema):
+    class Config:
+        model = Book
+        model_fields = ['id', 'title', 'author', 'price', 'published_date']
+
+
+# Define a FilterSchema for your model
+class BookFilterSchema(FilterSchema):
+    title: Optional[str] = None
+    author: Optional[str] = None
+    min_price: Optional[float] = None
+
+
+@api_controller('/books')
+class BookController:
+    @route.get('', response=PaginatedResponseSchema[BookSchema])
+    @paginate(PageNumberPaginationExtra, filter_schema=BookFilterSchema, page_size=20)
+    def list_books(self):
+        return Book.objects.all()
+
+
+api = NinjaExtraAPI(title='Books API')
+api.register_controllers(BookController)
+```
+
+**Example API calls:**
+- `GET /api/books/?page=1&page_size=20` - Paginated results
+- `GET /api/books/?title=Python&page=1` - Filter by title and paginate
+- `GET /api/books/?author=John&min_price=10&page=2` - Multiple filters with pagination
+
+### **Advanced Filtering with Custom Lookups**
+
+Use Django Ninja's `FilterLookup` annotation for more complex filtering:
+
+```python
+from typing import Annotated, Optional
+from ninja import FilterSchema, FilterLookup
+
+
+class AdvancedBookFilterSchema(FilterSchema):
+    # Case-insensitive containment search
+    title: Annotated[Optional[str], FilterLookup("title__icontains")] = None
+    
+    # Exact match on author name
+    author: Annotated[Optional[str], FilterLookup("author__name__iexact")] = None
+    
+    # Greater than or equal to price
+    min_price: Annotated[Optional[float], FilterLookup("price__gte")] = None
+    
+    # Less than or equal to price
+    max_price: Annotated[Optional[float], FilterLookup("price__lte")] = None
+    
+    # Date range filtering
+    published_after: Annotated[Optional[str], FilterLookup("published_date__gte")] = None
+
+
+@api_controller('/books')
+class BookController:
+    @route.get('', response=PaginatedResponseSchema[BookSchema])
+    @paginate(PageNumberPaginationExtra, filter_schema=AdvancedBookFilterSchema, page_size=20)
+    def list_books(self):
+        return Book.objects.all()
+```
+
+### **Using FilterSchema with Model Controllers**
+
+FilterSchema can also be integrated with Model Controllers through the `ModelPagination` configuration:
+
+```python
+from ninja import FilterSchema
+from ninja_extra.controllers import ModelControllerBase
+from ninja_extra.controllers.model import ModelConfig, ModelPagination
+from ninja_extra.pagination import PageNumberPaginationExtra
+from myapp.models import Book
+
+
+class BookFilterSchema(FilterSchema):
+    title: Optional[str] = None
+    author__name: Optional[str] = None
+    price__gte: Optional[float] = None
+
+
+class BookModelController(ModelControllerBase):
+    model_config = ModelConfig(
+        model=Book,
+        pagination=ModelPagination(
+            klass=PageNumberPaginationExtra,
+            filter_schema=BookFilterSchema,
+            paginator_kwargs={"page_size": 25}
+        )
+    )
+```
+
+This configuration automatically applies the FilterSchema to the `list` endpoint of your Model Controller.
+
+### **How It Works**
+
+1. **Query Parameters**: When a request is made, both filter and pagination parameters are extracted from query parameters
+2. **Filtering**: The FilterSchema validates and applies filters to the queryset first
+3. **Pagination**: The filtered results are then paginated according to the pagination parameters
+4. **Response**: The paginated response includes filtered results with pagination metadata
+
+### **OpenAPI Schema**
+
+When using FilterSchema with pagination, the OpenAPI documentation automatically includes both filter parameters and pagination parameters, making your API self-documenting and easy to use.

ninja_extra/controllers/model/builder.py

@@ -155,6 +155,9 @@ def _register_list_endpoint(self) -> None:
             )
             if self._config.pagination.paginator_kwargs:  # pragma: no cover
                 paginate_kwargs.update(self._config.pagination.paginator_kwargs)
+            # Add filter_schema if provided
+            if self._config.pagination.filter_schema:
+                paginate_kwargs["filter_schema"] = self._config.pagination.filter_schema
 
         list_items = self._route_factory.list(
             path="/",

ninja_extra/controllers/model/endpoints.py

@@ -3,6 +3,7 @@
 
 from django.db.models import Model as DjangoModel
 from django.db.models import QuerySet
+from ninja import FilterSchema
 from ninja.constants import NOT_SET, NOT_SET_TYPE
 from ninja.pagination import PaginationBase
 from ninja.params import Body
@@ -392,6 +393,7 @@ def list(
         pagination_class: t.Optional[
             t.Type[PaginationBase]
         ] = PageNumberPaginationExtra,
+        filter_schema: t.Optional[t.Type[FilterSchema]] = None,
         **paginate_kwargs: t.Any,
     ) -> ModelEndpointFunction:
         """
@@ -408,7 +410,9 @@ def _setup(model_controller_type: t.Type["ModelControllerBase"]) -> t.Callable:
             )
 
             if pagination_response_schema and pagination_class:
-                list_items = paginate(pagination_class, **paginate_kwargs)(list_items)
+                list_items = paginate(
+                    pagination_class, filter_schema=filter_schema, **paginate_kwargs
+                )(list_items)
                 return route.get(
                     working_path,
                     response=response

ninja_extra/pagination/decorator.py

@@ -1,7 +1,8 @@
 import inspect
 import logging
-from typing import Any, Callable, Type, cast, overload
+from typing import Any, Callable, Optional, Type, cast, overload
 
+from ninja import FilterSchema
 from ninja.constants import NOT_SET
 from ninja.pagination import PaginationBase
 from ninja.signature import is_async
@@ -22,13 +23,17 @@ def paginate() -> Callable[..., Any]:  # pragma: no cover
 
 @overload
 def paginate(
-    func_or_pgn_class: Any = NOT_SET, **paginator_params: Any
+    func_or_pgn_class: Any = NOT_SET,
+    filter_schema: Optional[Type[FilterSchema]] = None,
+    **paginator_params: Any,
 ) -> Callable[..., Any]:  # pragma: no cover
     ...
 
 
 def paginate(
-    func_or_pgn_class: Any = NOT_SET, **paginator_params: Any
+    func_or_pgn_class: Any = NOT_SET,
+    filter_schema: Optional[Type[FilterSchema]] = None,
+    **paginator_params: Any,
 ) -> Callable[..., Any]:
     isfunction = inspect.isfunction(func_or_pgn_class)
     is_not_set = func_or_pgn_class == NOT_SET
@@ -38,20 +43,25 @@ def paginate(
     )
 
     if isfunction:
-        return _inject_pagination(func_or_pgn_class, pagination_class)
+        return _inject_pagination(
+            func_or_pgn_class, pagination_class, filter_schema=filter_schema
+        )
 
     if not is_not_set:
         pagination_class = func_or_pgn_class
 
     def wrapper(func: Callable[..., Any]) -> Any:
-        return _inject_pagination(func, pagination_class, **paginator_params)
+        return _inject_pagination(
+            func, pagination_class, filter_schema=filter_schema, **paginator_params
+        )
 
     return wrapper
 
 
 def _inject_pagination(
     func: Callable[..., Any],
     paginator_class: Type[PaginationBase],
+    filter_schema: Optional[Type[FilterSchema]] = None,
     **paginator_params: Any,
 ) -> Callable[..., Any]:
     paginator: PaginationBase = paginator_class(**paginator_params)
@@ -61,7 +71,10 @@ def _inject_pagination(
     if is_async(func):
         paginator_operation_class = AsyncPaginatorOperation
     paginator_operation = paginator_operation_class(
-        paginator=paginator, view_func=func, paginator_kwargs_name=paginator_kwargs_name
+        paginator=paginator,
+        view_func=func,
+        paginator_kwargs_name=paginator_kwargs_name,
+        filter_schema=filter_schema,
     )
 
     return paginator_operation.as_view