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
orThreadingGroup
) or you’ll getNotImplementedError
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
) mappingConnection
objects to the return value for the respective connections:Group.run
returns a map ofConnection
torunners.Result
,Group.get
returns a map ofConnection
totransfer.Result
, etc.If any connections encountered exceptions, a
GroupException
is raised, which is a thin wrapper around what would otherwise have been theGroupResult
returned; within that wrappedGroupResult
, the excepting connections map to the exception that was raised, in place of aResult
(as noResult
was obtained.) Any non-excepting connections will have aResult
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, versussocket.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 automaticallyclose
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 ofConnection
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 toadmin@host1
,admin@host2
andadmin@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 memberConnections
.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 memberConnections
.Note
This method changes some behaviors over e.g. directly calling
Connection.get
on afor
loop of connections; the biggest is that the implied default value for thelocal
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 individualget()
calls.- Returns
a
GroupResult
whose values aretransfer.Result
instances.
New in version 2.6.
- put(*args, **kwargs)¶
Executes
Connection.put
on all memberConnections
.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 aretransfer.Result
instances.
New in version 2.6.
- run(*args, **kwargs)¶
Executes
Connection.run
on all memberConnections
.- Returns
a
GroupResult
.
New in version 2.0.
- sudo(*args, **kwargs)¶
Executes
Connection.sudo
on all memberConnections
.- 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 theGroup
.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
andfailed
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.