Contributing
Any and all contributions and involvement with the project is welcome. The easiest way to begin contributing is to check out the open issues on GitHub.
Documentation
The documentation is built using mkdocs. All documentation is in markdown format, and can be found in ./docs/
Contributing Code
Step 1: prerequisites
fastapi-pagination
uses poetry for dependency management.
Please, install poetry before continuing.
Minimum supported python version is 3.8
.
Step 2: clone the repo
Step 3: install dependencies
To install all dependencies, run:
To install only basic dependencies, run:
To install docs requirements, run:
Step 4: do your changes
If you want to add new feature, please, create an issue first and describe your idea.
If you want to add new extension for pagination you will need to create a new module in fastapi_pagination/ext/
directory.
Please, use fastapi_pagination/ext/sqlalchemy.py
as an example.
Generally, you will need to call function paginate
and signature should include next arguments:
from typing import Any, Optional
from fastapi_pagination.api import apply_items_transformer, create_page
from fastapi_pagination.bases import AbstractParams
from fastapi_pagination.types import AdditionalData, AsyncItemsTransformer
from fastapi_pagination.utils import verify_params
async def paginate(
query: QuerySet,
params: Optional[AbstractParams] = None, # Optional params for pagination (if None, current params will be used)
*,
transformer: Optional[AsyncItemsTransformer] = None, # Optional transformer for items
additional_data: Optional[AdditionalData] = None, # Optional additional data for page object
) -> Any:
params, raw_params = verify_params(params, "limit-offset") # verify params is of correct type
total = await query.count() # get total count of items
items = await query.limit(raw_params.limit).offset(raw_params.offset).all() # get items for current page
t_items = await apply_items_transformer(items, transformer, async_=True) # apply transformer if needed
return create_page( # create page object
t_items,
total=total,
params=params,
**(additional_data or {}),
)
If you want to add/updated docs, then you will need to edit ./docs/
directory.
You can run mkdocs serve
to see your changes locally.
Step 5: run pre-commit hooks
Before creating a commit, please, run pre-commit hooks:
You can also install pre-commit hooks to run automatically before each commit:
Step 6: run tests
To run tests, run:
If you want to run tests with coverage, run:
If you want to run only unit tests, run:
If you want to run only integration tests, then you will also will need to have PostgreSQL
, MongoDB
and Casandra
running.
To run integration tests, run:
Step 7: create a pull request
After you have done all changes, please, create a pull request.