Merge pull request #53 from QtiQla/master

add searching and ordering

Author: eadwinCode

.pre-commit-config.yaml

@@ -14,14 +14,14 @@ repos:
       name: Code Formatting
       entry: "make fmt"
       types: [python]
-      language_version: python3.8
+      language_version: python3
       language: python
     - id: code_linting
       args: [ ]
       name: Code Linting
       entry: "make lint"
       types: [ python ]
-      language_version: python3.8
+      language_version: python3
       language: python
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v2.3.0

docs/settings.md

@@ -1,4 +1,5 @@
 # **Settings**
+
 Django-Ninja-Extra has some settings that can be overridden by adding a `NINJA_EXTRA` field in Django `settings.py` with some key-value pair as shown below:
 
 ```python
@@ -17,40 +18,54 @@ NINJA_EXTRA = {
         'user': '1000/day',
         'anon': '100/day',
     },
-    'NUM_PROXIES': None
+    'NUM_PROXIES': None,
+    'ORDERING_CLASS':"ninja_extra.ordering.Ordering",
+    'SEARCHING_CLASS':"ninja_extra.searching.Search",
 }
 ```
+
 You can override what you don't need. It is not necessary need to override everything.
 
-`PAGINATION_CLASS`
-=======================
-It defines the default paginator class used by the `paginate` decorator 
+# `PAGINATION_CLASS`
+
+It defines the default paginator class used by the `paginate` decorator
 function if a paginator class is not defined.
 default: `ninja_extra.pagination.LimitOffsetPagination`
 
-`PAGINATION_PER_PAGE`
-=======================
+# `PAGINATION_PER_PAGE`
+
 It defines the default page size that is passed to the `PAGINATION_CLASS` during instantiation.
 default: `100`
 
+# `INJECTOR_MODULES`
 
-`INJECTOR_MODULES`
-=======================
 It contains a list of strings that defines the path to injector `Module`.
 default: `[]`
 
-`THROTTLE_CLASSES`
-=======================
+# `THROTTLE_CLASSES`
+
 It contains a list of strings that defines the path default throttling classes.
 default: `[
     "ninja_extra.throttling.AnonRateThrottle",
     "ninja_extra.throttling.UserRateThrottle",
 ]`
 
-`THROTTLE_RATES`
-=======================
+# `THROTTLE_RATES`
+
 It contains a key-value pair of different throttling rates which are applies to different `THROTTLING_CLASSES`.
 default: `{
     'user': '1000/day',
     'anon': '100/day',
 }`
+
+# `ORDERING_CLASS`
+
+It defines the default ordering class used by the `ordering` decorator
+function if a ordering class is not defined.
+default: `ninja_extra.ordering.Ordering`
+
+# `SEARCHING_CLASS`
+
+It defines the default searching class used by the `searching` decorator
+function if a searching class is not defined.
+default: `ninja_extra.searching.Searching`

docs/tutorial/ordering.md

