[IMP] fastapi: Rename 'total' to 'count' into PagedCollection

fastapi/readme/USAGE.rst

@@ -1116,8 +1116,9 @@ the app is robust and easy to maintain. Here are some of them:
 
 * As a corollary of the previous point, a search handler must always use the
   pagination mechanism with a reasonable default page size. The result list
-  must be enclosed in a json document that contains the total number of records
-  and the list of records.
+  must be enclosed in a json document that contains the count of records into
+  the system matching your search criteria and the list of records for the given
+  page and size.
 
 * Use plural for the name of a service. For example, if you provide a service
   that allows you to manage the sale orders, you must use the name 'sale_orders'
@@ -1149,7 +1150,7 @@ you be consistent when writing a route handler for a search route.
 1. A dependency method to use to specify the pagination parameters in the same
    way for all the search route handlers: **'odoo.addons.fastapi.paging'**.
 2. A PagedCollection pydantic model to use to return the result of a search route
-   handler enclosed in a json document that contains the total number of records.
+   handler enclosed in a json document that contains the count of records.
 
 .. code-block:: python
 
@@ -1179,7 +1180,7 @@ you be consistent when writing a route handler for a search route.
         count = env["sale.order"].search_count([])
         orders = env["sale.order"].search([], limit=paging.limit, offset=paging.offset)
         return PagedCollection[SaleOrder](
-            total=count,
+            count=count,
             items=[SaleOrder.model_validate(order) for order in orders],
         )
 

fastapi/readme/newsfragments/380.feature

@@ -0,0 +1,7 @@
+The field *total* in the *PagedCollection* schema is replaced by the field *count*.
+The field *total* is now deprecated and will be removed in the next major version.
+This change is backward compatible. The json document returned will now
+contain both fields *total* and *count* with the same value. In your python
+code the field *total*, if used, will fill the field *count* with the same
+value. You are encouraged to use the field *count* instead of *total* and adapt
+your code accordingly.

fastapi/schemas.py

@@ -1,19 +1,40 @@
 # Copyright 2022 ACSONE SA/NV
 # License AGPL-3.0 or later (http://www.gnu.org/licenses/agpl).
-
+import warnings
 from enum import Enum
-from typing import Generic, List, Optional, TypeVar
+from typing import Annotated, Generic, List, Optional, TypeVar
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, computed_field
 
 T = TypeVar("T")
 
 
 class PagedCollection(BaseModel, Generic[T]):
-
-    total: int
+    count: Annotated[
+        int,
+        Field(
+            ...,
+            desciption="Count of items into the system.\n "
+            "Replaces the total field which is deprecated",
+            validation_alias=AliasChoices("count", "total"),
+        ),
+    ]
     items: List[T]
 
+    @computed_field()
+    @property
+    def total(self) -> int:
+        return self.count
+
+    @total.setter
+    def total(self, value: int):
+        warnings.warn(
+            "The total field is deprecated, please use count instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.count = value
+
 
 class Paging(BaseModel):
     limit: Optional[int] = None