Development

The first thing that should be mentioned is that the webserver that is integrated into Sanic is not just a development server.

It is production ready out-of-the-box, unless you enable in debug mode.

Debug mode#

By setting the debug mode, Sanic will be more verbose in its output and will disable several run-time optimizations.

# server.py
from sanic import Sanic
from sanic.response import json

app = Sanic(__name__)

@app.route("/")
async def hello_world(request):
    return json({"hello": "world"})

sanic server:app --host=0.0.0.0 --port=1234 --debug

Automatic Reloader#

sanic path.to:app --reload

sanic path.to:app -r

sanic path.to:app --reload --reload-dir=/path/to/templates

sanic path.to:app -r -R /path/to/one -R /path/to/two

Development REPL#

The Sanic CLI comes with a REPL (aka "read-eval-print loop") that can be used to interact with your application. This is useful for debugging and testing. A REPL is the interactive shell that you get when you run python without any arguments.

sanic path.to.server:app --repl

sanic path.to.server:app --dev

As seen in the screenshot above, the REPL will automatically add a few variables to the global namespace. These are:

• app - The Sanic application instance. This is the same instance that is passed to the sanic CLI.
• sanic - The sanic module. This is the same module that is imported when you run import sanic.
• do - A function that will create a mock Request object and pass it to your application. This is useful for testing your application from the REPL.
• client - An instance of httpx.Client that is configured to make requests to your application. This is useful for testing your application from the REPL. Note: This is only available if httpx is installed in your environment.

Async/Await support#

>>> await app.ctx.db.fetchval("SELECT 1")
1 

The app variable#

You need to keep in mind that the app variable is your app instance as it existed when the REPL was started. It is the instance that is loaded when running the CLI command. This means that any changes that are made to your source code and subsequently reloaded in the workers will not be reflected in the app variable. If you want to interact with the reloaded app instance, you will need to restart the REPL.

However, it is also very useful to have access to the original app instance in the REPL for adhoc testing and debugging.

The client variable#

When httpx is installed in your environment, the client variable will be available in the REPL. This is an instance of httpx.Client that is configured to make requests to your running application.

>>> client.get("/")
<Response [200 OK]>

The do function#

As discussed above, the app instance exists as it did at the time the REPL was started, and as was modified inside the REPL. Any changes to the instance that cause a server to be reloaded will not be reflected in the app variable. This is where the do function comes in.

Let's say that you have modified your application inside the REPL to add a new route:

>>> @app.get("/new-route")
... async def new_route(request):
...     return sanic.json({"hello": "world"})
...
>>>

You can use the do function to mock out a request, and pass it to the application as if it were a real HTTP request. This will allow you to test your new route without having to restart the REPL.

>>> await do("/new-route")
Result(request=<Request: GET /new-route>, response=<JSONResponse: 200 application/json>)

The do function returns a Result object that contains the Request and Response objects that were returned by your application. It is a NamedTuple, so you can access the values by name:

>>> result = await do("/new-route")
>>> result.request
<Request: GET /new-route>
>>> result.response
<JSONResponse: 200 application/json>

Or, by destructuring the tuple:

>>> request, response = await do("/new-route")
>>> request
<Request: GET /new-route>
>>> response
<JSONResponse: 200 application/json>

When to use do vs client?#

Added in v23.12

Complete development mode#

sanic path.to:app --dev

sanic path.to:app -d

Added to the --dev flag in v23.12 is the ability to start a REPL. See the Development REPL section for more information.

As of v23.12, the --dev flag is roughly equivalent to --debug --reload --repl. Using --dev will require you to expressly begin the REPL by hitting "ENTER", while passing the --repl flag explicitly starts it. Before v23.12, the --dev flag is more similar to --debug --reload.

sanic path.to:app --dev --no-repl

Automatic TLS certificate#

When running in DEBUG mode, you can ask Sanic to handle setting up localhost temporary TLS certificates. This is helpful if you want to access your local development environment with https://.

This functionality is provided by either mkcert or trustme. Both are good choices, but there are some differences. trustme is a Python library and can be installed into your environment with pip. This makes for easy envrionment handling, but it is not compatible when running a HTTP/3 server. mkcert might be a more involved installation process, but can install a local CA and make it easier to use.

app.config.LOCAL_CERT_CREATOR = "auto"
app.config.LOCAL_CERT_CREATOR = "mkcert"
app.config.LOCAL_CERT_CREATOR = "trustme"

sanic path.to.server:app --auto-tls --debug

Added in v22.6