Sanic Extensions

Warnings

• breaking Sanic-Ext versions are tightly coupled with Sanic framework versions. For example, `sanic-ext==25.12.0` is intended for use with `sanic>=23.12,<26.0`. Using a significantly older or newer Sanic version with an incompatible `sanic-ext` version can lead to runtime errors or unexpected behavior.
  Fix: Always install `sanic-ext` with a major version that matches or is compatible with your `sanic` installation. Refer to Sanic-Ext's documentation for specific version compatibility matrices.
• gotcha The behavior and capabilities of request data validation and OpenAPI schema generation have evolved across versions, especially with the introduction of `msgspec` support in `v23.12.0` and refinements to `pydantic`/`attrs` integration. Default type coercions or schema representations might differ slightly.
  Fix: If migrating from older versions, thoroughly test your API endpoints and review generated OpenAPI documentation. Consider explicitly installing `sanic-ext[msgspec]` or `sanic-ext[pydantic]` to leverage specific validation libraries.
• gotcha Prior to `v25.12.0`, Sanic-Ext could experience `KeyErrors` in query parameter validation under certain conditions. Additionally, issues related to handler list mutation (when dynamically adding/removing handlers) were present.
  Fix: Upgrade to `sanic-ext==25.12.0` or newer to benefit from fixes addressing `KeyErrors` in query param validation and handler list mutation stability. If upgrading is not immediately possible, avoid dynamic modification of handler lists after `Extend(app)` is called.
• gotcha In versions prior to `v25.12.0`, the background logger might fail to remove unpickleable items, potentially leading to resource leaks or unexpected behavior in long-running applications that utilize background logging.
  Fix: Upgrade to `sanic-ext==25.12.0` or newer to resolve issues with the background logger failing to remove unpickleable items. Ensure that objects passed to background tasks are pickleable where necessary.

Install

• pip install sanic-ext Install latest version
• pip install sanic-ext[msgspec] Install with msgspec support
• pip install sanic-ext[pydantic] Install with Pydantic support

Imports

• Extend

  from sanic_ext import Extend

  The primary way to initialize Sanic-Ext is through `from sanic_ext import Extend`.
• Sanic

  from sanic import Sanic

  Sanic-Ext expects the Sanic application object, which is imported from the main `sanic` library.

Quickstart

This quickstart demonstrates how to initialize Sanic-Ext with a Sanic application and use its dependency injection feature for route handlers. By type-hinting parameters in a route function, Sanic-Ext automatically extracts them from the request (e.g., query parameters, path parameters, or request body) and performs basic validation. After running, you can typically access OpenAPI documentation at `/docs` or `/swagger` in your browser.

from sanic import Sanic
from sanic_ext import Extend
from typing import Optional

app = Sanic("My App with Sanic-Ext")
Extend(app)

@app.get("/")
async def hello_world(name: str = "World"):
    # Sanic-Ext automatically injects query parameters based on type hints
    return {"hello": name}

@app.post("/items")
async def create_item(item_id: int, description: Optional[str] = None):
    # This demonstrates basic type-hinted injection for path/query parameters
    return {"item_id": item_id, "description": description, "status": "created"}

if __name__ == "__main__":
    # Run the Sanic application
    # Sanic-Ext provides features like OpenAPI docs at /docs or /swagger
    app.run(host="0.0.0.0", port=8000, debug=True)