1.2 How Django is extended

The pattern

A dotted path is a module’s path with one more name after the last dot. import_string imports the module and returns that attribute of it (import_string; Importing by name: import_string and autodiscover_modules).

The default CACHES is one extension point whole: its alias "default" names LocMemCache, which is called with the alias’s "LOCATION" and the rest of its dictionary, both empty here. In the figure, look for when the path becomes a class, the base class nothing tests, and what keeps the instance.

Three of the things the figure shows differ from one point to the next. What is done with the import: most points call a class, the middleware calls a factory, a few name a function and WSGI_APPLICATION the application itself, and some import a module with importlib.import_module instead, as the database and session engines do.

What the object must be: most points have a base class that Django’s own implementations subclass, but a setting’s loading code tests it only for the installed applications, the static file finders and the default primary key; elsewhere an object need only have what Django uses of it.

And how long it lives, which is whatever holds it: an object made at import, the request, a cached_property or a functools cache on what builds it, a Local with a value for each thread or asynchronous context, or nothing, so that each use makes a new one.

The installed applications

Each entry of INSTALLED_APPS is the path of a package or of an AppConfig subclass. AppConfig.create imports a package with importlib.import_module, taking the configuration class from its submodule called apps where it finds one, and anything else with import_string; the class must subclass AppConfig. Apps.populate makes the configurations once a process, keeps them in the app registry, imports each application’s models module, and last calls each AppConfig.ready once, the place for an application’s startup code.

Django also looks inside each installed application by name: for its template tags, commands, migrations and translations with no setting, and for its templates and static files where the settings ask (MigrationLoader.migrations_module; Settings, apps and startup).

The middleware

Each entry of MIDDLEWARE is the dotted path of a factory: BaseHandler.load_middleware imports it and calls it once with the layer inside it, and what it returns is the middleware, called for each request. No base class is asked for, MiddlewareMixin being a convenience: the factory must return something other than None and may raise MiddlewareNotUsed to be left out. A server’s handler runs the factories when it is made, once a process (Building the middleware chain).

The backends

A backend is a pluggable implementation that a setting names, and six kinds share a shape. The setting maps each alias, "default" and any others, to a dictionary whose "ENGINE" (in DATABASES) or "BACKEND" (in CACHES, STORAGES, TASKS, MAILERS and TEMPLATES) names the backend, and an object made at import, such as caches, makes the backend for an alias when code asks for it. The base classes, BaseDatabaseWrapper, BaseCache, Storage, BaseTaskBackend, BaseEmailBackend and BaseEngine, are not tested when a backend is made.

They differ in how long a backend lives. caches, task_backends and connections are each a BaseConnectionHandler, which keeps backends in a Local, one for each thread or asynchronous context; ConnectionHandler’s is never shared between threads, for the reason Django’s neighbours gives. storages and engines keep one for each alias in a dictionary all threads share. TEMPLATES is a list, and a backend’s alias is its "NAME" or else the next-to-last name of its path, "django" for DjangoTemplates; engines makes the backend the first time its alias is asked for, as the system checks and get_template do for every engine, and keeps it for the process. mailers makes a new backend at each access, because mail backends had always been made for one sending, DEP 18 says.

A database’s "ENGINE" names a package, not a class: Django imports its base module and takes the class called DatabaseWrapper from it.

The other settings

Other settings name code, each loaded by import_string unless the loader says otherwise: “by module” is importlib.import_module.

Registries

Some extension points are not settings: an object handed to a registry, or a module Django finds by name.

Signals: Django calling out

A signal runs the other way. The project’s code connects a function, a receiver, to a Signal that Django made, and Django calls the receivers when it sends the signal, as a request starts and finishes or a model is saved. The signals Django sends lists them.