From 46704021857d1b358553a51bdf175d22c6db96e6 Mon Sep 17 00:00:00 2001 From: Wellington Date: Fri, 6 Dec 2024 23:56:10 -0300 Subject: [PATCH] docs: adjust pagination docs --- docs/docs/guides/response/pagination.md | 52 +++++++++++-------------- 1 file changed, 22 insertions(+), 30 deletions(-) diff --git a/docs/docs/guides/response/pagination.md b/docs/docs/guides/response/pagination.md index 1e79181fc..8691ecde9 100644 --- a/docs/docs/guides/response/pagination.md +++ b/docs/docs/guides/response/pagination.md @@ -2,7 +2,6 @@ **Django Ninja** comes with a pagination support. This allows you to split large result sets into individual pages. - To apply pagination to a function - just apply `paginate` decorator: ```python hl_lines="1 4" @@ -14,7 +13,6 @@ def list_users(request): return User.objects.all() ``` - That's it! Now you can query users with `limit` and `offset` GET parameters @@ -25,7 +23,6 @@ Now you can query users with `limit` and `offset` GET parameters by default limit is set to `100` (you can change it in your settings.py using `NINJA_PAGINATION_PER_PAGE`) - ## Built in Pagination Classes ### LimitOffsetPagination (default) @@ -42,17 +39,18 @@ def list_users(request): ``` Example query: + ``` /api/users?limit=10&offset=0 ``` this class has two input parameters: - - `limit` - defines a number of queryset on the page (default = 100, change in NINJA_PAGINATION_PER_PAGE) - - `offset` - set's the page window offset (default: 0, indexing starts with 0) - +- `limit` - defines a number of queryset on the page (default = 100, change in NINJA_PAGINATION_PER_PAGE) +- `offset` - set's the page window offset (default: 0, indexing starts with 0) ### PageNumberPagination + ```python hl_lines="1 4" from ninja.pagination import paginate, PageNumberPagination @@ -63,24 +61,24 @@ def list_users(request): ``` Example query: + ``` /api/users?page=2 ``` -this class has one parameter `page` and outputs 100 queryset per page by default (can be changed with settings.py) +this class has two parameters `page` and `page_size`, outputs 100 queryset per page by default (can be changed with settings.py) Page numbering start with 1 -you can also set custom page_size value individually per view: +if you need to limit certain endpoint higher or lower your default config you can inherit +and customize `Input` class like this ```python hl_lines="2" -@api.get("/users") -@paginate(PageNumberPagination, page_size=50) -def list_users(... +class MyLargerPageNumberPagination(PageNumberPagination): + class Input(PageNumberPagination.Input): + page_size: int = Field(20, ge=1, le=1000) ``` - - ## Accessing paginator parameters in view function If you need access to `Input` parameters used for pagination in your view function - use `pass_parameter` argument @@ -88,25 +86,21 @@ If you need access to `Input` parameters used for pagination in your view functi In that case input data will be available in `**kwargs`: ```python hl_lines="2 4" -@api.get("/someview") -@paginate(pass_parameter="pagination_info") -def someview(request, **kwargs): - page = kwargs["pagination_info"].page - return ... +class MyLargerPageNumberPagination(PageNumberPagination): + class Input(PageNumberPagination.Input): + page_size: int = Field(1000, ge=1, le=1000) ``` - ## Creating Custom Pagination Class To create a custom pagination class you should subclass `ninja.pagination.PaginationBase` and override the `Input` and `Output` schema classes and `paginate_queryset(self, queryset, request, **params)` method: - - The `Input` schema is a Schema class that describes parameters that should be passed to your paginator (f.e. page-number or limit/offset values). - - The `Output` schema describes schema for page output (f.e. count/next-page/items/etc). - - The `paginate_queryset` method is passed the initial queryset and should return an iterable object that contains only the data in the requested page. This method accepts the following arguments: - - `queryset`: a queryset (or iterable) returned by the api function - - `pagination` - the paginator.Input parameters (parsed and validated) - - `**params`: kwargs that will contain all the arguments that decorated function received - +- The `Input` schema is a Schema class that describes parameters that should be passed to your paginator (f.e. page-number or limit/offset values). +- The `Output` schema describes schema for page output (f.e. count/next-page/items/etc). +- The `paginate_queryset` method is passed the initial queryset and should return an iterable object that contains only the data in the requested page. This method accepts the following arguments: + - `queryset`: a queryset (or iterable) returned by the api function + - `pagination` - the paginator.Input parameters (parsed and validated) + - `**params`: kwargs that will contain all the arguments that decorated function received Example: @@ -119,7 +113,7 @@ class CustomPagination(PaginationBase): # only `skip` param, defaults to 5 per page class Input(Schema): skip: int - + class Output(Schema): items: List[Any] # `items` is a default attribute @@ -163,12 +157,11 @@ class CustomPagination(PaginationBase): results: List[Any] total: int per_page: int - + items_attribute: str = "results" ``` - ## Apply pagination to multiple operations at once There is often a case when you need to add pagination to all views that returns querysets or list @@ -195,7 +188,6 @@ In this example both operations will have pagination enabled to apply pagination to main `api` instance use `default_router` argument: - ```python api = NinjaAPI(default_router=RouterPaginated())