sanic Documentation

Technical Documentation: sanic-org/sanic

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Guide Content En Index (`guide/content/en/index.md`) Copy Section

title: The lightning-fast asynchronous Python web framework
layout: home
features:

• title: Simple and lightweight
  details: Intuitive API with smart defaults and no bloat allows you to get straight to work building your app.
• title: Unopinionated and flexible
  details: Build the way you want to build without letting your tooling constrain you.
• title: Performant and scalable
  details: Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small.
• title: Production ready
  details: Out of the box, it comes bundled with a web server ready to power your web applications.
• title: Trusted by millions
  details: Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework
• title: Community driven
  details: The project is maintained and run by the community for the community.

⚡ The lightning-fast asynchronous Python web framework Copy Section

.. attrs::
:class: columns is-multiline mt-6

.. attrs::
    :class: column is-4

    #### Simple and lightweight

    Intuitive API with smart defaults and no bloat allows you to get straight to work building your app.

.. attrs::
    :class: column is-4

    #### Unopinionated and flexible

    Build the way you want to build without letting your tooling constrain you.

.. attrs::
    :class: column is-4

    #### Performant and scalable

    Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small.

.. attrs::
    :class: column is-4

    #### Production ready

    Out of the box, it comes bundled with a web server ready to power your web applications.

.. attrs::
    :class: column is-4

    #### Trusted by millions

    Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework

.. attrs::
    :class: column is-4

    #### Community driven

    The project is maintained and run by the community for the community.

.. attrs::
:class: is-size-3 mt-6

**With the features and tools you'd expect.**

.. attrs::
:class: is-size-3 ml-6

