Add UseAdditionalFields customization (#1180)

Author: uriyyo

docs/tutorials_advanced/customization.md

@@ -30,7 +30,7 @@ Now we can customize our page.
 If you want to change default name of page class, you should use `UseName` customizer:
 
 ```py
-{!../docs_src/tutorials_advanced/customization.py [ln:17-21]!}
+{!../docs_src/tutorials_advanced/customization.py [ln:18-22]!}
 ```
 
 1. Now your class will be names 'IntPage' instead of 'CustomizedPage'.
@@ -47,7 +47,7 @@ By default, cursor-based page don't include total count of items, and offset-bas
 If you want to change this behavior, you should use `UseIncludeTotal` customizer:
 
 ```py
-{!../docs_src/tutorials_advanced/customization.py [ln:22-26]!}
+{!../docs_src/tutorials_advanced/customization.py [ln:23-27]!}
 ```
 
 1. Now when you will paginate using `PageNoTotal` class, it will not include total count of items.
@@ -57,7 +57,7 @@ If you want to change this behavior, you should use `UseIncludeTotal` customizer
 If you want to change default values of pagination parameters, you should use `UseParamsFields` customizer:
 
 ```py
-{!../docs_src/tutorials_advanced/customization.py [ln:27-31]!}
+{!../docs_src/tutorials_advanced/customization.py [ln:28-32]!}
 ```
 
 1. Now when `size` parameter is not provided, it will be equal to 500.
@@ -68,7 +68,7 @@ If you want to change default values of pagination parameters, you should use `U
 If you want to change type of pagination parameters, you should use `UseParams` customizer:
 
 ```py
-{!../docs_src/tutorials_advanced/customization.py [ln:32-36]!}
+{!../docs_src/tutorials_advanced/customization.py [ln:33-37]!}
 ```
 
 1. Now all pagination parameters will be optional.
@@ -79,7 +79,7 @@ If you want to change type of pagination parameters, you should use `UseParams`
 If you want use another name of field rather than default, you should use `UseFieldsAliases` customizer:
 
 ```py
-{!../docs_src/tutorials_advanced/customization.py [ln:46-50]!}
+{!../docs_src/tutorials_advanced/customization.py [ln:47-51]!}
 ```
 
 1. Now `total` field will be serialized as `count`.
@@ -90,7 +90,7 @@ If you want use another name of field rather than default, you should use `UseFi
 If you want to exclude some fields from serialization, you should use `UseExcludedFields` customizer:
 
 ```py
-{!../docs_src/tutorials_advanced/customization.py [ln:51-55]!}
+{!../docs_src/tutorials_advanced/customization.py [ln:52-56]!}
 ```
 
 1. Now `total` field will not be serialized.
@@ -101,7 +101,7 @@ If you want to exclude some fields from serialization, you should use `UseExclud
 If you want to change pydantic model config, you should use `UseModelConfig` customizer:
 
 ```py
-{!../docs_src/tutorials_advanced/customization.py [ln:56-60]!}
+{!../docs_src/tutorials_advanced/customization.py [ln:57-61]!}
 ```
 
 1. Now `Page` class will have `anystr_lower` set to `True`.
@@ -112,7 +112,7 @@ If you want to change pydantic model config, you should use `UseModelConfig` cus
 If you want to change type of page parameters, you should use `UseParams` customizer:
 
 ```py
-{!../docs_src/tutorials_advanced/customization.py [ln:38-46]!}
+{!../docs_src/tutorials_advanced/customization.py [ln:39-47]!}
 ```
 
 1. Now `Page.__params_type__` attribute will be point to `MyParams` class.
@@ -123,7 +123,7 @@ If you want to change type of page parameters, you should use `UseParams` custom
 You can use multiple customizers at once, just pass them as to regular `Annotated`:
 
 ```py
-{!../docs_src/tutorials_advanced/customization.py [ln:62-68]!}
+{!../docs_src/tutorials_advanced/customization.py [ln:63-69]!}
 ```
 
 1. Now `CustomPage` will have `CustomPage` name, no total count of items, all params optional.

docs_src/tutorials_advanced/customization.py

@@ -1,8 +1,9 @@
-from typing import TypeVar
+from typing import Optional, TypeVar
 
 from fastapi_pagination import Page, Params
 from fastapi_pagination.customization import (
     CustomizedPage,
+    UseAdditionalFields,
     UseExcludedFields,
     UseFieldsAliases,
     UseIncludeTotal,
@@ -65,3 +66,12 @@ class MyParams(Params): ...  # your magic here
     UseIncludeTotal(False),
     UseOptionalParams(),
 ]  # (1)
+
+
+PageWithAdditionalFields = CustomizedPage[
+    Page[T],
+    UseAdditionalFields(
+        filters=str,  # without default value
+        sort=(Optional[str], None),  # with default value
+    ),
+]  # (1)

fastapi_pagination/customization.py

@@ -14,6 +14,7 @@
     "UseModelConfig",
     "UseExcludedFields",
     "UseFieldsAliases",
+    "UseAdditionalFields",
     "ClsNamespace",
     "PageCls",
 ]
@@ -32,6 +33,7 @@
     Tuple,
     Type,
     TypeVar,
+    Union,
     no_type_check,
     runtime_checkable,
 )
@@ -321,3 +323,20 @@ def customize_page_ns(self, page_cls: PageCls, ns: ClsNamespace) -> None:
             for name, alias in self.aliases.items():
                 assert name in page_cls.__fields__, f"Unknown field {name!r}"
                 fields_config[name]["alias"] = alias
+
+
+_RawFieldDef: TypeAlias = Union[Any, Tuple[Any, Any]]
+
+
+class UseAdditionalFields(PageCustomizer):
+    def __init__(self, **fields: _RawFieldDef) -> None:
+        self.fields = fields
+
+    def customize_page_ns(self, page_cls: PageCls, ns: ClsNamespace) -> None:
+        anns = ns.setdefault("__annotations__", {})
+
+        for name, field in self.fields.items():
+            if isinstance(field, tuple):
+                anns[name], ns[name] = field
+            else:
+                anns[name] = field

tests/test_customization.py

@@ -9,6 +9,7 @@
     ClsNamespace,
     CustomizedPage,
     PageCustomizer,
+    UseAdditionalFields,
     UseExcludedFields,
     UseFieldsAliases,
     UseIncludeTotal,
@@ -201,3 +202,28 @@ def test_use_aliases():
         assert CustomPage.model_fields["total"].serialization_alias == "count"
     else:
         assert CustomPage.__fields__["total"].alias == "count"
+
+
+def test_additional_fields():
+    CustomPage = CustomizedPage[
+        Page,
+        UseAdditionalFields(
+            a=int,
+            b=(str, "my-default"),
+        ),
+    ]
+
+    if IS_PYDANTIC_V2:
+        from pydantic_core import PydanticUndefined
+
+        assert CustomPage.model_fields["a"].annotation == int
+        assert CustomPage.model_fields["a"].default is PydanticUndefined
+
+        assert CustomPage.model_fields["b"].annotation == str
+        assert CustomPage.model_fields["b"].default == "my-default"
+    else:
+        assert CustomPage.__fields__["a"].type_ == int
+        assert CustomPage.__fields__["a"].default is None
+
+        assert CustomPage.__fields__["b"].type_ == str
+        assert CustomPage.__fields__["b"].default == "my-default"