21.1 Finding the command

Three entry points, one function

A command can be typed three ways, and all three call execute_from_command_line.

• manage.py is a file of the project, written by the startproject command. It sets "DJANGO_SETTINGS_MODULE" to the project’s settings module unless the environment has a value already, and calls the function with sys.argv.
• django-admin is a script that installing Django creates, declared as an entry point that names the function directly (pyproject.toml).
• python -m django runs Django’s __main__ module, which calls it too.

The function makes a ManagementUtility from the argument list and calls its execute. The utility keeps the list, and the base name of its first item as the program’s name for messages; where that is "__main__.py" it says "python -m django" instead.

So the three differ in what surrounds the call. Only manage.py says which settings to use. And they differ in where Python will look for the project’s code: running manage.py puts the project’s directory first on the module search path, because Python does that with the directory of any script it is given, and python -m django gets the current directory there. django-admin gets neither, and has to be told where the project is, by the environment or by --pythonpath.

What execute does before it knows the command

ManagementUtility.execute takes the second item of the argument list as the name of the subcommand, or "help" if there is none. It cannot look the name up at once, because which commands exist depends on the settings.

1. It reads --settings and --pythonpath. A parser that knows only those two options is run over the rest of the line, ignoring everything it does not recognise and any error. handle_default_options then acts on what was found: a settings module’s name is written to the environment variable, and a directory is put at the front of the module search path.
2. It tries the settings. It reads settings.INSTALLED_APPS, which loads the settings module if one is named. If the read raises ImproperlyConfigured, whatever the cause, the exception is kept on the utility and execute goes on without settings. That is the exception raised when no settings module is named, when the named module itself is not found, and when a setting that must be a list is not one. An exception of any other class, from a missing package above the module or from the module’s own code, is not caught, and ends every command there with a traceback.
3. It starts Django, if the read worked, by calling django.setup. For the runserver command with its reloader the call is made so that a failure does not end the process; Who calls django.setup tells that case.
4. It answers a request for shell completion, if the environment says that is what this run is (below).
5. It dispatches on the subcommand. The words help and version, and --help, -h or --version standing alone, are answered by the utility itself. Anything else is taken for a command’s name: ManagementUtility.fetch_command returns a command object, and its BaseCommand.run_from_argv is called with the whole argument list.

The two options are read here and again later. Every command’s own parser declares --settings and --pythonpath too, so that they are accepted and shown in its help, and BaseCommand.run_from_argv passes the parsed options through handle_default_options a second time. The early reading is the one that decides which commands there are.

The dictionary of commands: get_commands

get_commands returns a dictionary from each command’s name to the name of the application that provides it.

It starts with Django’s own commands, the modules of django/core/management/commands/, each entered under the name "django.core". If the settings are not configured, that is the whole dictionary. Otherwise it goes through the installed applications in the reverse of their order in settings.INSTALLED_APPS, and for each one adds the commands found in the application’s own management/commands directory, replacing any entry of the same name.

find_commands does the finding, and it imports nothing. It asks pkgutil.iter_modules for the modules in the directory and keeps the names that are not packages and do not begin with an underscore. A helper module can therefore sit beside the commands, under a name that starts with one.

The order of the loop is a rule of precedence. Because later entries replace earlier ones, and the applications are taken last to first, the application listed first wins, and any application wins over Django. The recorded project installs django.contrib.staticfiles and then two applications of its own, trees and press. Here is what each place offers, and which offers are not taken up.

The commands of the project: what find_commands finds in each place, in the order of INSTALLED_APPS
    django.core
      check, compilemessages, createcachetable, dbshell, diffsettings, dumpdata, flush,
      inspectdb, listurls, loaddata, makemessages, makemigrations, migrate, optimizemigration,
      runserver (not used: django.contrib.staticfiles has one), sendtestemail, shell,
      showmigrations, sqlflush, sqlmigrate, sqlsequencereset, squashmigrations, startapp,
      startproject, test, testserver
    django.contrib.staticfiles
      collectstatic, findstatic, runserver
    trees
      count, prune
    press
      count (not used: trees has one), juice

