group

class fabric.group.Group(*hosts, **kwargs)

A collection of Connection objects whose API operates on its contents.

Warning

This is a partially abstract class; you need to use one of its concrete subclasses (such as SerialGroup or ThreadingGroup) or you’ll get NotImplementedError on most of the methods.

Most methods in this class wrap those of Connection and will accept the same arguments; however their return values and exception-raising behavior differ:

• Return values are dict-like objects (GroupResult) mapping Connection objects to the return value for the respective connections: Group.run returns a map of Connection to runners.Result, Group.get returns a map of Connection to transfer.Result, etc.

• If any connections encountered exceptions, a GroupException is raised, which is a thin wrapper around what would otherwise have been the GroupResult returned; within that wrapped GroupResult, the excepting connections map to the exception that was raised, in place of a Result (as no Result was obtained.) Any non-excepting connections will have a Result value, as normal.

For example, when no exceptions occur, a session might look like this:

>>> group = SerialGroup('host1', 'host2')
>>> group.run("this is fine")
{
    <Connection host='host1'>: <Result cmd='this is fine' exited=0>,
    <Connection host='host2'>: <Result cmd='this is fine' exited=0>,
}

With exceptions (anywhere from 1 to “all of them”), it looks like so; note the different exception classes, e.g. UnexpectedExit for a completed session whose command exited poorly, versus socket.gaierror for a host that had DNS problems:

>>> group = SerialGroup('host1', 'host2', 'notahost')
>>> group.run("will it blend?")
{
    <Connection host='host1'>: <Result cmd='will it blend?' exited=0>,
    <Connection host='host2'>: <UnexpectedExit: cmd='...' exited=1>,
    <Connection host='notahost'>: gaierror(...),
}

As with Connection, Group objects may be used as context managers, which will automatically close the object on block exit.

New in version 2.0.

Changed in version 2.4: Added context manager behavior.

__init__(*hosts, **kwargs)

Create a group of connections from one or more shorthand host strings.

See Connection for details on the format of these strings - they will be used as the first positional argument of Connection constructors.

Any keyword arguments given will be forwarded directly to those Connection constructors as well. For example, to get a serially executing group object that connects to admin@host1, admin@host2 and admin@host3, and forwards your SSH agent too:

group = SerialGroup(
    "host1", "host2", "host3", user="admin", forward_agent=True,
)

Changed in version 2.3: Added **kwargs (was previously only *hosts).

__weakref__

list of weak references to the object (if defined)

close()

Executes Connection.close on all member Connections.

New in version 2.4.

classmethod from_connections(connections)

Alternate constructor accepting Connection objects.

New in version 2.0.

get(*args, **kwargs)

Executes Connection.get on all member Connections.

Note

This method changes some behaviors over e.g. directly calling Connection.get on a for loop of connections; the biggest is that the implied default value for the local parameter is "{host}/", which triggers use of local path parameterization based on each connection’s target hostname.

Thus, unless you override local yourself, a copy of the downloaded file will be stored in (relative) directories named after each host in the group.

Warning

Using file-like objects as the local argument is not currently supported, as it would be equivalent to supplying that same object to a series of individual get() calls.

Returns

a GroupResult whose values are transfer.Result instances.

New in version 2.6.

put(*args, **kwargs)

Executes Connection.put on all member Connections.

This is a straightforward application: aside from whatever the concrete group subclass does for concurrency or lack thereof, the effective result is like running a loop over the connections and calling their put method.

Returns

a GroupResult whose values are transfer.Result instances.

New in version 2.6.

run(*args, **kwargs)

Executes Connection.run on all member Connections.

Returns

a GroupResult.

New in version 2.0.

sudo(*args, **kwargs)

Executes Connection.sudo on all member Connections.

Returns

a GroupResult.

New in version 2.6.

class fabric.group.GroupResult(*args, **kwargs)

Collection of results and/or exceptions arising from Group methods.

Acts like a dict, but adds a couple convenience methods, to wit:

• Keys are the individual Connection objects from within the Group.

• Values are either return values / results from the called method (e.g. runners.Result objects), or an exception object, if one prevented the method from returning.

• Subclasses dict, so has all dict methods.

• Has succeeded and failed attributes containing sub-dicts limited to just those key/value pairs that succeeded or encountered exceptions, respectively.

  • Of note, these attributes allow high level logic, e.g. if mygroup.run('command').failed and so forth.

New in version 2.0.

__weakref__

list of weak references to the object (if defined)

property failed

A sub-dict containing only failed results.

New in version 2.0.

property succeeded

A sub-dict containing only successful results.

New in version 2.0.

class fabric.group.SerialGroup(*hosts, **kwargs)

Subclass of Group which executes in simple, serial fashion.

New in version 2.0.

class fabric.group.ThreadingGroup(*hosts, **kwargs)

Subclass of Group which uses threading to execute concurrently.

New in version 2.0.