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 mirror those of Connection, taking the same arguments; however their return values and exception-raising behavior differs:

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

Returns:a GroupResult.

New in version 2.0.

run(*args, **kwargs)

Executes Connection.run on all member Connections.

Returns:a GroupResult.

New in version 2.0.

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)

failed

A sub-dict containing only failed results.

New in version 2.0.

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.