1.1 The parts of Django, and what each leans on

Django’s source is a set of packages under django/, and their imports stand them in layers, the departments of What Django is, each leaning on those beneath it. A few imports run against the layers.

An import at the top of a module is a dependency from the moment the module loads; one inside a function is made when the function runs. The layers are read from the first kind; the second is how a part reaches one above it without loading it.

The figure places the packages in their layers. At the bottom is the floor, the utilities, the settings and the app registry, and with them django/core/exceptions.py; every other package imports from it. An accented arrow runs against the layers.

Figure 1.2 The packages in layers. An arrow runs from a package to one it imports at module level; an accented arrow runs against the layers. The arrows are a selection, not all there are: the floor’s by every package, and every layer’s by django/contrib/, are one arrow each, and the accented ones are the crossings the text tells.

The parts, one by one

The table gives each part, from the floor up: what it holds, what it imports as it loads, what imports it, and the chapter that tells it.

Table 1.1 Imports at load are those beyond the floor: a selection, as the figure’s arrows are, unless the cell says nothing or only. Imported by counts import statements, inside a function as well as at load; an empty cell there makes no claim.

part: what it holds	imports at load	imported by	chapter
`utils/` django/: lazy objects, importing by dotted path, data structures, text	imports at load in modules that belong to other parts, the mail package, the cache, `django.http`	imported by every other package	chapter The utility layer
`exceptions.py` django/core/: the exceptions the parts share	imports at load nothing		chapter Django’s exceptions: `django.core.exceptions`
`__init__.py` django/conf/: the settings	imports at load nothing		chapter Settings, apps and startup
`apps/` django/: the app registry	imports at load nothing		chapter Settings, apps and startup
`dispatch/` django/: `Signal`	imports at load nothing		chapter Caching, files, mail, signals and tasks
`signals.py` django/core/: a request’s signals, `setting_changed`	imports at load only `django.dispatch`		chapter Caching, files, mail, signals and tasks
`mail/` django/core/: mail	imports at load nothing		chapter Caching, files, mail, signals and tasks
`files/` django/core/: files	imports at load only `setting_changed`		chapter Caching, files, mail, signals and tasks
`cache/` django/core/: the cache	imports at load the ORM, in its database backend		chapter Caching, files, mail, signals and tasks
`serializers/` django/core/: serialization	imports at load the ORM		chapter Caching, files, mail, signals and tasks
`tasks/` django/: tasks	imports at load the ORM’s `TextChoices`	imported by nothing outside it	chapter Caching, files, mail, signals and tasks
`checks/` django/core/: the system checks	imports at load the database connections, the caches, the mail package		chapter The system checks
`db/` django/: models, querysets, SQL, backends, migrations	imports at load the checks, `files/` django/core/, the validators, the signals, the serializers, `CommandError` and `OutputWrapper`, `django.forms`	imported by never `http/` django/, `urls/` django/, `middleware/` django/, `mail/` django/core/, `files/` django/core/, `dispatch/` django/	chapter Models and fields, QuerySets, From QuerySet to SQL, Database backends, Migrations
`template/` django/, `templatetags/` django/: the template engine and its backends, the libraries a template loads	imports at load `http/` django/, `middleware/` django/	imported by never `db/` django/, `http/` django/, `urls/` django/, `middleware/` django/, `handlers/` django/core/	chapter Templates
`forms/` django/: forms, fields, widgets, renderers	imports at load the template system, `utils.py` django/db/models/	imported by never `http/` django/, `urls/` django/, `middleware/` django/, `handlers/` django/core/	chapter Forms
`http/` django/: the request and the response	imports at load the upload handlers of `files/` django/core/, `request_finished`, `DjangoJSONEncoder`		chapter Requests and responses
`urls/` django/: the resolver, and beside it `urls/` django/conf/	imports at load `http/` django/; `urls/` django/conf/ also `views/` django/		chapter URL routing
`views/` django/: the views Django ships	imports at load `urls/` django/, `http/` django/, the template system, the forms, the ORM	imported by beyond the tools and `contrib/` django/, only the handler, `urls/` django/conf/, `urls/` django/	chapter Views
`middleware/` django/: the middleware	imports at load `urls/` django/, `http/` django/		chapter Handlers and middleware, Security
`handlers/` django/core/: the handler	imports at load `urls/` django/, `http/` django/, the ORM, `debug.py` django/views/	imported by beyond the tools and `contrib/` django/, only `wsgi.py` django/core/, `asgi.py` django/core/, `basehttp.py` django/core/servers/	chapter Handlers and middleware
`management/` django/core/: the commands	imports at load more of the ORM than of any other part		chapter Management commands
`test/` django/: the test framework	imports at load the handler, the ORM, the mail package, the template system	imported by only the test command, `testing.py` django/contrib/staticfiles/	chapter The test framework
`contrib/` django/: the applications	imports at load every layer	imported by nothing at load; inside functions, only `static.py` django/templatetags/, `client.py` django/test/, `signals.py` django/test/	chapter Authentication, sessions and messages, The admin, Content types, static files and the other contrib apps

The floor

The utilities import the settings: django/utils/timezone.py reads TIME_ZONE and USE_TZ, and BaseConnectionHandler the setting its subclass names. That makes no cycle. The utility modules that django/conf/__init__.py imports import nothing of django.conf, and settings reads the settings module only the first time the settings are needed, so a utility can import it as it loads and read it later.

Some modules of django/utils/ belong by subject to another part and import upward: django/utils/log.py imports the mail package for AdminEmailHandler, and django/utils/cache.py the cache and django.http (The utility layer).

The services

django/core/signals.py defines a request’s signals, request_started, request_finished and got_request_exception, with setting_changed, and imports only django.dispatch. Through it a lower part hears of a request without importing the handler: django/db/__init__.py connects close_old_connections to the first two, and the cache closes its connections on request_finished.

The cache’s database backend imports the ORM, but the cache loads it only when CACHES names it. The serializers stand among the services but lean on the data side: django/core/serializers/ writes model instances, and imports django.db.models and the app registry as it loads.

The system checks are a tool by purpose, but their imports put them among the services: the models, the fields, the URL resolver and the template backend import django/core/checks/ as they load, and it imports the database connections, the caches and the mail package as it loads, and the URLconf and the template engines, among others, only inside functions.

The data side

django/db/ imports from two parts above it as it loads. For the migrations it takes CommandError and OutputWrapper from the management package. And django/db/models/fields/__init__.py imports django.forms, for the method with which a model field makes the form field that edits it.

The forms import back, as they load, only a helper module, django/db/models/utils.py, and the rest of the ORM inside functions. But Python imports a package before any module in it, so importing the helper loads django.db.models.

The presentation side

The modules of the template engine, its compiler and its context import only the utilities, the exceptions and one another, though an engine always includes the csrf context processor, imported by its dotted path. Four other modules import from the request side. SimpleTemplateResponse is a subclass of HttpResponse; the querystring tag builds a QueryDict; the csrf context processor takes the token from get_token in django/middleware/csrf.py; and so does the backends’ csrf_input.