Reference

    ██████╗      ██╗ █████╗ ███╗   ██╗ ██████╗  ██████╗
    ██╔══██╗     ██║██╔══██╗████╗  ██║██╔════╝ ██╔═══██╗
    ██║  ██║     ██║███████║██╔██╗ ██║██║  ███╗██║   ██║
    ██║  ██║██   ██║██╔══██║██║╚██╗██║██║   ██║██║   ██║
    ██████╔╝╚█████╔╝██║  ██║██║ ╚████║╚██████╔╝╚██████╔╝
    ╚═════╝  ╚════╝ ╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝  ╚═════╝

██████╗  ██████╗ ██╗   ██╗████████╗██╗███╗   ██╗███████╗███████╗
██╔══██╗██╔═══██╗██║   ██║╚══██╔══╝██║████╗  ██║██╔════╝██╔════╝
██████╔╝██║   ██║██║   ██║   ██║   ██║██╔██╗ ██║█████╗  ███████╗
██╔══██╗██║   ██║██║   ██║   ██║   ██║██║╚██╗██║██╔══╝  ╚════██║
██║  ██║╚██████╔╝╚██████╔╝   ██║   ██║██║ ╚████║███████╗███████║
╚═╝  ╚═╝ ╚═════╝  ╚═════╝    ╚═╝   ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝

A simple Django app that allows you to specify batches of commands in your settings files and then run them in sequence by name using the provided routine command.

class django_routines.ManagementCommand

Bases: _RoutineCommand

A RoutineCommand that holds a information for invoking a management command.

property management: str | Tuple[str, ...]

Alias for command.

"options": Dict[str, Any]

Any options to pass to the command via call_command(). Not valid for SystemCommands

"kind": ClassVar[str] = 'management'

The kind of this command (i.e. management or system).

__init__(command, priority=0, switches=(), pre_hook=None, post_hook=None, result=None, options=<factory>)
Parameters:
Return type:

None

classmethod from_dict(obj)

Return a RoutineCommand object from a dictionary representing it.

Parameters:

obj (ManagementCommand | SystemCommand | Dict[str, Any])

Return type:

ManagementCommand | SystemCommand

"post_hook": str | Callable[[Routine, ManagementCommand | SystemCommand, ManagementCommand | SystemCommand | None, Dict[str, Any]], bool | None] | None = None

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.

"pre_hook": str | Callable[[Routine, ManagementCommand | SystemCommand, ManagementCommand | SystemCommand | None, Dict[str, Any]], bool | None] | None = None

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.

"priority": int = 0

The order of the command in the routine. Priority ties will be run in insertion order.

"result": Any = None

The result of the command run. This will either be the value returned by call_command() or a subprocess.run() result object if the command was run in a subprocess.

"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
"command": 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()

class django_routines.SystemCommand

Bases: _RoutineCommand

A RoutineCommand that represents a system command instead of a management command.

property system: str | Tuple[str, ...]

Alias for command.

"kind": ClassVar[str] = 'system'

The kind of this command (i.e. management or system).

__init__(command, priority=0, switches=(), pre_hook=None, post_hook=None, result=None)
Parameters:
Return type:

None

classmethod from_dict(obj)

Return a RoutineCommand object from a dictionary representing it.

Parameters:

obj (ManagementCommand | SystemCommand | Dict[str, Any])

Return type:

ManagementCommand | SystemCommand

"post_hook": str | Callable[[Routine, ManagementCommand | SystemCommand, ManagementCommand | SystemCommand | None, Dict[str, Any]], bool | None] | None = None

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.

"pre_hook": str | Callable[[Routine, ManagementCommand | SystemCommand, ManagementCommand | SystemCommand | None, Dict[str, Any]], bool | None] | None = None

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.

"priority": int = 0

The order of the command in the routine. Priority ties will be run in insertion order.

"result": Any = None

The result of the command run. This will either be the value returned by call_command() or a subprocess.run() result object if the command was run in a subprocess.

"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
"command": 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()

class django_routines.Routine

Bases: object

Dataclass to hold the routine information.

"name": str

The name of the routine.

"help_text": str | Promise

The help text to display for the routine. May be a string wrapped by gettext_lazy()

"commands": List[ManagementCommand | SystemCommand]

The commands to run in the routine.

"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.

__init__(name, help_text, commands=<factory>, switch_helps=<factory>, subprocess=False, atomic=False, continue_on_error=False, initialize=None, finalize=None, pre_hook=None, post_hook=None)
Parameters:
Return type:

None

"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.

