fabric.group.Group

class documentation

class Group(list): (source)

Known subclasses: fabric.group.SerialGroup, fabric.group.ThreadingGroup

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. `~invoke.exceptions.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. .. versionadded:: 2.0 .. versionchanged:: 2.4 Added context manager behavior.

Class Method	`from_connections`	Alternate constructor accepting `.Connection` objects.
Method	`__enter__`	Undocumented
Method	`__exit__`	Undocumented
Method	`__init__`	Create a group of connections from one or more shorthand host strings.
Method	`close`	Executes `.Connection.close` on all member `Connections <.Connection>`.
Method	`get`	Executes `.Connection.get` on all member `Connections <.Connection>`.
Method	`put`	Executes `.Connection.put` on all member `Connections <.Connection>`.
Method	`run`	Executes `.Connection.run` on all member `Connections <.Connection>`.
Method	`sudo`	Executes `.Connection.sudo` on all member `Connections <.Connection>`.
Method	`_do`	Undocumented

@classmethod
def from_connections(cls, connections): (source) ¶

Alternate constructor accepting `.Connection` objects. .. versionadded:: 2.0

def __enter__(self): (source) ¶

Undocumented

def __exit__(self, *exc): (source) ¶

Undocumented

def __init__(self, *hosts, **kwargs): (source) ¶

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, ) .. versionchanged:: 2.3 Added ``**kwargs`` (was previously only ``*hosts``).

def close(self): (source) ¶

Executes `.Connection.close` on all member `Connections <.Connection>`. .. versionadded:: 2.4

def get(self, *args, **kwargs): (source) ¶

Executes `.Connection.get` on all member `Connections <.Connection>`. .. 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. .. versionadded:: 2.6

def put(self, *args, **kwargs): (source) ¶

Executes `.Connection.put` on all member `Connections <.Connection>`. 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. .. versionadded:: 2.6

def run(self, *args, **kwargs): (source) ¶

Executes `.Connection.run` on all member `Connections <.Connection>`. :returns: a `.GroupResult`. .. versionadded:: 2.0

def sudo(self, *args, **kwargs): (source) ¶

Executes `.Connection.sudo` on all member `Connections <.Connection>`. :returns: a `.GroupResult`. .. versionadded:: 2.6

def _do(self, method, *args, **kwargs): (source) ¶

overridden in fabric.group.SerialGroup, fabric.group.ThreadingGroup

Undocumented