{"id":10034,"library":"piccolo-api","title":"Piccolo API Utilities","description":"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.","status":"active","version":"1.9.0","language":"en","source_language":"en","source_url":"https://github.com/piccolo-orm/piccolo_api","tags":["ASGI","Piccolo","ORM","Authentication","Middleware","JWT","Rate Limiting"],"install":[{"cmd":"pip install piccolo-api","lang":"bash","label":"Basic Install"},{"cmd":"pip install \"piccolo-api[mfa]\"","lang":"bash","label":"Install with MFA support"}],"dependencies":[{"reason":"Core ORM integration","package":"piccolo","optional":false},{"reason":"ASGI framework dependency","package":"starlette","optional":false},{"reason":"ASGI server for examples/development","package":"uvicorn","optional":false},{"reason":"JSON Web Token handling","package":"pyjwt","optional":false},{"reason":"Required for Multi-Factor Authentication (MFA)","package":"cryptography","optional":true},{"reason":"Required for Multi-Factor Authentication (MFA)","package":"pynacl","optional":true}],"imports":[{"note":"Common classes like JWTAuth are exposed at the top level for convenience.","wrong":"from piccolo_api.middleware.auth.jwt import JWTAuth","symbol":"JWTAuth","correct":"from piccolo_api import JWTAuth"},{"note":"Common classes like SessionsAuthBackend are exposed at the top level for convenience.","wrong":"from piccolo_api.middleware.auth.sessions import SessionsAuthBackend","symbol":"SessionsAuthBackend","correct":"from piccolo_api import SessionsAuthBackend"},{"note":"Common classes like RateLimitMiddleware are exposed at the top level for convenience.","wrong":"from piccolo_api.rate_limit import RateLimitMiddleware","symbol":"RateLimitMiddleware","correct":"from piccolo_api import RateLimitMiddleware"}],"quickstart":{"code":"import os\nfrom starlette.applications import Starlette\nfrom starlette.responses import JSONResponse\nfrom starlette.routing import Route\n\nfrom piccolo_api import JWTAuth\n\n# For demonstration, typically loaded from environment variables\nSECRET_KEY = os.environ.get('JWT_SECRET_KEY', 'your_super_secret_key_here')\n\nasync def homepage(request):\n    return JSONResponse({'hello': 'world'})\n\nasync def protected_route(request):\n    return JSONResponse({'data': 'This is protected data!'})\n\nroutes = [\n    Route('/', homepage),\n    Route('/protected', protected_route)\n]\n\nmiddleware = [\n    JWTAuth(\n        secret_key=SECRET_KEY,\n        # Exclude paths that don't require authentication\n        excluded_paths=['/', '/docs'], \n        # Allow an endpoint to create a token for testing\n        # In a real app, this would be a login endpoint\n        get_token_response=lambda user_id: JSONResponse({'token': f'fake-jwt-token-for-{user_id}'})\n    )\n]\n\napp = Starlette(routes=routes, middleware=middleware)\n\n# To run this:\n# uvicorn your_module_name:app --port 8000 --reload\n# Access with: http://127.0.0.1:8000/\n# Try http://127.0.0.1:8000/protected with a valid JWT in Authorization header\n# You can use the get_token_response for generating a dummy token in dev.","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer.","message":"Python 3.8 and 3.9 are no longer supported since `piccolo-api` version 1.6.0. The library now requires Python >= 3.10.","severity":"breaking","affected_versions":">=1.6.0"},{"fix":"Upgrade `piccolo-api` to version 1.4.1 or newer: `pip install --upgrade piccolo-api`.","message":"Pydantic 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.","severity":"breaking","affected_versions":"<1.4.1 when used with Pydantic >=2.8.0"},{"fix":"Install `piccolo-api` with the `mfa` extra: `pip install \"piccolo-api[mfa]\"`.","message":"Multi-Factor Authentication (MFA) features require additional optional dependencies (`cryptography` and `pynacl`). Using MFA without these installed will result in `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"All versions with MFA support (>=1.5.0)"},{"fix":"Load encryption keys from environment variables using `os.environ.get('MFA_ENCRYPTION_KEY')`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions with MFA support (>=1.5.0)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `piccolo-api` with the `mfa` extra: `pip install \"piccolo-api[mfa]\"` (or `pynacl` if that's the missing module).","cause":"You are attempting to use Multi-Factor Authentication (MFA) features without having the necessary optional dependencies installed.","error":"ModuleNotFoundError: No module named 'cryptography'"},{"fix":"Upgrade `piccolo-api` to `1.4.1` or newer: `pip install --upgrade piccolo-api`. Ensure your `pyproject.toml` or `requirements.txt` specifies a compatible version.","cause":"This (or similar Pydantic validation errors) can occur due to an incompatibility between `piccolo-api < 1.4.1` and `Pydantic >= 2.8.0`.","error":"pydantic_core._pydantic_core.ValidationError: Input should be a valid string"},{"fix":"Upgrade your Python environment to version 3.10 or newer.","cause":"You are running `piccolo-api` on an unsupported Python version. Python 3.8 and 3.9 were dropped in `piccolo-api` v1.6.0.","error":"RuntimeError: Your current Python version is 3.9.13 but Piccolo API requires >=3.10"}]}