Replacement is by name and by nothing else. The runserver of django.contrib.staticfiles is a subclass of Django’s that adds the serving of static files, but that is its author’s choice: the dictionary would point just as well at a class that shared nothing with the one it displaced. A project replaces a command of Django’s, or of another application, by putting a file of the same name in an application listed earlier.

The dictionary is built once in a process, because get_commands is wrapped in functools.cache. The recordings in call_command: a command called from code show it: the directories are listed under the first call in a process and under none after it. In a process whose installed applications change, the test framework’s, a receiver of the setting_changed signal empties the cache whenever "INSTALLED_APPS" is overridden.

From a name to an object

ManagementUtility.fetch_command looks the subcommand up in the dictionary and hands the application’s name to load_command_class. That function imports the command’s module by its dotted path, the application’s name, then management, commands and the command’s own name, and returns an instance of the module’s class Command, made with no arguments. That is the whole of the contract a command module has to meet: the right place, and a class of that name. An error raised by the import is not caught.

The lookup stops in one of two ways, both ending the process with status 1.

The name is not in the dictionary. fetch_command complains on standard error. If difflib.get_close_matches finds a known name near the one typed, it is offered. And where the settings were not loaded, the complaint is preceded by the reason the project’s commands may be missing: the exception kept from the attempt, if the environment names a settings module, or else a line saying that no settings were specified.

The command needs settings and there are none. Once the object exists, fetch_command looks at the exception that execute kept. If there is one and the command’s BaseCommand.requires_settings is true, which is the default, the exception’s message is printed. Four of Django’s commands set the attribute to false and run regardless: startproject, startapp, shell and makemessages.

Without any settings, then, a project’s command is unknown, a command of Django’s that needs settings is refused with the reason, and one that does not need them runs.

No settings: python -m django, with DJANGO_SETTINGS_MODULE not set
    python -m django count 3
      stderr | No Django settings specified.
      stderr | Unknown command: 'count'
      stderr | Type 'python -m django help' for usage.
      exit status 1
    python -m django check
      stderr | Requested setting INSTALLED_APPS, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.
      exit status 1
    python -m django shell --no-imports -c print(40+2)
      stdout | 42
      exit status 0

A settings module that is named and does not exist has the same two outcomes, with its own message. In the third run below nothing but the option names the settings, and the project is importable because python -m django was started in its directory.

The --settings option, for a module that does not exist and for one that does
    python manage.py count 3 --settings=orchard.no_such_settings
      stderr | No module named 'orchard.no_such_settings'.
      stderr | Unknown command: 'count'
      stderr | Type 'manage.py help' for usage.
      exit status 1
    python manage.py check --settings=orchard.no_such_settings
      stderr | No module named 'orchard.no_such_settings'.
      exit status 1
    python -m django count 3 --settings=orchard.settings
      stdout | 36 trees in 3 rows
      exit status 0

A value in the dictionary may also be a command object in place of an application’s name: fetch_command and call_command both test for one and use it as it is. Django itself stores only names there.

Help, version and completion

Some things a command line can ask for are answered by ManagementUtility without running a command.

Help. With no subcommand, with help alone, or with --help or -h as the only argument, ManagementUtility.main_help_text lists every name in the dictionary under the application it comes from. If the settings could not be loaded, the list ends with a note that says so and gives the error, since the list is then Django’s commands only. Help followed by a name fetches that command, as above, and prints its parser’s help.

The version. The subcommand version, or --version as the only argument, prints what get_version returns.

Completion. ManagementUtility.autocomplete is called on every run, after the step that starts Django, and returns at once unless the environment has "DJANGO_AUTO_COMPLETE". The Bash completion script that comes with Django’s source sets that variable and runs the program again, with the words typed so far in "COMP_WORDS" and the index of the word being completed in "COMP_CWORD". The method prints the candidates for that word and exits: the names of the commands, or the options of the command already named, which it gets by fetching that command and building its parser.