Settings¶

DJANGO_ROUTINES¶

The configuration for django-routines is stored in the DJANGO_ROUTINES setting attribute. It is a dictionary structure that defines the routines and their commands. The structure is complex so we provide dataclasses and functions that facilitate type safe definition of the configuration.

Structure¶

DJANGO_ROUTINES: dict¶

Django routines configuration dictionary. The keys in this dictionary are the names of the routines. Each routine is a dictionary containing a routine specification:

"<routine name>"

The routine specification dictionary contains the following keys:

"help_text": str | Promise: The help text to display for the routine. May be a string wrapped by gettext_lazy()

"switch_helps": Dict[str, str | Promise]: Help text for switches. The keys are the switch names, and the values are the help text to display for each switch in the CLI help output.

"subprocess": bool = False: If true run each of the commands in a subprocess.

"atomic": bool = False: Run all commands in the same transaction.

"continue_on_error": bool = False: Keep going if a command fails.

"initialize": str | Callable[[Routine, List[ManagementCommand | SystemCommand], Set[str], Dict[str, Any]], None] | None = None

A function to run before the routine is run. See InitializeCallback

May be the callable function or an import string to the callable function.

"finalize": str | Callable[[Routine, List[Any]], None] | None = None

A function to run after the routine is run. See FinalizeCallback

May be the callable function or an import string to the callable function.

This function will be run before each command that lacks its own pre_hook in the routine. See PreHook. You can determine if this is the starting command of the routine by checking if the previous command is None.

May be the callable function or an import string to the callable function.

This function will be run after each command that lacks its own post_hook in the routine. See PostHook. You can determine if this is the last command of the routine by checking if the next command is None. Post hooks may also be used to exit the routine early by returning True.

May be the callable function or an import string to the callable function.

"commands": List[ManagementCommand | SystemCommand]

The commands to run in the routine.

The command dictionaries must contain either a management or system key that maps to a command specification.

"management | system": str | Tuple[str, ...]

The command and its arguments to run the routine, all strings or coercible to strings that the command will parse correctly.

This should be what you would pass as the args of call_command() or subprocess.run()

"options": Dict[str, Any]: Any options to pass to the command via call_command(). Not valid for SystemCommands

"priority": int = 0: The order of the command in the routine. Priority ties will be run in insertion order.

"switches": List[str] | Tuple[str, ...] = ()

If any switches are specified, the command will only run when one of the switches is activated on routine invocation from the command line. For example, if you list a switch named init, you would have to invoke the routine like so to run this command as part of the routine:

django-admin routine <routine_name> --init

A function that will be run before the command is run. It may make modifications to the command or decide to skip the command by returning True. See PreHook

May be the callable function or an import string to the callable function.

A function that will be run after the command has been run. It may make modifications to the command (including its result) or decide to exit the routine early by returning True. See PostHook

It may also make modifications to the next command that will be run, if any.

May be the callable function or an import string to the callable function.

Examples¶

The dictionary can be specified using any combination of these different methods.

settings.py¶

DJANGO_ROUTINES = {
    "<routine_name>": {
        "commands": [
            {
                "management": ("<management_command>", "<arg1>"),
                "options": {},  # kwargs for call_command
                "priority": 0,  # an integery priority for execution order
                "switches": ["<switch_name>"],  # optional switch enablers
                "pre_hook": None,  # or a callable pre hook function
                "post_hook": None,  # or a callable post hook function
            },
            {
                "system": ("<cmd>", "<arg1>"),
                "priority": 0,  # an integery priority for execution order
                "switches": ["<switch_name>"],  # optional switch enablers
                "pre_hook": None,  # or a callable pre hook function
                "post_hook": None,  # or a callable post hook function
            },
        ],
        "help_text": "<help_text>",
        "switch_helps": {
            "<switch_name>": "<switch_help_text>.",
        },
        "subprocess": False,  # or True
        "atomic": False,  # or True
        "continue_on_error": False,  # or True
        "initialize": None,  # or a callable initialize function
        "finalize": None,  # or a callable finalize function
        "pre_hook": None,  # or a callable pre hook function
        "post_hook": None,  # or a callable post hook function
    },
}

The data classes provide a type-safe, editor friendly way to define the configuration.

settings.py¶

from django_routines import ManagementCommand, Routine, SystemCommand 


DJANGO_ROUTINES = {
    "<routine_name>": Routine(
        "<routine_name>",
        commands=[
            ManagementCommand(
                ("<management_command>", "<arg1>",),
                priority=0,  # an integery priority for execution order
                options={},  # kwargs for call_command
                switches=["<switch_name>"],  # optional switch enablers
                pre_hook=None,  # or a callable pre hook function
                post_hook=None,  # or a callable post hook function
            ),
            SystemCommand(
                ("<cmd>", "<arg1>",),
                priority=0,  # an integery priority for execution order
                switches=["<switch_name>"],  # optional switch enablers
                pre_hook=None,  # or a callable pre hook function
                post_hook=None,  # or a callable post hook function
            ),
        ],
        help_text="<help_text>",
        switch_helps={
            "<switch_name>": "<switch_help_text>.",
        },
        subprocess=False,  # or True
        atomic=False,  # or True
        continue_on_error=False,  # or True
        initialize=None,  # or a callable initialize function
        finalize=None,  # or a callable finalize function
        pre_hook=None,  # or a callable pre hook function
        post_hook=None,  # or a callable post hook function
    )
}

The shortcut functions are especially useful when composing routines across multiple different settings files. They allow you to not worry about definition order. The priority parameter allows for deterministic routine order even if the order of the functions changes.

settings.py¶

from django_routines import routine, command, system

# the function version of dict.py
routine(
    "<routine_name>",
    help_text="<help_text>",
    switch_helps={
        "<switch_name>": "<switch_help_text>.",
    },
    subprocess=False,  # or True
    atomic=False,  # or True
    continue_on_error=False,  # or True
    initialize=None,  # or a callable initialize function
    finalize=None,  # or a callable finalize function
    pre_hook=None,  # or a callable pre hook function
    post_hook=None,  # or a callable post hook function
)

command(
    "<routine_name>",
    "<management_command>",
    "<arg1>",
    priority=0,  # an integer priority for execution order
    options={},  # kwargs for call_command
    switches=["<switch_name>"],  # optional switch enablers
    pre_hook=None,  # or a callable pre hook function
    post_hook=None,  # or a callable post hook function
)

system(
    "<routine_name>",
    "<cmd>",
    "<arg1>",
    priority=0,  # an integer priority for execution order
    switches=["<switch_name>"],  # optional switch enablers
    pre_hook=None,  # or a callable pre hook function
    post_hook=None,  # or a callable post hook function
)