@@ -0,0 +1,81 @@
+# **Ordering**
+
+**Django Ninja Extra** provides an intuitive ordering model using `ordering` decoration from the Django-Ninja-Extra ordering module. It expects a Queryset from as a route function result.
+
+> This feature was inspired by the [DRF OrderingFilter](https://www.django-rest-framework.org/api-guide/filtering/#orderingfilter)
+
+## **Properties**
+
+`def ordering(func_or_ordering_class: Any = NOT_SET, **ordering_params: Any) -> Callable[..., Any]:`
+
+- func_or_ordering_class: Defines a route function or an Ordering Class. default: `ninja_extra.ordering.Ordering`
+- ordering_params: extra parameters for initialising Ordering Class
+
+### Changing Default Ordering Class
+
+To change the default ordering class, you need to add a `NINJA_EXTRA` variable in `settings.py` with a key `ORDERING_CLASS` and value defining path to ordering class
+
+```python
+# Django project settings.py
+INSTALLED_APPS = [
+    ...
+]
+NINJA_EXTRA={
+    'ORDERING_CLASS': 'someapp.somemodule.CustomOrdering'
+}
+```
+
+## **Usage**
+
+- If you do not specify the `ordering_fields` parameter, all fields from the QuerySet will be used for ordering.
+- For example, to order users by username:
+  > http://example.com/api/users?ordering=username
+- The client may also specify reverse orderings by prefixing the field name with '-', example:
+  > http://example.com/api/users?ordering=-username
+- Multiple orderings may also be specified:
+  > http://example.com/api/users?ordering=username,email
+
+```python
+from typing import List
+from ninja_extra.ordering import ordering, Ordering
+from ninja_extra import api_controller, route, NinjaExtraAPI
+from ninja import ModelSchema
+from django.contrib.auth import get_user_model
+
+user_model = get_user_model()
+
+
+class UserSchema(ModelSchema):
+    class Config:
+        model = user_model
+        model_fields = ['username', 'email']
+
+
+@api_controller('/users')
+class UserController:
+    @route.get('', response=List[UserSchema])
+    @ordering(Ordering, ordering_fields=['username', 'email'])
+    def get_users(self):
+        return user_model.objects.all()
+
+    @route.get('/all-sort', response=List[UserSchema])
+    @ordering
+    def get_users_with_all_field_ordering(self):
+        return user_model.objects.all()
+
+
+api = NinjaExtraAPI(title='Ordering Test')
+api.register_controllers(UserController)
+```
+
+## Note
+
+> If you use the `paginate` decorator and the `ordering` decorator together, the `paginate` decorator should be above the `ordering` decorator because first the data are sorted and then the data are paginated, for example:
+>
+> ```python
+>    @route.get('', response=List[UserSchema])
+>    @paginate
+>    @ordering(Ordering, ordering_fields=['username', 'email'])
+>    def get_users(self):
+>        return user_model.objects.all()
+> ```

docs/tutorial/searching.md

@@ -0,0 +1,90 @@
+# **Searching**
+
+**Django Ninja Extra** provides an intuitive searching model using `searching` decoration from the Django-Ninja-Extra searching module. It expects a Queryset from as a route function result.
+
+> This feature was inspired by the [DRF SearchFilter](https://www.django-rest-framework.org/api-guide/filtering/#searchfilter)
+
+## **Properties**
+
+`def searching(func_or_searching_class: Any = NOT_SET, **searching_params: Any) -> Callable[..., Any]:`
+
+- func_or_searching_class: Defines a route function or an Searching Class. default: `ninja_extra.searching.Searching`
+- searching_params: extra parameters for initialising Searching Class
+
+### Changing Default Searching Class
+
+To change the default searching class, you need to add a `NINJA_EXTRA` variable in `settings.py` with a key `SEARCHING_CLASS` and value defining path to searching class
+
+```python
+# Django project settings.py
+INSTALLED_APPS = [
+    ...
+]
+NINJA_EXTRA={
+    'SEARCHING_CLASS': 'someapp.somemodule.CustomSearching'
+}
+```
+
+## **Usage**
+
+- If you do not specify the `search_fields` parameter, will return the result without change.
+- For example, to search users by username or email:
+  > http://example.com/api/users?search=someuser
+- You can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation:
+  > search_fields = ['username', 'email', 'profile__profession']
+- By default, searches will use case-insensitive partial matches.  The search parameter may contain multiple search terms, which should be whitespace and/or comma separated.  If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched. The search behavior may be restricted by prepending various characters to the `search_fields`.
+
+  * '^' Starts-with search.
+  * '=' Exact matches.
+  * '@' Full-text search.  (Currently only supported Django's [PostgreSQL backend](https://docs.djangoproject.com/en/stable/ref/contrib/postgres/search/).)
+  * '$' Regex search.
+
+  For example:
+
+    > search_fields = ['=username', '=email']
+
+```python
+from typing import List
+from ninja_extra.searching import searching, Searching
+from ninja_extra import api_controller, route, NinjaExtraAPI
+from ninja import ModelSchema
+from django.contrib.auth import get_user_model
+
+user_model = get_user_model()
+
+
+class UserSchema(ModelSchema):
+    class Config:
+        model = user_model
+        model_fields = ['username', 'email']
+
+
+@api_controller('/users')
+class UserController:
+    @route.get('', response=List[UserSchema])
+    @searching(Searching, search_fields=['username', 'email'])
+    def get_users(self):
+        return user_model.objects.all()
+
+    @route.get('/iexact-email', response=List[UserSchema])
+    @searching(search_fields=['=email'])
+    def get_users_with_search_iexact_email(self):
+        return user_model.objects.all()
+
+
+api = NinjaExtraAPI(title='Searching Test')
+api.register_controllers(UserController)
+```
+
+## Note
+
+> If you use the `paginate` decorator, the `ordering` decorator and the `searching` decorator together, the `paginate` decorator should be above the `ordering` decorator and the `ordering` decorator should be above the `searching` decorator because first the data is filtered, then the data is sorted and then paginated:, for example:
+>
+> ```python
+>    @route.get('', response=List[UserSchema])
+>    @paginate
+>    @ordering(Ordering, ordering_fields=['username', 'email'])
+>    @searching(Searching, search_fields=['username', 'email'])
+>    def get_users(self):
+>        return user_model.objects.all()
+> ```

mkdocs.yml

@@ -46,6 +46,9 @@ nav:
   - Form Request: tutorial/form.md
   - Schema: tutorial/schema.md
   - Pagination: tutorial/pagination.md
+  - Filtering:
+    - Ordering: tutorial/ordering.md
+    - Searching: tutorial/searching.md
   - Error Handling: tutorial/custom_exception.md
   - Versioning: tutorial/versioning.md
   - Throttling: tutorial/throttling.md

ninja_extra/conf/settings.py

@@ -21,6 +21,8 @@ def __init__(self, data: dict) -> None:
         "ninja_extra.throttling.UserRateThrottle",
     ],
     THROTTLE_RATES={"user": None, "anon": None},
+    ORDERING_CLASS="ninja_extra.ordering.Ordering",
+    SEARCHING_CLASS="ninja_extra.searching.Searching",
 )
 
 USER_SETTINGS = UserDefinedSettingsMapper(
@@ -43,6 +45,12 @@ class Config:
     THROTTLE_CLASSES: List[Any] = []
     NUM_PROXIES: Optional[int] = None
     INJECTOR_MODULES: List[Any] = []
+    ORDERING_CLASS: Any = Field(
+        "ninja_extra.ordering.Ordering",
+    )
+    SEARCHING_CLASS: Any = Field(
+        "ninja_extra.searching.Searching",
+    )
 
     @validator("INJECTOR_MODULES", pre=True)
     def pre_injector_module_validate(cls, value: Any) -> Any:
@@ -62,6 +70,18 @@ def pre_pagination_class_validate(cls, value: Any) -> Any:
             raise ValueError("Invalid data type")
         return value
 
+    @validator("ORDERING_CLASS", pre=True)
+    def pre_ordering_class_validate(cls, value: Any) -> Any:
+        if isinstance(value, list):
+            raise ValueError("Invalid data type")
+        return value
+
+    @validator("SEARCHING_CLASS", pre=True)
+    def pre_searching_class_validate(cls, value: Any) -> Any:
+        if isinstance(value, list):
+            raise ValueError("Invalid data type")
+        return value
+
     @root_validator
     def validate_ninja_extra_settings(cls, values: Any) -> Any:
         for item in NinjaExtra_SETTINGS_DEFAULTS.keys():