**And some {span:has-text-primary:you wouldn't believe}.**

.. tab:: Production-grade

After installing, Sanic has all the tools you need for a scalable, production-grade server—out of the box!

Including [full TLS support](/en/guide/how-to/tls.md).

```python
from sanic import Sanic
from sanic.response import text

app = Sanic("MyHelloWorldApp")

@app.get("/")
async def hello_world(request):
    return text("Hello, world.")
```

```sh
sanic path.to.server:app
[2023-01-31 12:34:56 +0000] [999996] [INFO] Sanic v22.12.0
[2023-01-31 12:34:56 +0000] [999996] [INFO] Goin' Fast @ http://127.0.0.1:8000
[2023-01-31 12:34:56 +0000] [999996] [INFO] mode: production, single worker
[2023-01-31 12:34:56 +0000] [999996] [INFO] server: sanic, HTTP/1.1
[2023-01-31 12:34:56 +0000] [999996] [INFO] python: 3.10.9
[2023-01-31 12:34:56 +0000] [999996] [INFO] platform: SomeOS-9.8.7
[2023-01-31 12:34:56 +0000] [999996] [INFO] packages: sanic-routing==22.8.0
[2023-01-31 12:34:56 +0000] [999997] [INFO] Starting worker [999997]
```

.. tab:: TLS server

Running Sanic with TLS enabled is as simple as passing it the file paths...
```sh
sanic path.to.server:app --cert=/path/to/bundle.crt --key=/path/to/privkey.pem
```

... or the a directory containing `fullchain.pem` and `privkey.pem`

```sh
sanic path.to.server:app --tls=/path/to/certs
```

**Even better**, while you are developing, let Sanic handle setting up local TLS certificates so you can access your site over TLS at [https://localhost:8443](https://localhost:8443)

```sh
sanic path.to.server:app --dev --auto-tls
```

.. tab:: Websockets

Up and running with websockets in no time using the [websockets](https://websockets.readthedocs.io) package.
```python
from sanic import Request, Websocket

@app.websocket("/feed")
async def feed(request: Request, ws: Websocket):
    async for msg in ws:
        await ws.send(msg)
```

.. tab:: Static files

Serving static files is of course intuitive and easy. Just name an endpoint and either a file or directory that should be served.

```python
app.static("/", "/path/to/index.html")
app.static("/uploads/", "/path/to/uploads/")
```

Moreover, serving a directory has two additional features: automatically serving an index, and automatically serving a file browser.

Sanic can automatically serve `index.html` (or any other named file) as an index page in a directory or its subdirectories.

```python
app.static(
    "/uploads/",
    "/path/to/uploads/",
    index="index.html"
)
```

And/or, setup Sanic to display a file browser.




```python
app.static(
    "/uploads/",
    "/path/to/uploads/",
    directory_view=True
)
```

.. tab:: Lifecycle

Beginning or ending a route with functionality is as simple as adding a decorator.

```python
@app.on_request
async def add_key(request):
    request.ctx.foo = "bar"

@app.on_response
async def custom_banner(request, response):
    response.headers["X-Foo"] = request.ctx.foo
```

Same with server events.

```python
@app.before_server_start
async def setup_db(app):
    app.ctx.db_pool = await db_setup()

@app.after_server_stop
async def setup_db(app):
    await app.ctx.db_pool.shutdown()
```

But, Sanic also allows you to tie into a bunch of built-in events (called signals), or create and dispatch your own.

```python
@app.signal("http.lifecycle.complete")  # built-in
async def my_signal_handler(conn_info):
    print("Connection has been closed")

@app.signal("something.happened.ohmy")  # custom
async def my_signal_handler():
    print("something happened")

await app.dispatch("something.happened.ohmy")
```

.. tab:: Smart error handling

Raising errors will intuitively result in proper HTTP errors:

```python
raise sanic.exceptions.NotFound  # Automatically responds with HTTP 404
```

Or, make your own:

```python
from sanic.exceptions import SanicException

class TeapotError(SanicException):
    status_code = 418
    message = "Sorry, I cannot brew coffee"

raise TeapotError
```

And, when an error does happen, Sanic's beautiful DEV mode error page will help you drill down to the bug quickly.



Regardless, Sanic comes with an algorithm that attempts to respond with HTML, JSON, or text-based errors as appropriate. Don't worry, it is super easy to setup and customize your error handling to your exact needs.

.. tab:: App Inspector

Check in on your live, running applications (whether local or remote).
```

/* Detailed source-code truncated for AI context efficiency. */

And, issue commands like `reload`, `shutdown`, `scale`...

    ```sh
    sanic inspect scale 4
    ```

    ... or even create your own!

    ```sh
    sanic inspect migrations
    ```

.. tab:: Extendable

    In addition to the tools that Sanic comes with, the officially supported [Sanic Extensions](./plugins/sanic-ext/getting-started.md) provides lots of extra goodies to make development easier.

    - **CORS** protection
    - Template rendering with **Jinja**
    - **Dependency injection** into route handlers
    - OpenAPI documentation with **Redoc** and/or **Swagger**
    - Predefined, endpoint-specific response **serializers**
    - Request query arguments and body input **validation**
    - **Auto create** HEAD, OPTIONS, and TRACE endpoints
    - Live **health monitor**

.. tab:: Developer Experience

    Sanic is **built for building**.

    From the moment it is installed, Sanic includes helpful tools to help the developer get their job done.

    - **One server** - Develop locally in DEV mode on the same server that will run your PRODUCTION application
    - **Auto reload** - Reload running applications every time you save a Python file, but also auto-reload **on any arbitrary directory** like HTML template directories
    - **Debugging tools** - Super helpful (and beautiful) [error pages](/en/guide/best-practices/exceptions) that help you traverse the trace stack easily
    - **Auto TLS** - Running a localhost website with `https` can be difficult, [Sanic makes it easy](/en/guide/how-to/tls.md)
    - **Streamlined testing** - Built-in testing capabilities, making it easier for developers to create and run tests, ensuring the quality and reliability of their services
    - **Modern Python** - Thoughtful use of type hints to help the developer IDE experience

---

### Guide Content En Guide Getting Started (`guide/content/en/guide/getting-started.md`)

# Getting Started

Before we begin, make sure you are running Python 3.9 or higher. Currently, Sanic is works with Python versions 3.9 – 3.13.

## Install

```sh
pip install sanic

Hello, world application Copy Chapter

.. column::

If you have ever used one of the many decorator based frameworks, this probably looks somewhat familiar to you.



.. note:: 

    If you are coming from Flask or another framework, there are a few important things to point out. Remember, Sanic aims for performance, flexibility, and ease of use. These guiding principles have tangible impact on the API and how it works.

.. column::

```python
from sanic import Sanic
from sanic.response import text

app = Sanic("MyHelloWorldApp")

@app.get("/")
async def hello_world(request):
    return text("Hello, world.")
```

Important to note Copy Section

• Every request handler can either be sync (def hello_world) or async (async def hello_world). Unless you have a clear reason for it, always go with async.
• The request object is always the first argument of your handler. Other frameworks pass this around in a context variable to be imported. In the async world, this would not work so well and it is far easier (not to mention cleaner and more performant) to be explicit about it.
• You must use a response type. MANY other frameworks allow you to have a return value like this: return "Hello, world." or this: return {"foo": "bar"}. But, in order to do this implicit calling, somewhere in the chain needs to spend valuable time trying to determine what you meant. So, at the expense of this ease, Sanic has decided to require an explicit call.

Running Copy Section

.. column::

Let's save the above file as `server.py`. And launch it.

.. column::

```sh
sanic server
```

.. note::

This **another** important distinction. Other frameworks come with a built in development server and explicitly say that it is _only_ intended for development use. The opposite is true with Sanic. 

**The packaged server is production ready.**

Sanic Extensions Copy Chapter

Sanic intentionally aims for a clean and unopinionated feature list. The project does not want to require you to build your application in a certain way, and tries to avoid prescribing specific development patterns. There are a number of third-party plugins that are built and maintained by the community to add additional features that do not otherwise meet the requirements of the core repository.

However, in order to help API developers, the Sanic organization maintains an official plugin called Sanic Extensions to provide all sorts of goodies, including:

• OpenAPI documentation with Redoc and/or Swagger
• CORS protection
• Dependency injection into route handlers
• Request query arguments and body input validation
• Auto create HEAD, OPTIONS, and TRACE endpoints
• Predefined, endpoint-specific response serializers

The preferred method to set it up is to install it along with Sanic, but you can also install the packages on their own.

.. column::

```sh
pip install sanic[ext]
```

.. column::

```sh
pip install sanic sanic-ext
```

Starting in v21.12, Sanic will automatically setup Sanic Extensions if it is in the same environment. You will also have access to two additional application properties:

• app.extend() - used to configure Sanic Extensions
• app.ext - the Extend instance attached to the application

See the plugin documentation for more information about how to use and work with the plugin

Guide Content En Plugins Sanic Ext Getting Started (`guide/content/en/plugins/sanic-ext/getting-started.md`) Copy Section

title: Sanic Extensions - Getting Started Copy Chapter

Getting Started

Sanic Extensions is an officially supported plugin developed, and maintained by the SCO. The primary goal of this project is to add additional features to help Web API and Web application development easier.

Features Copy Chapter

• CORS protection
• Template rendering with Jinja
• Dependency injection into route handlers
• OpenAPI documentation with Redoc and/or Swagger
• Predefined, endpoint-specific response serializers
• Request query arguments and body input validation
• Auto create HEAD, OPTIONS, and TRACE endpoints

Minimum requirements Copy Chapter

• Python: 3.8+
• Sanic: 21.9+

Install Copy Chapter

The best method is to just install Sanic Extensions along with Sanic itself:

pip install sanic[ext]

You can of course also just install it by itself.

pip install sanic-ext

Extend your application Copy Chapter

Out of the box, Sanic Extensions will enable a bunch of features for you.

.. column::

To setup Sanic Extensions (v21.12+), you need to do: **nothing**. If it is installed in the environment, it is setup and ready to go.

This code is the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md) _without any changes_, but using Sanic Extensions with `sanic-ext` installed in the background.

.. column::

```python
from sanic import Sanic
from sanic.response import text

app = Sanic("MyHelloWorldApp")

@app.get("/")
async def hello_world(request):
    return text("Hello, world.")
```

.. column::

**_OLD DEPRECATED SETUP_**

In v21.9, the easiest way to get started is to instantiate it with `Extend`.

If you look back at the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md), you will see the only additions here are the two highlighted lines.

.. column::

```python
from sanic import Sanic
from sanic.response import text
from sanic_ext import Extend

app = Sanic("MyHelloWorldApp")
Extend(app)

@app.get("/")
async def hello_world(request):
    return text("Hello, world.")
```

Regardless of how it is setup, you should now be able to view the OpenAPI documentation and see some of the functionality in action: http://localhost:8000/docs.

Guide Content En Plugins Sanic Testing Getting Started (`guide/content/en/plugins/sanic-testing/getting-started.md`) Copy Section

title: Sanic Testing - Getting Started Copy Chapter

Getting Started

Sanic Testing is the official testing client for Sanic. Its primary use is to power the tests of the Sanic project itself. However, it is also meant as an easy-to-use client for getting your API tests up and running quickly.

Minimum requirements Copy Chapter

• Python: 3.7+
• Sanic: 21.3+

Versions of Sanic older than 21.3 have this module integrated into Sanic itself as sanic.testing.

Install Copy Chapter

Sanic Testing can be installed from PyPI:

pip install sanic-testing

Basic Usage Copy Chapter

As long as the sanic-testing package is in the environment, there is nothing you need to do to start using it.

Writing a sync test Copy Section

In order to use the test client, you just need to access the property test_client on your application instance:

import pytest
from sanic import Sanic, response

@pytest.fixture
def app():
    sanic_app = Sanic("TestSanic")

    @sanic_app.get("/")
    def basic(request):
        return response.text("foo")

    return sanic_app

def test_basic_test_client(app):
    request, response = app.test_client.get("/")

    assert request.method.lower() == "get"
    assert response.body == b"foo"
    assert response.status == 200

Writing an async test Copy Section

In order to use the async test client in pytest, you should install the pytest-asyncio plugin.

pip install pytest-asyncio

You can then create an async test and use the ASGI client:

import pytest
from sanic import Sanic, response

@pytest.fixture
def app():
    sanic_app = Sanic(__name__)

    @sanic_app.get("/")
    def basic(request):
        return response.text("foo")

    return sanic_app

@pytest.mark.asyncio
async def test_basic_asgi_client(app):
    request, response = await app.asgi_client.get("/")

    assert request.method.lower() == "get"
    assert response.body == b"foo"
    assert response.status == 200

Index (`docs/index.rst`) Copy Section

.. include:: ../README.rst

User Guide

To learn about using Sanic, checkout the User Guide <https://sanicframework.org/guide/>__.

API

.. toctree::
:maxdepth: 3

👥 User Guide https://sanicframework.org/guide/
sanic/api_reference
💻 Source code https://github.com/sanic-org/sanic/
sanic/changelog
sanic/contributing
❓ Support https://community.sanicframework.org/
💬 Chat https://discord.gg/FARQzAEMAA

Module Documentation

.. toctree::

• :ref:genindex
• :ref:modindex

Guide Requirements (`guide/requirements.txt`) Copy Section

sanic>=23.12
sanic-ext>=23.12
msgspec
python-frontmatter
pygments
docstring-parser
libsass
mistune

Sanic Api Reference (`docs/sanic/api_reference.rst`) Copy Section

📑 API Reference

.. toctree::
:maxdepth: 2

api/app
api/blueprints
api/core
api/exceptions
api/router
api/server
api/utility

Sanic Changelog (`docs/sanic/changelog.rst`) Copy Section

📜 Changelog

| 🔶 Current release
| 🔷 In support release
|

.. mdinclude:: ./releases/23/23.6.md
.. mdinclude:: ./releases/23/23.3.md
.. mdinclude:: ./releases/22/22.12.md
.. mdinclude:: ./releases/22/22.9.md
.. mdinclude:: ./releases/22/22.6.md
.. mdinclude:: ./releases/22/22.3.md
.. mdinclude:: ./releases/21/21.12.md
.. mdinclude:: ./releases/21/21.9.md
.. include:: ../../CHANGELOG.rst

Sanic Contributing (`docs/sanic/contributing.rst`) Copy Section

♥️ Contributing

.. include:: ../../CONTRIBUTING.rst

Sanic Api App (`docs/sanic/api/app.rst`) Copy Section

Application

sanic.app Copy Chapter

.. automodule:: sanic.app
:members:
:show-inheritance:
:inherited-members:

sanic.config Copy Chapter

.. automodule:: sanic.config
:members:
:show-inheritance:

sanic.application.constants Copy Chapter

.. automodule:: sanic.application.constants
:exclude-members: StrEnum
:members:
:show-inheritance:
:inherited-members:

sanic.application.state Copy Chapter

.. automodule:: sanic.application.state
:members:
:show-inheritance:

Sanic Api Blueprints (`docs/sanic/api/blueprints.rst`) Copy Section

Blueprints

sanic.blueprints Copy Chapter

.. automodule:: sanic.blueprints
:members:
:show-inheritance:
:inherited-members:

sanic.blueprint_group Copy Chapter

.. automodule:: sanic.blueprint_group
:members:
:special-members:

Sanic Api Core (`docs/sanic/api/core.rst`) Copy Section

Core

sanic.cookies Copy Chapter

.. automodule:: sanic.cookies
:members:
:show-inheritance:

sanic.handlers Copy Chapter

.. automodule:: sanic.handlers
:members:
:show-inheritance:

sanic.headers Copy Chapter

.. automodule:: sanic.headers
:members:
:show-inheritance:

sanic.request Copy Chapter

.. automodule:: sanic.request
:members:
:show-inheritance:

sanic.response Copy Chapter

.. automodule:: sanic.response
:members:
:show-inheritance:

sanic.views Copy Chapter

.. automodule:: sanic.views
:members:
:show-inheritance:

Sanic Api Exceptions (`docs/sanic/api/exceptions.rst`) Copy Section

Exceptions

sanic.errorpages Copy Chapter

.. automodule:: sanic.errorpages
:members:
:show-inheritance:

sanic.exceptions Copy Chapter

.. automodule:: sanic.exceptions
:members:
:show-inheritance:

Sanic Api Router (`docs/sanic/api/router.rst`) Copy Section

Routing

sanic_routing models Copy Chapter

.. autoclass:: sanic_routing.route::Route
:members:

.. autoclass:: sanic_routing.group::RouteGroup
:members:

sanic.router Copy Chapter

.. automodule:: sanic.router
:members:
:show-inheritance:

Sanic Api Server (`docs/sanic/api/server.rst`) Copy Section

Sanic Server

sanic.http Copy Chapter

.. automodule:: sanic.http
:members:
:show-inheritance:

sanic.server Copy Chapter

.. automodule:: sanic.server
:members:
:show-inheritance:

Sanic Api Utility (`docs/sanic/api/utility.rst`) Copy Section

Utility

sanic.compat Copy Chapter

.. automodule:: sanic.compat
:members:
:show-inheritance:

sanic.log Copy Chapter

.. automodule:: sanic.log
:members:
:show-inheritance:

Guide Config En Navbar.Yaml (`guide/config/en/navbar.yaml`) Copy Section

root:
- label: Home
path: index.html
- label: Community
items:
- label: Forums
href: https://community.sanicframework.org
- label: Discord
href: https://discord.gg/FARQzAEMAA
- label: Twitter
href: https://twitter.com/sanicframework
- label: Help
path: ./help.html
- label: GitHub
href: https://github.com/sanic-org/sanic

Guide Config En Sidebar.Yaml (`guide/config/en/sidebar.yaml`) Copy Section

root:
- label: User Guide
items:
- label: General
items:
- label: Introduction
path: guide/introduction.html
- label: Getting Started
path: guide/getting-started.html
- label: Basics
items:
- label: Sanic Application
path: guide/basics/app.html
- label: Handlers
path: guide/basics/handlers.html
- label: Request
path: guide/basics/request.html
- label: Response
path: guide/basics/response.html
- label: Routing
path: guide/basics/routing.html
- label: Listeners
path: guide/basics/listeners.html
- label: Middleware
path: guide/basics/middleware.html
- label: Headers
path: guide/basics/headers.html
- label: Cookies
path: guide/basics/cookies.html
- label: Background Tasks
path: guide/basics/tasks.html
- label: Advanced
items:
- label: Class Based Views
path: guide/advanced/class-based-views.html
- label: Proxy Configuration
path: guide/advanced/proxy-headers.html
- label: Streaming
path: guide/advanced/streaming.html
- label: Websockets
path: guide/advanced/websockets.html
- label: Versioning
path: guide/advanced/versioning.html
- label: Signals
path: guide/advanced/signals.html
- label: Custom CLI Commands
path: guide/advanced/commands.html
- label: Best Practices
items:
- label: Blueprints
path: guide/best-practices/blueprints.html
- label: Exceptions
path: guide/best-practices/exceptions.html
- label: Decorators
path: guide/best-practices/decorators.html
- label: Logging
path: guide/best-practices/logging.html
- label: Testing
path: guide/best-practices/testing.html
- label: Running Sanic
items:
- label: Configuration
path: guide/running/configuration.html
- label: Development
path: guide/running/development.html
- label: Running Sanic
path: guide/running/running.html
- label: Worker Manager
path: guide/running/manager.html
- label: Dynamic Applications
path: guide/running/app-loader.html
- label: Inspector
path: guide/running/inspector.html
- label: Deployment
items:
- label: Caddy
path: guide/deployment/caddy.html
- label: Nginx
path: guide/deployment/nginx.html
- label: Docker
path: guide/deployment/docker.html
- label: How to ...
items:
- label: Table of Contents
path: guide/how-to/table-of-contents.html
- label: Application Mounting
path: guide/how-to/mounting.html
- label: Authentication
path: guide/how-to/authentication.html
- label: Autodiscovery
path: guide/how-to/autodiscovery.html
- label: CORS
path: guide/how-to/cors.html
- label: ORM
path: guide/how-to/orm.html
- label: Static Redirects
path: guide/how-to/static-redirects.html
- label: TLS/SSL/HTTPS
path: guide/how-to/tls.html
- label: Plugins
items:
- label: Sanic Extensions
items:
- label: Getting Started
path: plugins/sanic-ext/getting-started.html
- label: HTTP - Methods
path: plugins/sanic-ext/http/methods.html
- label: HTTP - CORS Protection
path: plugins/sanic-ext/http/cors.html
- label: OpenAPI - Basics
path: plugins/sanic-ext/openapi/basics.html
- label: OpenAPI - UI
path: plugins/sanic-ext/openapi/ui.html
- label: OpenAPI - Decorators
path: plugins/sanic-ext/openapi/decorators.html
# - label: OpenAPI - Advanced
# path: plugins/sanic-ext/openapi/advanced.html
- label: OpenAPI - Auto Documentation
path: plugins/sanic-ext/openapi/autodoc.html
- label: OpenAPI - Security
path: plugins/sanic-ext/openapi/security.html
- label: Convenience
path: plugins/sanic-ext/convenience.html
- label: Templating - Jinja
path: plugins/sanic-ext/templating/jinja.html
- label: Templating - html5tagger
path: plugins/sanic-ext/templating/html5tagger.html
- label: Dependency Injection
path: plugins/sanic-ext/injection.html
- label: Validation
path: plugins/sanic-ext/validation.html
- label: Health Monitor
path: plugins/sanic-ext/health-monitor.html
- label: Background Logger
path: plugins/sanic-ext/logger.html
- label: Configuration
path: plugins/sanic-ext/configuration.html
- label: Custom Extensions
path: plugins/sanic-ext/custom.html
- label: Sanic Testing
items:
- label: Getting Started
path: plugins/sanic-testing/getting-started.html
- label: Test Clients
path: plugins/sanic-testing/clients.html
- label: Release Notes
items:
- label: "2025"
items:
- label: Sanic 25.12
path: release-notes/2025/v25.12.html
- label: Sanic 25.3
path: release-notes/2025/v25.3.html
- label: "2024"
items:
- label: Sanic 24.12
path: release-notes/2024/v24.12.html
- label: Sanic 24.6
path: release-notes/2024/v24.6.html
- label: "2023"
items:
- label: Sanic 23.12
path: release-notes/2023/v23.12.html
- label: Sanic 23.9
path: release-notes/2023/v23.9.html
- label: Sanic 23.6
path: release-notes/2023/v23.6.html
- label: Sanic 23.3
path: release-notes/2023/v23.3.html
- label: "2022"
items:
- label: Sanic 22.12
path: release-notes/2022/v22.12.html
- label: Sanic 22.9
path: release-notes/2022/v22.9.html
- label: Sanic 22.6
path: release-notes/2022/v22.6.html
- label: Sanic 22.3
path: release-notes/2022/v22.3.html
- label: "2021"
items:
- label: Sanic 21.12
path: release-notes/2021/v21.12.html
- label: Sanic 21.9
path: release-notes/2021/v21.9.html
- label: Sanic 21.6
path: release-notes/2021/v21.6.html
- label: Sanic 21.3
path: release-notes/2021/v21.3.html
- label: Changelog
path: release-notes/changelog.html
- label: Organization
items:
- label: Contributing
path: organization/contributing.html
- label: Code of Conduct
path: organization/code-of-conduct.html
- label: S.C.O.P.E. (Governance)
path: organization/scope.html
- label: Policies
path: organization/policies.html
- label: API Reference
items:
- label: Application
items:
- label: sanic.app
path: /api/sanic.app.html
- label: sanic.config
path: /api/sanic.config.html
- label: sanic.application
path: /api/sanic.application.html
- label: Blueprint
items:
- label: sanic.blueprints
path: /api/sanic.blueprints.html
- label: sanic.blueprint_group
path: /api/sanic.blueprint_group.html
- label: Constant
items:
- label: sanic.constants
path: /api/sanic.constants.html
- label: Core
items:
- label: sanic.cookies
path: /api/sanic.cookies.html
- label: sanic.handlers
path: /api/sanic.handlers.html
- label: sanic.headers
path: /api/sanic.headers.html
- label: sanic.middleware
path: /api/sanic.middleware.html
- label: sanic.mixins
path: /api/sanic.mixins.html
- label: sanic.request
path: /api/sanic.request.html
- label: sanic.response
path: /api/sanic.response.html
- label: sanic.views
path: /api/sanic.views.html
- label: Display
items:
- label: sanic.pages
path: /api/sanic.pages.html
- label: Exception
items:
- label: sanic.errorpages
path: /api/sanic.errorpages.html
- label: sanic.exceptions
path: /api/sanic.exceptions.html
- label: Model
items:
- label: sanic.models
path: /api/sanic.models.html
- label: Routing
items:
- label: sanic.router
path: /api/sanic.router.html
- label: sanic.signals
path: /api/sanic.signals.html
- label: Server
items:
- label: sanic.http
path: /api/sanic.http.html
- label: sanic.server
path: /api/sanic.server.html
- label: sanic.worker
path: /api/sanic.worker.html
- label: Utility
items:
- label: sanic.compat
path: /api/sanic.compat.html
- label: sanic.helpers
path: /api/sanic.helpers.html
- label: sanic.logging
path: /api/sanic.logging.html
- label: sanic.utils
path: /api/sanic.utils.html

Guide Content En Built With Sanic (`guide/content/en/built-with-sanic.md`) Copy Section

title: Full Speed Ahead - How We Built This Site with Sanic layout: main Copy Chapter

.. attrs::
:class: title

Full Speed Ahead:

.. attrs::
:class: subtitle

How We Built This Site with Sanic

Welcome to our little corner of the Internet where we proudly say, "Yes, we built this with Sanic!" This isn't just a website; it's our playground, our test lab, our battlefield, and, well, our home.

The Story: "We Drink Our Own Champagne" Copy Section

We believe in Sanic so much that we decided to put it to the ultimate test—running our own website. It's like a chef eating at their own restaurant, only with less risk of food poisoning.

Why? Because building a website or web application is hard. There are countless moving parts, a plethora of challenges, and the ever-present need for speed and reliability. We want to show you just one of the many ways you could do it.

In this high-stakes digital kitchen, Sanic is our secret ingredient. By deploying our own website on Sanic, we're not just showcasing its capabilities; we're stress-testing them in the real world. This is our chance to walk the walk, proving that Sanic isn't just good on paper—it's a robust, high-performance framework that can handle everything from the smallest blog to the busiest e-commerce site.

So, here we are, sipping our own champagne, confident in the knowledge that if Sanic can run our site, it can power yours too. Cheers to coding at the speed of thought! 🥂

The Setup: Digital Ocean, Ahoy! Copy Section

We launched our site on Digital Ocean's App Platform because we love high-performance cloud sailing. Think of it as having a Ferrari in the cloud—fast, sleek, but way easier to handle.

Why go for simplicity? With a lean team and no DevOps gurus, we needed a no-fuss, straightforward solution. Digital Ocean gives us that smooth sailing platform-as-a-service (PaaS) experience. It’s perfect for our needs: easy setup, automatic deployments, and the kind of reliability that lets you sleep soundly.

Our choice reflects our ethos: focus on your strengths and let the platform do the heavy lifting. For us, it means creating amazing web experiences with Sanic, supported by a deployment solution that's simple yet powerful. ⛵

The Code: GitHub's Where It's At Copy Section

All our code is out in the open, basking in the glory of public scrutiny on GitHub. Why hide the magic? It's right there, in full view, at our GitHub repository. Go ahead, take a peek, fork it, play with it, break it (and then kindly fix it).

Open-source isn't just a buzzword for us; it's our ethos. It's about building something bigger than ourselves, together. Our code is a testament to collaborative innovation, a playground for development, and a real-life example of Sanic in action.

Every line of code, every commit, reflects our journey with Sanic, showcasing how we leverage its speed and scalability. Your contributions, whether fixing a bug, suggesting a feature, or enhancing documentation, are what propel this project forward.

So, dive in, contribute your genius, and let's keep shaping the future of web development with Sanic. Together, we're not just coding – we're creating a community-driven powerhouse. 🚀

The Invitation: Write, Code, Break, Fix! Copy Section

• Documentarians: Love making complex stuff sound easy? Our docs are your canvas. Paint away in words! 🎨

• Code Ninjas: Find bugs? Squash 'em. Got ideas? Code 'em. Make pull requests rain! 🥷

• Bug Hunters: If you find bugs, don't just stare. Let us know. We love a good bug hunt. 🐛

The Bottom Line Copy Section

We built this site with Sanic to show off what it can do. It's fast, it's fun, and it's what we use. So, if things load swiftly, pat us on the back. If they don't, well, uh... we blame cosmic rays?

Join us in making Sanic not just good, but "I-can't-believe-it's-not-butter" good!

Cheers,
The Sanic Team (who occasionally wear capes)

Guide Content En Help (`guide/content/en/help.md`) Copy Section

title: Need some help? layout: main Copy Chapter

Need some help?

As an active community of developers, we try to support each other. If you need some help, try one of the following:

.. column::

### Discord 💬

Best place to turn for quick answers and live chat

`#sanic-support` channel on the [Discord server](https://discord.gg/FARQzAEMAA)

.. column::

### Community Forums 👥

Good for sharing snippets of code and longer support queries

`Questions and Help` category on the [Forums](https://community.sanicframework.org/c/questions-and-help/6)

We also actively monitor the [sanic] tag on Stack Overflow.

Guide Public Web Robots (`guide/public/web/robots.txt`) Copy Section

User-agent: *
Allow: /
Sitemap: https://sanic.dev/sitemap.xml
Host: https://sanic.dev

Sanic Releases 21 21.12 (`docs/sanic/releases/21/21.12.md`) Copy Section

Version 21.12.1 🔷 Copy Chapter

Current LTS version

• #2349 Only display MOTD on startup
• #2354 Ignore name argument in Python 3.7
• #2355 Add config.update support for all config values

Version 21.12.0 🔹 Copy Chapter

Features Copy Section

• #2260 Allow early Blueprint registrations to still apply later added objects
• #2262 Noisy exceptions - force logging of all exceptions
• #2264 Optional uvloop by configuration
• #2270 Vhost support using multiple TLS certificates
• #2277 Change signal routing for increased consistency
  • BREAKING CHANGE: If you were manually routing signals there is a breaking change. The signal router's get is no longer 100% determinative. There is now an additional step to loop thru the returned signals for proper matching on the requirements. If signals are being dispatched using app.dispatch or bp.dispatch, there is no change.
• #2290 Add contextual exceptions
• #2291 Increase join concat performance
• #2295, #2316, #2331 Restructure of CLI and application state with new displays and more command parity with app.run
• #2302 Add route context at definition time
• #2304 Named tasks and new API for managing background tasks
• #2307 On app auto-reload, provide insight of changed files
• #2308 Auto extend application with Sanic Extensions if it is installed, and provide first class support for accessing the extensions
• #2309 Builtin signals changed to Enum
• #2313 Support additional config implementation use case
• #2321 Refactor environment variable hydration logic
• #2327 Prevent sending multiple or mixed responses on a single request
• #2330 Custom type casting on environment variables
• #2332 Make all deprecation notices consistent
• #2335 Allow underscore to start instance names

Bugfixes Copy Section

• #2273 Replace assignation by typing for websocket_handshake
• #2285 Fix IPv6 display in startup logs
• #2299 Dispatch http.lifecyle.response from exception handler

Deprecations and Removals Copy Section

• #2306 Removal of deprecated items
  • Sanic and Blueprint may no longer have arbitrary properties attached to them
  • Sanic and Blueprint forced to have compliant names
    • alphanumeric + _ + -
    • must start with letter or _
  • load_env keyword argument of Sanic
  • sanic.exceptions.abort
  • sanic.views.CompositionView
  • sanic.response.StreamingHTTPResponse
    • NOTE: the stream() response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https://sanicframework.org/en/guide/advanced/streaming.html#response-streaming
• #2320 Remove app instance from Config for error handler setting

Developer infrastructure Copy Section

• #2251 Change dev install command
• #2286 Change codeclimate complexity threshold from 5 to 10
• #2287 Update host test function names so they are not overwritten
• #2292 Fail CI on error
• #2311, #2324 Do not run tests for draft PRs
• #2336 Remove paths from coverage checks
• #2338 Cleanup ports on tests

Improved Documentation Copy Section

• #2269, #2329, #2333 Cleanup typos and fix language

Miscellaneous Copy Section

• #2257, #2294, #2341 Add Python 3.10 support
• #2279, #2317, #2322 Add/correct missing type annotations
• #2305 Fix examples to use modern implementations

Sanic Releases 21 21.9 (`docs/sanic/releases/21/21.9.md`) Copy Section

Version 21.9.3 Copy Chapter

Rerelease of v21.9.2 with some cleanup

Version 21.9.2 Copy Chapter

• #2268 Make HTTP connections start in IDLE stage, avoiding delays and error messages
• #2310 More consistent config setting with post-FALLBACK_ERROR_FORMAT apply

Version 21.9.1 Copy Chapter

• #2259 Allow non-conforming ErrorHandlers

Version 21.9.0 Copy Chapter

Features Copy Section

• #2158, #2248 Complete overhaul of I/O to websockets
• #2160 Add new 17 signals into server and request lifecycles
• #2162 Smarter auto fallback formatting upon exception
• #2184 Introduce implementation for copying a Blueprint
• #2200 Accept header parsing
• #2207 Log remote address if available
• #2209 Add convenience methods to BP groups
• #2216 Add default messages to SanicExceptions
• #2225 Type annotation convenience for annotated handlers with path parameters
• #2236 Allow Falsey (but not-None) responses from route handlers
• #2238 Add exception decorator to Blueprint Groups
• #2244 Explicit static directive for serving file or dir (ex: static(..., resource_type="file"))
• #2245 Close HTTP loop when connection task cancelled

Bugfixes Copy Section

• #2188 Fix the handling of the end of a chunked request
• #2195 Resolve unexpected error handling on static requests
• #2208 Make blueprint-based exceptions attach and trigger in a more intuitive manner
• #2211 Fixed for handling exceptions of asgi app call
• #2213 Fix bug where ws exceptions not being logged
• #2231 Cleaner closing of tasks by using abort() in strategic places to avoid dangling sockets
• #2247 Fix logging of auto-reload status in debug mode
• #2246 Account for BP with exception handler but no routes

Developer infrastructure Copy Section

• #2194 HTTP unit tests with raw client
• #2199 Switch to codeclimate
• #2214 Try Reopening Windows Tests
• #2229 Refactor HttpProtocol into a base class
• #2230 Refactor server.py into multi-file module

Miscellaneous Copy Section

• #2173 Remove Duplicated Dependencies and PEP 517 Support
• #2193, #2196, #2217 Type annotation changes

Sanic Releases 22 22.12 (`docs/sanic/releases/22/22.12.md`) Copy Section

Version 22.12.0 🔷 Copy Chapter

Current version

Features Copy Section

• #2569 Add JSONResponse class with some convenient methods when updating a response object
• #2598 Change uvloop requirement to >=0.15.0
• #2609 Add compatibility with websockets v11.0
• #2610 Kill server early on worker error
  • Raise deadlock timeout to 30s
• #2617 Scale number of running server workers
• #2621 #2634 Send SIGKILL on subsequent ctrl+c to force worker exit
• #2622 Add API to restart all workers from the multiplexer
• #2624 Default to spawn for all subprocesses unless specifically set:
  python Copy

  from sanic import Sanic
  
  Sanic.start_method = "fork"

• #2625 Filename normalisation of form-data/multipart file uploads
• #2626 Move to HTTP Inspector:
  • Remote access to inspect running Sanic instances
  • TLS support for encrypted calls to Inspector
  • Authentication to Inspector with API key
  • Ability to extend Inspector with custom commands
• #2632 Control order of restart operations
• #2633 Move reload interval to class variable
• #2636 Add priority to register_middleware method
• #2639 Add unquote to add_route method
• #2640 ASGI websockets to receive text or bytes

Bugfixes Copy Section

• #2607 Force socket shutdown before close to allow rebinding
• #2590 Use actual StrEnum in Python 3.11+
• #2615 Ensure middleware executes only once per request timeout
• #2627 Crash ASGI application on lifespan failure
• #2635 Resolve error with low-level server creation on Windows

Deprecations and Removals Copy Section

• #2608 #2630 Signal conditions and triggers saved on signal.extra
• #2626 Move to HTTP Inspector
  • 🚨 BREAKING CHANGE: Moves the Inspector to a Sanic app from a simple TCP socket with a custom protocol
  • DEPRECATE: The --inspect* commands have been deprecated in favor of inspect ... commands
• #2628 Replace deprecated distutils.strtobool

Developer infrastructure Copy Section

• #2612 Add CI testing for Python 3.11

Sanic Releases 22 22.3 (`docs/sanic/releases/22/22.3.md`) Copy Section

Version 22.3.0 Copy Chapter

Features Copy Section

• #2347 API for multi-application server
  • 🚨 BREAKING CHANGE: The old sanic.worker.GunicornWorker has been removed. To run Sanic with gunicorn, you should use it thru uvicorn as described in their docs.
  • 🧁 SIDE EFFECT: Named background tasks are now supported, even in Python 3.7
• #2357 Parse Authorization header as Request.credentials
• #2361 Add config option to skip Touchup step in application startup
• #2372 Updates to CLI help messaging
• #2382 Downgrade warnings to backwater debug messages
• #2396 Allow for multidict v0.6
• #2401 Upgrade CLI catching for alternative application run types
• #2402 Conditionally inject CLI arguments into factory
• #2413 Add new start and stop event listeners to reloader process
• #2414 Remove loop as required listener arg
• #2415 Better exception for bad URL parsing
• sanic-routing#47 Add a new extention parameter type: <file:ext>, <file:ext=jpg>, <file:ext=jpg|png|gif|svg>, <file=int:ext>, <file=int:ext=jpg|png|gif|svg>, <file=float:ext=tar.gz>
  • 👶 BETA FEATURE: This feature will not work with path type matching, and is being released as a beta feature only.
• sanic-routing#57 Change register_pattern to accept a str or Pattern
• sanic-routing#58 Default matching on non-empty strings only, and new strorempty pattern type
  • 🚨 BREAKING CHANGE: Previously a route with a dynamic string parameter (/<foo> or /<foo:str>) would match on any string, including empty strings. It will now only match a non-empty string. To retain the old behavior, you should use the new parameter type: /<foo:strorempty>.

Bugfixes Copy Section

• #2373 Remove error_logger on websockets
• #2381 Fix newly assigned None in task registry
• sanic-routing#52 Add type casting to regex route matching
• sanic-routing#60 Add requirements check on regex routes (this resolves, for example, multiple static directories with differing host values)

Deprecations and Removals Copy Section

• #2362 22.3 Deprecations and changes
  1. debug=True and --debug do NOT automatically run auto_reload
  2. Default error render is with plain text (browsers still get HTML by default because auto looks at headers)
  3. config is required for ErrorHandler.finalize
  4. ErrorHandler.lookup requires two positional args
  5. Unused websocket protocol args removed
• #2344 Deprecate loading of lowercase environment variables

Developer infrastructure Copy Section

• #2363 Revert code coverage back to Codecov
• #2405 Upgrade tests for sanic-routing changes
• sanic-testing#35 Allow for httpx v0.22

Improved Documentation Copy Section

• #2350 Fix link in README for ASGI
• #2398 Document middleware on_request and on_response
• #2409 Add missing documentation for Request.respond

Miscellaneous Copy Section

• #2376 Fix typing for ListenerMixin.listener
• #2383 Clear deprecation warning in asyncio.wait
• #2387 Cleanup __slots__ implementations
• #2390 Clear deprecation warning in asyncio.get_event_loop

Sanic Releases 22 22.6 (`docs/sanic/releases/22/22.6.md`) Copy Section

Version 22.6.2 Copy Chapter

Bugfixes Copy Section

• #2522 Always show server location in ASGI

Version 22.6.1 Copy Chapter

Bugfixes Copy Section

• #2477 Sanic static directory fails when folder name ends with ".."

Version 22.6.0 Copy Chapter

Features Copy Section

• #2378 Introduce HTTP/3 and autogeneration of TLS certificates in DEBUG mode
  • 👶 EARLY RELEASE FEATURE: Serving Sanic over HTTP/3 is an early release feature. It does not yet fully cover the HTTP/3 spec, but instead aims for feature parity with Sanic's existing HTTP/1.1 server. Websockets, WebTransport, push responses are examples of some features not yet implemented.
  • 📦 EXTRA REQUIREMENT: Not all HTTP clients are capable of interfacing with HTTP/3 servers. You may need to install a HTTP/3 capable client.
  • 📦 EXTRA REQUIREMENT: In order to use TLS autogeneration, you must install either mkcert or trustme.
• #2416 Add message to task.cancel
• #2420 Add exception aliases for more consistent naming with standard HTTP response types (BadRequest, MethodNotAllowed, RangeNotSatisfiable)
• #2432 Expose ASGI scope as a property on the Request object
• #2438 Easier access to websocket class for annotation: from sanic import Websocket
• #2439 New API for reading form values with options: Request.get_form
• #2445 Add custom loads function
• #2447, #2486 Improved API to support setting cache control headers
• #2453 Move verbosity filtering to logger
• #2475 Expose getter for current request using Request.get_current()

Bugfixes Copy Section

• #2448 Fix to allow running with pythonw.exe or places where there is no sys.stdout
• #2451 Trigger http.lifecycle.request signal in ASGI mode
• #2455 Resolve typing of stacked route definitions
• #2463 Properly catch websocket CancelledError in websocket handler in Python 3.7

Deprecations and Removals Copy Section

• #2487 v22.6 deprecations and changes
  1. Optional application registry
  2. Execution of custom handlers after some part of response was sent
  3. Configuring fallback handlers on the ErrorHandler
  4. Custom LOGO setting
  5. sanic.response.stream
  6. AsyncioServer.init

Developer infrastructure Copy Section

• #2449 Clean up black and isort config
• #2479 Fix some flappy tests

Improved Documentation Copy Section

• #2461 Update example to match current application naming standards
• #2466 Better type annotation for Extend
• #2485 Improved help messages in CLI

Sanic Releases 22 22.9 (`docs/sanic/releases/22/22.9.md`) Copy Section

Version 22.9.1 Copy Chapter

Features Copy Section

• #2585 Improved error message when no applications have been registered

Bugfixes Copy Section

• #2578 Add certificate loader for in process certificate creation
• #2591 Do not use sentinel identity for spawn compatibility
• #2592 Fix properties in nested blueprint groups
• #2595 Introduce sleep interval on new worker reloader

Deprecations and Removals Copy Section

Developer infrastructure Copy Section

• #2588 Markdown templates on issue forms

Improved Documentation Copy Section

• #2556 v22.9 documentation
• #2582 Cleanup documentation on Windows support

Version 22.9.0 Copy Chapter

Features Copy Section

• #2445 Add custom loads function
• #2490 Make WebsocketImplProtocol async iterable
• #2499 Sanic Server WorkerManager refactor
• #2506 Use pathlib for path resolution (for static file serving)
• #2508 Use path.parts instead of match (for static file serving)
• #2513 Better request cancel handling
• #2516 Add request properties for HTTP method info:
  • request.is_safe
  • request.is_idempotent
  • request.is_cacheable
  • See MDN docs for more information about when these apply
• #2522 Always show server location in ASGI
• #2526 Cache control support for static files for returning 304 when appropriate
• #2533 Refactor _static_request_handler
• #2540 Add signals before and after handler execution
  • http.handler.before
  • http.handler.after
• #2542 Add [redacted] to CLI :)
• #2546 Add deprecation warning filter
• #2550 Middleware priority and performance enhancements

Bugfixes Copy Section

• #2495 Prevent directory traversion with static files
• #2515 Do not apply double slash to paths in certain static dirs in Blueprints

Deprecations and Removals Copy Section

• #2525 Warn on duplicate route names, will be prevented outright in v23.3
• #2537 Raise warning and deprecation notice on duplicate exceptions, will be prevented outright in v23.3

Developer infrastructure Copy Section

• #2504 Cleanup test suite
• #2505 Replace Unsupported Python Version Number from the Contributing Doc
• #2530 Do not include tests folder in installed package resolver

Improved Documentation Copy Section

• #2502 Fix a few typos
• #2517 #2536 Add some type hints

Sanic Releases 23 23.3 (`docs/sanic/releases/23/23.3.md`) Copy Section

Version 23.3.0 Copy Chapter

Features Copy Section

• #2545 Standardize init of exceptions for more consistent control of HTTP responses using exceptions

• #2606 Decode headers as UTF-8 also in ASGI

• #2646 Separate ASGI request and lifespan callables

• #2659 Use FALLBACK_ERROR_FORMAT for handlers that return empty()

• #2662 Add basic file browser (HTML page) and auto-index serving

• #2667 Nicer traceback formatting (HTML page)

• #2668 Smarter error page rendering format selection; more reliant upon header and "common sense" defaults

• #2680 Check the status of socket before shutting down with SHUT_RDWR

• #2687 Refresh Request.accept functionality to be more performant and spec-compliant

• #2696 Add header accessors as properties

  text Copy

  Example-Field: Foo, Bar
  Example-Field: Baz

  python Copy

  request.headers.example_field == "Foo, Bar,Baz"

• #2700 Simpler CLI targets

  sh Copy

  $ sanic path.to.module:app          # global app instance
  $ sanic path.to.module:create_app   # factory pattern
  $ sanic ./path/to/directory/        # simple serve

• #2701 API to define a number of workers in managed processes

• #2704 Add convenience for dynamic changes to routing

• #2706 Add convenience methods for cookie creation and deletion

  python Copy

  response = text("...")
  response.add_cookie("test", "It worked!", domain=".yummy-yummy-cookie.com")

• #2707 Simplified parse_content_header escaping to be RFC-compliant and remove outdated FF hack

• #2710 Stricter charset handling and escaping of request URLs

• #2711 Consume body on DELETE by default

• #2719 Allow password to be passed to TLS context

• #2720 Skip middleware on RequestCancelled

• #2721 Change access logging format to %s

• #2722 Add CertLoader as application option for directly controlling SSLContext objects

• #2725 Worker sync state tolerance on race condition

Bugfixes Copy Section

• #2651 ASGI websocket to pass thru bytes as is
• #2697 Fix comparison between datetime aware and naive in file when using If-Modified-Since

Deprecations and Removals Copy Section

• #2666 Remove deprecated __blueprintname__ property

Improved Documentation Copy Section

• #2712 Improved example using 'https' to create the redirect

Sanic Releases 23 23.6 (`docs/sanic/releases/23/23.6.md`) Copy Section

Version 23.6.0 🔶 Copy Chapter

Features Copy Section

• #2670 Increase KEEP_ALIVE_TIMEOUT default to 120 seconds
• #2716 Adding allow route overwrite option in blueprint
• #2724 and #2792 Add a new exception signal for ALL exceptions raised anywhere in application
• #2727 Add name prefixing to BP groups
• #2754 Update request type on middleware types
• #2770 Better exception message on startup time application induced import error
• #2776 Set multiprocessing start method early
• #2785 Add custom typing to config and ctx objects
• #2790 Add request.client_ip

Bugfixes Copy Section

• #2728 Fix traversals for intended results
• #2729 Handle case when headers argument of ResponseStream constructor is None
• #2737 Fix type annotation for JSONREsponse default content type
• #2740 Use Sanic's serializer for JSON responses in the Inspector
• #2760 Support for Request.get_current in ASGI mode
• #2773 Alow Blueprint routes to explicitly define error_format
• #2774 Resolve headers on different renderers
• #2782 Resolve pypy compatibility issues

Deprecations and Removals Copy Section

• #2777 Remove Python 3.7 support

Developer infrastructure Copy Section

• #2766 Unpin setuptools version
• #2779 Run keep alive tests in loop to get available port

Improved Documentation Copy Section

• #2741 Better documentation examples about running Sanic
  From that list, the items to highlight in the release notes:

Guide Content En Guide Introduction (`guide/content/en/guide/introduction.md`) Copy Section

Introduction

Sanic is a Python 3.10+ web server and web framework that's written to go fast. It allows the usage of the async/await syntax added in Python 3.5, which makes your code non-blocking and speedy.

.. attrs::
:class: introduction-table

|  |  |
|--|--|
| Build    | [](https://github.com/sanic-org/sanic/actions/workflows/tests.yml) |
| Docs     | [](https://sanicframework.org/) [](http://sanic.readthedocs.io/en/latest/?badge=latest) |
| Package  | [](https://pypi.python.org/pypi/sanic/) [](https://pypi.python.org/pypi/sanic/) [](https://pypi.python.org/pypi/sanic) [](https://pypi.python.org/pypi/sanic) [](https://github.com/ambv/black) |
| Support  | [](https://community.sanicframework.org/) [](https://discord.gg/FARQzAEMAA) [](https://github.com/mekicha/awesome-sanic) |
| Stats    | [](https://pepy.tech/project/sanic) [](https://pepy.tech/project/sanic) [](https://anaconda.org/conda-forge/sanic) |

What is it? Copy Chapter

First things first, before you jump in the water, you should know that Sanic is different than other frameworks.

Right there in that first sentence there is a huge mistake because Sanic is both a framework and a web server. In the deployment section we will talk a little bit more about this.

But, remember, out of the box Sanic comes with everything you need to write, deploy, and scale a production grade web application. 🚀

Goal Copy Chapter

To provide a simple way to get up and running a highly performant HTTP server that is easy to build, to expand, and ultimately to scale.

Features Copy Chapter

.. column::

### Core

- Built in, **_fast_** web server
- Production ready
- Highly scalable
- ASGI compliant
- Simple and intuitive API design
- By the community, for the community

.. column::

### Sanic Extensions [[learn more](../plugins/sanic-ext/getting-started.md)]

- CORS protection
- Template rendering with Jinja
- Dependency injection into route handlers
- OpenAPI documentation with Redoc and/or Swagger
- Predefined, endpoint-specific response serializers
- Request query arguments and body input validation
- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints

Sponsor Copy Chapter

Check out open collective to learn more about helping to fund Sanic.

Join the Community Copy Chapter

The main channel for discussion is at the community forums. There also is a Discord Server for live discussion and chat.

The Stackoverflow [sanic] tag is actively monitored by project maintainers.

Contribution Copy Chapter

We are always happy to have new contributions. We have marked issues good for anyone looking to get started, and welcome questions/answers/discussion on the forums. Please take a look at our Contribution guidelines.

Guide Content En Organization Code Of Conduct (`guide/content/en/organization/code-of-conduct.md`) Copy Section

Contributor Covenant Code of Conduct

Our Pledge Copy Chapter

In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.

Our Standards Copy Chapter

Examples of behavior that contributes to creating a positive environment
include:

• Using welcoming and inclusive language
• Being respectful of differing viewpoints and experiences
• Gracefully accepting constructive criticism
• Focusing on what is best for the community
• Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

• The use of sexualized language or imagery and unwelcome sexual attention or
  advances
• Trolling, insulting/derogatory comments, and personal or political attacks
• Public or private harassment
• Publishing others' private information, such as a physical or electronic
  address, without explicit permission
• Other conduct which could reasonably be considered inappropriate in a
  professional setting

Our Responsibilities Copy Chapter

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

Scope Copy Chapter

This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.

Enforcement Copy Chapter

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at [email protected]. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.

Attribution Copy Chapter

This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
available at http://contributor-covenant.org/version/1/4

Guide Content En Organization Contributing (`guide/content/en/organization/contributing.md`) Copy Section

Contributing

Thank you for your interest! Sanic is always looking for contributors. If you don't feel comfortable contributing code, adding docstrings to the source files, or helping with the Sanic User Guide by providing documentation or implementation examples would be appreciated!

We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic. Our code of conduct sets the standards for behavior.

Installation Copy Chapter

To develop on Sanic (and mainly to just run the tests) it is highly recommend to install from sources.

So assume you have already cloned the repo and are in the working directory with a virtual environment already set up, then run:

pip install -e ".[dev]"

Dependency Changes Copy Chapter

Sanic doesn't use requirements*.txt files to manage any kind of dependencies related to it in order to simplify the effort required in managing the dependencies. Please make sure you have read and understood the following section of the document that explains the way sanic manages dependencies inside the setup.py file.

Running all tests Copy Chapter

To run the tests for Sanic it is recommended to use tox like so:

tox

See it's that simple!

tox.ini contains different environments. Running tox without any arguments will
run all unittests, perform lint and other checks.

Run unittests Copy Chapter

tox environment -> [testenv]

To execute only unittests, run tox with environment like so:

tox -e py37 -v -- tests/test_config.py
# or
tox -e py310 -v -- tests/test_config.py

Run lint checks Copy Chapter

tox environment -> [testenv:lint]

Permform flake8\ , black and isort checks.

tox -e lint

Run type annotation checks Copy Chapter

tox environment -> [testenv:type-checking]

Permform mypy checks.

tox -e type-checking

Run other checks Copy Chapter

tox environment -> [testenv:check]

Perform other checks.

tox -e check

Run Static Analysis Copy Chapter

tox environment -> [testenv:security]

Perform static analysis security scan

tox -e security

Run Documentation sanity check Copy Chapter

tox environment -> [testenv:docs]

Perform sanity check on documentation

tox -e docs

Code Style Copy Chapter

To maintain the code consistency, Sanic uses the following tools:

1. isort
2. black
3. flake8
4. slotscheck

isort Copy Section

isort sorts Python imports. It divides imports into three categories sorted each in alphabetical order:

1. built-in
2. third-party
3. project-specific

black Copy Section

black is a Python code formatter.

flake8 Copy Section

flake8 is a Python style guide that wraps the following tools into one:

1. PyFlakes
2. pycodestyle
3. Ned Batchelder's McCabe script

slotscheck Copy Section

slotscheck ensures that there are no problems with __slots__ (e.g., overlaps, or missing slots in base classes).

isort, black, flake8, and slotscheck checks are performed during tox lint checks.

The easiest way to make your code conform is to run the following before committing:

make pretty

Refer to tox documentation for more details.

Pull requests Copy Chapter

So the pull request approval rules are pretty simple:

1. All pull requests must pass unit tests.
2. All pull requests must be reviewed and approved by at least one current member of the Core Developer team.
3. All pull requests must pass flake8 checks.
4. All pull requests must match isort and black requirements.
5. All pull requests must be PROPERLY type annotated, unless exemption is given.
6. All pull requests must be consistent with the existing code.
7. If you decide to remove/change anything from any common interface a deprecation message should accompany it in accordance with our deprecation policy.
8. If you implement a new feature you should have at least one unit test to accompany it.
9. An example must be one of the following:
   • Example of how to use Sanic
   • Example of how to use Sanic extensions
   • Example of how to use Sanic and asynchronous library

Documentation Copy Chapter

Check back. We are reworking our documentation so this will change.

Guide Content En Organization Policies (`guide/content/en/organization/policies.md`) Copy Section

Policies

Versioning Copy Chapter

Sanic uses calendar versioning, aka "calver". To be more specific, the pattern follows:

YY.MM.MICRO

Generally, versions are referred to in their YY.MM form. The MICRO number indicates an incremental patch version, starting at 0.

Reporting a Vulnerability Copy Chapter

If you discover a security vulnerability, we ask that you do not create an issue on GitHub. Instead, please send a message to the core-devs on the community forums. Once logged in, you can send a message to the core-devs by clicking the message button.

Alternatively, you can send a private message to Adam Hopkins on Discord. Find him on the Sanic discord server.

This will help to not publicize the issue until the team can address it and resolve it.

Release Schedule Copy Chapter

There are four (4) scheduled releases per year: March, June, September, and December. Therefore, there are four (4) released versions per year: YY.3, YY.6, YY.9, and YY.12.

This release schedule provides:

• a predictable release cadence,
• relatively short development windows allowing features to be regularly released,
• controlled deprecations, and
• consistent stability with a yearly LTS.

We also use the yearly release cycle in conjunction with our governance model, covered by the S.C.O.P.E.

Long term support v Interim releases Copy Section

Sanic releases a long term support release (aka "LTS") once a year in December. The LTS releases receive bug fixes and security updates for 24 months. Interim releases throughout the year occur every three months, and are supported until the subsequent release.

☑️ = security fixes
✅ = full support
⚪ = no support

Deprecation Copy Chapter

Before a feature is deprecated, or breaking changes are introduced into the API, it shall be publicized and shall appear with deprecation warnings through two release cycles. No deprecations shall be made in an LTS release.

Breaking changes or feature removal may happen outside of these guidelines when absolutely warranted. These circumstances should be rare. For example, it might happen when no alternative is available to curtail a major security issue.

Guide Content En Organization Scope (`guide/content/en/organization/scope.md`) Copy Section

Sanic Community Organization Policy E-manual (SCOPE)

.. attrs::
:class: is-size-7

_December 2019, version 1_

Goals Copy Chapter

To create a sustainable, community-driven organization around the Sanic projects that promote: (1) stability and predictability, (2) quick iteration and enhancement cycles, (3) engagement from outside contributors, (4) overall reliable software, and (5) a safe, rewarding environment for the community members.

Overview Copy Chapter

This Policy is the governance model for the Sanic Community Organization (“SCO”). The SCO is a meritocratic, consensus-based community organization responsible for all projects adopted by it. Anyone with an interest in one of the projects can join the community, contribute to the community or projects, and participate in the decision making process. This document describes how that participation takes place and how to set about earning merit within the project community.

Structure Copy Chapter

The SCO has multiple projects. Each project is represented by a single GitHub repository under the Sanic community umbrella. These projects are used by users, developed by contributors, governed by core developers, released by release managers, and ultimately overseen by a steering council. If this sounds similar to the Python project and PEP 8016 that is because it is intentionally designed that way.

Roles and responsibilities Copy Chapter

Users Copy Section

Users are community members who have a need for the projects. They are the developers and personnel that download and install the packages. Users are the most important members of the community and without them the projects would have no purpose. Anyone can be a user and the licenses adopted by the projects shall be appropriate open source licenses.

The SCO asks its users to participate in the project and community as much as possible.

User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user contributions include (but are not limited to):

• evangelizing about the project (e.g. a link on a website and word-of-mouth awareness raising)
• informing developers of strengths and weaknesses from a new user perspective
• providing moral support (a ‘thank you’ goes a long way)
• providing financial support (the software is open source, but its developers need to eat)

Users who continue to engage with the SCO, its projects, and its community will often become more and more involved. Such users may find themselves becoming contributors, as described in the next section.

Contributors Copy Section

Contributors are community members who contribute in concrete ways to one or more of the projects. Anyone can become a contributor and contributions can take many forms. Contributions and requirements are governed by each project separately by a contribution policy.

There is no expectation of commitment to the project, no specific skill requirements and no selection process.

In addition to their actions as users, contributors may also find themselves doing one or more of the following:

• supporting new users (existing users are often the best people to support new users)
• reporting bugs
• identifying requirements
• providing graphics and web design
• Programming
• example use cases
• assisting with project infrastructure
• writing documentation
• fixing bugs
• adding features
• providing constructive opinions and engaging in community discourse

Contributors engage with the projects through GitHub and the Community Forums. They submit changes to the projects itself via pull requests, which will be considered for inclusion in the project by the community at large. The Community Forums are the most appropriate place to ask for help when making that first contribution.

Indeed one of the most important roles of a contributor may be to simply engage in the community conversation. Most decisions about the direction of a project are made by consensus. This is discussed in more detail below. In general, however, it is helpful for the health and direction of the projects for the contributors to speak freely (within the confines of the code of conduct) and express their opinions and experiences to help drive the consensus building.

As contributors gain experience and familiarity with a project, their profile within, and commitment to, the community will increase. At some stage, they may find themselves being nominated for a core developer team.

Core Developer Copy Section

Each project under the SCO umbrella has its own team of core developers. They are the people in charge of that project.

What is a core developer?

Core developers are community members who have shown that they are committed to the continued development of the project through ongoing engagement with the community. Being a core developer allows contributors to more easily carry on with their project related activities by giving them direct access to the project’s resources. They can make changes directly to the project repository without having to submit changes via pull requests from a fork.

This does not mean that a core developer is free to do what they want. In fact, core developers have no more direct authority over the final release of a package than do contributors. While this honor does indicate a valued member of the community who has demonstrated a healthy respect for the project’s aims and objectives, their work continues to be reviewed by the community before acceptance in an official release.

What can a core developer do on a project?

Each project might define this role slightly differently. However, the general usage of this designation is that an individual has risen to a level of trust within the community such that they now are given some control. This comes in the form of push rights to non-protected branches, and the ability to have a voice in the approval of pull requests.

The projects employ various communication mechanisms to ensure that all contributions are reviewed by the community as a whole. This includes tools provided by GitHub, as well as the Community Forums. By the time a contributor is invited to become a core developer, they should be familiar with the various tools and workflows as a user and then as a contributor.

How to become a core developer?

Anyone can become a core developer; there are no special requirements, other than to have shown a willingness and ability to positively participate in the project as a team player.

Typically, a potential core developer will need to show that they have an understanding of the project, its objectives and its strategy. They will also have provided valuable contributions to the project over a period of time. However, there is no technical or other skill requirement for eligibility.

New core developers can be nominated by any existing core developer at any time. At least twice a year (April and October) there will be a ballot process run by the Steering Council. Voting should be done by secret ballot. Each existing core developer for that project receives a number of votes equivalent to the number of nominees on the ballot. For example, if there are four nominees, then each existing core developer has four votes. The core developer may cast those votes however they choose, but may not vote for a single nominee more than once. A nominee must receive two-thirds approval from the number of cast ballots (not the number of eligible ballots). Once accepted by the core developers, it is the responsibility of the Steering Council to approve and finalize the nomination. The Steering Council does not have the right to determine whether a nominee is meritorious enough to receive the core developer title. However, they do retain the right to override a vote in cases where the health of the community would so require.

Once the vote has been held, the aggregated voting results are published on the Community Forums. The nominee is entitled to request an explanation of any override against them. A nominee that fails to be admitted as a core developer may be nominated again in the future.

It is important to recognize that being a core developer is a privilege, not a right. That privilege must be earned and once earned it can be removed by the Steering Council (see next section) in extreme circumstances. However, under normal circumstances the core developer title exists for as long as the individual wishes to continue engaging with the project and community.

A committer who shows an above-average level of contribution to the project, particularly with respect to its strategic direction and long-term health, may be nominated to become a member of the Steering Council, or a Release Manager. This role is described below.

What are the rights and responsibilities of core developers?

As discussed, the majority of decisions to be made are by consensus building. In certain circumstances where an issue has become more contentious, or a major decision needs to be made, the Release Manager or Steering Council may decide (or be required) to implement the RFC process, which is outlined in more detail below.

It is also incumbent upon core developers to have a voice in the governance of the community. All core developers for all of the projects have the ability to be nominated to be on the Steering Council and vote in their elections.

This Policy (the “SCOPE”) may only be changed under the authority of two-thirds of active core developers, except that in the first six (6) months after adoption, the core developers reserve the right to make changes under the authority of a simple majority of active core developers.

What if a core developer becomes inactive?

It is hoped that all core developers participate and remain active on a regular basis in their projects. However, it is also understood that such commitments may not be realistic or possible from time to time.

Therefore, the Steering Council has the duty to encourage participation and the responsibility to place core developers into an inactive status if they are no longer willing or capable to participate. The main purpose of this is not to punish a person for behavior, but to help the development process to continue for those that do remain active.

To this end, a core developer that becomes “inactive” shall not have commit rights to a repository, and shall not participate in any votes. To be eligible to vote in an election, a core developer must have been active at the time of the previous scheduled project release.

Inactive members may ask the Steering Council to reinstate their status at any time, and upon such request the Steering Council shall make the core developer active again.

Individuals that know they will be unable to maintain their active status for a period are asked to be in communication with the Steering Council and declare themselves inactive if necessary.

An “active” core developer is an individual that has participated in a meaningful way during the previous six months. Any further definition is within the discretion of the Steering Council.

Release Manager Copy Section

Core developers shall have access only to make commits and merges on non-protected branches. The “master” branch and other protected branches are controlled by the release management team for that project. Release managers shall be elected from the core development team by the core development team, and shall serve for a full release cycle.

Each core developer team may decide how many release managers to have for each release cycle. It is highly encouraged that there be at least two release managers for a release cycle to help divide the responsibilities and not force too much effort upon a single person. However, there also should not be so many managers that their efforts are impeded.

The main responsibilities of the release management team include:

• push the development cycle forward by monitoring and facilitating technical discussions
• establish a release calendar and perform actions required to release packages
• approve pull requests to the master branch and other protected branches
• merge pull requests to the master branch and other protected branches

The release managers do not have the authority to veto or withhold a merge of a pull request that otherwise meets contribution criteria and has been accepted by the community. It is not their responsibility to decide what should be developed, but rather that the decisions of the community are carried out and that the project is being moved forward.

From time to time, a decision may need to be made that cannot be achieved through consensus. In that case, the release managers have the authority to call upon the removal of the decision to the RFC process. This should not occur regularly (unless required as discussed below), and its use should be discouraged in favor of the more communal consensus building strategy.

Since not all projects have the same requirements, the specifics governing release managers on a project shall be set forth in an Appendix to this Policy, or in the project’s contribution guidelines.

If necessary, the Steering Council has the right to remove a release manager that is derelict in their duties, or for other good cause.

Steering Council Copy Section

The Steering Council is the governing body consisting of those individuals identified as the “project owner” and having control of the resources and assets of the SCO. Their ultimate goal is to ensure the smooth operation of the projects by removing impediments, and assisting the members as needed. It is expected that they will be regular voices in the community.

What can the Steering Council do?

The members of the Steering Council do not individually have any more authority than any other core developer, and shall not have any additional rights to make decisions, commits, merges, or the like on a project.

However, as a body, the Steering Council has the following capacity:

• accept, remand, and reject all RFCs
• enforce the community code of conduct
• administer community assets such as repositories, servers, forums, integration services, and the like (or, to delegate such authority to someone else)
• place core developers into inactive status where appropriate take any other enforcement measures afforded to it in this Policy, including, in extreme cases, removing core developers
• adopt or remove projects from the community umbrella

It is highly encouraged that the Steering Council delegate its authority as much as possible, and where appropriate, to other willing community members.

The Steering Council does not have the authority to change this Policy.

How many members are on the Steering Council?

Four.

While it seems like a committee with four votes may potentially end in a deadlock with no way to break a majority vote, the Steering Council is discouraged from voting as much as possible. Instead, it should try to work by consensus, and requires three consenting votes when it is necessary to vote on a matter.

How long do members serve on the Steering Council?

A single term shall be for two calendar years starting in January. Terms shall be staggered so that each year there are two members continuing from the previous year’s council.

Therefore, the inaugural vote shall have two positions available for a two year term, and two positions available for a one year term.

There are no limits to the number of terms that can be served, and it is possible for an individual to serve consecutive terms.

Who runs the Steering Council?

After the Steering Council is elected, the group shall collectively decide upon one person to act as the Chair. The Chair does not have any additional rights or authority over any other member of the Steering Council.

The role of the Chair is merely as a coordinator and facilitator. The Chair is expected to ensure that all governance processes are adhered to. The position is more administrative and clerical, and is expected that the Chair sets agendas and coordinates discussion of the group.

How are council members elected?

Once a year, all eligible core developers for each of the projects shall have the right to elect members to the Steering Council.

Nominations shall be open from September 1 and shall close on September 30. After that, voting shall begin on October 1 and shall close on October 31. Every core developer active on the date of the June release of the Sanic Framework for that year shall be eligible to receive one vote per vacant seat on the Steering Council. For the sake of clarity, to be eligible to vote, a core developer does not need to be a core developer on Sanic Framework, but rather just have been active within their respective project on that date.

The top recipients of votes shall be declared the winners. If there is any tie, it is highly encouraged that the tied nominees themselves resolve the dispute before a decision is made at random.

In regards to the inaugural vote of the Steering Council, the top two vote-recipients shall serve for two years, and the next two vote-recipients shall assume the one-year seats.

To be an eligible candidate for the Steering Council, the individual must have been a core developer in active status on at least one project for the previous twelve months.

What if there is a vacancy?

If a vacancy on the Steering Council exists during a term, then the next highest vote-recipient in the previous election shall be offered to complete the remainder of the term. If one cannot be found this way, the Steering Council may decide the most appropriate course of action to fill the seat (whether by appointment, vote, or other means).

If a member of the Steering Council becomes inactive, then that individual shall be removed from the Steering Council immediately and the seat shall become vacant.

In extreme cases, the body of all core developers has the right to bring a vote to remove a member of the Steering Council for cause by a two-thirds majority of all eligible voting core developers.

How shall the Steering Council conduct its business?

As much as possible, the Steering Council shall conduct its business and discussions in the open. Any member of the community should be allowed to enter the conversation with them. However, at times it may be necessary or appropriate for discussions to be held privately. Selecting the proper venue for conversations is part of the administrative duties of the Chair.

While the specifics of how to operate are beyond the scope of the Policy, it is encouraged that the Steering Council attempt to meet at least one time per quarter in a “real-time” discussion. This could be achieved via video conferencing, live chatting, or other appropriate means.

Support Copy Chapter

All participants in the community are encouraged to provide support for users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognize that all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring guaranteed response times or results should therefore seek to purchase a support contract from a community member. However, for those willing to engage with the project on its own terms, and willing to help support other users, the community support channels are ideal.

Decision making process Copy Chapter

Decisions about the future of the projects are made through discussion with all members of the community, from the newest user to the most experienced member. Everyone has a voice.

All non-sensitive project management discussion takes place on the community forums, or other designated channels. Occasionally, sensitive discussions may occur in private.

In order to ensure that the project is not bogged down by endless discussion and continual voting, the project operates a policy of lazy consensus. This allows the majority of decisions to be made without resorting to a formal vote. For any major decision (as defined below), there is a separate Request for Comment (RFC) process.

Technical decisions Copy Section

Pull requests and technical decisions should generally fall into the following categories.

• Routine: Documentation fixes, code changes that are for cleanup or additional testing. No functionality changes.
• Minor: Changes to the code base that either fix a bug, or introduce a trivial feature. No breaking changes.
• Major: Any change to the code base that breaks or deprecates existing API, alters operation in a non-trivial manner, or adds a significant feature.

It is generally the responsibility of the release managers to make sure that changes to the repositories receive the proper authorization before merge.

The release managers retain the authority to individually review and accept routine decisions that meet standards for code quality without additional input.

Lazy consensus Copy Section

Decision making (whether by the community or Steering Council) typically involves the following steps:

• proposal
• discussion
• vote (if consensus is not reached through discussion)
• decision

Any community member can make a proposal for consideration by the community. In order to initiate a discussion about a new idea, they should post a message on the appropriate channel on the Community forums, or submit a pull request implementing the idea on GitHub. This will prompt a review and, if necessary, a discussion of the idea.

The goal of this review and discussion is to gain approval for the contribution. Since most people in the project community have a shared vision, there is often little need for discussion in order to reach consensus.

In general, as long as nobody explicitly opposes a proposal or patch, it is recognized as having the support of the community. This is called lazy consensus; that is, those who have not stated their opinion explicitly have implicitly agreed to the implementation of the proposal.

Lazy consensus is a very important concept within the SCO. It is this process that allows a large group of people to efficiently reach consensus, as someone with no objections to a proposal need not spend time stating their position, and others need not spend time reading such messages.

For lazy consensus to be effective, it is necessary to allow an appropriate amount of time before assuming that there are no objections to the proposal. This is somewhat dependent upon the circumstances, but it is generally assumed that 72 hours is reasonable. This requirement ensures that everyone is given enough time to read, digest and respond to the proposal. This time period is chosen so as to be as inclusive as possible of all participants, regardless of their location and time commitments. The facilitators of discussion (whether it be the Chair or the Release Managers, where applicable) shall be charged with determining the proper length of time for such consensus to be reached.

As discussed above regarding so-called routine decisions, the release managers have the right to make decisions within a shorter period of time. In such cases, lazy consensus shall be implied.

Request for Comment (RFC) Copy Section

The Steering Council shall be in charge of overseeing the RFC process. It shall be a process that remains open to debate to all members of the community, and shall allow for ample time to consider a proposal and for members to respond and engage in meaningful discussion.

The final decision is vested with the Steering Council. However, it is strongly discouraged that the Steering Council adopt a decision that is contrary to any consensus that may exist in the community. From time to time this may happen if there is a conflict between consensus and the overall project and community goals.

An RFC shall be initiated by submission to the Steering Council in the public manner as set forth by the Steering Council. Debate shall continue and be facilitated by the Steering Council in general, and the Chair specifically.

In circumstances that the Steering Council feels it is appropriate, the RFC process may be waived in favor of lazy consensus.

Guide Content En Release Notes Changelog (`guide/content/en/release-notes/changelog.md`) Copy Section

content_class: changelog Copy Chapter

Changelog

🔶 Current release
🔷 In support LTS release

Version 25.12.0 🔶 Copy Chapter

Current LTS version

Features Copy Section

• #3071 Add automatic charset=UTF-8 to text content types
• #3079 Add DetailedConverter for advanced environment variable conversion
• #3080 Update str_to_bool function to include nope as a valid false value
• #3102 Better server error messaging
• #3110 Add daemon mode to Sanic CLI
• #3114 Return task when creating a task
• #3117 Explicit symlink params for static files/dirs

Bugfixes Copy Section

• #3064 Change the log type to debug
• #3068 Silent on RuntimeError when write_eof
• #3077 Fix WorkerManager.kill on Windows
• #3085 Fix AttributeError in close_if_idle() when _http is not initialized
• #3086 Fix race condition in worker restart causing spawn failure
• #3088 Fixing bad term cleanup at exit
• #3119 Fix static file serving for directories with CJK characters
• #3120 Respect LOG_EXTRA in all cases
• #3121 Respect KEEP_ALIVE config
• #3122 Check state in shutdown for handling uvloop double kill

Deprecations and Removals Copy Section

• #3115 Remove Python 3.9 support and add Python 3.14

Developer infrastructure Copy Section

• #3083 Add typing for parameters of constructor of WorkerManager
• #3084 Create baseline for bandit to remove false positives
• #3091 Use secrets for generating unique ping payloads
• #3094 Add some typing and fix some tests
• #3095 Update required Python to >=3.10
• #3101 Upgrade tracerite to latest
• #3107 Testing improvements
• #3108 Move to 2-stage coverage check
• #3109 Bump dawidd6/action-download-artifact from 3 to 6

Improved Documentation Copy Section

• #3035 Fixes sanic_ext openapi component documentation
• #3054 Fix 'how we built sanic' sidebar link
• #3056 Fix broken link in website
• #3057 Add correct path for Contribution guidelines
• #3065 Fixed incorrect links throughout the documentation
• #3066 Single letter typo fix for request.md documentation

Version 25.3.0 Copy Chapter

Features Copy Section

• #3030 Improve websockets import ordering
• #3042 Add REPL context
• #3046 Support latest v14 websockets
• #3049 Subclassing HTTPMethodView to allow generics

Bugfixes Copy Section

• #3047 Add default to response.cookies
• #3048 Add exception logging on connection auto close

Developer infrastructure Copy Section

• #3023 Cleanup from Python 3.8 removal
• #3024 Improve type hinting
• #3028 Add missing tests
• #3041 Improve GitHub Actions checks

Version 24.12.0 🔷 Copy Chapter

Features Copy Section

• #3019 Add custom commands to sanic CLI

Bugfixes Copy Section

• #2992 Fix mixins.startup.serve UnboundLocalError
• #3000 Fix type annocation for JSONResponse method for return type bytes allowed for dumps callable
• #3009 Fix SanicException.quiet attribute handling when set to False
• #3014 Cleanup some typing
• #3015 Kill the entire process group if applicable
• #3016 Fix incompatible type annotation of get method in the HTTPMethodView class

Deprecations and Removals Copy Section

• #3020 Remove Python 3.8 support

Developer infrastructure Copy Section

• #3017 Cleanup setup.cfg

Improved Documentation Copy Section

• #3007 Fix typo in documentation for sanic-ext

Version 24.6.0 Copy Chapter

Features Copy Section

• #2838 Simplify request cookies getlist
• #2850 Unix sockets can now use pathlib.Path
• #2931 #2958 Logging improvements
• #2947 Make the .message field on exceptions non-empty
• #2961 #2964 Allow for custom name generation

Bugfixes Copy Section

• #2919 Remove deprecation notice in websockets
• #2937 Resolve response streaming error when in ASGI mode
• #2959 Resolve Python 3.12 deprecation notic
• #2960 Ensure proper intent for noisy exceptions
• #2970 #2978 Fix missing dependencies for 3.12
• #2971 Fix middleware exceptions on Not Found routes with error in middleware
• #2973 Resolve cheduling logic for transport.close and transport.abort
• #2976 Fix deleting a cookie that was created with secure=False
• #2979 Throw error on bad body length
• #2980 Throw error on bad body encoding

Deprecations and Removals Copy Section

• #2899 Remove erroneous line from REPL impacting environments without HTTPX
• #2962 Merge entity header removal

Developer infrastructure Copy Section

• #2882 #2896 Apply dynamic port fixture for improving tests with port selection
• #2887 Updates to docker image builds
• #2932 Cleanup code base with Ruff

Improved Documentation Copy Section

• #2924 Cleanup markdown on html5tagger page
• #2930 Cleanup typo on Sanic Extensions README.md
• #2934 Add more context to the health check documents
• #2936 Improve worker manager documentation
• #2955 Fixed wrong formatting in request.md

Version 23.12.0 🔷 Copy Chapter

Features Copy Section

• #2775 Start and restart arbitrary processes
• #2811 Cleaner process management in shutdown
• #2812 Suppress task cancel traceback on open websocket
• #2822 Listener and signal prioritization
• #2831 Reduce memory consumption
• #2837 Accept bare cookies
• #2841 Add websocket.handler. signals
• #2805 Add changed files to reload trigger listeners
• #2813 Allow for simple signals
• #2827 Improve functionality and consistency of Sanic.event()
• #2851 Allow range requests for a single byte
• #2854 Better Request.scheme for websocket requests
• #2858 Convert Sanic Request to a Websockets Request for handshake
• #2859 Add a REPL to the sanic CLI
• #2870 Add Python 3.12 support
• #2875 Better exception on multiprocessing context conflicts

Bugfixes Copy Section

• #2803 Fix MOTD display for extra data

Developer infrastructure Copy Section

• #2796 Refactor unit test cases
• #2801 Fix test_fast when there is only one CPU
• #2807 Add constraint for autodocsum (lint issue in old package version)
• #2808 Refactor GitHub Actions
• #2814 Run CI pipeline on git push
• #2846 Drop old performance tests/benchmarks
• #2848 Makefile cleanup
• #2865
  #2869
  #2872
  #2879
  Add ruff to toolchain
• #2866 Fix the alt svc test to run locally with explicit buffer nbytes
• #2877 Use Python's trusted publisher in deployments
• #2882 Introduce dynamic port fixture in targeted locations in the test suite

Improved Documentation Copy Section

• #2781
  #2821
  #2861
  #2863
  Conversion of User Guide to the SHH (Sanic, html5tagger, HTMX) stack
• #2810 Update README
• #2855 Edit Discord badge
• #2864 Adjust documentation for using state properties within http/https redirection document

Version 23.9.0 Copy Chapter

Due to circumstances at the time, v.23.9 was skipped.

Version 23.6.0 Copy Chapter

Features Copy Section

• #2670 Increase KEEP_ALIVE_TIMEOUT default to 120 seconds
• #2716 Adding allow route overwrite option in blueprint
• #2724 and #2792 Add a new exception signal for ALL exceptions raised anywhere in application
• #2727 Add name prefixing to BP groups
• #2754 Update request type on middleware types
• #2770 Better exception message on startup time application induced import error
• #2776 Set multiprocessing start method early
• #2785 Add custom typing to config and ctx objects
• #2790 Add request.client_ip

Bugfixes Copy Section

• #2728 Fix traversals for intended results
• #2729 Handle case when headers argument of ResponseStream constructor is None
• #2737 Fix type annotation for JSONREsponse default content type
• #2740 Use Sanic's serializer for JSON responses in the Inspector
• #2760 Support for Request.get_current in ASGI mode
• #2773 Alow Blueprint routes to explicitly define error_format
• #2774 Resolve headers on different renderers
• #2782 Resolve pypy compatibility issues

Deprecations and Removals Copy Section

• #2777 Remove Python 3.7 support

Developer infrastructure Copy Section

• #2766 Unpin setuptools version
• #2779 Run keep alive tests in loop to get available port

Improved Documentation Copy Section

• #2741 Better documentation examples about running Sanic
  From that list, the items to highlight in the release notes:

Version 23.3.0 Copy Chapter

Features Copy Section

• #2545 Standardize init of exceptions for more consistent control of HTTP responses using exceptions

• #2606 Decode headers as UTF-8 also in ASGI

• #2646 Separate ASGI request and lifespan callables

• #2659 Use FALLBACK_ERROR_FORMAT for handlers that return empty()

• #2662 Add basic file browser (HTML page) and auto-index serving

• #2667 Nicer traceback formatting (HTML page)

• #2668 Smarter error page rendering format selection; more reliant upon header and "common sense" defaults

• #2680 Check the status of socket before shutting down with SHUT_RDWR

• #2687 Refresh Request.accept functionality to be more performant and spec-compliant

• #2696 Add header accessors as properties

  text Copy

  Example-Field: Foo, Bar
  Example-Field: Baz

  python Copy

  request.headers.example_field == "Foo, Bar,Baz"

• #2700 Simpler CLI targets

  sh Copy

  $ sanic path.to.module:app          # global app instance
  $ sanic path.to.module:create_app   # factory pattern
  $ sanic ./path/to/directory/        # simple serve

• #2701 API to define a number of workers in managed processes

• #2704 Add convenience for dynamic changes to routing

• #2706 Add convenience methods for cookie creation and deletion

  python Copy

  response = text("...")
  response.add_cookie("test", "It worked!", domain=".yummy-yummy-cookie.com")

• #2707 Simplified parse_content_header escaping to be RFC-compliant and remove outdated FF hack

• #2710 Stricter charset handling and escaping of request URLs

• #2711 Consume body on DELETE by default

• #2719 Allow password to be passed to TLS context

• #2720 Skip middleware on RequestCancelled

• #2721 Change access logging format to %s

• #2722 Add CertLoader as application option for directly controlling SSLContext objects

• #2725 Worker sync state tolerance on race condition

Bugfixes Copy Section

• #2651 ASGI websocket to pass thru bytes as is
• #2697 Fix comparison between datetime aware and naive in file when using If-Modified-Since

Deprecations and Removals Copy Section

• #2666 Remove deprecated __blueprintname__ property

Improved Documentation Copy Section

• #2712 Improved example using 'https' to create the redirect

Version 22.12.0 Copy Chapter

Current LTS version

Features Copy Section

• #2569 Add JSONResponse class with some convenient methods when updating a response object
• #2598 Change uvloop requirement to >=0.15.0
• #2609 Add compatibility with websockets v11.0
• #2610 Kill server early on worker error
  • Raise deadlock timeout to 30s
• #2617 Scale number of running server workers
• #2621 #2634 Send SIGKILL on subsequent ctrl+c to force worker exit
• #2622 Add API to restart all workers from the multiplexer
• #2624 Default to spawn for all subprocesses unless specifically set:
  python Copy

  from sanic import Sanic
  
  Sanic.start_method = "fork"

• #2625 Filename normalisation of form-data/multipart file uploads
• #2626 Move to HTTP Inspector:
  • Remote access to inspect running Sanic instances
  • TLS support for encrypted calls to Inspector
  • Authentication to Inspector with API key
  • Ability to extend Inspector with custom commands
• #2632 Control order of restart operations
• #2633 Move reload interval to class variable
• #2636 Add priority to register_middleware method
• #2639 Add unquote to add_route method
• #2640 ASGI websockets to receive text or bytes

Bugfixes Copy Section

• #2607 Force socket shutdown before close to allow rebinding
• #2590 Use actual StrEnum in Python 3.11+
• #2615 Ensure middleware executes only once per request timeout
• #2627 Crash ASGI application on lifespan failure
• #2635 Resolve error with low-level server creation on Windows

Deprecations and Removals Copy Section

• #2608 #2630 Signal conditions and triggers saved on signal.extra
• #2626 Move to HTTP Inspector
  • 🚨 BREAKING CHANGE: Moves the Inspector to a Sanic app from a simple TCP socket with a custom protocol
  • DEPRECATE: The --inspect* commands have been deprecated in favor of inspect ... commands
• #2628 Replace deprecated distutils.strtobool

Developer infrastructure Copy Section

• #2612 Add CI testing for Python 3.11

Version 22.9.1 Copy Chapter

Features Copy Section

• #2585 Improved error message when no applications have been registered

Bugfixes Copy Section

• #2578 Add certificate loader for in process certificate creation
• #2591 Do not use sentinel identity for spawn compatibility
• #2592 Fix properties in nested blueprint groups
• #2595 Introduce sleep interval on new worker reloader

Deprecations and Removals Copy Section

Developer infrastructure Copy Section

• #2588 Markdown templates on issue forms

Improved Documentation Copy Section

• #2556 v22.9 documentation
• #2582 Cleanup documentation on Windows support

Version 22.9.0 Copy Chapter

Features Copy Section

• #2445 Add custom loads function
• #2490 Make WebsocketImplProtocol async iterable
• #2499 Sanic Server WorkerManager refactor
• #2506 Use pathlib for path resolution (for static file serving)
• #2508 Use path.parts instead of match (for static file serving)
• #2513 Better request cancel handling
• #2516 Add request properties for HTTP method info:
  • request.is_safe
  • request.is_idempotent
  • request.is_cacheable
  • See MDN docs for more information about when these apply
• #2522 Always show server location in ASGI
• #2526 Cache control support for static files for returning 304 when appropriate
• #2533 Refactor _static_request_handler
• #2540 Add signals before and after handler execution
  • http.handler.before
  • http.handler.after
• #2542 Add [redacted] to CLI :)
• #2546 Add deprecation warning filter
• #2550 Middleware priority and performance enhancements

Bugfixes Copy Section

• #2495 Prevent directory traversion with static files
• #2515 Do not apply double slash to paths in certain static dirs in Blueprints

Deprecations and Removals Copy Section

• #2525 Warn on duplicate route names, will be prevented outright in v23.3
• #2537 Raise warning and deprecation notice on duplicate exceptions, will be prevented outright in v23.3

Developer infrastructure Copy Section

• #2504 Cleanup test suite
• #2505 Replace Unsupported Python Version Number from the Contributing Doc
• #2530 Do not include tests folder in installed package resolver

Improved Documentation Copy Section

• #2502 Fix a few typos
• #2517 #2536 Add some type hints

Version 22.6.2 Copy Chapter

Bugfixes Copy Section

• #2522 Always show server location in ASGI

Version 22.6.1 Copy Chapter

Bugfixes Copy Section

• #2477 Sanic static directory fails when folder name ends with ".."

Version 22.6.0 Copy Chapter

Features Copy Section

• #2378 Introduce HTTP/3 and autogeneration of TLS certificates in DEBUG mode
  • 👶 EARLY RELEASE FEATURE: Serving Sanic over HTTP/3 is an early release feature. It does not yet fully cover the HTTP/3 spec, but instead aims for feature parity with Sanic's existing HTTP/1.1 server. Websockets, WebTransport, push responses are examples of some features not yet implemented.
  • 📦 EXTRA REQUIREMENT: Not all HTTP clients are capable of interfacing with HTTP/3 servers. You may need to install a HTTP/3 capable client.
  • 📦 EXTRA REQUIREMENT: In order to use TLS autogeneration, you must install either mkcert or trustme.
• #2416 Add message to task.cancel
• #2420 Add exception aliases for more consistent naming with standard HTTP response types (BadRequest, MethodNotAllowed, RangeNotSatisfiable)
• #2432 Expose ASGI scope as a property on the Request object
• #2438 Easier access to websocket class for annotation: from sanic import Websocket
• #2439 New API for reading form values with options: Request.get_form
• #2445 Add custom loads function
• #2447, #2486 Improved API to support setting cache control headers
• #2453 Move verbosity filtering to logger
• #2475 Expose getter for current request using Request.get_current()

Bugfixes Copy Section

• #2448 Fix to allow running with pythonw.exe or places where there is no sys.stdout
• #2451 Trigger http.lifecycle.request signal in ASGI mode
• #2455 Resolve typing of stacked route definitions
• #2463 Properly catch websocket CancelledError in websocket handler in Python 3.7

Deprecations and Removals Copy Section

• #2487 v22.6 deprecations and changes
  1. Optional application registry
  2. Execution of custom handlers after some part of response was sent
  3. Configuring fallback handlers on the ErrorHandler
  4. Custom LOGO setting
  5. sanic.response.stream
  6. AsyncioServer.init

Developer infrastructure Copy Section

• #2449 Clean up black and isort config
• #2479 Fix some flappy tests

Improved Documentation Copy Section

• #2461 Update example to match current application naming standards
• #2466 Better type annotation for Extend
• #2485 Improved help messages in CLI

Version 22.3.0 Copy Chapter

Features Copy Section

• #2347 API for multi-application server
  • 🚨 BREAKING CHANGE: The old sanic.worker.GunicornWorker has been removed. To run Sanic with gunicorn, you should use it thru uvicorn as described in their docs.
  • 🧁 SIDE EFFECT: Named background tasks are now supported, even in Python 3.7
• #2357 Parse Authorization header as Request.credentials
• #2361 Add config option to skip Touchup step in application startup
• #2372 Updates to CLI help messaging
• #2382 Downgrade warnings to backwater debug messages
• #2396 Allow for multidict v0.6
• #2401 Upgrade CLI catching for alternative application run types
• #2402 Conditionally inject CLI arguments into factory
• #2413 Add new start and stop event listeners to reloader process
• #2414 Remove loop as required listener arg
• #2415 Better exception for bad URL parsing
• sanic-routing#47 Add a new extention parameter type: <file:ext>, <file:ext=jpg>, <file:ext=jpg|png|gif|svg>, <file=int:ext>, <file=int:ext=jpg|png|gif|svg>, <file=float:ext=tar.gz>
  • 👶 BETA FEATURE: This feature will not work with path type matching, and is being released as a beta feature only.
• sanic-routing#57 Change register_pattern to accept a str or Pattern
• sanic-routing#58 Default matching on non-empty strings only, and new strorempty pattern type
  • 🚨 BREAKING CHANGE: Previously a route with a dynamic string parameter (/<foo> or /<foo:str>) would match on any string, including empty strings. It will now only match a non-empty string. To retain the old behavior, you should use the new parameter type: /<foo:strorempty>.

Bugfixes Copy Section

• #2373 Remove error_logger on websockets
• #2381 Fix newly assigned None in task registry
• sanic-routing#52 Add type casting to regex route matching
• sanic-routing#60 Add requirements check on regex routes (this resolves, for example, multiple static directories with differing host values)

Deprecations and Removals Copy Section

• #2362 22.3 Deprecations and changes
  1. debug=True and --debug do NOT automatically run auto_reload
  2. Default error render is with plain text (browsers still get HTML by default because auto looks at headers)
  3. config is required for ErrorHandler.finalize
  4. ErrorHandler.lookup requires two positional args
  5. Unused websocket protocol args removed
• #2344 Deprecate loading of lowercase environment variables

Developer infrastructure Copy Section

• #2363 Revert code coverage back to Codecov
• #2405 Upgrade tests for sanic-routing changes
• sanic-testing#35 Allow for httpx v0.22

Improved Documentation Copy Section

• #2350 Fix link in README for ASGI
• #2398 Document middleware on_request and on_response
• #2409 Add missing documentation for Request.respond

Miscellaneous Copy Section

• #2376 Fix typing for ListenerMixin.listener
• #2383 Clear deprecation warning in asyncio.wait
• #2387 Cleanup __slots__ implementations
• #2390 Clear deprecation warning in asyncio.get_event_loop

Version 21.12.1 Copy Chapter

• #2349 Only display MOTD on startup
• #2354 Ignore name argument in Python 3.7
• #2355 Add config.update support for all config values

Version 21.12.0 Copy Chapter

Features Copy Section

• #2260 Allow early Blueprint registrations to still apply later added objects
• #2262 Noisy exceptions - force logging of all exceptions
• #2264 Optional uvloop by configuration
• #2270 Vhost support using multiple TLS certificates
• #2277 Change signal routing for increased consistency
  • BREAKING CHANGE: If you were manually routing signals there is a breaking change. The signal router's get is no longer 100% determinative. There is now an additional step to loop thru the returned signals for proper matching on the requirements. If signals are being dispatched using app.dispatch or bp.dispatch, there is no change.
• #2290 Add contextual exceptions
• #2291 Increase join concat performance
• #2295, #2316, #2331 Restructure of CLI and application state with new displays and more command parity with app.run
• #2302 Add route context at definition time
• #2304 Named tasks and new API for managing background tasks
• #2307 On app auto-reload, provide insight of changed files
• #2308 Auto extend application with Sanic Extensions if it is installed, and provide first class support for accessing the extensions
• #2309 Builtin signals changed to Enum
• #2313 Support additional config implementation use case
• #2321 Refactor environment variable hydration logic
• #2327 Prevent sending multiple or mixed responses on a single request
• #2330 Custom type casting on environment variables
• #2332 Make all deprecation notices consistent
• #2335 Allow underscore to start instance names

Bugfixes Copy Section

• #2273 Replace assignation by typing for websocket_handshake
• #2285 Fix IPv6 display in startup logs
• #2299 Dispatch http.lifecyle.response from exception handler

Deprecations and Removals Copy Section

• #2306 Removal of deprecated items
  • Sanic and Blueprint may no longer have arbitrary properties attached to them
  • Sanic and Blueprint forced to have compliant names
    • alphanumeric + _ + -
    • must start with letter or _
  • load_env keyword argument of Sanic
  • sanic.exceptions.abort
  • sanic.views.CompositionView
  • sanic.response.StreamingHTTPResponse
    • NOTE: the stream() response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https://sanicframework.org/en/guide/advanced/streaming.html#response-streaming
• #2320 Remove app instance from Config for error handler setting

Developer infrastructure Copy Section

• #2251 Change dev install command
• #2286 Change codeclimate complexity threshold from 5 to 10
• #2287 Update host test function names so they are not overwritten
• #2292 Fail CI on error
• #2311, #2324 Do not run tests for draft PRs
• #2336 Remove paths from coverage checks
• #2338 Cleanup ports on tests

Improved Documentation Copy Section

• #2269, #2329, #2333 Cleanup typos and fix language

Miscellaneous Copy Section

• #2257, #2294, #2341 Add Python 3.10 support
• #2279, #2317, #2322 Add/correct missing type annotations
• #2305 Fix examples to use modern implementations

Version 21.9.3 Copy Chapter

Rerelease of v21.9.2 with some cleanup

Version 21.9.2 Copy Chapter

• #2268 Make HTTP connections start in IDLE stage, avoiding delays and error messages
• #2310 More consistent config setting with post-FALLBACK_ERROR_FORMAT apply

Version 21.9.1 Copy Chapter

• #2259 Allow non-conforming ErrorHandlers

Version 21.9.0 Copy Chapter

Features Copy Section

• #2158, #2248 Complete overhaul of I/O to websockets
• #2160 Add new 17 signals into server and request lifecycles
• #2162 Smarter auto fallback formatting upon exception
• #2184 Introduce implementation for copying a Blueprint
• #2200 Accept header parsing
• #2207 Log remote address if available
• #2209 Add convenience methods to BP groups
• #2216 Add default messages to SanicExceptions
• #2225 Type annotation convenience for annotated handlers with path parameters
• #2236 Allow Falsey (but not-None) responses from route handlers
• #2238 Add exception decorator to Blueprint Groups
• #2244 Explicit static directive for serving file or dir (ex: static(..., resource_type="file"))
• #2245 Close HTTP loop when connection task cancelled

Bugfixes Copy Section

• #2188 Fix the handling of the end of a chunked request
• #2195 Resolve unexpected error handling on static requests
• #2208 Make blueprint-based exceptions attach and trigger in a more intuitive manner
• #2211 Fixed for handling exceptions of asgi app call
• #2213 Fix bug where ws exceptions not being logged
• #2231 Cleaner closing of tasks by using abort() in strategic places to avoid dangling sockets
• #2247 Fix logging of auto-reload status in debug mode
• #2246 Account for BP with exception handler but no routes

Developer infrastructure Copy Section

• #2194 HTTP unit tests with raw client
• #2199 Switch to codeclimate
• #2214 Try Reopening Windows Tests
• #2229 Refactor HttpProtocol into a base class
• #2230 Refactor server.py into multi-file module

Miscellaneous Copy Section

• #2173 Remove Duplicated Dependencies and PEP 517 Support
• #2193, #2196, #2217 Type annotation changes

Version 21.6.1 Copy Chapter

Bugfixes

• #2178 Update
  sanic-routing to allow for better splitting of complex URI
  templates
• #2183 Proper
  handling of chunked request bodies to resolve phantom 503 in logs
• #2181 Resolve
  regression in exception logging
• #2201 Cleanup
  request info in pipelined requests

Version 21.6.0 Copy Chapter

Features

• #2094 Add
  response.eof() method for closing a stream in a handler

• #2097 Allow
  case-insensitive HTTP Upgrade header

• #2104 Explicit
  usage of CIMultiDict getters

• #2109 Consistent
  use of error loggers

• #2114 New
  client_ip access of connection info instance

• #2119 Alternatate
  classes on instantiation for Config and Sanic.ctx

• #2133 Implement
  new version of AST router

  • Proper differentiation between alpha and string param
    types
  • Adds a slug param type, example: <foo:slug>
  • Deprecates <foo:string> in favor of <foo:str>
  • Deprecates <foo:number> in favor of <foo:float>
  • Adds a route.uri accessor

• #2136 CLI
  improvements with new optional params

• #2137 Add
  version_prefix to URL builders

• #2140 Event
  autoregistration with EVENT_AUTOREGISTER

• #2146,
  #2147 Require
  stricter names on Sanic() and Blueprint()

• #2150 Infinitely
  reusable and nestable Blueprint and BlueprintGroup

• #2154 Upgrade
  websockets dependency to min version

• #2155 Allow for
  maximum header sizes to be increased: REQUEST_MAX_HEADER_SIZE

• #2157 Allow app
  factory pattern in CLI

• #2165 Change HTTP
  methods to enums

• #2167 Allow
  auto-reloading on additional directories

• #2168 Add simple
  HTTP server to CLI

• #2170 Additional
  methods for attaching HTTPMethodView

Bugfixes

• #2091 Fix
  UserWarning in ASGI mode for missing __slots__
• #2099 Fix static
  request handler logging exception on 404
• #2110 Fix
  request.args.pop removes parameters inconsistently
• #2107 Fix type
  hinting for load_env
• #2127 Make sure
  ASGI ws subprotocols is a list
• #2128 Fix issue
  where Blueprint exception handlers do not consistently route to
  proper handler

Deprecations and Removals

• #2156 Remove
  config value REQUEST_BUFFER_QUEUE_SIZE
• #2170
  CompositionView deprecated and marked for removal in 21.12
• #2172 Deprecate
  StreamingHTTPResponse

Developer infrastructure

• #2149 Remove
  Travis CI in favor of GitHub Actions

Improved Documentation

• #2164 Fix typo in
  documentation
• #2100 Remove
  documentation for non-existent arguments

Version 21.3.2 Copy Chapter

Bugfixes

• #2081 Disable
  response timeout on websocket connections
• #2085 Make sure
  that blueprints with no slash is maintained when applied

Version 21.3.1 Copy Chapter

Bugfixes

• #2076 Static files
  inside subfolders are not accessible (404)

Version 21.3.0 Copy Chapter

Release
Notes

Features

• #1876 Unified
  streaming server
• #2005 New
  Request.id property
• #2008 Allow
  Pathlib Path objects to be passed to app.static() helper
• #2010,
  #2031 New
  startup-optimized router
• #2018
  #2064 Listeners
  for main server process
• #2032 Add raw
  header info to request object
• #2042
  #2060
  #2061 Introduce
  Signals API
• #2043 Add
  __str__ and __repr__ to Sanic and Blueprint
• #2047 Enable
  versioning and strict slash on BlueprintGroup
• #2053 Make
  get_app name argument optional
• #2055 JSON encoder
  change via app
• #2063 App and
  connection level context objects

Bugfixes

• Resolve #1420
  url_for where strict_slashes are on for a path ending in /
• Resolve #1525
  Routing is incorrect with some special characters
• Resolve #1653 ASGI
  headers in body
• Resolve #1722
  Using curl in chunk mode
• Resolve #1730
  Extra content in ASGI streaming response
• Resolve #1749
  Restore broken middleware edge cases
• Resolve #1785
  #1804 Synchronous
  error handlers
• Resolve #1790
  Protocol errors did not support async error handlers #1790
• Resolve #1824
  Timeout on specific methods
• Resolve #1875
  Response timeout error from all routes after returning several
  timeouts from a specific route
• Resolve #1988
  Handling of safe methods with body
• #2001 Raise
  ValueError when cookie max-age is not an integer

Deprecations and Removals

• #2007 * Config
  using from_envvar * Config using from_pyfile * Config using
  from_object
• #2009 Remove Sanic
  test client to its own package
• #2036,
  #2037 Drop Python
  3.6 support
• Request.endpoint deprecated in favor of Request.name
• handler type name prefixes removed (static, websocket, etc)

Developer infrastructure

• #1995 Create
  FUNDING.yml
• #2013 Add codeql
  to CI pipeline
• #2038 Codecov
  configuration updates
• #2049 Updated
  setup.py to use find_packages

Improved Documentation

• #1218
  Documentation for sanic.log.* is missing
• #1608 Add
  documentation on calver and LTS
• #1731 Support
  mounting application elsewhere than at root path
• #2006 Upgraded
  type annotations and improved docstrings and API documentation
• #2052 Fix some
  examples and docs

Miscellaneous

• Request.route property
• Better websocket subprotocols support
• Resolve bug with middleware in Blueprint Group when passed
  callable
• Moves common logic between Blueprint and Sanic into mixins
• Route naming changed to be more consistent
  • request endpoint is the route name
  • route names are fully namespaced
• Some new convenience decorators:
  • @app.main_process_start
  • @app.main_process_stop
  • @app.before_server_start
  • @app.after_server_start
  • @app.before_server_stop
  • @app.after_server_stop
  • @app.on_request
  • @app.on_response
• Fixes Allow header that did not include HEAD
• Using "name" keyword in url_for for a "static" route where
  name does not exist
• Cannot have multiple app.static() without using the named param
• Using "filename" keyword in url_for on a file route
• unquote in route def (not automatic)
• routes_all is tuples
• Handler arguments are kwarg only
• request.match_info is now a cached (and not computed) property
• Unknown static file mimetype is sent as application/octet-stream
• _host keyword in url_for
• Add charset default to utf-8 for text and js content types if
  not specified
• Version for a route can be str, float, or int
• Route has ctx property
• App has routes_static, routes_dynamic, routes_regex
• #2044 Code cleanup
  and refactoring
• #2072 Remove
  BaseSanic metaclass
• #2074 Performance
  adjustments in handle_request_

Version 20.12.3 Copy Chapter

Bugfixes

• #2021 Remove
  prefix from websocket handler name

Version 20.12.2 Copy Chapter

Dependencies

• #2026 Fix uvloop
  to 0.14 because 0.15 drops Python 3.6 support
• #2029 Remove old
  chardet requirement, add in hard multidict requirement

Version 19.12.5 Copy Chapter

Dependencies

• #2025 Fix uvloop
  to 0.14 because 0.15 drops Python 3.6 support
• #2027 Remove old
  chardet requirement, add in hard multidict requirement

Version 20.12.0 Copy Chapter

Features

• #1993 Add disable
  app registry
• #1945 Static route
  more verbose if file not found
• #1954 Fix static
  routes registration on a blueprint
• #1961 Add Python
  3.9 support
• #1962 Sanic CLI
  upgrade
• #1967 Update
  aiofile version requirements
• #1969 Update
  multidict version requirements
• #1970 Add py.typed
  file
• #1972 Speed
  optimization in request handler
• #1979 Add app
  registry and Sanic class level app retrieval

Bugfixes

• #1965 Fix Chunked
  Transport-Encoding in ASGI streaming response

Deprecations and Removals

• #1981 Cleanup and
  remove deprecated code

Developer infrastructure

• #1956 Fix load
  module test
• #1973 Transition
  Travis from .org to .com
• #1986 Update tox
  requirements

Improved Documentation

• #1951
  Documentation improvements
• #1983 Remove
  duplicate contents in testing.rst
• #1984 Fix typo in
  routing.rst

Version 20.9.1 Copy Chapter

Bugfixes

• #1954 Fix static
  route registration on blueprints
• #1957 Removes
  duplicate headers in ASGI streaming body

Version 19.12.3 Copy Chapter

Bugfixes

• #1959 Removes
  duplicate headers in ASGI streaming body

Version 20.9.0 Copy Chapter

Features

• #1887 Pass
  subprotocols in websockets (both sanic server and ASGI)
• #1894
  Automatically set test_mode flag on app instance
• #1903 Add new
  unified method for updating app values
• #1906,
  #1909 Adds
  WEBSOCKET_PING_TIMEOUT and WEBSOCKET_PING_INTERVAL configuration
  values
• #1935 httpx
  version dependency updated, it is slated for removal as a
  dependency in v20.12
• #1937 Added auto,
  text, and json fallback error handlers (in v21.3, the default will
  change form html to auto)

Bugfixes

• #1897 Resolves
  exception from unread bytes in stream

Deprecations and Removals

• #1903
  config.from_envar, config.from_pyfile, and config.from_object are
  deprecated and set to be removed in v21.3

Developer infrastructure

• #1890,
  #1891 Update isort
  calls to be compatible with new API
• #1893 Remove
  version section from setup.cfg
• #1924 Adding
  --strict-markers for pytest

Improved Documentation

• #1922 Add explicit
  ASGI compliance to the README

Version 20.6.3 Copy Chapter

Bugfixes

• #1884 Revert
  change to multiprocessing mode

Version 20.6.2 Copy Chapter

Features

• #1641 Socket
  binding implemented properly for IPv6 and UNIX sockets

Version 20.6.1 Copy Chapter

Features

• #1760 Add version
  parameter to websocket routes
• #1866 Add sanic
  as an entry point command
• #1880 Add handler
  names for websockets for url_for usage

Bugfixes

• #1776 Bug fix for
  host parameter issue with lists
• #1842 Fix static
  _handler pickling error
• #1827 Fix reloader
  on OSX py38 and Windows
• #1848 Reverse
  named_response_middlware execution order, to match normal response
  middleware execution order
• #1853 Fix pickle
  error when attempting to pickle an application which contains
  websocket routes

Deprecations and Removals

• #1739 Deprecate
  body_bytes to merge into body

Developer infrastructure

• #1852 Fix naming
  of CI test env on Python nightlies
• #1857 Adjust
  websockets version to setup.py
• #1869 Wrap
  run()'s "protocol" type annotation in Optional[]

Improved Documentation

• #1846 Update docs
  to clarify response middleware execution order
• #1865 Fixing rst
  format issue that was hiding documentation

Version 20.6.0 Copy Chapter

Released, but unintentionally omitting PR #1880, so was replaced by
20.6.1

Version 20.3.0 Copy Chapter

Features

• #1762 Add
  srv.start_serving() and srv.serve_forever() to AsyncioServer
• #1767 Make Sanic
  usable on hypercorn -k trio myweb.app
• #1768 No
  tracebacks on normal errors and prettier error pages
• #1769 Code cleanup
  in file responses
• #1793 and
  #1819 Upgrade
  str.format() to f-strings
• #1798 Allow
  multiple workers on MacOS with Python 3.8
• #1820 Do not set
  content-type and content-length headers in exceptions

Bugfixes

• #1748 Remove loop
  argument in asyncio.Event in Python 3.8
• #1764 Allow route
  decorators to stack up again
• #1789 Fix tests
  using hosts yielding incorrect url_for
• #1808 Fix Ctrl+C
  and tests on Windows

Deprecations and Removals

• #1800 Begin
  deprecation in way of first-class streaming, removal of
  body_init, body_push, and body_finish
• #1801 Complete
  deprecation from
  #1666 of
  dictionary context on request objects.
• #1807 Remove
  server config args that can be read directly from app
• #1818 Complete
  deprecation of app.remove_route and request.raw_args

Dependencies

• #1794 Bump httpx
  to 0.11.1
• #1806 Import
  ASGIDispatch from top-level httpx (from third-party
  deprecation)

Developer infrastructure

• #1833 Resolve
  broken documentation builds

Improved Documentation

• #1755 Usage of
  response.empty()
• #1778 Update
  README
• #1783 Fix typo
• #1784 Corrected
  changelog for docs move of MD to RST
  (#1691)
• #1803 Update
  config docs to match DEFAULT_CONFIG
• #1814 Update
  getting_started.rst
• #1821 Update to
  deployment
• #1822 Update docs
  with changes done in 20.3
• #1834 Order of
  listeners

Version 19.12.0 Copy Chapter

Bugfixes

• Fix blueprint middleware application

  Currently, any blueprint middleware registered, irrespective of
  which blueprint was used to do so, was being applied to all of the
  routes created by the @app and @blueprint alike.

  As part of this change, the blueprint based middleware application
  is enforced based on where they are registered.

  • If you register a middleware via @blueprint.middleware then it
    will apply only to the routes defined by the blueprint.
  • If you register a middleware via @blueprint_group.middleware
    then it will apply to all blueprint based routes that are part
    of the group.
  • If you define a middleware via @app.middleware then it will be
    applied on all available routes
    (#37)

• Fix [url_for]{.title-ref} behavior with missing SERVER_NAME

  If the [SERVER_NAME]{.title-ref} was missing in the
  [app.config]{.title-ref} entity, the [url_for]{.title-ref} on the
  [request]{.title-ref} and [app]{.title-ref} were failing due to an
  [AttributeError]{.title-ref}. This fix makes the availability of
  [SERVER_NAME]{.title-ref} on our [app.config]{.title-ref} an
  optional behavior.
  (#1707)

Improved Documentation

• Move docs from MD to RST

  Moved all docs from markdown to restructured text like the rest of
  the docs to unify the scheme and make it easier in the future to
  update documentation.
  (#1691)

• Fix documentation for [get]{.title-ref} and [getlist]{.title-ref} of
  the [request.args]{.title-ref}

  Add additional example for showing the usage of
  [getlist]{.title-ref} and fix the documentation string for
  [request.args]{.title-ref} behavior
  (#1704)

Version 19.6.3 Copy Chapter

Features

• Enable Towncrier Support

  As part of this feature, [towncrier]{.title-ref} is being introduced
  as a mechanism to partially automate the process of generating and
  managing change logs as part of each of pull requests.
  (#1631)

Improved Documentation

• Documentation infrastructure changes
  • Enable having a single common [CHANGELOG]{.title-ref} file for
    both GitHub page and documentation
  • Fix Sphinix deprecation warnings
  • Fix documentation warnings due to invalid [rst]{.title-ref}
    indentation
  • Enable common contribution guidelines file across GitHub and
    documentation via [CONTRIBUTING.rst]{.title-ref}
    (#1631)

Version 19.6.2 Copy Chapter

Features

• #1562 Remove
  aiohttp dependency and create new SanicTestClient based upon
  requests-async
• #1475 Added ASGI
  support (Beta)
• #1436 Add
  Configure support from object string

Bugfixes

• #1587 Add missing
  handle for Expect header.
• #1560 Allow to
  disable Transfer-Encoding: chunked.
• #1558 Fix graceful
  shutdown.
• #1594 Strict
  Slashes behavior fix

Deprecations and Removals

• #1544 Drop
  dependency on distutil
• #1562 Drop support
  for Python 3.5
• #1568 Deprecate
  route removal.

.. warning:: Warning

Sanic will not support Python 3.5 from version 19.6 and forward. 
However, version 18.12LTS will have its support period extended thru
December 2020, and therefore passing Python\'s official support version
3.5, which is set to expire in September 2020.

Version 19.3 Copy Chapter

Features

• #1497 Add support
  for zero-length and RFC 5987 encoded filename for
  multipart/form-data requests.

• #1484 The type of
  expires attribute of sanic.cookies.Cookie is now enforced to
  be of type datetime.

• #1482 Add support
  for the stream parameter of sanic.Sanic.add_route() available
  to sanic.Blueprint.add_route().

• #1481 Accept
  negative values for route parameters with type int or number.

• #1476 Deprecated
  the use of sanic.request.Request.raw_args - it has a fundamental
  flaw in which is drops repeated query string parameters. Added
  sanic.request.Request.query_args as a replacement for the
  original use-case.

• #1472 Remove an
  unwanted None check in Request class repr implementation. This
  changes the default repr of a Request from <Request> to
  <Request: None />

• #1470 Added 2 new
  parameters to sanic.app.Sanic.create_server:

  • return_asyncio_server - whether to return an
    asyncio.Server.
  • asyncio_server_kwargs - kwargs to pass to
    loop.create_server for the event loop that sanic is using.

  This is a breaking change.

• #1499 Added a set
  of test cases that test and benchmark route resolution.

• #1457 The type of
  the "max-age" value in a sanic.cookies.Cookie is now enforced
  to be an integer. Non-integer values are replaced with 0.

• #1445 Added the
  endpoint attribute to an incoming request, containing the name
  of the handler function.

• #1423 Improved
  request streaming. request.stream is now a bounded-size buffer
  instead of an unbounded queue. Callers must now call
  await request.stream.read() instead of
  await request.stream.get() to read each portion of the body.

  This is a breaking change.

Bugfixes

• #1502 Sanic was
  prefetching time.time() and updating it once per second to avoid
  excessive time.time() calls. The implementation was observed to
  cause memory leaks in some cases. The benefit of the prefetch
  appeared to negligible, so this has been removed. Fixes
  #1500
• #1501 Fix a bug in
  the auto-reloader when the process was launched as a module i.e.
  python -m init0.mod1 where the sanic server is started in
  init0/mod1.py with debug enabled and imports another module in
  init0.
• #1376 Allow sanic
  test client to bind to a random port by specifying port=None
  when constructing a SanicTestClient
• #1399 Added the
  ability to specify middleware on a blueprint group, so that all
  routes produced from the blueprints in the group have the
  middleware applied.
• #1442 Allow the
  the use the SANIC_ACCESS_LOG environment variable to
  enable/disable the access log when not explicitly passed to
  app.run(). This allows the access log to be disabled for example
  when running via gunicorn.

Developer infrastructure

• #1529 Update
  project PyPI credentials
• #1515 fix linter
  issue causing travis build failures (fix #1514)
• #1490 Fix python
  version in doc build
• #1478 Upgrade
  setuptools version and use native docutils in doc build
• #1464 Upgrade
  pytest, and fix caplog unit tests

Improved Documentation

• #1516 Fix typo at
  the exception documentation
• #1510 fix typo in
  Asyncio example
• #1486
  Documentation typo
• #1477 Fix grammar
  in README.md
• #1489 Added
  "databases" to the extensions list
• #1483 Add
  sanic-zipkin to extensions list
• #1487 Removed link
  to deleted repo, Sanic-OAuth, from the extensions list
• #1460 18.12
  changelog
• #1449 Add example
  of amending request object
• #1446 Update
  README
• #1444 Update
  README
• #1443 Update
  README, including new logo
• #1440 fix minor
  type and pip install instruction mismatch
• #1424
  Documentation Enhancements

Note: 19.3.0 was skipped for packagement purposes and not released on
PyPI

Version 18.12 Copy Chapter

18.12.0 Copy Section

• Changes:

  • Improved codebase test coverage from 81% to 91%.
  • Added stream_large_files and host examples in static_file
    document
  • Added methods to append and finish body content on Request
    (#1379)
  • Integrated with .appveyor.yml for windows ci support
  • Added documentation for AF_INET6 and AF_UNIX socket usage
  • Adopt black/isort for codestyle
  • Cancel task when connection_lost
  • Simplify request ip and port retrieval logic
  • Handle config error in load config file.
  • Integrate with codecov for CI
  • Add missed documentation for config section.
  • Deprecate Handler.log
  • Pinned httptools requirement to version 0.0.10+

• Fixes:

  • Fix remove_entity_headers helper function (#1415)
  • Fix TypeError when use Blueprint.group() to group blueprint
    with default url_prefix, Use os.path.normpath to avoid invalid
    url_prefix like api//v1 f8a6af1 Rename the http module to
    helpers to prevent conflicts with the built-in Python http
    library (fixes #1323)
  • Fix unittests on windows
  • Fix Namespacing of sanic logger
  • Fix missing quotes in decorator example
  • Fix redirect with quoted param
  • Fix doc for latest blueprint code
  • Fix build of latex documentation relating to markdown lists
  • Fix loop exception handling in app.py
  • Fix content length mismatch in windows and other platform
  • Fix Range header handling for static files (#1402)
  • Fix the logger and make it work (#1397)
  • Fix type pikcle->pickle in multiprocessing test
  • Fix pickling blueprints Change the string passed in the
    "name" section of the namedtuples in Blueprint to match the
    name of the Blueprint module attribute name. This allows
    blueprints to be pickled and unpickled, without errors, which
    is a requirement of running Sanic in multiprocessing mode in
    Windows. Added a test for pickling and unpickling blueprints
    Added a test for pickling and unpickling sanic itself Added a
    test for enabling multiprocessing on an app with a blueprint
    (only useful to catch this bug if the tests are run on
    Windows).
  • Fix document for logging

Version 0.8 Copy Chapter

0.8.3

• Changes:
  • Ownership changed to org 'sanic-org'

0.8.0

• Changes:
  • Add Server-Sent Events extension (Innokenty Lebedev)
  • Graceful handling of request_handler_task cancellation (Ashley
    Sommer)
  • Sanitize URL before redirection (aveao)
  • Add url_bytes to request (johndoe46)
  • py37 support for travisci (yunstanford)
  • Auto reloader support for OSX (garyo)
  • Add UUID route support (Volodymyr Maksymiv)
  • Add pausable response streams (Ashley Sommer)
  • Add weakref to request slots (vopankov)
  • remove ubuntu 12.04 from test fixture due to deprecation
    (yunstanford)
  • Allow streaming handlers in add_route (kinware)
  • use travis_retry for tox (Raphael Deem)
  • update aiohttp version for test client (yunstanford)
  • add redirect import for clarity (yingshaoxo)
  • Update HTTP Entity headers (Arnulfo Solís)
  • Add register_listener method (Stephan Fitzpatrick)
  • Remove uvloop/ujson dependencies for Windows (abuckenheimer)
  • Content-length header on 204/304 responses (Arnulfo Solís)
  • Extend WebSocketProtocol arguments and add docs (Bob Olde
    Hampsink, yunstanford)
  • Update development status from pre-alpha to beta (Maksim
    Anisenkov)
  • KeepAlive Timeout log level changed to debug (Arnulfo Solís)
  • Pin pytest to 3.3.2 because of pytest-dev/pytest#3170 (Maksim
    Aniskenov)
  • Install Python 3.5 and 3.6 on docker container for tests (Shahin
    Azad)
  • Add support for blueprint groups and nesting (Elias Tarhini)
  • Remove uvloop for windows setup (Aleksandr Kurlov)
  • Auto Reload (Yaser Amari)
  • Documentation updates/fixups (multiple contributors)
• Fixes:
  • Fix: auto_reload in Linux (Ashley Sommer)
  • Fix: broken tests for aiohttp >= 3.3.0 (Ashley Sommer)
  • Fix: disable auto_reload by default on windows (abuckenheimer)
  • Fix (1143): Turn off access log with gunicorn (hqy)
  • Fix (1268): Support status code for file response (Cosmo Borsky)
  • Fix (1266): Add content_type flag to Sanic.static (Cosmo Borsky)
  • Fix: subprotocols parameter missing from add_websocket_route
    (ciscorn)
  • Fix (1242): Responses for CI header (yunstanford)
  • Fix (1237): add version constraint for websockets (yunstanford)
  • Fix (1231): memory leak - always release resource (Phillip Xu)
  • Fix (1221): make request truthy if transport exists (Raphael
    Deem)
  • Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer)
  • Fix try_everything examples (PyManiacGR, kot83)
  • Fix (1158): default to auto_reload in debug mode (Raphael Deem)
  • Fix (1136): ErrorHandler.response handler call too restrictive
    (Julien Castiaux)
  • Fix: raw requires bytes-like object (cloudship)
  • Fix (1120): passing a list in to a route decorator's host arg
    (Timothy Ebiuwhe)
  • Fix: Bug in multipart/form-data parser (DirkGuijt)
  • Fix: Exception for missing parameter when value is null
    (NyanKiyoshi)
  • Fix: Parameter check (Howie Hu)
  • Fix (1089): Routing issue with named parameters and different
    methods (yunstanford)
  • Fix (1085): Signal handling in multi-worker mode (yunstanford)
  • Fix: single quote in readme.rst (Cosven)
  • Fix: method typos (Dmitry Dygalo)
  • Fix: log_response correct output for ip and port (Wibowo
    Arindrarto)
  • Fix (1042): Exception Handling (Raphael Deem)
  • Fix: Chinese URIs (Howie Hu)
  • Fix (1079): timeout bug when self.transport is None (Raphael
    Deem)
  • Fix (1074): fix strict_slashes when route has slash (Raphael
    Deem)
  • Fix (1050): add samesite cookie to cookie keys (Raphael Deem)
  • Fix (1065): allow add_task after server starts (Raphael Deem)
  • Fix (1061): double quotes in unauthorized exception (Raphael
    Deem)
  • Fix (1062): inject the app in add_task method (Raphael Deem)
  • Fix: update environment.yml for readthedocs (Eli Uriegas)
  • Fix: Cancel request task when response timeout is triggered
    (Jeong YunWon)
  • Fix (1052): Method not allowed response for RFC7231 compliance
    (Raphael Deem)
  • Fix: IPv6 Address and Socket Data Format (Dan Palmer)

Note: Changelog was unmaintained between 0.1 and 0.7

Version 0.1 Copy Chapter

0.1.7

• Reversed static url and directory arguments to meet spec

0.1.6

• Static files
• Lazy Cookie Loading

0.1.5

• Cookies
• Blueprint listeners and ordering
• Faster Router
• Fix: Incomplete file reads on medium+ sized post requests
• Breaking: after_start and before_stop now pass sanic as their
  first argument

0.1.4

• Multiprocessing

0.1.3

• Blueprint support
• Faster Response processing

0.1.1 - 0.1.2

• Struggling to update pypi via CI

0.1.0

• Released to public

Guide Content En Guide Advanced Class Based Views (`guide/content/en/guide/advanced/class-based-views.md`) Copy Section

Class Based Views

Why use them? Copy Chapter

.. column::

### The problem

A common pattern when designing an API is to have multiple functionality on the same endpoint that depends upon the HTTP method.

While both of these options work, they are not good design practices and may be hard to maintain over time as your project grows.

.. column::

```python
@app.get("/foo")
async def foo_get(request):
    ...

@app.post("/foo")
async def foo_post(request):
    ...

@app.put("/foo")
async def foo_put(request):
    ...

@app.route("/bar", methods=["GET", "POST", "PATCH"])
async def bar(request):
    if request.method == "GET":
        ...

    elif request.method == "POST":
        ...
        
    elif request.method == "PATCH":
        ...
```

.. column::

### The solution

Class-based views are simply classes that implement response behavior to requests. They provide a way to compartmentalize handling of different HTTP request types at the same endpoint.

.. column::

```python
from sanic.views import HTTPMethodView

class FooBar(HTTPMethodView):
    async def get(self, request):
        ...
    
    async def post(self, request):
        ...
    
    async def put(self, request):
        ...

app.add_route(FooBar.as_view(), "/foobar")
```

Defining a view Copy Chapter

A class-based view should subclass :class:sanic.views.HTTPMethodView. You can then implement class methods with the name of the corresponding HTTP method. If a request is received that has no defined method, a 405: Method not allowed response will be generated.

.. column::

To register a class-based view on an endpoint, the `app.add_route` method is used. The first argument should be the defined class with the method `as_view` invoked, and the second should be the URL endpoint.

The available methods are:

- get
- post
- put
- patch
- delete
- head
- options

.. column::

```python
from sanic.views import HTTPMethodView
from sanic.response import text

class SimpleView(HTTPMethodView):

  def get(self, request):
      return text("I am get method")

  # You can also use async syntax
  async def post(self, request):
      return text("I am post method")

  def put(self, request):
      return text("I am put method")

  def patch(self, request):
      return text("I am patch method")

  def delete(self, request):
      return text("I am delete method")

app.add_route(SimpleView.as_view(), "/")
```

Path parameters Copy Chapter

.. column::

You can use path parameters exactly as discussed in [the routing section](../basics/routing.md).

.. column::

```python
class NameView(HTTPMethodView):

  def get(self, request, name):
    return text("Hello {}".format(name))

app.add_route(NameView.as_view(), "/<name>")
```

Decorators Copy Chapter

As discussed in the decorators section, often you will need to add functionality to endpoints with the use of decorators. You have two options with CBV:

1. Apply to all HTTP methods in the view
2. Apply individually to HTTP methods in the view

Let's see what the options look like:

.. column::

### Apply to all methods

If you want to add any decorators to the class, you can set the `decorators` class variable. These will be applied to the class when `as_view` is called.

.. column::

```python
class ViewWithDecorator(HTTPMethodView):
  decorators = [some_decorator_here]

  def get(self, request, name):
    return text("Hello I have a decorator")

  def post(self, request, name):
    return text("Hello I also have a decorator")

app.add_route(ViewWithDecorator.as_view(), "/url")
```

.. column::

### Apply to individual methods

But if you just want to decorate some methods and not all methods, you can as shown here.

.. column::

```python
class ViewWithSomeDecorator(HTTPMethodView):

    @staticmethod
    @some_decorator_here
    def get(request, name):
        return text("Hello I have a decorator")

    def post(self, request, name):
        return text("Hello I do not have any decorators")

    @some_decorator_here
    def patch(self, request, name):
        return text("Hello I have a decorator")
```

Generating a URL Copy Chapter

.. column::

This works just like [generating any other URL](../basics/routing.md#generating-a-url), except that the class name is a part of the endpoint.

.. column::

```python
@app.route("/")
def index(request):
    url = app.url_for("SpecialClassView")
    return redirect(url)

class SpecialClassView(HTTPMethodView):
    def get(self, request):
        return text("Hello from the Special Class View!")

app.add_route(SpecialClassView.as_view(), "/special_class_view")
```

Guide Content En Guide Advanced Commands (`guide/content/en/guide/advanced/commands.md`) Copy Section

Custom CLI Commands

Sanic ships with a CLI for running the Sanic server. Sometimes, you may have the need to enhance that CLI to run your own custom commands. Commands are invoked using the following basic pattern:

sanic path.to:app exec <command> [--arg=value]

.. column::

To enable this, you can use your `Sanic` app instance to wrap functions that can be callable from the CLI using the `@app.command` decorator.

.. column::

```python
@app.command
async def hello(name="world"):
    print(f"Hello, {name}.")
```

.. column::

Now, you can easily invoke this command using the `exec` action.

.. column::

```sh
sanic path.to:app exec hello --name=Adam
```

Command handlers can be either synchronous or asynchronous. The handler can accept any number of keyword arguments, which will be passed in from the CLI.

.. column::

By default, the name of the function will be the command name. You can override this by passing the `name` argument to the decorator.

.. column::

```python
@app.command(name="greet")
async def hello(name="world"):
    print(f"Hello, {name}.")
```

```sh
sanic path.to:app exec greet --name=Adam
```

.. warning::

This feature is still in **BETA** and may change in future versions. There is no type coercion or validation on the arguments passed in from the CLI, and the CLI will ignore any return values from the command handler. Future enhancements and changes are likely.

Added in v24.12

Guide Content En Guide Advanced Proxy Headers (`guide/content/en/guide/advanced/proxy-headers.md`) Copy Section

Proxy configuration

When you use a reverse proxy server (e.g. nginx), the value of request.ip will contain the IP of a proxy, typically 127.0.0.1. Almost always, this is not what you will want.

Sanic may be configured to use proxy headers for determining the true client IP, available as request.remote_addr. The full external URL is also constructed from header fields if available.

.. tip:: Heads up

Without proper precautions, a malicious client may use proxy headers to spoof its own IP. To avoid such issues, Sanic does not use any proxy headers unless explicitly enabled.

.. column::

Services behind reverse proxies must configure one or more of the following [configuration values](../deployment/configuration.md):

- `FORWARDED_SECRET`
- `REAL_IP_HEADER`
- `PROXIES_COUNT`

.. column::

```python
app.config.FORWARDED_SECRET = "super-duper-secret"
app.config.REAL_IP_HEADER = "CF-Connecting-IP"
app.config.PROXIES_COUNT = 2
```

Forwarded header Copy Chapter

In order to use the Forwarded header, you should set app.config.FORWARDED_SECRET to a value known to the trusted proxy server. The secret is used to securely identify a specific proxy server.

Sanic ignores any elements without the secret key, and will not even parse the header if no secret is set.

All other proxy headers are ignored once a trusted forwarded element is found, as it already carries complete information about the client.

To learn more about the Forwarded header, read the related MDN and Nginx articles.

Traditional proxy headers Copy Chapter

IP Headers Copy Section

When your proxy forwards you the IP address in a known header, you can tell Sanic what that is with the REAL_IP_HEADER config value.

X-Forwarded-For Copy Section

This header typically contains a chain of IP addresses through each layer of a proxy. Setting PROXIES_COUNT tells Sanic how deep to look to get an actual IP address for the client. This value should equal the expected number of IP addresses in the chain.

Other X-headers Copy Section

If a client IP is found by one of these methods, Sanic uses the following headers for URL parts:

• x-forwarded-proto
• x-forwarded-host
• x-forwarded-port
• x-forwarded-path
• x-scheme

Examples Copy Chapter

In the following examples, all requests will assume that the endpoint looks like this:

@app.route("/fwd")
async def forwarded(request):
    return json(
        {
            "remote_addr": request.remote_addr,
            "scheme": request.scheme,
            "server_name": request.server_name,
            "server_port": request.server_port,
            "forwarded": request.forwarded,
        }
    )

Example 1

Without configured FORWARDED_SECRET, x-headers should be respected

curl localhost:8000/fwd \
	-H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \
	-H "X-Real-IP: 127.0.0.2" \
	-H "X-Forwarded-For: 127.0.1.1" \
	-H "X-Scheme: ws" \
	-H "Host: local.site" | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
```

.. column::

```bash
# curl response
{
  "remote_addr": "127.0.0.2",
  "scheme": "ws",
  "server_name": "local.site",
  "server_port": 80,
  "forwarded": {
    "for": "127.0.0.2",
    "proto": "ws"
  }
}
```

Example 2

FORWARDED_SECRET now configured

curl localhost:8000/fwd \
	-H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \
	-H "X-Real-IP: 127.0.0.2" \
	-H "X-Forwarded-For: 127.0.1.1" \
	-H "X-Scheme: ws" \
	-H "Host: local.site" | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "mySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "[::2]",
  "scheme": "https",
  "server_name": "me.tld",
  "server_port": 443,
  "forwarded": {
    "for": "[::2]",
    "proto": "https",
    "host": "me.tld",
    "path": "/app/",
    "secret": "mySecret"
  }
}
```

Example 3

Empty Forwarded header -> use X-headers

curl localhost:8000/fwd \
	-H "X-Real-IP: 127.0.0.2" \
	-H "X-Forwarded-For: 127.0.1.1" \
	-H "X-Scheme: ws" \
	-H "Host: local.site" | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "mySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "127.0.0.2",
  "scheme": "ws",
  "server_name": "local.site",
  "server_port": 80,
  "forwarded": {
    "for": "127.0.0.2",
    "proto": "ws"
  }
}
```

Example 4

Header present but not matching anything

curl localhost:8000/fwd \
	-H "Forwarded: nomatch" | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "mySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "",
  "scheme": "http",
  "server_name": "localhost",
  "server_port": 8000,
  "forwarded": {}
}

```

Example 5

Forwarded header present but no matching secret -> use X-headers

curl localhost:8000/fwd \
	-H "Forwarded: for=1.1.1.1;secret=x, for=127.0.0.1" \
	-H "X-Real-IP: 127.0.0.2" | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "mySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "127.0.0.2",
  "scheme": "http",
  "server_name": "localhost",
  "server_port": 8000,
  "forwarded": {
    "for": "127.0.0.2"
  }
}
```

Example 6

Different formatting and hitting both ends of the header

curl localhost:8000/fwd \
	-H 'Forwarded: Secret="mySecret";For=127.0.0.4;Port=1234' | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "mySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "127.0.0.4",
  "scheme": "http",
  "server_name": "localhost",
  "server_port": 1234,
  "forwarded": {
    "secret": "mySecret",
    "for": "127.0.0.4",
    "port": 1234
  }
}
```

Example 7

Test escapes (modify this if you see anyone implementing quoted-pairs)

curl localhost:8000/fwd \
	-H 'Forwarded: for=test;quoted="\,x=x;y=\";secret=mySecret' | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "mySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "test",
  "scheme": "http",
  "server_name": "localhost",
  "server_port": 8000,
  "forwarded": {
    "for": "test",
    "quoted": "\\,x=x;y=\\",
    "secret": "mySecret"
  }
}
```

Example 8

Secret insulated by malformed field #1

curl localhost:8000/fwd \
	-H 'Forwarded: for=test;secret=mySecret;b0rked;proto=wss;' | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "mySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "test",
  "scheme": "http",
  "server_name": "localhost",
  "server_port": 8000,
  "forwarded": {
    "for": "test",
    "secret": "mySecret"
  }
}
```

Example 9

Secret insulated by malformed field #2

curl localhost:8000/fwd \
	-H 'Forwarded: for=test;b0rked;secret=mySecret;proto=wss' | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "mySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "",
  "scheme": "wss",
  "server_name": "localhost",
  "server_port": 8000,
  "forwarded": {
    "secret": "mySecret",
    "proto": "wss"
  }
}
```

Example 10

Unexpected termination should not lose existing acceptable values

curl localhost:8000/fwd \
	-H 'Forwarded: b0rked;secret=mySecret;proto=wss' | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "mySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "",
  "scheme": "wss",
  "server_name": "localhost",
  "server_port": 8000,
  "forwarded": {
    "secret": "mySecret",
    "proto": "wss"
  }
}
```

Example 11

Field normalization

curl localhost:8000/fwd \
	-H 'Forwarded: PROTO=WSS;BY="CAFE::8000";FOR=unknown;PORT=X;HOST="A:2";PATH="/With%20Spaces%22Quoted%22/sanicApp?key=val";SECRET=mySecret' | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "mySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "",
  "scheme": "wss",
  "server_name": "a",
  "server_port": 2,
  "forwarded": {
    "proto": "wss",
    "by": "[cafe::8000]",
    "host": "a:2",
    "path": "/With Spaces\"Quoted\"/sanicApp?key=val",
    "secret": "mySecret"
  }
}
```

Example 12

Using "by" field as secret

curl localhost:8000/fwd \
	-H 'Forwarded: for=1.2.3.4; by=_proxySecret' | jq

.. column::

```python
# Sanic application config
app.config.PROXIES_COUNT = 1
app.config.REAL_IP_HEADER = "x-real-ip"
app.config.FORWARDED_SECRET = "_proxySecret"
```

.. column::

```bash
# curl response
{
  "remote_addr": "1.2.3.4",
  "scheme": "http",
  "server_name": "localhost",
  "server_port": 8000,
  "forwarded": {
    "for": "1.2.3.4",
    "by": "_proxySecret"
  }
}

```

Guide Content En Guide Advanced Signals (`guide/content/en/guide/advanced/signals.md`) Copy Section

Signals

Signals provide a way for one part of your application to tell another part that something happened.

@app.signal("user.registration.created")
async def send_registration_email(**context):
    await send_email(context["email"], template="registration")

@app.post("/register")
async def handle_registration(request):
    await do_registration(request)
    await request.app.dispatch(
        "user.registration.created",
        context={"email": request.json.email}
    })

Adding a signal Copy Chapter

.. column::

The API for adding a signal is very similar to adding a route.

.. column::

```python
async def my_signal_handler():
    print("something happened")

app.add_signal(my_signal_handler, "something.happened.ohmy")
```

.. column::

But, perhaps a slightly more convenient method is to use the built-in decorators.

.. column::

```python
@app.signal("something.happened.ohmy")
async def my_signal_handler():
    print("something happened")
```

.. column::

If the signal requires conditions, make sure to add them while adding the handler.

.. column::

```python
async def my_signal_handler1():
    print("something happened")

app.add_signal(
    my_signal_handler,
    "something.happened.ohmy1",
    conditions={"some_condition": "value"}
)

@app.signal("something.happened.ohmy2", conditions={"some_condition": "value"})
async def my_signal_handler2():
    print("something happened")
```

.. column::

Signals can also be declared on blueprints

.. column::

```python
bp = Blueprint("foo")

@bp.signal("something.happened.ohmy")
async def my_signal_handler():
    print("something happened")
```

Built-in signals Copy Chapter

In addition to creating a new signal, there are a number of built-in signals that are dispatched from Sanic itself. These signals exist to provide developers with more opportunities to add functionality into the request and server lifecycles.

Added in v21.9

.. column::

You can attach them just like any other signal to an application or blueprint instance.

.. column::

```python
@app.signal("http.lifecycle.complete")
async def my_signal_handler(conn_info):
    print("Connection has been closed")
```

These signals are the signals that are available, along with the arguments that the handlers take, and the conditions that attach (if any).

Version 22.9 added http.handler.before and http.handler.after.

Version 23.6 added server.exception.report.

.. column::

To make using the built-in signals easier, there is an `Enum` object that contains all of the allowed built-ins. With a modern IDE this will help so that you do not need to remember the full list of event names as strings.

*Added in v21.12*

.. column::

```python
from sanic.signals import Event

@app.signal(Event.HTTP_LIFECYCLE_COMPLETE)
async def my_signal_handler(conn_info):
    print("Connection has been closed")
```

Events Copy Chapter

.. column::

Signals are based off of an _event_. An event, is simply a string in the following pattern:

.. column::

```
namespace.reference.action
```

.. tip:: Events must have three parts. If you do not know what to use, try these patterns:

- `my_app.something.happened`
- `sanic.notice.hello`

Event parameters Copy Section

.. column::

An event can be "dynamic" and declared using the same syntax as [path parameters](../basics/routing.md#path-parameters). This allows matching based upon arbitrary values.

.. column::

```python
@app.signal("foo.bar.<thing>")
async def signal_handler(thing):
    print(f"[signal_handler] {thing=}")

@app.get("/")
async def trigger(request):
    await app.dispatch("foo.bar.baz")
    return response.text("Done.")
```

Checkout path parameters for more information on allowed type definitions.

.. info:: Only the third part of an event (the action) may be dynamic:

- `foo.bar.` 🆗
- `foo..baz` ❌

Waiting Copy Section

.. column::

In addition to executing a signal handler, your application can wait for an event to be triggered.

.. column::

```python
await app.event("foo.bar.baz")
```

.. column::

**IMPORTANT**: waiting is a blocking function. Therefore, you likely will want this to run in a [background task](../basics/tasks.md).

.. column::

```python
async def wait_for_event(app):
    while True:
        print("> waiting")
        await app.event("foo.bar.baz")
        print("> event found\n")

@app.after_server_start
async def after_server_start(app, loop):
    app.add_task(wait_for_event(app))
```

.. column::

If your event was defined with a dynamic path, you can use `*` to catch any action.

.. column::

```python
@app.signal("foo.bar.<thing>")

...

await app.event("foo.bar.*")
```

Dispatching Copy Chapter

In the future, Sanic will dispatch some events automatically to assist developers to hook into life cycle events.

.. column::

Dispatching an event will do two things:

1. execute any signal handlers defined on the event, and
2. resolve anything that is "waiting" for the event to complete.

.. column::

```python
@app.signal("foo.bar.<thing>")
async def foo_bar(thing):
    print(f"{thing=}")

await app.dispatch("foo.bar.baz")
```
```
thing=baz
```

Context Copy Section

.. column::

Sometimes you may find the need to pass extra information into the signal handler. In our first example above, we wanted our email registration process to have the email address for the user.

.. column::

```python
@app.signal("user.registration.created")
async def send_registration_email(**context):
    print(context)

await app.dispatch(
    "user.registration.created",
    context={"hello": "world"}
)
```
```
{'hello': 'world'}
```

.. tip:: FYI

Signals are dispatched in a background task.

Blueprints Copy Section

Dispatching blueprint signals works similar in concept to middleware. Anything that is done from the app level, will trickle down to the blueprints. However, dispatching on a blueprint, will only execute the signals that are defined on that blueprint.

.. column::

Perhaps an example is easier to explain:

.. column::

```python
bp = Blueprint("bp")

app_counter = 0
bp_counter = 0

@app.signal("foo.bar.baz")
def app_signal():
    nonlocal app_counter
    app_counter += 1

@bp.signal("foo.bar.baz")
def bp_signal():
    nonlocal bp_counter
    bp_counter += 1
```

.. column::

Running `app.dispatch("foo.bar.baz")` will execute both signals.

.. column::

```python
await app.dispatch("foo.bar.baz")
assert app_counter == 1
assert bp_counter == 1
```

.. column::

Running `bp.dispatch("foo.bar.baz")` will execute only the blueprint signal.

.. column::

```python
await bp.dispatch("foo.bar.baz")
assert app_counter == 1
assert bp_counter == 2
```

Guide Content En Guide Advanced Streaming (`guide/content/en/guide/advanced/streaming.md`) Copy Section

Streaming

Request streaming Copy Chapter

Sanic allows you to stream data sent by the client to begin processing data as the bytes arrive.

.. column::

When enabled on an endpoint, you can stream the request body using `await request.stream.read()`.

That method will return `None` when the body is completed.

.. column::

```python
from sanic.views import stream

class SimpleView(HTTPMethodView):
    @stream
    async def post(self, request):
        result = ""
        while True:
            body = await request.stream.read()
            if body is None:
                break
            result += body.decode("utf-8")
        return text(result)
```

.. column::

It also can be enabled with a keyword argument in the decorator...

.. column::

```python
@app.post("/stream", stream=True)
async def handler(request):
        ...
        body = await request.stream.read()
        ...
```

.. column::

... or the `add_route()` method.

.. column::

```python
bp.add_route(
    bp_handler,
    "/bp_stream",
    methods=["POST"],
    stream=True,
)
```

.. tip:: FYI

Only post, put and patch decorators have stream argument.

Response streaming Copy Chapter

.. column::

Sanic allows you to stream content to the client.

.. column::

```python
@app.route("/")
async def test(request):
    response = await request.respond(content_type="text/csv")
    await response.send("foo,")
    await response.send("bar")

    # Optionally, you can explicitly end the stream by calling:
    await response.eof()
```

This is useful in situations where you want to stream content to the client that originates in an external service, like a database. For example, you can stream database records to the client with the asynchronous cursor that asyncpg provides.

@app.route("/")
async def index(request):
    response = await request.respond()
    conn = await asyncpg.connect(database='test')
    async with conn.transaction():
        async for record in conn.cursor('SELECT generate_series(0, 10)'):
            await response.send(record[0])

You can explicitly end a stream by calling await response.eof(). It a convenience method to replace await response.send("", True). It should be called one time after your handler has determined that it has nothing left to send back to the client. While it is optional to use with Sanic server, if you are running Sanic in ASGI mode, then you must explicitly terminate the stream.

Calling eof became optional in v21.6

File streaming Copy Chapter

.. column::

Sanic provides `sanic.response.file_stream` function that is useful when you want to send a large file. It returns a `StreamingHTTPResponse` object and will use chunked transfer encoding by default; for this reason Sanic doesn’t add `Content-Length` HTTP header in the response.

A typical use case might be streaming an video file.

.. column::

```python
@app.route("/mp4")
async def handler_file_stream(request):
    return await response.file_stream(
        "/path/to/sample.mp4",
        chunk_size=1024,
        mime_type="application/metalink4+xml",
        headers={
            "Content-Disposition": 'Attachment; filename="nicer_name.meta4"',
            "Content-Type": "application/metalink4+xml",
        },
    )
```

.. column::

If you want to use the `Content-Length` header, you can disable chunked transfer encoding and add it manually simply by adding the `Content-Length` header.

.. column::

```python
from aiofiles import os as async_os
from sanic.response import file_stream

@app.route("/")
async def index(request):
    file_path = "/srv/www/whatever.png"

    file_stat = await async_os.stat(file_path)
    headers = {"Content-Length": str(file_stat.st_size)}

    return await file_stream(
        file_path,
        headers=headers,
    )
```

Guide Content En Guide Advanced Versioning (`guide/content/en/guide/advanced/versioning.md`) Copy Section

Versioning

It is standard practice in API building to add versions to your endpoints. This allows you to easily differentiate incompatible endpoints when you try and change your API down the road in a breaking manner.

Adding a version will add a /v{version} url prefix to your endpoints.

The version can be a int, float, or str. Acceptable values:

• 1, 2, 3
• 1.1, 2.25, 3.0
• "1", "v1", "v1.1"

Per route Copy Chapter

.. column::

You can pass a version number to the routes directly.

.. column::

```python
# /v1/text
@app.route("/text", version=1)
def handle_request(request):
    return response.text("Hello world! Version 1")

# /v2/text
@app.route("/text", version=2)
def handle_request(request):
    return response.text("Hello world! Version 2")
```

Per Blueprint Copy Chapter

.. column::

You can also pass a version number to the blueprint, which will apply to all routes in that blueprint.

.. column::

```python
bp = Blueprint("test", url_prefix="/foo", version=1)

# /v1/foo/html
@bp.route("/html")
def handle_request(request):
    return response.html("<p>Hello world!</p>")
```

Per Blueprint Group Copy Chapter

.. column::

In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint
group. The same will be inherited to all the blueprint grouped under it if the blueprints don't already override the
same information with a value specified while creating a blueprint instance.

When using blueprint groups for managing the versions, the following order is followed to apply the Version prefix to
the routes being registered.

1. Route Level configuration
2. Blueprint level configuration
3. Blueprint Group level configuration

If we find a more pointed versioning specification, we will pick that over the more generic versioning specification
provided under the Blueprint or Blueprint Group

.. column::

```python
from sanic.blueprints import Blueprint
from sanic.response import json

bp1 = Blueprint(
    name="blueprint-1",
    url_prefix="/bp1",
    version=1.25,
)
bp2 = Blueprint(
    name="blueprint-2",
    url_prefix="/bp2",
)

group = Blueprint.group(
    [bp1, bp2],
    url_prefix="/bp-group",
    version="v2",
)

# GET /v1.25/bp-group/bp1/endpoint-1
@bp1.get("/endpoint-1")
async def handle_endpoint_1_bp1(request):
    return json({"Source": "blueprint-1/endpoint-1"})

# GET /v2/bp-group/bp2/endpoint-2
@bp2.get("/endpoint-1")
async def handle_endpoint_1_bp2(request):
    return json({"Source": "blueprint-2/endpoint-1"})

# GET /v1/bp-group/bp2/endpoint-2
@bp2.get("/endpoint-2", version=1)
async def handle_endpoint_2_bp2(request):
    return json({"Source": "blueprint-2/endpoint-2"})
```

Version prefix Copy Chapter

As seen above, the version that is applied to a route is always the first segment in the generated URI path. Therefore, to make it possible to add path segments before the version, every place that a version argument is passed, you can also pass version_prefix.

The version_prefix argument can be defined in:

• app.route and bp.route decorators (and all the convenience decorators also)
• Blueprint instantiation
• Blueprint.group constructor
• BlueprintGroup instantiation
• app.blueprint registration

If there are definitions in multiple places, a more specific definition overrides a more general. This list provides that hierarchy.

The default value of version_prefix is /v.

.. column::

An often requested feature is to be able to mount versioned routes on `/api`. This can easily be accomplished with `version_prefix`.

.. column::

```python
# /v1/my/path
app.route("/my/path", version=1, version_prefix="/api/v")
```

.. column::

Perhaps a more compelling usage is to load all `/api` routes into a single `BlueprintGroup`.

.. column::

```python
# /v1/my/path
app = Sanic(__name__)
v2ip = Blueprint("v2ip", url_prefix="/ip", version=2)
api = Blueprint.group(v2ip, version_prefix="/api/version")

# /api/version2/ip
@v2ip.get("/")
async def handler(request):
    return text(request.ip)

app.blueprint(api)
```

We can therefore learn that a route's URI is:

version_prefix + version + url_prefix + URI definition

.. tip::

Just like with `url_prefix`, it is possible to define path parameters inside a `version_prefix`. It is perfectly legitimate to do this. Just remember that every route will have that parameter injected into the handler.

```python
version_prefix="/<foo:str>/v"
```

Added in v21.6

Guide Content En Guide Advanced Websockets (`guide/content/en/guide/advanced/websockets.md`) Copy Section

Websockets

Sanic provides an easy to use abstraction on top of websockets.

Routing Copy Chapter

.. column::

Websocket handlers can be hooked up to the router similar to regular handlers.

.. column::

```python
from sanic import Request, Websocket

async def feed(request: Request, ws: Websocket):
    pass

app.add_websocket_route(feed, "/feed")
```
```python
from sanic import Request, Websocket

@app.websocket("/feed")
async def feed(request: Request, ws: Websocket):
    pass
```

Handler Copy Chapter

.. column::

Typically, a websocket handler will want to hold open a loop.

It can then use the `send()` and `recv()` methods on the second object injected into the handler.

This example is a simple endpoint that echos back to the client messages that it receives.

.. column::

```python
from sanic import Request, Websocket

@app.websocket("/feed")
async def feed(request: Request, ws: Websocket):
    while True:
        data = "hello!"
        print("Sending: " + data)
        await ws.send(data)
        data = await ws.recv()
        print("Received: " + data)
```

.. column::

You can simplify your loop by just iterating over the `Websocket` object in a for loop.

*Added in v22.9*

.. column::

```python
from sanic import Request, Websocket

@app.websocket("/feed")
async def feed(request: Request, ws: Websocket):
    async for msg in ws:
        await ws.send(msg)
```

Configuration Copy Chapter

See configuration section for more details, however the defaults are shown below.

app.config.WEBSOCKET_MAX_SIZE = 2 ** 20
app.config.WEBSOCKET_PING_INTERVAL = 20
app.config.WEBSOCKET_PING_TIMEOUT = 20

Guide Content En Guide Basics App (`guide/content/en/guide/basics/app.md`) Copy Section

title: Sanic Application Copy Chapter

Sanic Application

See API docs: sanic.app

Instance Copy Chapter

.. column::

The most basic building block is the :class:`sanic.app.Sanic` instance. It is not required, but the custom is to instantiate this in a file called `server.py`.

.. column::

```python
# /path/to/server.py

from sanic import Sanic

app = Sanic("MyHelloWorldApp")
```

Application context Copy Chapter

Most applications will have the need to share/reuse data or objects across different parts of the code base. Sanic helps be providing the ctx object on application instances. It is a free space for the developer to attach any objects or data that should existe throughout the lifetime of the application.

.. column::

The most common pattern is to attach a database instance to the application.

.. column::

```python
app = Sanic("MyApp")
app.ctx.db = Database()
```

.. column::

While the previous example will work and is illustrative, it is typically considered best practice to attach objects in one of the two application startup [listeners](./listeners).

.. column::

```python
app = Sanic("MyApp")

@app.before_server_start
async def attach_db(app, loop):
    app.ctx.db = Database()
```

App Registry Copy Chapter

.. column::

When you instantiate a Sanic instance, that can be retrieved at a later time from the Sanic app registry. This can be useful, for example, if you need to access your Sanic instance from a location where it is not otherwise accessible.

.. column::

```python
# ./path/to/server.py
from sanic import Sanic

app = Sanic("my_awesome_server")

# ./path/to/somewhere_else.py
from sanic import Sanic

app = Sanic.get_app("my_awesome_server")
```

.. column::

If you call `Sanic.get_app("non-existing")` on an app that does not exist, it will raise :class:`sanic.exceptions.SanicException` by default. You can, instead, force the method to return a new instance of Sanic with that name.

.. column::

```python
app = Sanic.get_app(
    "non-existing",
    force_create=True,
)
```

.. column::

If there is **only one** Sanic instance registered, then calling `Sanic.get_app()` with no arguments will return that instance

.. column::

```python
Sanic("My only app")

app = Sanic.get_app()
```

Configuration Copy Chapter

.. column::

Sanic holds the configuration in the `config` attribute of the `Sanic` instance. Configuration can be modified **either** using dot-notation **OR** like a dictionary.

.. column::

```python
app = Sanic('myapp')

app.config.DB_NAME = 'appdb'
app.config['DB_USER'] = 'appuser'

db_settings = {
    'DB_HOST': 'localhost',
    'DB_NAME': 'appdb',
    'DB_USER': 'appuser'
}
app.config.update(db_settings)
```

.. note:: Heads up

Config keys _should_ be uppercase. But, this is mainly by convention, and lowercase will work most of the time.
```python
app.config.GOOD = "yay!"
app.config.bad = "boo"
```

There is much more detail about configuration later on.

Factory pattern Copy Chapter

Many of the examples in these docs will show the instantiation of the :class:sanic.app.Sanic instance in a file called server.py in the "global scope" (i.e. not inside a function). This is a common pattern for very simple "hello world" style applications, but it is often beneficial to use a factory pattern instead.

A "factory" is just a function that returns an instance of the object you want to use. This allows you to abstract the instantiation of the object, but also may make it easier to isolate the application instance.

.. column::

A super simple factory pattern could look like this:

.. column::

```python
# ./path/to/server.py
from sanic import Sanic
from .path.to.config import MyConfig
from .path.to.some.blueprint import bp


def create_app(config=MyConfig) -> Sanic:
    app = Sanic("MyApp", config=config)
    app.blueprint(bp)
    return app
```

.. column::

When we get to running Sanic later, you will learn that the Sanic CLI can detect this pattern and use it to run your application.

.. column::

```sh
sanic path.to.server:create_app
```

Customization Copy Chapter

The Sanic application instance can be customized for your application needs in a variety of ways at instantiation.

For complete details, see the API docs.

Custom configuration Copy Section

.. column::

This simplest form of custom configuration would be to pass your own object directly into that Sanic application instance

If you create a custom configuration object, it is *highly* recommended that you subclass the :class:`sanic.config.Config` option to inherit its behavior. You could use this option for adding properties, or your own set of custom logic.

*Added in v21.6*

.. column::

```python
from sanic.config import Config

class MyConfig(Config):
    FOO = "bar"

app = Sanic(..., config=MyConfig())
```

.. column::

A useful example of this feature would be if you wanted to use a config file in a form that differs from what is [supported](../running/configuration.md#using-sanicupdateconfig).

.. column::

```python
from sanic import Sanic, text
from sanic.config import Config

class TomlConfig(Config):
    def __init__(self, *args, path: str, **kwargs):
        super().__init__(*args, **kwargs)

        with open(path, "r") as f:
            self.apply(toml.load(f))

    def apply(self, config):
        self.update(self._to_uppercase(config))

    def _to_uppercase(self, obj: Dict[str, Any]) -> Dict[str, Any]:
        retval: Dict[str, Any] = {}
        for key, value in obj.items():
            upper_key = key.upper()
            if isinstance(value, list):
                retval[upper_key] = [
                    self._to_uppercase(item) for item in value
                ]
            elif isinstance(value, dict):
                retval[upper_key] = self._to_uppercase(value)
            else:
                retval[upper_key] = value
        return retval

toml_config = TomlConfig(path="/path/to/config.toml")
app = Sanic(toml_config.APP_NAME, config=toml_config)
```

Custom context Copy Section

.. column::

By default, the application context is a [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) that allows you to set any properties you want on it. However, you also have the option of passing any object whatsoever instead.

*Added in v21.6*

.. column::

```python
app = Sanic(..., ctx=1)
```

```python
app = Sanic(..., ctx={})
```

```python
class MyContext:
    ...

app = Sanic(..., ctx=MyContext())
```

Custom requests Copy Section

.. column::

It is sometimes helpful to have your own `Request` class, and tell Sanic to use that instead of the default. One example is if you wanted to modify the default `request.id` generator.



.. note:: Important

    It is important to remember that you are passing the *class* not an instance of the class.

.. column::

```python
import time

from sanic import Request, Sanic, text

class NanoSecondRequest(Request):
    @classmethod
    def generate_id(*_):
        return time.time_ns()

app = Sanic(..., request_class=NanoSecondRequest)

@app.get("/")
async def handler(request):
    return text(str(request.id))
```

Custom error handler Copy Section

.. column::

See [exception handling](../best-practices/exceptions.md#custom-error-handling) for more

.. column::

```python
from sanic.handlers import ErrorHandler

class CustomErrorHandler(ErrorHandler):
    def default(self, request, exception):
        ''' handles errors that have no error handlers assigned '''
        # You custom error handling logic...
        return super().default(request, exception)

app = Sanic(..., error_handler=CustomErrorHandler())
```

Custom dumps function Copy Section

.. column::

It may sometimes be necessary or desirable to provide a custom function that serializes an object to JSON data.

.. column::

```python
import ujson

dumps = partial(ujson.dumps, escape_forward_slashes=False)
app = Sanic(__name__, dumps=dumps)
```

.. column::

Or, perhaps use another library or create your own.

.. column::

```python
from orjson import dumps

app = Sanic("MyApp", dumps=dumps)
```

Custom loads function Copy Section

.. column::

Similar to `dumps`, you can also provide a custom function for deserializing data.

*Added in v22.9*

.. column::

```python
from orjson import loads

app = Sanic("MyApp", loads=loads)
```

Custom typed application Copy Section

Beginning in v23.6, the correct type annotation of a default Sanic application instance is:

sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]

It refers to two generic types:

1. The first is the type of the configuration object. It defaults to :class:sanic.config.Config, but can be any subclass of that.
2. The second is the type of the application context. It defaults to SimpleNamespace(), but can be any object as show above.

Let's look at some examples of how the type will change.

.. column::

Consider this example where we pass a custom subclass of :class:`sanic.config.Config` and a custom context object.

.. column::

```python
from sanic import Sanic
from sanic.config import Config

class CustomConfig(Config):
    pass

app = Sanic("test", config=CustomConfig())
reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace]"
```
```
sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace]
```

.. column::

Similarly, when passing a custom context object, the type will change to reflect that.

.. column::

```python
from sanic import Sanic

class Foo:
    pass

app = Sanic("test", ctx=Foo())
reveal_type(app)  # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, main.Foo]"
```
```
sanic.app.Sanic[sanic.config.Config, main.Foo]
```

.. column::

Of course, you can set both the config and context to custom types.

.. column::

```python
from sanic import Sanic
from sanic.config import Config

class CustomConfig(Config):
    pass

class Foo:
    pass

app = Sanic("test", config=CustomConfig(), ctx=Foo())
reveal_type(app)  # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, main.Foo]"
```
```
sanic.app.Sanic[main.CustomConfig, main.Foo]
```

This pattern is particularly useful if you create a custom type alias for your application instance so that you can use it to annotate listeners and handlers.

# ./path/to/types.py
from sanic.app import Sanic
from sanic.config import Config
from myapp.context import MyContext
from typing import TypeAlias

MyApp = TypeAlias("MyApp", Sanic[Config, MyContext])

# ./path/to/listeners.py
from myapp.types import MyApp

def add_listeners(app: MyApp):
    @app.before_server_start
    async def before_server_start(app: MyApp):
        # do something with your fully typed app instance
        await app.ctx.db.connect()

# ./path/to/server.py
from myapp.types import MyApp
from myapp.context import MyContext
from myapp.config import MyConfig
from myapp.listeners import add_listeners

app = Sanic("myapp", config=MyConfig(), ctx=MyContext())
add_listeners(app)

Added in v23.6

Custom typed request Copy Section

Sanic also allows you to customize the type of the request object. This is useful if you want to add custom properties to the request object, or be able to access your custom properties of a typed application instance.

The correct, default type of a Sanic request instance is:

sanic.request.Request[
    sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace],
    types.SimpleNamespace
]

It refers to two generic types:

1. The first is the type of the application instance. It defaults to sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace], but can be any subclass of that.
2. The second is the type of the request context. It defaults to types.SimpleNamespace, but can be any object as show above in custom requests.

Let's look at some examples of how the type will change.

.. column::

Expanding upon the full example above where there is a type alias for a customized application instance, we can also create a custom request type so that we can access those same type annotations.

Of course, you do not need type aliases for this to work. We are only showing them here to cut down on the amount of code shown.

.. column::

```python
from sanic import Request
from myapp.types import MyApp
from types import SimpleNamespace

def add_routes(app: MyApp):
    @app.get("/")
    async def handler(request: Request[MyApp, SimpleNamespace]):
        # do something with your fully typed app instance
        results = await request.app.ctx.db.query("SELECT * FROM foo")
```

.. column::

Perhaps you have a custom request object that generates a custom context object. You can type annotate it to properly access those properties with your IDE as shown here.

.. column::

```python
from sanic import Request, Sanic
from sanic.config import Config

class CustomConfig(Config):
    pass

class Foo:
    pass

class RequestContext:
    foo: Foo

class CustomRequest(Request[Sanic[CustomConfig, Foo], RequestContext]):
    @staticmethod
    def make_context() -> RequestContext:
        ctx = RequestContext()
        ctx.foo = Foo()
        return ctx

app = Sanic(
    "test", config=CustomConfig(), ctx=Foo(), request_class=CustomRequest
)

@app.get("/")
async def handler(request: CustomRequest):
    # Full access to typed:
    # - custom application configuration object
    # - custom application context object
    # - custom request context object
    pass
```

See more information in the custom request context section.

Added in v23.6

Guide Content En Guide Basics Cookies (`guide/content/en/guide/basics/cookies.md`) Copy Section

Cookies

Reading Copy Chapter

.. column::

Cookies can be accessed via the `Request` object’s `cookies` dictionary.

.. column::

```python
@app.route("/cookie")
async def test(request):
    test_cookie = request.cookies.get("test")
    return text(f"Test cookie: {test_cookie}")
```

.. tip:: FYI

💡 The `request.cookies` object is one of a few types that is a dictionary with each value being a `list`. This is because HTTP allows a single key to be reused to send multiple values.

Most of the time you will want to use the `.get()` method to access the first element and not a `list`. If you do want a `list` of all items, you can use `.getlist()`.

*Added in v23.3*