Node reference


Maybe it’s useful to read the read about the node object first.

class deployer.node.base.Action(attr_name, node_instance, func, is_property=False, is_query=False, query=None)

Node actions, which are defined as just functions, will be wrapped into this Action class. When one such action is called, this class will make sure that a correct env object is passed into the function as its first argument. :param node_instance: The Node Env to which this Action is bound. :type node_instance: None or deployer.node.Env

class deployer.node.base.Env(node, pty=None, logger=None, is_sandbox=False)

Wraps a deployer.node.Node into an executable context.

n = Node()
e = Env(n)

Instead of self, the first parameter of a Node-action will be this Env instance. It acts like a proxy to the Node, but in the meantime it takes care of logging, sandboxing, the terminal and context.


Node actions can never be executed directly on the node instance, without wrapping it in an Env object first. But if you use the interactive shell, the shell will do this for you.

  • node (deployer.node.Node) – The node that this Env should wrap.
  • pty (deployer.pseudo_terminal.Pty) – The terminal object that wraps the input and output streams.
  • logger (deployer.logger.LoggerInterface) – (optional) The logger interface.
  • is_sandbox (bool) – Run all commands in here in sandbox mode.

Interface for user input. Returns a deployer.console.Console instance.

classmethod default_from_node(node)

Create a default environment for this node to run.

It will be attached to stdin/stdout and commands will be logged to stdout. The is the most obvious default to create an Env instance.

Parameters:nodeNode instance

deployer.host_container.HostsContainer instance. This is the proxy to the actual hosts.


Dynamically initialize a node from within another node. This will make sure that the node class is initialized with the correct logger, sandbox and pty settings. e.g:

Parameters:node_class – A Node subclass.
class SomeNode(Node):
    def action(self):

class RootNode(Node):
    def action(self):
        # Wrap SomeNode into an Env object
        node = self.initialize_node(SomeNode)

        # Use the node.
class deployer.node.base.EnvAction(env, action)

Action wrapped by an Env object. Calling this will execute the action in the environment.

class deployer.node.base.IsolationIdentifierType

Manners of identifing a node in an array of nodes.


Use a tuple of Host slugs


Use a tuple of Host classes


Use a tuple of integers

class deployer.node.base.Node(parent=None)

This is the base class for any deployment node.

For the attributes, also have a look at the proxy class deployer.node.Env. The parent parameter is used internally to pass the parent Node instance into here.

Hosts = None

Hosts can be None or a definition of the hosts that should be used for this node. e.g.:

class MyNode(Node):
    class Hosts:
        role1 = [ LocalHost ]
        role2 = [ SSHHost1, SSHHost2]

Reference to the parent Node. (This is always assigned in the constructor. You should never override it.)

class deployer.node.base.NodeBase

Metaclass for Node. This takes mostly care of wrapping Node members into the correct descriptor, but it does some metaclass magic.

class deployer.node.base.ParallelActionResult(isolations_and_results)

When an action of a ParallelNode was called from outside the parallel node itself, a ParallelActionResult instance is returned. This contains the result for each isolation.

(Unconventional, but) Iterating through the ParallelActionResult class will yield the values (the results) instead of the keys, because of backwards compatibility and this is typically what people are interested in if they run: for result in node.action(...).

The keys, items and values functions work as usual.

class deployer.node.base.ParallelNode(parent=None)

A ParallelNode is a Node which has only one role, named host. Multiple hosts can be given for this role, but all of them will be isolated, during execution. This allows parallel executing of functions on each ‘cell’.

If you call a method on a ParallelNode, it will be called one for every host, which can be accessed through the host property.

Note:This was called SimpleNode before.

This is the proxy to the active host.

Returns:HostContainer instance.

Deprecated alias for ParallelNode

alias of ParallelNode


Deprecated alias for ParallelNodeBase

alias of ParallelNodeBase

deployer.node.base.iter_isolations(node, identifier_type='INT_TUPLES')

Yield (index, Node) for each isolation of this node.

class deployer.node.base.required_property(description='')

Placeholder for properties which are required when a service is inherit.

class MyNode(Node):
    name = required_property()

    def method(self):
        # This will raise an exception, unless this class was
        # inherited, and `name` was filled in.
        print (



When using a deployment shell, don’t print the returned result to stdout. For example, when the result is superfluous to be printed, because the action itself contains already print statements, while the result can be useful for the caller.


If the node has not yet been separated in serveral parallel, isolated nodes per host. Don’t do it yet for this function. When anothor action of the same host without this decorator is called, the node will be split.

It’s for instance useful for reading input, which is similar for all isolated executions, (like asking which Git Checkout has to be taken), before forking all the threads.

Note that this will not guarantee that a node will not be split into its isolations, it does only say, that it does not have to. It is was already been split before, and this is called from a certain isolation, we’ll keep it like that.


When using role isolation, and several hosts are available, run on only one role. Useful for instance, for a database client. it does not make sense to run the interactive client on every host which has database access.


Give this node action an alias. It will also be accessable using that name in the deployment shell. This is useful, when you want to have special characters which are not allowed in Python function names, like dots, in the name of an action.

Role mapping

deployer.node.role_mapping.ALL_HOSTS = ALL_HOSTS

Constant to indicate in a role mapping that all hosts of the parent should be mapped to this role.


alias of RoleMapping

class deployer.node.role_mapping.DefaultRoleMapping(*host_mapping, **mappings)

Default mapping: take the host container from the parent.