MultiTool

The celery multi program.

Attributes

Attribute	Type	Description
MultiParser	`class` = MultiParser	The parser class used to process and expand node-specific arguments from the command line.
OptionParser	`class` = NamespacedOptionParser	The parser class used to handle namespaced command-line options for the multi-node manager.
reserved_options	`list` = [('--nosplash', 'nosplash'), ('--quiet', 'quiet'), ('-q', 'quiet'), ('--verbose', 'verbose'), ('--no-color', 'no_color')]	A list of tuples mapping command-line flags to internal attribute names for global configuration like logging and color.
stop_verify	`callable` = stopwait	A compatibility alias for the stopwait method used to shut down nodes and verify their termination.

Constructor

Signature

def MultiTool(
    env: Any = None,
    cmd: Any = None,
    fh: Any = None,
    stdout: Any = None,
    stderr: Any = None,
    **kwargs: dict
) - > null

Parameters

Name	Type	Description
env	`Any` = None	The environment configuration for the tool.
cmd	`Any` = None	The command to be executed.
fh	`Any` = None	An old alias for stdout used for terminal output.
stdout	`Any` = None	The standard output stream.
stderr	`Any` = None	The standard error stream.
**kwargs	`dict`	Additional keyword arguments for terminal setup.

Methods

`execute_from_commandline()`

@classmethod
def execute_from_commandline(
    argv: list,
    cmd: string = null
) - > int

Parses command-line arguments and executes the corresponding multi-node command.

Parameters

Name	Type	Description
argv	`list`	The list of command-line arguments including the program name.
cmd	`string` = null	The base command to execute for each node.

Returns

Type	Description
`int`	The exit code of the executed command, typically 0 for success.

`validate_arguments()`

@classmethod
def validate_arguments(
    argv: list
) - > boolean

Validates that the provided arguments contain a valid command name.

Parameters

Name	Type	Description
argv	`list`	The list of arguments to validate.

Returns

Type	Description
`boolean`	True if the first argument is present and does not start with a hyphen.

`call_command()`

@classmethod
def call_command(
    command: string,
    argv: list
) - > int

Dispatches the execution to the internal method mapped to the specified command name.

Parameters

Name	Type	Description
command	`string`	The name of the command to invoke (e.g., 'start', 'stop').
argv	`list`	The arguments to pass to the command handler.

Returns

Type	Description
`int`	The result of the command execution or an error code if the command is invalid.

`start()`

@classmethod
def start(
    cluster: [Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)
) - > int

Starts the defined cluster of nodes.

Parameters

Name	Type	Description
cluster	`[Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)`	The cluster instance containing the nodes to be started.

Returns

Type	Description
`int`	Returns 1 if any node failed to start, otherwise 0.

`stop()`

@classmethod
def stop(
    cluster: [Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster),
    sig: int
) - > any

Sends a stop signal to the nodes in the cluster.

Parameters

Name	Type	Description
cluster	`[Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)`	The cluster instance to stop.
sig	`int`	The signal number to send to the nodes.

Returns

Type	Description
`any`	The return value from the cluster's stop operation.

`stopwait()`

@classmethod
def stopwait(
    cluster: [Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster),
    sig: int
) - > any

Sends a stop signal to the nodes and waits for them to terminate.

Parameters

Name	Type	Description
cluster	`[Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)`	The cluster instance to stop.
sig	`int`	The signal number to send to the nodes.

Returns

Type	Description
`any`	The return value from the cluster's stopwait operation.

`restart()`

@classmethod
def restart(
    cluster: [Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster),
    sig: int
) - > int

Restarts the nodes in the cluster by stopping and then starting them.

Parameters

Name	Type	Description
cluster	`[Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)`	The cluster instance to restart.
sig	`int`	The signal number used for the stop phase of the restart.

Returns

Type	Description
`int`	Returns 1 if any node failed to restart, otherwise 0.

`names()`

@classmethod
def names(
    cluster: [Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)
) - > null

Prints the names of all nodes defined in the cluster to the terminal.

Parameters

Name	Type	Description
cluster	`[Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)`	The cluster whose node names should be displayed.

Returns

Type	Description
`null`	null

`get()`

@classmethod
def get(
    wanted: string,
    argv: list
) - > int

Retrieves and displays the full command-line arguments for a specific node.

Parameters

Name	Type	Description
wanted	`string`	The name of the specific node to retrieve.
argv	`list`	Arguments used to construct the cluster context.

Returns

