Registry / web-framework / piccolo-api

piccolo-api

JSON →
library1.9.0pypypiunverified

Piccolo API provides utilities for integrating the Piccolo ORM with ASGI applications. It includes essential ASGI middleware for common tasks like authentication (JWT, sessions, MFA) and rate limiting. The library is actively maintained, with regular releases (currently v1.9.0) addressing dependency updates, Python version support, and new features like Multi-Factor Authentication.

pip install piccolo-api
INSTALL
IMPORT
SIG · PICCOLO-API
P
piccolo-api
web-frameworkpythonv1.9.0
Install
6.7s avg
Import
Disk
62MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 57.5MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 6.7s · import 0.000s · 64MB
62MB installed
● package 62MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

JWTAuth
from piccolo_api.auth.jwt import JWTAuth
from piccolo_api.auth.jwt import JWTAuth

This quickstart demonstrates how to set up a basic Starlette application with JWT authentication using `piccolo-api`. It includes a public and a protected route, and shows how to configure `JWTAuth` middleware with a secret key and excluded paths. Remember to manage your secret keys securely, ideally via environment variables.

import os from starlette.applications import Starlette from starlette.responses import JSONResponse from starlette.routing import Route from piccolo_api import JWTAuth # For demonstration, typically loaded from environment variables SECRET_KEY = os.environ.get('JWT_SECRET_KEY', 'your_super_secret_key_here') async def homepage(request): return JSONResponse({'hello': 'world'}) async def protected_route(request): return JSONResponse({'data': 'This is protected data!'}) routes = [ Route('/', homepage), Route('/protected', protected_route) ] middleware = [ JWTAuth( secret_key=SECRET_KEY, # Exclude paths that don't require authentication excluded_paths=['/', '/docs'], # Allow an endpoint to create a token for testing # In a real app, this would be a login endpoint get_token_response=lambda user_id: JSONResponse({'token': f'fake-jwt-token-for-{user_id}'}) ) ] app = Starlette(routes=routes, middleware=middleware) # To run this: # uvicorn your_module_name:app --port 8000 --reload # Access with: http://127.0.0.1:8000/ # Try http://127.0.0.1:8000/protected with a valid JWT in Authorization header # You can use the get_token_response for generating a dummy token in dev.
piccolo --version
Debug
Known issues
breakingPython 3.8 and 3.9 are no longer supported since `piccolo-api` version 1.6.0. The library now requires Python >= 3.10.
fix
Upgrade your Python environment to 3.10 or newer.
affects: >=1.6.0
breakingPydantic 2.8.0 introduced breaking changes that caused issues with `piccolo-api` versions prior to 1.4.1. If you use Pydantic 2.8.0 or newer with an older `piccolo-api`, you may encounter validation errors.
fix
Upgrade `piccolo-api` to version 1.4.1 or newer: `pip install --upgrade piccolo-api`.
affects: <1.4.1 when used with Pydantic >=2.8.0
gotchaMulti-Factor Authentication (MFA) features require additional optional dependencies (`cryptography` and `pynacl`). Using MFA without these installed will result in `ModuleNotFoundError`.
fix
Install `piccolo-api` with the `mfa` extra: `pip install "piccolo-api[mfa]"`.
affects: All versions with MFA support (>=1.5.0)
gotchaWhen configuring Multi-Factor Authentication (MFA), it's highly recommended to provide sensitive encryption keys (e.g., `MFA_ENCRYPTION_KEY`) using environment variables for security reasons, rather than hardcoding them.
fix
Load encryption keys from environment variables using `os.environ.get('MFA_ENCRYPTION_KEY')`.
affects: All versions with MFA support (>=1.5.0)
Upgrade
Version history
1.9.0latest on PyPI · released Feb 11, 2026
Audit
Dependencies
piccolorequiredCore ORM integration
starletterequiredASGI framework dependency
uvicornrequiredASGI server for examples/development
pyjwtrequiredJSON Web Token handling
cryptographyoptionalRequired for Multi-Factor Authentication (MFA)
pynacloptionalRequired for Multi-Factor Authentication (MFA)
Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
piccolo-api — pip install piccolo-api · libregistry