Merge pull request #26 from uriyyo/v0.6.0

0.6.0

.pre-commit-config.yaml

@@ -1,11 +1,6 @@
 repos:
-  - repo: https://github.com/asottile/seed-isort-config
-    rev: v1.9.3
-    hooks:
-      - id: seed-isort-config
-
   - repo: https://github.com/pre-commit/mirrors-isort
-    rev: v5.6.4
+    rev: v5.7.0
     hooks:
       - id: isort
 
@@ -24,7 +19,7 @@ repos:
           - flake8-bugbear
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.800
+    rev: v0.812
     hooks:
       - id: mypy
         exclude: tests

README.md

@@ -28,11 +28,10 @@ Available integrations:
 ## Example
 
 ```python
-from fastapi import FastAPI, Depends
+from fastapi import FastAPI
 from pydantic import BaseModel
 
-from fastapi_pagination import PaginationParams, Page
-from fastapi_pagination.paginator import paginate
+from fastapi_pagination import Page, add_pagination, paginate
 
 app = FastAPI()
 
@@ -49,34 +48,9 @@ users = [
 
 
 @app.get('/users', response_model=Page[User])
-async def get_users(params: PaginationParams = Depends()):
-    return paginate(users, params)
-```
-
-## Example using implicit params
-
-```python
-from fastapi import FastAPI, Depends
-from pydantic import BaseModel
-
-from fastapi_pagination import Page, pagination_params
-from fastapi_pagination.paginator import paginate
-
-app = FastAPI()
-
-
-class User(BaseModel):
-    name: str
-    surname: str
-
-
-users = [
-    User(name='Yurii', surname='Karabas'),
-    # ...
-]
-
-
-@app.get('/users', response_model=Page[User], dependencies=[Depends(pagination_params)])
 async def get_users():
     return paginate(users)
+
+
+add_pagination(app)
 ```

docs/advanced.md

@@ -1,16 +1,16 @@
 There are 3 thing you should know about:
 
 * `Page` - `pydantic` model that represents paginated results.
-* `PaginationParams` - class that represents pagination params passed from user.
+* `Params` - class that represents pagination params passed from user.
 * `paginate` - function that is used to paginate your query and data.
 
-## `Page` and `PaginationParams`
+## `Page` and `Params`
 
-`fastapi-pagination` by default provides you with 2 implementations of `Page` and `PaginationParams`.
+`fastapi-pagination` by default provides you with 2 implementations of `Page` and `Params`.
 
-### 1. `Page` and `PaginationParams` (default)
+### 1. `Page` and `Params` (default)
 
-`PaginationParams` constrains:
+`Params` constrains:
 
 1. `page` >= 0
 2. 0 < `size` <= 100 (default value 50)
@@ -39,9 +39,9 @@ Data schema of `Page`:
 
 Can be imported from `fastapi_pagination`.
 
-### 2. Limit-Offset `Page` and `PaginationParams`
+### 2. Limit-Offset `Page` and `Params`
 
-`PaginationParams` constrains:
+`Params` constrains:
 
 1. 0 < `limit` <= 100 (default value 50)
 2. `offset` > 0
@@ -68,7 +68,7 @@ Data schema of `Page`:
 }
 ```
 
-Can be imported from `fastapi_pagination.limi_offset`.
+Can be imported from `fastapi_pagination.limit_offset`.
 
 ## `paginate`
 
@@ -77,7 +77,7 @@ Can be imported from `fastapi_pagination.limi_offset`.
 `fastapi_pagination.paginate` - can be used to paginate any python sequence like tuple or list
 
 ```python
-from fastapi_pagination import paginate
+from fastapi_pagination import paginate, Page, Params
 
 users = [...]
 

docs/customization.md

@@ -9,16 +9,17 @@ In order to create custom `Page` you need to inherit from
 from __future__ import annotations
 from typing import TypeVar, Generic, Sequence
 
+from fastapi_pagination import Params
 from fastapi_pagination.bases import AbstractPage, AbstractParams
-from fastapi_pagination import use_as_page
 
 T = TypeVar("T")
 
 
-@use_as_page
 class Page(AbstractPage[T], Generic[T]):
     results: Sequence[T]
 