Type	Description
`int`	Returns EX_OK on success or EX_FAILURE if the node is not found.

`show()`

@classmethod
def show(
    cluster: [Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)
) - > int

Displays the full command-line strings that would be executed for every node in the cluster.

Parameters

Name	Type	Description
cluster	`[Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)`	The cluster instance to inspect.

Returns

Type	Description
`int`	The exit status of the operation.

`kill()`

@classmethod
def kill(
    cluster: [Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)
) - > any

Forcefully terminates the nodes in the cluster.

Parameters

Name	Type	Description
cluster	`[Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)`	The cluster instance to kill.

Returns

Type	Description
`any`	The result of the cluster kill operation.

`expand()`

@classmethod
def expand(
    template: string,
    argv: list
) - > int

Expands a template string using the variables available for each node in the cluster.

Parameters

Name	Type	Description
template	`string`	The string template containing placeholders to expand.
argv	`list`	Arguments used to construct the cluster context.

Returns

Type	Description
`int`	The exit status of the operation.

`help()`

@classmethod
def help(
    argv: list
) - > null

Displays the program's documentation and usage information.

Parameters

Name	Type	Description
argv	`list`	Optional arguments for the help command.

Returns

Type	Description
`null`	null

`cluster_from_argv()`

@classmethod
def cluster_from_argv(
    argv: list,
    cmd: string = null
) - > [Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)

Creates a Cluster object from the provided command-line arguments.

Parameters

Name	Type	Description
argv	`list`	The arguments defining the cluster nodes.
cmd	`string` = null	The base command for the nodes.

Returns

Type	Description
`[Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)`	An initialized Cluster instance.

`Cluster()`

@classmethod
def Cluster(
    nodes: list,
    cmd: string = null
) - > [Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)

Factory method to instantiate a Cluster with the appropriate event callbacks.

Parameters

Name	Type	Description
nodes	`list`	The list of node definitions.
cmd	`string` = null	The base command for the nodes.

Returns

Type	Description
`[Cluster](../../apps/multi/cluster.md?sid=celery_apps_multi_cluster)`	A Cluster instance configured with the tool's logging and event handlers.

`on_stopping_preamble()`

@classmethod
def on_stopping_preamble(
    nodes: list
) - > null

Logs a message indicating that the node shutdown process has started.

Parameters

Name	Type	Description
nodes	`list`	The list of nodes being stopped.

Returns

Type	Description
`null`	null

`on_send_signal()`

@classmethod
def on_send_signal(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node),
    sig: int
) - > null

Logs the action of sending a specific signal to a node.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The node receiving the signal.
sig	`int`	The signal number being sent.

Returns

Type	Description
`null`	null

`on_still_waiting_for()`

@classmethod
def on_still_waiting_for(
    nodes: list
) - > null

Logs a status message listing nodes that have not yet shut down.

Parameters

Name	Type	Description
nodes	`list`	The list of nodes still active.

Returns

Type	Description
`null`	null

`on_still_waiting_progress()`

@classmethod
def on_still_waiting_progress(
    nodes: list
) - > null

Logs a progress indicator (dot) while waiting for nodes to exit.

Parameters

Name	Type	Description
nodes	`list`	The list of nodes still being waited upon.

Returns

Type	Description
`null`	null

`on_still_waiting_end()`

@classmethod
def on_still_waiting_end() - > null

Finalizes the progress logging line for waiting operations.

Returns

Type	Description
`null`	null

`on_node_signal_dead()`

@classmethod
def on_node_signal_dead(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node)
) - > null

Logs an error when a signal cannot be sent because the node process does not exist.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The node that could not be signaled.

Returns

Type	Description
`null`	null

`on_node_start()`

@classmethod
def on_node_start(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node)
) - > null

Logs the initiation of a node startup.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The node being started.

Returns

Type	Description
`null`	null

`on_node_restart()`

@classmethod
def on_node_restart(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node)
) - > null

Logs the initiation of a node restart.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The node being restarted.

Returns

Type	Description
`null`	null

`on_node_down()`

@classmethod
def on_node_down(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node)
) - > null

Logs that a node is down or has stopped.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The node that is down.

Returns

Type	Description
`null`	null

`on_node_shutdown_ok()`

@classmethod
def on_node_shutdown_ok(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node)
) - > null

Logs a successful shutdown confirmation for a specific node.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The node that shut down successfully.

Returns

Type	Description
`null`	null

`on_node_status()`

@classmethod
def on_node_status(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node),
    retval: int
) - > null

