fastapi-filebased-routing 1.0.0__tar.gz

fastapi_filebased_routing-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.13", "3.14"]
+    name: Test (Python ${{ matrix.python }})
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install Python
+        run: uv python install ${{ matrix.python }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest --tb=short -q
+
+  lint:
+    runs-on: ubuntu-latest
+    name: Lint & Types
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff check
+        run: uv run ruff check src/ tests/
+
+      - name: Ruff format
+        run: uv run ruff format --check src/ tests/
+
+      - name: Mypy
+        run: uv run mypy src/

fastapi_filebased_routing-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    name: Build & Publish
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always
+
+      - name: Create GitHub Release
+        run: gh release create ${{ github.ref_name }} dist/* --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}

fastapi_filebased_routing-1.0.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store

fastapi_filebased_routing-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+        files: ^(src|tests)/
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+        files: ^(src|tests)/
+
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src/
+        language: system
+        types: [python]
+        files: ^src/
+        pass_filenames: false

fastapi_filebased_routing-1.0.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-02-08
+
+### Added
+
+- **Directory-level middleware** via `_middleware.py` files — applies to all routes in the directory subtree
+- **File-level middleware** via `middleware = [...]` at module level in `route.py` — applies to all handlers in the file
+- **Handler-level middleware** via `class handler(route):` syntax with `middleware = [...]` — per-handler configuration
+- **Three-layer middleware execution order**: directory (parent→child) → file → handler
+- **`route` base class** with metaclass that returns `RouteConfig` — `class get(route):` returns callable config, not a class
+- **`RouteConfig` dataclass** — carries handler, middleware, and metadata (tags, summary, deprecated, status_code)
+- **`build_middleware_chain()`** — composable middleware chain with `call_next` semantics
+- **`_make_middleware_route()`** — custom APIRoute subclass preserving FastAPI dependency injection
+- **`MiddlewareValidationError`** exception for middleware configuration issues
+- **Middleware context enrichment** — middleware can set `request.state` values visible to subsequent middleware and handlers
+- **Middleware short-circuit** — middleware can return response without calling `call_next`
+- **Startup-time validation** — all middleware validated when `create_router_from_path()` is called
+- **Handler-level metadata override** — `class handler(route):` can set `tags`, `summary`, `deprecated`, `status_code`
+- `examples/middleware/` — comprehensive example showing all middleware features
+
+### Changed
+
+- Bumped version to 0.2.0
+
+### Fixed
+
+- N/A
+
+## [0.1.0] - 2025-10-01
+
+### Added
+
+- Automatic route discovery from directory structure with `create_router_from_path()`
+- HTTP method handlers: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
+- WebSocket handler support via `async def websocket(ws: WebSocket)` convention
+- Dynamic path parameters using `[param]` directory syntax
+- Optional path parameters using `[[param]]` directory syntax with automatic variant generation
+- Catch-all path parameters using `[...param]` directory syntax for arbitrary nested paths
+- Route groups using `(group)` directory syntax for code organization without URL impact
+- Convention-based status codes (POST→201, DELETE→204, others→200)
+- Route metadata support: TAGS, SUMMARY, DEPRECATED constants in route files
+- Automatic tag derivation from path segments (skipping api/version prefixes)
+- Security validation for path traversal attempts
+- Symlink validation to prevent directory traversal attacks
+- Parameter name validation (must be valid Python identifiers)
+- Duplicate route detection with detailed error reporting
+- Sync and async handler support (both `def` and `async def`)
+- Full FastAPI APIRouter integration for seamless coexistence with manual routes
+- Router prefix support via `prefix` parameter
+- Type-safe with PEP 561 marker
+- 98%+ test coverage across all modules
+
+[Unreleased]: https://github.com/irudi/fastapi-filebased-routing/compare/v0.2.0...main
+[0.2.0]: https://github.com/irudi/fastapi-filebased-routing/releases/tag/v0.2.0
+[0.1.0]: https://github.com/irudi/fastapi-filebased-routing/releases/tag/v0.1.0

fastapi_filebased_routing-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 irudi
+
+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.

fastapi_filebased_routing-1.0.0/PKG-INFO

@@ -0,0 +1,359 @@
+Metadata-Version: 2.4
+Name: fastapi-filebased-routing
+Version: 1.0.0
+Summary: Next.js-style file-based routing for FastAPI
+Project-URL: Homepage, https://github.com/irudi/fastapi-filebased-routing
+Project-URL: Documentation, https://github.com/irudi/fastapi-filebased-routing#readme
+Project-URL: Repository, https://github.com/irudi/fastapi-filebased-routing
+Project-URL: Bug Tracker, https://github.com/irudi/fastapi-filebased-routing/issues
+Author: irudi
+License: MIT
+License-File: LICENSE
+Keywords: fastapi,file-based,filesystem,nextjs,routing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: fastapi>=0.115.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fastapi-filebased-routing
+
+Next.js-style file-based routing for FastAPI
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-filebased-routing.svg)](https://pypi.org/project/fastapi-filebased-routing/)
+[![Python](https://img.shields.io/pypi/pyversions/fastapi-filebased-routing.svg)](https://pypi.org/project/fastapi-filebased-routing/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Define your API routes through directory structure and convention, not manual registration. Create a `route.py` file in a directory and it becomes an endpoint automatically. Say goodbye to router boilerplate and route registration conflicts.
+
+## Table of Contents
+
+- [🚀 Installation & Quickstart](#-installation--quickstart)
+- [📁 File-Based Routing Explained](#-file-based-routing-explained)
+- [📍 Route Handlers](#-route-handlers)
+- [🔗 Middleware](#-middleware)
+- [📦 Examples](#-examples)
+- [📖 API Reference](#-api-reference)
+- [💡 Why This Plugin?](#-why-this-plugin)
+- [🤝 Contributing](#-contributing)
+
+## 🚀 Installation & Quickstart
+
+Requires **Python 3.13+** and **FastAPI 0.115.0+**.
+
+```bash
+pip install fastapi-filebased-routing
+```
+
+```python
+from fastapi import FastAPI
+from fastapi_filebased_routing import create_router_from_path
+
+app = FastAPI()
+app.include_router(create_router_from_path("app"))
+```
+
+That's it. Every `route.py` file in your `app/` directory is automatically discovered and registered.
+
+## 📁 File-Based Routing Explained
+
+Your directory structure defines your URL routes. Given `create_router_from_path("app")`:
+
+```
+app/
+├── _middleware.py                  # directory middleware → ALL routes
+├── health/
+│   └── route.py                   # get → /health
+├── api/
+│   ├── _middleware.py             # directory middleware → /api/**
+│   ├── [[version]]/
+│   │   └── route.py              # → /api and /api/{version}
+│   └── users/
+│       ├── route.py              # file-level middleware + handlers
+│       └── [user_id]/
+│           └── route.py          # handler-level middleware via class
+├── files/
+│   └── [...path]/
+│       └── route.py              # catch-all route
+├── ws/
+│   └── chat/
+│       └── route.py              # websocket handler
+└── (admin)/                       # group: excluded from URL
+    ├── _middleware.py             # directory middleware → /settings/**
+    └── settings/
+        └── route.py              # → /settings
+```
+
+Each `route.py` exports [route handlers](#-route-handlers). Each `_middleware.py` defines [directory middleware](#directory-level-middleware).
+
+### Route Conventions
+
+| Convention | Route Example | URL | Handler Parameter |
+|------------|---------------|-----|-------------------|
+| `users/` | `app/users/route.py` | `/users` | — |
+| `[id]/` | `app/users/[id]/route.py` | `/users/123` | `id: str` |
+| `[[version]]/` | `app/api/[[version]]/route.py` | `/api` and `/api/v2` | `version: str \| None` |
+| `[...path]/` | `app/files/[...path]/route.py` | `/files/a/b/c` | `path: str` |
+| `(group)/` | `app/(admin)/settings/route.py` | `/settings` | — |
+
+**Files:** `route.py` contains [handlers](#-route-handlers). `_middleware.py` contains [directory middleware](#directory-level-middleware) that cascades to all subdirectories.
+
+## 📍 Route Handlers
+
+Each `route.py` exports handlers. Supported HTTP methods: `get`, `post`, `put`, `patch`, `delete`, `head`, `options`, `websocket`. Functions prefixed with `_` are private helpers and ignored. Default status codes: `POST` → 201, `DELETE` → 204, all others → 200.
+
+```python
+# app/api/users/route.py
+from fastapi_filebased_routing import route
+
+# Module-level metadata (applies to all handlers in this file)
+TAGS = ["users"]                         # auto-derived from first path segment if omitted
+SUMMARY = "User management endpoints"    # OpenAPI summary
+DEPRECATED = True                        # mark all handlers as deprecated
+
+# File-level middleware (applies to all handlers in this file, does NOT cascade to subdirectories)
+middleware = [rate_limit(100)]
+
+# Simple handler — just a function
+async def get():
+    """List users."""
+    return {"users": []}
+
+# Configured handler — per-handler control over metadata and middleware
+class post(route):
+    status_code = 200                    # override convention-based 201
+    tags = ["admin"]                     # override module-level TAGS
+    summary = "Create a user"            # override module-level SUMMARY
+    deprecated = True                    # override module-level DEPRECATED
+    middleware = [require_role("admin")]  # or use inline: async def middleware(request, call_next): ...
+
+    async def handler(name: str):
+        return {"name": name}
+```
+
+Both styles coexist freely. Directory bracket names (e.g., `[user_id]`) become path parameters automatically injected into handler signatures. See [`examples/`](examples/) for complete working projects.
+
+## 🔗 Middleware
+
+Three-layer middleware system that lets you scope cross-cutting concerns (auth, logging, rate limiting) to directories, files, or individual handlers. Middleware is validated at startup and assembled into chains with zero per-request overhead.
+
+All middleware functions use the same signature:
+
+```python
+async def my_middleware(request, call_next):
+    # Before handler
+    response = await call_next(request)
+    # After handler
+    return response
+```
+
+Middleware must be `async`. Sync middleware raises a validation error at startup.
+
+### Directory-Level Middleware
+
+Create a `_middleware.py` file in any directory. Its middleware applies to all routes in that directory and all subdirectories. Use **one** of two forms:
+
+**List form** — multiple middleware functions:
+
+```python
+# app/api/_middleware.py — applies to all routes under /api/**
+from app.auth import auth_required
+from app.logging import request_logger
+
+middleware = [auth_required, request_logger]
+```
+
+**Single function form** — one inline middleware:
+
+```python
+# app/_middleware.py — root-level timing middleware
+import time
+
+async def middleware(request, call_next):
+    start = time.monotonic()
+    response = await call_next(request)
+    response.headers["X-Response-Time"] = f"{time.monotonic() - start:.4f}"
+    return response
+```
+
+Pick one form per file. If both are defined, standard Python name resolution applies — the last assignment to `middleware` wins.
+
+Directory middleware cascades: a `_middleware.py` in `app/` applies to every route, while one in `app/api/` only applies to routes under `/api/`. Parent middleware always runs before child middleware.
+
+### File-Level Middleware
+
+Set `middleware = [...]` at the top of any `route.py` to apply middleware to all handlers in that file. Unlike directory middleware, file-level middleware does **not** cascade to subdirectories.
+
+```python
+# app/api/users/route.py
+middleware = [rate_limit(100)]  # applies to get and post below, not to /api/users/[user_id]
+
+async def get():
+    """List users. Rate limited."""
+    return {"users": []}
+
+async def post(name: str):
+    """Create user. Rate limited."""
+    return {"name": name}
+```
+
+### Handler-Level Middleware
+
+`class handler(route):` blocks support a `middleware` attribute — as a list or a single inline function:
+
+```python
+# app/api/orders/route.py
+from fastapi_filebased_routing import route
+
+class post(route):
+    async def middleware(request, call_next):
+        if not request.headers.get("X-Idempotency-Key"):
+            from fastapi.responses import JSONResponse
+            return JSONResponse(
+                {"error": "X-Idempotency-Key header required"},
+                status_code=400,
+            )
+        return await call_next(request)
+
+    async def handler(order: dict):
+        """Create order. Requires idempotency key."""
+        return {"order_id": "abc-123", **order}
+```
+
+### Execution Order
+
+When a request hits a route with middleware at multiple levels, they execute in this order:
+
+```
+Directory middleware (root → leaf)
+  → File-level middleware
+    → Handler-level middleware
+      → Handler function
+    ← Handler-level middleware
+  ← File-level middleware
+← Directory middleware
+```
+
+Each middleware can modify the request before calling `call_next`, and modify the response after. Middleware can also short-circuit by returning a response without calling `call_next`:
+
+```python
+async def auth_guard(request, call_next):
+    if not request.headers.get("Authorization"):
+        return JSONResponse({"error": "unauthorized"}, status_code=401)
+    return await call_next(request)
+```
+
+## 📦 Examples
+
+See the [`examples/`](examples/) directory for runnable projects:
+
+- **[`basic/`](examples/basic/)** — Routing fundamentals: static, dynamic, CRUD
+- **[`middleware/`](examples/middleware/)** — All three middleware layers in action
+- **[`advanced/`](examples/advanced/)** — Optional params, catch-all, route groups, WebSockets
+
+## 📖 API Reference
+
+### `create_router_from_path`
+
+```python
+def create_router_from_path(
+    base_path: str | Path,
+    *,
+    prefix: str = "",
+) -> APIRouter
+```
+
+Create a FastAPI APIRouter from a directory of `route.py` files.
+
+**Parameters:**
+- `base_path` (str | Path): Root directory containing route.py files
+- `prefix` (str, optional): URL prefix for all discovered routes (default: "")
+
+**Returns:**
+- `APIRouter`: A FastAPI router with all discovered routes registered
+
+**Raises:**
+- `RouteDiscoveryError`: If base_path doesn't exist or isn't a directory
+- `RouteValidationError`: If a route file has invalid exports or parameters
+- `DuplicateRouteError`: If two route files resolve to the same path+method
+- `PathParseError`: If a directory name has invalid syntax
+- `MiddlewareValidationError`: If a `_middleware.py` file fails to import or contains invalid middleware
+
+**Example:**
+
+```python
+from fastapi import FastAPI
+from fastapi_filebased_routing import create_router_from_path
+
+app = FastAPI()
+
+# Basic usage
+app.include_router(create_router_from_path("app"))
+
+# With prefix
+app.include_router(create_router_from_path("app", prefix="/api/v1"))
+
+# Multiple routers
+app.include_router(create_router_from_path("app/public"))
+app.include_router(create_router_from_path("app/admin", prefix="/admin"))
+```
+
+### `route`
+
+Base class for handler-level middleware and metadata configuration. Uses a metaclass that returns a `RouteConfig` instead of a class.
+
+```python
+from fastapi_filebased_routing import route
+
+class get(route):
+    middleware = [auth_required]
+    tags = ["users"]
+    summary = "Get user details"
+
+    async def handler(user_id: str):
+        return {"user_id": user_id}
+
+# `get` is now a RouteConfig, not a class
+# `get(user_id="123")` calls the handler directly
+```
+
+## 💡 Why This Plugin?
+
+FastAPI developers building medium-to-large APIs face these problems:
+
+1. **Manual route registration is tedious.** Every endpoint requires updating a centralized router file.
+2. **Route discoverability degrades.** Finding the handler for `/api/v1/users/{id}` requires searching across files.
+3. **Middleware wiring is repetitive.** Applying auth to 20 admin endpoints means 20 copies of `Depends(require_admin)`.
+4. **Full-stack developers experience friction.** Next.js has file-based routing, FastAPI requires manual wiring.
+
+This plugin solves all four with:
+
+- Zero-configuration route discovery from directory structure
+- Three-layer middleware system (directory, file, handler) with cascading inheritance
+- Next.js feature parity: dynamic params, optional params, catch-all, route groups
+- Convention over configuration for status codes, tags, and metadata
+- Battle-tested security (path traversal protection, symlink validation)
+- WebSocket support, sync and async handlers
+- Hot reload compatible (`uvicorn --reload` works out of the box)
+- Full mypy strict mode support, coexists with manual FastAPI routing
+
+## 🤝 Contributing
+
+This plugin is extracted from a production codebase and is actively maintained. Issues, feature requests, and pull requests are welcome.
+
+GitHub: https://github.com/rsmdt/fastapi-filebased-routing.py