"pre_hook": str | Callable[[Routine, ManagementCommand | SystemCommand, ManagementCommand | SystemCommand | None, Dict[str, Any]], bool | None] | None = None

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.

"post_hook": str | Callable[[Routine, ManagementCommand | SystemCommand, ManagementCommand | SystemCommand | None, Dict[str, Any]], bool | None] | None = None

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.

classmethod from_dict(obj)

Return a RoutineCommand object from a dictionary representing it.

Parameters:

obj (Routine | Dict[str, Any])

Return type:

Routine

django_routines.routine(name, help_text='', *commands, subprocess=False, atomic=False, continue_on_error=False, initialize=None, finalize=None, pre_hook=None, post_hook=None, **switch_helps)

Register a routine to the t.List of routines in settings to be run.

Parameters:
Raises:

ImproperlyConfigured if the DJANGO_ROUTINES settings variable is not valid.

django_routines.command(routine, *command, priority=0, switches=(), pre_hook=None, post_hook=None, **options)

Add a command to the named routine in settings to be run.

Note

You must call this function from a settings file.

Parameters:
Raises:

ImproperlyConfigured if the DJANGO_ROUTINES settings variable is not valid.

Returns:

The new command.

django_routines.get_routine(name, scope=None)

Get the routine by name.

Note

If called before settings have been configured, this function must be called from settings.

Parameters:

name (str) – The name of the routine to get.

Returns:

The routine.

Raises:

KeyError if the routine does not exist, or routines have not been configured.

Raises:

ImproperlyConfigured if the DJANGO_ROUTINES settings variable is not valid.

Return type:

Routine

django_routines.routines(scope=None)

A generator that yields Routine objects from settings.

Yield:

Routine objects

Raises:

ImproperlyConfigured if the DJANGO_ROUTINES settings variable is not valid.

Return type:

Generator[Routine, None, None]

django_routines.Command

Command type, either a ManagementCommand or SystemCommand.

alias of ManagementCommand | SystemCommand

django_routines.InitializeCallback

A callable or import string to a callable that will be run just before the routine’s first command is run.

Signature: (routine, plan, switches, options) -> None

Parameters:

alias of str | Callable[[Routine, List[ManagementCommand | SystemCommand], Set[str], Dict[str, Any]], None]

django_routines.FinalizeCallback

A callable or import string to a callable that will be run just after the routine’s last command is run.

See also django_typer.management.finalize().

Signature: (routine, results) -> None

Parameters:

  • routine (RoutineCommand) – An instance of the running routine command.

  • results (list) – The results of the commands that were run in the routine.

alias of str | Callable[[Routine, List[Any]], None]

django_routines.PreHook

Function type signature for a pre-hook functions. Pre-hook functions can modify command objects (including their arguments) before they are run.

Signature: (routine, command, previous, options) -> bool | None

Parameters:
Returns:

Return true to skip the command.

Return type:

Optional[bool]

alias of str | Callable[[Routine, Command, Command | None, Dict[str, Any]], bool | None]

django_routines.PostHook

Function type signature for a post-hook functions. Post-hook functions can modify command objects (including their results) after they are run or the next command before it is run. Returning a truthy value will exit the routine early.

Signature: (routine, command, next, options) -> bool | None

Parameters:
Returns:

Return true to exit the routine early.

Return type:

Optional[bool]

alias of str | Callable[[Routine, Command, Command | None, Dict[str, Any]], bool | None]

exceptions

exception django_routines.exceptions.ExitEarly

Bases: Exception

Raise this exception to exit a routine early.

routine command

django_routines.management.commands.routine.load_hook(hook)

Load a hook function from a string or return the hook as-is.

Raises:

ImportError if the hook string cannot be imported.

Parameters:

hook (str | Callable[[Routine, Command, Command | None, Dict[str, Any]], bool | None])

Return type:

Callable[[Routine, Command, Command | None, Dict[str, Any]], bool | None]

class django_routines.management.commands.routine.Command

Bases: TyperCommand

A TyperCommand that reads the DJANGO_ROUTINES setting from settings and builds out a set of subcommands for each routine that when invoked will run those routines in order. Each routine also has a subcommand called list that prints which commands will be executed and in what order given the switches the user has selected.

Note

If --verbosity is supplied, the value will be passed via options to any command in the routine that accepts it.

"switches": Set[str] = {}

The set of active switches for this routine run.

property routine: Routine | None

The routine this command instance was created to run.

property plan: List[ManagementCommand | SystemCommand]

The Commands that make up the execution plan for the currently active routine and switches.

finished(results)

If we have a finalize callback defined, call it with the results of the routine run.

Parameters:

results (List[Any])