group

class fabric.group.Group(*hosts)

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(...),
}

New in version 2.0.

__init__(*hosts)

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

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

__weakref__

list of weak references to the object (if defined)

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)

Subclass of Group which executes in simple, serial fashion.

New in version 2.0.

class fabric.group.ThreadingGroup(*hosts)

Subclass of Group which uses threading to execute concurrently.

New in version 2.0.