Debian Codegraph @

docs/howto/deployment/asgi/index.txt

raw
1 =======================
2 How to deploy with ASGI
3 =======================
4
5 As well as WSGI, Django also supports deploying on ASGI_, the emerging Python
6 standard for asynchronous web servers and applications.
7
8 .. _ASGI: https://asgi.readthedocs.io/en/latest/
9
10 Django's :djadmin:`startproject` management command sets up a default ASGI
11 configuration for you, which you can tweak as needed for your project, and
12 direct any ASGI-compliant application server to use.
13
14 Django includes getting-started documentation for the following ASGI servers:
15
16 .. toctree::
17 :maxdepth: 1
18
19 daphne
20 hypercorn
21 uvicorn
22
23 The ``application`` object
24 ==========================
25
26 Like WSGI, ASGI has you supply an ``application`` callable which
27 the application server uses to communicate with your code. It's commonly
28 provided as an object named ``application`` in a Python module accessible to
29 the server.
30
31 The :djadmin:`startproject` command creates a file
32 :file:`<project_name>/asgi.py` that contains such an ``application`` callable.
33
34 It's not used by the development server (``runserver``), but can be used by
35 any ASGI server either in development or in production.
36
37 ASGI servers usually take the path to the application callable as a string;
38 for most Django projects, this will look like ``myproject.asgi:application``.
39
40 .. warning::
41
42 While Django's default ASGI handler will run all your code in a synchronous
43 thread, if you choose to run your own async handler you must be aware of
44 async-safety.
45
46 Do not call blocking synchronous functions or libraries in any async code.
47 Django prevents you from doing this with the parts of Django that are not
48 async-safe, but the same may not be true of third-party apps or Python
49 libraries.
50
51 Configuring the settings module
52 ===============================
53
54 When the ASGI server loads your application, Django needs to import the
55 settings module — that's where your entire application is defined.
56
57 Django uses the :envvar:`DJANGO_SETTINGS_MODULE` environment variable to locate
58 the appropriate settings module. It must contain the dotted path to the
59 settings module. You can use a different value for development and production;
60 it all depends on how you organize your settings.
61
62 If this variable isn't set, the default :file:`asgi.py` sets it to
63 ``mysite.settings``, where ``mysite`` is the name of your project.
64
65 Applying ASGI middleware
66 ========================
67
68 To apply ASGI middleware, or to embed Django in another ASGI application, you
69 can wrap Django's ``application`` object in the ``asgi.py`` file. For example::
70
71 from some_asgi_library import AmazingMiddleware
72
73 application = AmazingMiddleware(application)