Logs the success or failure status of a node operation based on its return value.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The node whose status is being reported.
retval	`int`	The exit code or return value of the node operation.

Returns

Type	Description
`null`	null

`on_node_signal()`

@classmethod
def on_node_signal(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node),
    sig: int
) - > null

Logs a message indicating a signal is being sent to a specific node.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The target node.
sig	`int`	The signal being sent.

Returns

Type	Description
`null`	null

`on_child_spawn()`

@classmethod
def on_child_spawn(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node),
    argstr: string,
    env: dict
) - > null

Logs the command-line string and environment used to spawn a child process.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The node being spawned.
argstr	`string`	The full command-line string executed.
env	`dict`	The environment variables passed to the child process.

Returns

Type	Description
`null`	null

`on_child_signalled()`

@classmethod
def on_child_signalled(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node),
    signum: int
) - > null

Logs that a child process was terminated by a system signal.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The node that was terminated.
signum	`int`	The signal number that caused termination.

Returns

Type	Description
`null`	null

`on_child_failure()`

@classmethod
def on_child_failure(
    node: [Node](../../apps/multi/node.md?sid=celery_apps_multi_node),
    retcode: int
) - > null

Logs that a child process failed and reports its exit code.

Parameters

Name	Type	Description
node	`[Node](../../apps/multi/node.md?sid=celery_apps_multi_node)`	The node that failed.
retcode	`int`	The non-zero exit code returned by the process.

Returns

Type	Description
`null`	null

`OK()`

@classmethod
def OK() - > string

Returns a colorized 'OK' string for status logging.

Returns

Type	Description
`string`	The formatted 'OK' status string.

`FAILED()`

@classmethod
def FAILED() - > string

Returns a colorized 'FAILED' string for status logging.

Returns

Type	Description
`string`	The formatted 'FAILED' status string.

`DOWN()`

@classmethod
def DOWN() - > string

Returns a colorized 'DOWN' string for status logging.

Returns

Type	Description
`string`	The formatted 'DOWN' status string.

Attributes​

Constructor​

Signature​

Parameters​

Methods​

execute_from_commandline()​

Parameters​

Returns​

validate_arguments()​

Parameters​

Returns​

call_command()​

Parameters​

Returns​

start()​

Parameters​

Returns​

stop()​

Parameters​

Returns​

stopwait()​

Parameters​

Returns​

restart()​

Parameters​

Returns​

names()​

Parameters​

Returns​

get()​

Parameters​

Returns​

show()​

Parameters​

Returns​

kill()​

Parameters​

Returns​

expand()​

Parameters​

Returns​

help()​

Parameters​

Returns​

cluster_from_argv()​

Parameters​

Returns​

Cluster()​

Parameters​

Returns​

on_stopping_preamble()​

Parameters​

Returns​

on_send_signal()​

Parameters​

Returns​

on_still_waiting_for()​

Parameters​

Returns​

on_still_waiting_progress()​

Parameters​

Returns​

on_still_waiting_end()​

Returns​

on_node_signal_dead()​

Parameters​

Returns​

on_node_start()​

Parameters​

Returns​

on_node_restart()​

Parameters​

Returns​

on_node_down()​

Parameters​

Returns​

on_node_shutdown_ok()​

Parameters​

Returns​

on_node_status()​

Attributes

Constructor

Signature

Parameters

Methods

`execute_from_commandline()`

Parameters

Returns

`validate_arguments()`

Parameters

Returns

`call_command()`

Parameters

Returns

`start()`

Parameters

Returns

`stop()`

Parameters

Returns

`stopwait()`

Parameters

Returns

`restart()`

Parameters

Returns

`names()`

Parameters

Returns

`get()`

Parameters

Returns

`show()`

Parameters

Returns

`kill()`

Parameters

Returns

`expand()`

Parameters

Returns

`help()`

Parameters

Returns

`cluster_from_argv()`

Parameters

Returns

`Cluster()`

Parameters

Returns

`on_stopping_preamble()`

Parameters

Returns

`on_send_signal()`

Parameters

Returns

`on_still_waiting_for()`

Parameters

Returns

`on_still_waiting_progress()`

Parameters

Returns

`on_still_waiting_end()`

Returns

`on_node_signal_dead()`

Parameters

Returns

`on_node_start()`

Parameters

Returns

`on_node_restart()`

Parameters

Returns

`on_node_down()`

Parameters

Returns

`on_node_shutdown_ok()`

Parameters

Returns

`on_node_status()`