Initial release.

.flake8

@@ -0,0 +1,4 @@
+[flake8]
+filename = *.py,src/
+max-line-length = 88
+extend-ignore = D105, D107, D401, E203, E402

.github/workflows/tests.yml

@@ -0,0 +1,125 @@
+---
+name: tests
+
+on:
+  push:
+    paths-ignore:
+      - "**.md"
+      - "LICENSE"
+      - ".gitignore"
+      - ".pre-commit-config.yaml"
+
+env:
+  CACHE_DIR: /tmp/.workflow_cache
+  POETRY_CACHE_DIR: /tmp/.workflow_cache/.pip_packages
+  POETRY_VIRTUALENVS_PATH: /tmp/.workflow_cache/.venvs
+  POETRY_HOME: /tmp/.workflow_cache/.poetry
+  PIP_CACHE_DIR: /tmp/.workflow_cache/.pip_packages
+  MYPY_CACHE_DIR: /tmp/.workflow_cache/.mypy
+
+jobs:
+  tests:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: ["ubuntu-latest"]
+        python-version: ["3.x"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        id: cache
+        with:
+          path: ${{ env.CACHE_DIR }}
+          key: tests-${{ matrix.os }}-${{ matrix.python-version }}--${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install dependencies
+        run: |
+          curl -sSL https://install.python-poetry.org | python -
+          $POETRY_HOME/bin/poetry install -n
+        if: steps.cache.outputs.cache-hit != 'true'
+
+      - name: Python code style
+        run: $POETRY_HOME/bin/poetry run black . --check --diff
+        if: ${{ always() }}
+
+      - name: Python code quality
+        run: $POETRY_HOME/bin/poetry run flake8 --docstring-convention google
+        if: ${{ always() }}
+
+      - name: Python code typing
+        run: $POETRY_HOME/bin/poetry run mypy --strict --install-types --non-interactive .
+        if: ${{ always() }}
+
+      - name: Python code complexity
+        run: $POETRY_HOME/bin/poetry run radon cc -n C fastapi_paginator 1>&2
+        if: ${{ always() }}
+
+      - name: Python code maintainability
+        run: $POETRY_HOME/bin/poetry run radon mi -n B fastapi_paginator 1>&2
+        if: ${{ always() }}
+
+      - name: Python code security
+        run: $POETRY_HOME/bin/poetry run bandit fastapi_paginator -rs B404,B603
+        if: ${{ always() }}
+
+      - name: YAML code style
+        run: $POETRY_HOME/bin/poetry run yamllint -s .
+        if: ${{ always() }}
+
+      - name: Test
+        run: $POETRY_HOME/bin/poetry run pytest --junitxml=test-results.xml --cov-report xml
+        if: ${{ always() }}
+
+      - name: Collect coverage report
+        uses: codecov/codecov-action@v3
+
+  publish:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: ["ubuntu-latest"]
+        python-version: ["3.x"]
+    if: ${{ github.repository == 'JGoutin/fastapi_paginator' && github.ref_type == 'tag' }}
+    needs: [tests]
+    environment: PyPI
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        id: cache
+        with:
+          path: ${{ env.CACHE_DIR }}
+          key: tests-${{ matrix.os }}-${{ matrix.python-version }}--${{ hashFiles('**/poetry.lock') }}
+
+      - name: Build packages
+        run: $POETRY_HOME/bin/poetry version $(echo -e "${{ github.ref_name }}" | tr -d 'v')
+
+      - name: Publish packages on PyPI
+        run: $POETRY_HOME/bin/poetry publish --build
+        env:
+          POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
+
+      - name: Publish release on GitHub
+        run: |
+          go install github.com/tcnksm/ghr@latest
+          ~/go/bin/ghr -generatenotes $PRERELEASE -c ${{ github.sha }} ${{ github.ref_name }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PRERELEASE: ${{ contains(github.ref_name, '-') && '-prerelease' || '' }}

.gitignore

@@ -0,0 +1,34 @@
+# Python compiled files
+__pycache__/
+*.py[cd]
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+[Dd]esktop.ini
+Thumbs.db
+*~
+*.bak
+
+# IDE generated files
+.project
+.pydevproject
+.spyproject
+.spyderproject
+.settings/
+.idea/
+.vscode/
+
+# Tests generated files
+.cache/
+.coverage
+.coverage.*
+.mypy_cache/
+.pytest_cache/
+
+# Build
+dist/

.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+---
+repos:
+  - repo: local
+    hooks:
+      - id: black
+        name: Black (Formatting)
+        entry: poetry run black . --preview
+        language: system
+        pass_filenames: false
+      - id: mypy
+        name: Mypy (Typing)
+        entry: poetry run mypy --strict .
+        language: system
+        pass_filenames: false
+      - id: flake8
+        name: Flake8 (Quality)
+        entry: poetry run flake8 --docstring-convention google
+        language: system
+        pass_filenames: false
+      - id: radon_cc
+        name: Radon (Cyclomatic complexity)
+        entry: poetry run radon cc -n C fastapi_paginator
+        language: system
+        pass_filenames: false
+        verbose: true
+      - id: radon_mi
+        name: Radon (Maintainability index)
+        entry: poetry run radon mi -n B fastapi_paginator
+        language: system
+        pass_filenames: false
+        verbose: true
+      - id: bandit
+        name: Bandit (Security)
+        entry: poetry run bandit fastapi_paginator -qrs B404,B603
+        language: system
+        pass_filenames: false

.yamllint.yaml

@@ -0,0 +1,5 @@
+---
+extends: default
+rules:
+  line-length: disable
+  truthy: disable

LICENSE

@@ -0,0 +1,9 @@
+Copyright 2022 Accelize
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,180 @@
+![Tests](https://github.com/JGoutin/fastapi_paginator/workflows/tests/badge.svg)
+[![codecov](https://codecov.io/gh/JGoutin/fastapi_paginator/branch/main/graph/badge.svg?token=QR5nYeX11F)](https://codecov.io/gh/JGoutin/fastapi_paginator)
+[![PyPI](https://img.shields.io/pypi/v/fastapi_paginator.svg)](https://pypi.org/project/fastapi_paginator)
+
+# FastAPI Paginator
+
+Easy to use paginator for [FastAPI](https://fastapi.tiangolo.com/)
+
+Currently, supports only [encode/databases](https://github.com/encode/databases) as 
+database library and tested with SQlite and PostgreSQL.
+
+## Features
+
+* Simple FastAPI integration.
+* Navigation with page numbers (With total page count returned on first page).
+* Navigation from a specific row (since).
+* Ordering result (On multiple columns).
+* Filtering result using various SQL functions.
+
+## Installation
+
+FastAPI Paginator is available on PyPI, so it can be installed like any other Python 
+package.
+
+Example with Pip:
+```bash
+pip install fastapi_paginator
+```
+
+## Usage
+
+### Routes creations in FastAPI
+
+To use it, you only need to create a `fastapi_paginator.Paginator` instance linked to
+the database and routes
+using `fastapi_paginator.PageParameters` and `fastapi_paginator.Page`.
+
+```python
+import databases
+import fastapi
+import pydantic
+import sqlalchemy
+import fastapi_paginator
+
+# Already existing database, FastAPI application, "item" table, and "item" model
+database = databases.Database(f"sqlite:///local.db}")
+app = fastapi.FastAPI()
+
+table = sqlalchemy.Table(
+    "table",
+    sqlalchemy.MetaData(),
+    Column("id", sqlalchemy.Integer, primary_key=True),
+    Column("name", sqlalchemy.String, nullable=False),
+)
+
+class Item(pydantic.BaseModel):
+    """Item in database."""
+
+    class Config:
+        """Config."""
+
+        orm_mode = True  # Required
+
+    id: int
+    name: str
+
+
+# Create a paginator for the database (Required only once per database)
+paginator = fastapi_paginator.Paginator(database)
+
+# Create a paginated route
+@app.get("/list")
+async def list_data(
+    page_parameters: fastapi_paginator.PageParameters = Depends(),
+) -> fastapi_paginator.Page[Item]:
+    """List data with pagination."""
+    return await paginator(table.select(), Item, page_parameters)
+```
+
+### Paginated routes usage from clients
+
+
+#### Request
+Paginator parameters are passed as query parameters, for instance:
+
+```http request
+GET /list?order_by=id&page=2
+```
+
+##### Query parameters
+
+###### page
+The page to return.
+
+When page is not specified or equal to `1`, the request returns `total_page` that is
+the maximum number of pages.
+
+*Cannot be used with `since`.*
+
+###### since
+
+The item from where starting to return the result.
+
+When navigating between successive pages, the `next_since` returned value should be used
+as `since` for the subsequent requests.
+
+*Cannot be used with `page`*.
+
+*Cannot be used with `order_by` if not ordering on the field used by `since`*.
+
+###### order_by
+Sort the resulting items by the specified field name.
+
+Order is descending if `-` is added before the field name, else order is ascending.
+
+This query parameter can be specified multiple time to sort by multiple columns.
+
+**Example:**
+"Ordering descending by the `created_at` column: `order_by=-created_at`
+
+###### filter_by
+
+Filter the resulting items.
+
+The query must be in the form `field_name operator argument`, with:
+  * `field_name`:  the name on the field on where apply the filter.
+  * `operator`:  one operator from the list bellow.
+  * `argument`: is the operator argument, it can be one or more value separated by `,`
+    (Depending on the operator), valid values must be a primitive JSON type like 
+    numbers, double-quoted strings, `true`, `false` and `null`.
+
+This query parameter can be specified multiple time to filter on more criteria
+(Using AND logical conjunction).
+
+Available operators:
+  * `=`: Equal to a single value (Also supports `null`, `true` and `false`)
+  * `<`: Lower than a single value.
+  * `<=`: Lower or equal than a single value.
+  * `>`: Greater than a single value.
+  * `>=`: Greater or equal than a single value.
+  * `between`: Between a pair of values (`value_1` <= `field_value` <= `value_2`).
+  * `in`: Present in a list of one or more values.
+  * `like`: Like a single value (`%` can be used as wildcard for zero to multiple
+     characters, `_` as wildcard for a single character, `/` can be used as escape
+     character for `%` and `_`).
+  * `ilike`: Same as `like`, but case insensitive.
+  * `startswith`: String representation starts with a single value.
+  * `endswith`: String representation ends with a single value.
+  * `contains`: String representation contains a single value.
+
+Any operator can be negated by adding `!` in front of it.
+
+*Warning*: Depending on your HTTP client, the query parameter value may require to be
+URL encoded.
+
+**Example:**
+Returning only data with a `name` field that does not start with
+`Product`: `filter_by=name%20%21like%20%22Product%25%22`
+(With URL encoded value of: `name !like "Product%"`')
+
+##### Response
+
+The response is a JSON dictionnary with the following fields:
+* `items`: The list returned items.
+* `next_since`: Next value to use with `since` query parameter.
+* `next_page`: Next value to use with `page` query parameter.
+* `total_pages`: Total pages, only computed and returned when on page 1
+
+### Using alternates JSON libraries
+
+It is possible to override the `json.loads` function used in all paginator as follows 
+(Example with [orjson](https://github.com/ijl/orjson)):
+
+```python
+import orjson
+import fastapi_paginator
+
+
+fastapi_paginator.Paginator.json_loads = orjson.loads
+```