Piccolo API Utilities

Common errors

• ModuleNotFoundError: No module named 'cryptography'

  cause You are attempting to use Multi-Factor Authentication (MFA) features without having the necessary optional dependencies installed.
  fix Install `piccolo-api` with the `mfa` extra: `pip install "piccolo-api[mfa]"` (or `pynacl` if that's the missing module).

• pydantic_core._pydantic_core.ValidationError: Input should be a valid string

  cause This (or similar Pydantic validation errors) can occur due to an incompatibility between `piccolo-api < 1.4.1` and `Pydantic >= 2.8.0`.
  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.

• RuntimeError: Your current Python version is 3.9.13 but Piccolo API requires >=3.10

  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.
  fix Upgrade your Python environment to version 3.10 or newer.

Warnings

• breaking Python 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.
• breaking 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.
  Fix: Upgrade `piccolo-api` to version 1.4.1 or newer: `pip install --upgrade piccolo-api`.
• gotcha Multi-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]"`.
• gotcha 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.
  Fix: Load encryption keys from environment variables using `os.environ.get('MFA_ENCRYPTION_KEY')`.

Install

• pip install piccolo-api Basic Install
• pip install "piccolo-api[mfa]" Install with MFA support

Imports

• JWTAuth
  wrong:

  from piccolo_api.middleware.auth.jwt import JWTAuth

  correct:

  from piccolo_api import JWTAuth

  Common classes like JWTAuth are exposed at the top level for convenience.
• SessionsAuthBackend
  wrong:

  from piccolo_api.middleware.auth.sessions import SessionsAuthBackend

  correct:

  from piccolo_api import SessionsAuthBackend

  Common classes like SessionsAuthBackend are exposed at the top level for convenience.
• RateLimitMiddleware
  wrong:

  from piccolo_api.rate_limit import RateLimitMiddleware

  correct:

  from piccolo_api import RateLimitMiddleware

  Common classes like RateLimitMiddleware are exposed at the top level for convenience.

Quickstart

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.