+    __params_type__ = Params  # Set params related to Page
+
     @classmethod
     def create(
             cls,
@@ -39,66 +40,42 @@ async def route():
 
 ## Params
 
-To create a custom `PaginationParams` you should implement `AbstractParams`
-protocol (it is not required to inherit from this cls).
-
-`AbstractParams` protocol requires class to have `to_limit_offset` method that must return instance
-of `fastapi_pagination.params.LimitOffsetPaginationParams` class.
+To create a custom `Params` you should inherit from `AbstractParams` and implement
+`to_raw_params` method.
 
 ```python
 from pydantic import BaseModel
 
-from fastapi_pagination.params import LimitOffsetPaginationParams
-from fastapi_pagination import using_params
+from fastapi_pagination.bases import RawParams, AbstractParams
 
 
-class Params(BaseModel):
+class Params(BaseModel, AbstractParams):
     total_items: int
     return_per_page: int
 
-    def to_limit_offset(self) -> LimitOffsetPaginationParams:
-        return LimitOffsetPaginationParams(
+    def to_raw_params(self) -> RawParams:
+        return RawParams(
             limit=self.total_items,
             offset=self.total_items * self.return_per_page,
         )
+```
 
+## Custom Params values
+
+```python
+from typing import TypeVar, Generic
+
+from fastapi import Query
+
+from fastapi_pagination.default import Page as BasePage, Params as BaseParams
+
+T = TypeVar("T")
+
+
+class Params(BaseParams):
+    size: int = Query(500, gt=0, le=1_000, description="Page size")
 
-pagination_params = using_params(Params)
-```
 
-Then custom params can be used in two ways:
-
-1. Using implicit params.
-
-    ```python
-    @app.get(
-        "/",
-        response_model=Page[UserOut],
-        dependencies=[Depends(pagination_params)],
-    )
-    async def route():
-        # In this case not need to pass params to paginator
-        return await paginate(User)
-    ```
-
-    ```python
-    @app.get(
-        "/",
-        response_model=Page[UserOut],
-    )
-    async def route(params: Params = Depends(pagination_params)):
-        # In this case not need to pass params to paginator
-        return await paginate(User)
-    ```
-
-2. Using explicit params.
-
-    ```python
-    @app.route(
-        "/",
-        response_model=Page[UserOut],
-    )
-    async def bar(params: Params):
-        # In this case params must be passed to paginator
-        return await paginate(User, params)
-    ```
+class Page(BasePage[T], Generic[T]):
+    __params_type__ = Params
+```

docs/first-steps.md

@@ -1,14 +1,14 @@
 It's pretty easy to use `fastapi-pagination`.
 
-First, you need to import `Page`, `PaginationParams` and one of `paginate`
+First, you need to import `Page`, `Params` and one of `paginate`
 functions from `fastapi_pagination`.
 
 * `Page` - is used as `response_model` in your route declaration.
-* `PaginationParams` - is a user provide params for pagination.
+* `Params` - is a user provide params for pagination.
 * `paginate` - is a function that will paginate your data.
 
 ```python
-from fastapi_pagination import Page, PaginationParams, paginate
+from fastapi_pagination import Page, Params, paginate
 from fastapi import FastAPI
 from pydantic import BaseModel
 
@@ -18,29 +18,49 @@ class User(BaseModel):
 
 
 app = FastAPI()
-users = [User("Yurii"), ...]
+
+users = [
+    User("Yurii"),
+    # ...
+]
 
 
 @app.get(
     "/",
     response_model=Page[User],
 )
-def route(params: PaginationParams):
+def route(params: Params):
     return paginate(users, params)
 ```
 
 In case when you don't like to explicitly pass `params` you can use
-`fastapi` dependency and use params implicitly.
+`add_pagination` function and use params implicitly.
 
 ```python
-from fastapi_pagination import pagination_params
+from fastapi_pagination import Page, paginate, add_pagination
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    name: str
+
+
+app = FastAPI()
+
+users = [
+    User("Yurii"),
+    # ...
+]
 
 
 @app.get(
     "/",
     response_model=Page[User],
-    dependencies=[Depends(pagination_params)]
 )
-def route():
+async def route():
     return paginate(users)
+
+
+add_pagination(app)
 ```

docs/index.md

@@ -5,11 +5,10 @@ FastAPI Pagination - easy to use pagination for FastAPI.
 Example of code and generated OpenAPI specification.
 
 ```python
-from fastapi import FastAPI, Depends
+from fastapi import FastAPI
 from pydantic import BaseModel
 
-from fastapi_pagination import Page, pagination_params
-from fastapi_pagination.paginator import paginate
+from fastapi_pagination import Page, add_pagination, paginate
 
 app = FastAPI()
 
@@ -25,13 +24,12 @@ users = [
 ]
 
 
-@app.get(
-    '/users',
-    response_model=Page[User],
-    dependencies=[Depends(pagination_params)],
-)
+@app.get('/users', response_model=Page[User])
 async def get_users():
-    return paginate(users) 
+    return paginate(users)
+
+
+add_pagination(app)
 ```
 
 ![OpenAPI](/images/openapi_example.png)