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, callpager(), thenrender().
Destaques
- Pure Python, zero dependencias de runtime
- HTML estruturado com classes customizaveis (
<nav>,<a>,<span>) limit()/offset()prontos paraLIMIT ? 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() -> intoffset() -> intpage() -> intpages() -> intfirst_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.
1 maintainer
Release files for coffeecode-paginator 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| coffeecode_paginator-1.0.0.tar.gz | 7.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| coffeecode_paginator-1.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 14.4 kB
Release files / coffeecode_paginator-1.0.0.tar.gz
| Download URL | coffeecode_paginator-1.0.0.tar.gz |
|---|---|
| Size | 7.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
afee4606548ed1f9f2c6fb47af1b2ffedde39869c94d494e41752543cd49f884
|
|
BLAKE2b-256 checksum How to use checksums |
7c52c7d7661d5c0b1f3cacad60e6de608939b1cba08c0dd77bead9d8a01fb4e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 30, 2026.
Transparency logRelease files / coffeecode_paginator-1.0.0-py3-none-any.whl
| Download URL | coffeecode_paginator-1.0.0-py3-none-any.whl |
|---|---|
| Size | 6.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7862cf8414fff5b3f9cf170869ddce05f1c923f988657a8d7a1df42033176f63
|
|
BLAKE2b-256 checksum How to use checksums |
28e3cbcdeff027bd57e0098072437da3c1b0a21770c34a2872696a4dd7792fee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 30, 2026.
Transparency log
