3~h40ddlmZddlmZddlmZddlmZGddeZ Gdd e Z d Z Gd d e Z Gd de Zy))Queue)ExceptionHandlingThread) Connection)GroupExceptioncVeZdZdZdZedZdZdZdZ dZ dZ d Z d Z d Zy ) Groupak 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") { : , : , } 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?") { : , : , : 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. c `|j|Dcgc]}t|fi|c}ycc}w)a 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``). N)extendr)selfhostskwargshosts U/var/www/peopleoo.sandbox-dev.co.uk/venv/lib/python3.12/site-packages/fabric/group.py__init__zGroup.__init__?s(* EBDZ//BCBs+c6|}|j||S)zg Alternate constructor accepting `.Connection` objects. .. versionadded:: 2.0 )r )cls connectionsgroups rfrom_connectionszGroup.from_connectionsVs [! ctN)NotImplementedError)r methodargsrs r_doz Group._docs "!rc.|jdg|i|S)z Executes `.Connection.run` on all member `Connections <.Connection>`. :returns: a `.GroupResult`. .. versionadded:: 2.0 runrr rrs rrz Group.runhstxx////rc.|jdg|i|S)z Executes `.Connection.sudo` on all member `Connections <.Connection>`. :returns: a `.GroupResult`. .. versionadded:: 2.6 sudor r!s rr#z Group.sudovstxx0000rc.|jdg|i|S)a 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 putr r!s rr%z Group.putstxx////rc\t|dkr d|vrd|d<|jdg|i|S)a 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 localz{host}/get)lenrr!s rr)z Group.gets:: t9q=WF2'F7Otxx////rc2|D]}|jy)zx Executes `.Connection.close` on all member `Connections <.Connection>`. .. versionadded:: 2.4 Nclose)r cxns rr-z Group.closes  C IIK rc|Srr s r __enter__zGroup.__enter__s rc$|jyrr,)r excs r__exit__zGroup.__exit__s  rN)__name__ __module__ __qualname____doc__r classmethodrrrr#r%r)r-r2r5r0rrr r sK3jD.  " 0 1*0 0Brr ceZdZdZdZy) SerialGroupzc Subclass of `.Group` which executes in simple, serial fashion. .. versionadded:: 2.0 ct}d}|D]} t|||i|||<|r t||S#t$r}|||<d}Yd}~?d}~wwxYw)NFT) GroupResultgetattr Exceptionr)r rrrresultsexceptedr.es rrzSerialGroup._doss- C 3wsF3TDVD   ) )     s9 AAANr6r7r8r9rr0rrr<r<s  rr<cNt|||i|}|j||fyr)r?r%)r.queuerrrresults r thread_workerrHs* !WS& !4 26 2F IIsFmrceZdZdZdZy)ThreadingGroupzg Subclass of `.Group` which uses threading to execute concurrently. .. versionadded:: 2.0 c  t}t}g}|D]2}ttt |||||}|j |4|D]}|j |D]}|j|js+|jd\}} | ||<|js+d} |D]8}|j} | | jdd}| j||<d} :| r t||S)N)r.rFrrr)targetrF)blockrr.T)r>rrrHdictappendstartjoinemptyr) exceptionrvaluer) r rrrrArFthreadsr.threadrGrBwrappers rrzThreadingGroup._dos#- #C,$!!  F NN6 " # F LLN  F KKM ++-))%)0KC"GCL ++- F&&(G"nnX.u5&}}    ) )rNrDr0rrrJrJs  -rrJcHeZdZdZfdZdZedZedZxZ S)r>a 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. .. versionadded:: 2.0 c@t||i|i|_i|_yr)superr _successes _failures)r rr __class__s rrzGroupResult.__init__3s# $)&)rc|js |jry|jD]4\}}t|tr||j|<&||j|<6yr)r[r\items isinstance BaseException)r keyrTs r _bifurcatezGroupResult._bifurcate8sS ??dnn **, -JC%/&+s#',$  -rc:|j|jS)z_ A sub-dict containing only successful results. .. versionadded:: 2.0 )rcr[r1s r succeededzGroupResult.succeededDs rc:|j|jS)z[ A sub-dict containing only failed results. .. versionadded:: 2.0 )rcr\r1s rfailedzGroupResult.failedNs ~~r) r6r7r8r9rrcpropertyrerg __classcell__)r]s@rr>r>s:( -rr>N)rFr invoke.utilr connectionr exceptionsrlistr r<rHrJrNr>r0rrrnsJ/"&@D@F%* 4U4n8$8r