fast-pager 0.0.1__tar.gz

fast_pager-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eytan Ohana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fast_pager-0.0.1/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: fast-pager
+Version: 0.0.1
+Summary: Automatic filterable, sortable, paginated query parameters for FastAPI, derived from your Pydantic models.
+Keywords: fastapi,pagination,filtering,sorting,pydantic,mongodb
+Author: Eytan Ohana
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/eytanohana/fast-pager
+Project-URL: Repository, https://github.com/eytanohana/fast-pager
+Project-URL: Issues, https://github.com/eytanohana/fast-pager/issues
+Description-Content-Type: text/markdown
+
+# fast-pager
+
+> Turn your Pydantic models into filterable, sortable, paginated FastAPI query parameters — automatically.
+
+`fast-pager` reads the Pydantic models you already use in your FastAPI routes and
+generates **type-safe query parameters** for filtering, sorting and pagination.
+Those parameters show up in your OpenAPI docs for free, and compile down to a
+real database query (MongoDB first, more backends later).
+
+```python
+class User(BaseModel):
+    name: str
+    age: int
+
+@app.get("/users")
+async def list_users(q: FilterQuery[User] = FilterDepends(User)):
+    return await db.users.find(q.to_mongo()).to_list(None)
+```
+
+A request to:
+
+```
+GET /users?name__contains=ana&age__gte=21&age__lt=65&sort=-age&limit=20
+```
+
+…compiles to:
+
+```python
+{"name": {"$regex": "ana"}, "age": {"$gte": 21, "$lt": 65}}
+# sort=[("age", -1)], skip=0, limit=20
+# (values in `contains` filters are regex-escaped before compilation)
+```
+
+…and every one of those parameters is documented, validated and typed in `/docs`.
+
+---
+
+## Built with AI
+
+This project is designed and developed with the assistance of AI (Anthropic's
+Claude Code). Design documents and code are AI-generated and human-reviewed.
+
+---
+
+## Status
+
+`fast-pager` is in the **design phase**. The package is published to PyPI as a
+placeholder (`0.0.x`) to reserve the name — it contains no functionality yet.
+Don't depend on it until `0.1`.
+
+## Releasing (maintainers)
+
+Releases are fully automated. From a clean `main`:
+
+```bash
+./scripts/release.sh patch     # or minor / major
+```
+
+The script bumps the version in `pyproject.toml` (via `uv version --bump`),
+commits, tags `v<version>`, and pushes. The tag triggers
+[`release.yml`](.github/workflows/release.yml), which:
+
+1. verifies the tag matches the `pyproject.toml` version,
+2. runs the full CI matrix,
+3. builds with `uv build` and publishes to PyPI via **Trusted Publishing**
+   (OIDC — no API tokens),
+4. creates the GitHub Release with generated notes.
+
+`fast_pager.__version__` reads from package metadata, so the version lives in
+exactly one place.
+
+---
+
+## Design documents
+
+This repository currently contains **only the product design** — no implementation yet.
+Read the docs in order:
+
+| # | Document | What it covers |
+|---|----------|----------------|
+| 00 | [Overview & Vision](docs/design/00-overview.md) | The problem, goals, non-goals, naming, guiding principles |
+| 01 | [Developer Experience](docs/design/01-developer-experience.md) | API surface options explored, the recommended ergonomics |
+| 02 | [Type & Operator System](docs/design/02-type-and-operator-system.md) | Which Python types we support, their operators, compound types, per-field configurability |
+| 03 | [Architecture](docs/design/03-architecture.md) | The layered pipeline, the filter AST, the FastAPI signature trick |
+| 04 | [Backend Roadmap](docs/design/04-backend-roadmap.md) | Mongo today, generalizing to any database tomorrow |
+| 05 | [Roadmap & Release Plan](docs/design/05-roadmap-and-release.md) | Phased path to a clean 1.0 on PyPI |
+
+Start with **[00-overview.md](docs/design/00-overview.md)**.

fast_pager-0.0.1/README.md

