Lightweight HTML pagination renderer with limit/offset helpers for SQL. Python fork of robsonvleite/paginator (PHP).

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

kauelima21

These details have not been verified by PyPI

Project links

Original PHP

Project description

Paginator (Python)

Port em Python do pacote PHP coffeecode/paginator de Robson V. Leite. Gera HTML de paginacao + helpers limit()/offset() para sua query SQL. API minima: configura no construtor, chama pager(), renderiza.

Python port of the PHP package coffeecode/paginator by Robson V. Leite. Renders pagination HTML and exposes limit()/offset() for SQL queries. Configure via constructor, call pager(), then render().

Destaques

Pure Python, zero dependencias de runtime
HTML estruturado com classes customizaveis (<nav>, <a>, <span>)
limit() / offset() prontos para LIMIT ? OFFSET ?
Suporte a hash (#anchor) e GET params extras nos links
Janela de paginas configuravel (range_)

Instalacao

pip install coffeecode-paginator

Requer Python >= 3.9.

Uso

from coffeecode_paginator import Paginator

pager = Paginator()
pager.pager(rows=100, limit=10, page=1)

print(pager.limit())   # 10
print(pager.offset())  # 0
print(pager.pages())   # 10
print(pager.render())

Saida (formatada para leitura):

<nav class="paginator">
  <a class="paginator_item" aria-label="Primeira página" title="Primeira página" href="?page=1"><<</a>
  <span class="paginator_item paginator_active">1</span>
  <a class="paginator_item" aria-label="Página 2" title="Página 2" href="?page=2">2</a>
  <a class="paginator_item" aria-label="Página 3" title="Página 3" href="?page=3">3</a>
  <a class="paginator_item" aria-label="Página 4" title="Página 4" href="?page=4">4</a>
  <a class="paginator_item" aria-label="Última página" title="Última página" href="?page=10">>></a>
</nav>

First/Last dinamicos

Esconde os links "Primeira"/"Última" quando voce ja esta na primeira/ultima:

pager.render(fixed_first_and_last=False)

FastAPI

from fastapi import FastAPI, Query
from fastapi.responses import HTMLResponse
from coffeecode_paginator import Paginator

app = FastAPI()

@app.get("/", response_class=HTMLResponse)
def index(page: int = Query(1, ge=1)):
    pager = Paginator()
    pager.pager(rows=237, limit=20, page=page)
    nav = pager.render() or ""
    return f"<html><body>{nav}</body></html>"

Flask

from flask import Flask, request
from coffeecode_paginator import Paginator

app = Flask(__name__)

@app.route("/")
def index():
    page = request.args.get("page", default=1, type=int)
    pager = Paginator()
    pager.pager(rows=100, limit=10, page=page)
    return f"<html><body>{pager.render() or ''}</body></html>"

Hash + GET params extras

pager.pager(rows=100, limit=10, page=2, hash_="results", params={"q": "hello"})
pager.render()
# href="?page=1#results&q=hello"
# href="?page=10#results&q=hello"

API

`Paginator(link="?page=", title="Página", first=("Primeira página", "<<"), last=("Última página", ">>"))`

Configura textos e template do link. Aceita qualquer prefixo: Paginator(link="/items/page/") gera href="/items/page/3".

`pager(rows, limit=10, page=None, range_=3, hash_=None, params=None)`

Calcula estado da paginacao. page invalido ou maior que o total e clampado para a ultima pagina valida (PHP redirecionava com header(); o port nao tem contexto HTTP — caller decide se redireciona).

`render(css_class=None, fixed_first_and_last=True)`

Retorna o HTML do <nav>. Retorna None quando rows <= limit (paginacao desnecessaria).

Helpers

limit() -> int
offset() -> int
page() -> int
pages() -> int
first_page(fixed=True) -> Optional[str]
last_page(fixed=True) -> Optional[str]

CSS sugerido

Mesmo do exemplo PHP — funciona out-of-the-box:

.paginator { list-style: none; padding: 0; margin-top: 30px; }
.paginator_item {
  display: inline-block; margin: 0 10px; padding: 4px 12px;
  background: #A287E7; color: #fff; text-decoration: none;
  border-radius: 4px;
}
.paginator_item:hover { background: #8A6ED5; }
.paginator_active, .paginator_active:hover { background: #cccccc; }

Equivalencia com a versao PHP

PHP	Python
`CoffeeCode\Paginator\Paginator`	`coffeecode_paginator.Paginator`
`pager($rows, $limit, $page, $range, $hash, $params)`	`pager(rows, limit, page, range_, hash_, params)`
`render($cssClass, $fixedFirstAndLast)`	`render(css_class, fixed_first_and_last)`
`firstPage()` / `lastPage()`	`first_page()` / `last_page()`
`header("Location: ...")` redirect	(omitido — caller redireciona)

Creditos

API original: Robson V. Leite — coffeecode/paginator (MIT)
Port Python: Kaue Leal

Licenca

MIT.

Project details

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

kauelima21

These details have not been verified by PyPI

Project links

Original PHP

Release history Release notifications | RSS feed

This version

1.0.0

Apr 30, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

coffeecode_paginator-1.0.0.tar.gz (7.9 kB view details)

Uploaded Apr 30, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

coffeecode_paginator-1.0.0-py3-none-any.whl (6.5 kB view details)

Uploaded Apr 30, 2026 Python 3

File details

Details for the file coffeecode_paginator-1.0.0.tar.gz.

File metadata

Download URL: coffeecode_paginator-1.0.0.tar.gz
Upload date: Apr 30, 2026
Size: 7.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for coffeecode_paginator-1.0.0.tar.gz
Algorithm	Hash digest
SHA256	`afee4606548ed1f9f2c6fb47af1b2ffedde39869c94d494e41752543cd49f884`
MD5	`a46417b682911f7cbcba7f61b708a688`
BLAKE2b-256	`7c52c7d7661d5c0b1f3cacad60e6de608939b1cba08c0dd77bead9d8a01fb4e0`

See more details on using hashes here.

Provenance

The following attestation bundles were made for coffeecode_paginator-1.0.0.tar.gz:

Publisher: release.yml on kauelima21/coffeecode-paginator

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: coffeecode_paginator-1.0.0.tar.gz
- Subject digest: afee4606548ed1f9f2c6fb47af1b2ffedde39869c94d494e41752543cd49f884
- Sigstore transparency entry: 1414977558
- Sigstore integration time: Apr 30, 2026
Source repository:
- Permalink: kauelima21/coffeecode-paginator@a652a351fbf4ae38439f625c58487fbf95424cc4
- Branch / Tag: refs/tags/v1.0.0
- Owner: https://github.com/kauelima21
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@a652a351fbf4ae38439f625c58487fbf95424cc4
- Trigger Event: push

File details

Details for the file coffeecode_paginator-1.0.0-py3-none-any.whl.

File metadata

Download URL: coffeecode_paginator-1.0.0-py3-none-any.whl
Upload date: Apr 30, 2026
Size: 6.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for coffeecode_paginator-1.0.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`7862cf8414fff5b3f9cf170869ddce05f1c923f988657a8d7a1df42033176f63`
MD5	`0d4faca80a83604f22711ffaffe017ca`
BLAKE2b-256	`28e3cbcdeff027bd57e0098072437da3c1b0a21770c34a2872696a4dd7792fee`

See more details on using hashes here.

Provenance

The following attestation bundles were made for coffeecode_paginator-1.0.0-py3-none-any.whl:

Publisher: release.yml on kauelima21/coffeecode-paginator

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: coffeecode_paginator-1.0.0-py3-none-any.whl
- Subject digest: 7862cf8414fff5b3f9cf170869ddce05f1c923f988657a8d7a1df42033176f63
- Sigstore transparency entry: 1414977628
- Sigstore integration time: Apr 30, 2026
Source repository:
- Permalink: kauelima21/coffeecode-paginator@a652a351fbf4ae38439f625c58487fbf95424cc4
- Branch / Tag: refs/tags/v1.0.0
- Owner: https://github.com/kauelima21
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@a652a351fbf4ae38439f625c58487fbf95424cc4
- Trigger Event: push

coffeecode-paginator 1.0.0

Navigation

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

Paginator (Python)

Destaques

Instalacao

Uso

First/Last dinamicos

FastAPI

Flask

Hash + GET params extras

API

Paginator(link="?page=", title="Página", first=("Primeira página", "<<"), last=("Última página", ">>"))

pager(rows, limit=10, page=None, range_=3, hash_=None, params=None)

render(css_class=None, fixed_first_and_last=True)

Helpers

CSS sugerido

Equivalencia com a versao PHP

Creditos

Licenca

Project details

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

`Paginator(link="?page=", title="Página", first=("Primeira página", "<<"), last=("Última página", ">>"))`

`pager(rows, limit=10, page=None, range_=3, hash_=None, params=None)`

`render(css_class=None, fixed_first_and_last=True)`