@@ -0,0 +1,88 @@
+# fast-pager
+
+> Turn your Pydantic models into filterable, sortable, paginated FastAPI query parameters — automatically.
+
+`fast-pager` reads the Pydantic models you already use in your FastAPI routes and
+generates **type-safe query parameters** for filtering, sorting and pagination.
+Those parameters show up in your OpenAPI docs for free, and compile down to a
+real database query (MongoDB first, more backends later).
+
+```python
+class User(BaseModel):
+    name: str
+    age: int
+
+@app.get("/users")
+async def list_users(q: FilterQuery[User] = FilterDepends(User)):
+    return await db.users.find(q.to_mongo()).to_list(None)
+```
+
+A request to:
+
+```
+GET /users?name__contains=ana&age__gte=21&age__lt=65&sort=-age&limit=20
+```
+
+…compiles to:
+
+```python
+{"name": {"$regex": "ana"}, "age": {"$gte": 21, "$lt": 65}}
+# sort=[("age", -1)], skip=0, limit=20
+# (values in `contains` filters are regex-escaped before compilation)
+```
+
+…and every one of those parameters is documented, validated and typed in `/docs`.
+
+---
+
+## Built with AI
+
+This project is designed and developed with the assistance of AI (Anthropic's
+Claude Code). Design documents and code are AI-generated and human-reviewed.
+
+---
+
+## Status
+
+`fast-pager` is in the **design phase**. The package is published to PyPI as a
+placeholder (`0.0.x`) to reserve the name — it contains no functionality yet.
+Don't depend on it until `0.1`.
+
+## Releasing (maintainers)
+
+Releases are fully automated. From a clean `main`:
+
+```bash
+./scripts/release.sh patch     # or minor / major
+```
+
+The script bumps the version in `pyproject.toml` (via `uv version --bump`),
+commits, tags `v<version>`, and pushes. The tag triggers
+[`release.yml`](.github/workflows/release.yml), which:
+
+1. verifies the tag matches the `pyproject.toml` version,
+2. runs the full CI matrix,
+3. builds with `uv build` and publishes to PyPI via **Trusted Publishing**
+   (OIDC — no API tokens),
+4. creates the GitHub Release with generated notes.
+
+`fast_pager.__version__` reads from package metadata, so the version lives in
+exactly one place.
+
+---
+
+## Design documents
+
+This repository currently contains **only the product design** — no implementation yet.
+Read the docs in order:
+
+| # | Document | What it covers |
+|---|----------|----------------|
+| 00 | [Overview & Vision](docs/design/00-overview.md) | The problem, goals, non-goals, naming, guiding principles |
+| 01 | [Developer Experience](docs/design/01-developer-experience.md) | API surface options explored, the recommended ergonomics |
+| 02 | [Type & Operator System](docs/design/02-type-and-operator-system.md) | Which Python types we support, their operators, compound types, per-field configurability |
+| 03 | [Architecture](docs/design/03-architecture.md) | The layered pipeline, the filter AST, the FastAPI signature trick |
+| 04 | [Backend Roadmap](docs/design/04-backend-roadmap.md) | Mongo today, generalizing to any database tomorrow |
+| 05 | [Roadmap & Release Plan](docs/design/05-roadmap-and-release.md) | Phased path to a clean 1.0 on PyPI |
+
+Start with **[00-overview.md](docs/design/00-overview.md)**.

fast_pager-0.0.1/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "fast-pager"
+version = "0.0.1"
+description = "Automatic filterable, sortable, paginated query parameters for FastAPI, derived from your Pydantic models."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+authors = [
+    { name = "Eytan Ohana" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["fastapi", "pagination", "filtering", "sorting", "pydantic", "mongodb"]
+classifiers = [
+    "Development Status :: 1 - Planning",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+    "Framework :: FastAPI",
+    "Framework :: Pydantic",
+]
+
+[project.urls]
+Homepage = "https://github.com/eytanohana/fast-pager"
+Repository = "https://github.com/eytanohana/fast-pager"
+Issues = "https://github.com/eytanohana/fast-pager/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.13,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.14.0",
+]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]

fast_pager-0.0.1/src/fast_pager/__init__.py

@@ -0,0 +1,14 @@
+"""fast-pager — filterable, sortable, paginated query parameters for FastAPI.
+
+Derives type-safe filter/sort/pagination query parameters from the Pydantic
+models you already use, surfaces them in OpenAPI, and compiles them to a
+backend query (MongoDB first).
+
+This is a placeholder release reserving the package name while the library is
+under active design. See the design documents in the repository:
+https://github.com/eytanohana/fast-pager
+"""
+
+from importlib.metadata import version
+
+__version__ = version("fast-pager")