o Th @sddlZddlZddlZddlZddlZddlZddlZddlZddlm Z m Z ddl m Z ddl mZmZmZmZmZmZmZmZmZmZzddlZWn eyWdZYnwzddlZWn eyidZYnwzddlZWn ey{dZYnwddlmZmZmZm Z m!Z!m"Z"ddl#m$Z$m%Z%m&Z&m'Z'm(Z(ddl)m*Z*m+Z+m,Z,erdd l-m.Z.dd l/m0Z0Gd d d Z1Gd dde1Z2GdddZ3Gddde3Z4  ddedee5dee5dee5dffddZ6de5fddZ7dS)N)PopenPIPE) TracebackType) TYPE_CHECKINGAnyCallableDict GeneratorIOListOptionalTupleType)UnexpectedExitFailureThreadException WatcherErrorSubprocessPipeErrorCommandTimedOut)WINDOWSpty_sizecharacter_bufferedready_for_reading bytes_to_read) has_filenoisattyExceptionHandlingThread)Context) StreamWatcherc @sneZdZUdZeeefed<eed<dZ dZ dsd d Z d ed ede dfddZ d edd fddZd ed edd fddZd ed ede dfddZdtddZduddZd edd fddZdeeddfdd Zd!ede efd"d#Zdeeeefeeeeffd$d%Zd eddfd&d'Zd(edeed d ffd)d*Zd+e d,edd fd-d.Z!d/eed0ed1e d(edd f d2d3Z"d/eed0ed1e dd fd4d5Z#d/eed0ed1e dd fd6d7Z$d8e de efd9d:Z% ;dvd8e d1e dZ&d8e d1e defd?d@Z'd/eedd fdAdBZ(dCeeefdDedeeeffdEdFZ)dGedHedefdIdJZ*e+defdKdLZ,dwdMdNZ-dOedd fdPdQZ.dOe/defdRdSZ0e+defdTdUZ1d edVedCeeefdd fdWdXZ2dYedd fdZd[Z3d\ede e/fd]d^Z4d\ede e/fd_d`Z5dOe/dd fdadbZ6dwdcddZ7defdedfZ8dxdidjZ9de efdkdlZ:dwdmdnZ;dwdodpZCannot give both 'asynchronous' and 'disown' at the same time!rDTFr?rL out_stream err_stream in_streamrEfallbackr,)outerrin)r#configr;rdpoptimeoutsr5 TypeErrorr>listkeysr.r/ ValueErrornormalize_hidesysrOrPstdinshould_use_ptyr"r,r!streams) r1r6r!keyrhruntimeconfig_timeoutrzrurvrwr2r2r3rF sD         z Runner._unify_kwargs_with_configrnc Csvd|j}d|j}tr"|dddd}|dddd}|r&dn|}|jdit|j|||d}|S)NrMz   rNr2) rerOrPrreplace returncoderSrIrJ)r1rnrOrPrQrrr2r2r3rkEs   zRunner._collate_resultrpcCsB||jkrdS|j}||jkr|j}||jvr|j|jrdSdS)Nr) handle_stdin handle_stderr handle_stdoutrWis_dead)r1rpoppositer2r2r3rfas  zRunner._thread_join_timeoutcCsg}g}|j|d|jdv|jddi}|jdr,|jd|jd|jdd||j<|js@|d|jdv|jd d||j<i}|D]\}}t||d }|||<qF|||fS) z Create and return a dictionary of IO thread worker objects. Caller is expected to handle persisting and/or starting the wrapped threads. rOrDry)buffer_rDoutputr{ echo_stdin)input_rr?rPrz)rpr6)rr!rrr"rrdr)r1rOrP thread_argsrWrpr6tr2r2r3rVqs.         zRunner.create_io_threadscKstdi|S)a4 Create & return a suitable `Result` instance from the given ``kwargs``. Subclasses may wish to override this in order to manipulate things or generate a `Result` subclass (e.g. ones containing additional metadata besides the default). .. versionadded:: 1.0 Nr2)r7)r1r6r2r2r3rSs zRunner.generate_resultreaderccs$ ||j}|s dS||Vq)a Iteratively read & decode bytes from a subprocess' out/err stream. :param reader: A literal reader function/partial, wrapping the actual stream object in question, which takes a number of bytes to read, and returns that many bytes (or ``None``). ``reader`` should be a reference to either `read_proc_stdout` or `read_proc_stderr`, which perform the actual, platform/library specific read calls. :returns: A generator yielding strings. Specifically, each resulting string is the result of decoding `read_chunk_size` bytes read from the subprocess' out/err stream. .. versionadded:: 1.0 TN)r)decode)r1rdatar2r2r3read_proc_outputs  zRunner.read_proc_outputstreamstringcCs|||dS)a Write ``string`` to ``stream``. Also calls ``.flush()`` on ``stream`` to ensure that real terminal streams don't buffer. :param stream: A file-like stream object, mapping to the ``out_stream`` or ``err_stream`` parameters of `run`. :param string: A Unicode string object. :returns: ``None``. .. versionadded:: 1.0 N)writeflush)r1rrr2r2r3write_our_outputs  zRunner.write_our_outputrrDrcCs:||D]}|s|j||d||||qdS)Nrr)rrrjrespond)r1rrDrrrr2r2r3_handle_outputs   zRunner._handle_outputcC|j||||jddS)a  Read process' stdout, storing into a buffer & printing/parsing. Intended for use as a thread target. Only terminates when all stdout from the subprocess has been read. :param buffer_: The capture buffer shared with the main thread. :param bool hide: Whether or not to replay data into ``output``. :param output: Output stream (file-like object) to write data into when not hiding. :returns: ``None``. .. versionadded:: 1.0 rN)rread_proc_stdoutr1rrDrr2r2r3rs  zRunner.handle_stdoutcCr)z Read process' stderr, storing into a buffer & printing/parsing. Identical to `handle_stdout` except for the stream read from; see its docstring for API details. .. versionadded:: 1.0 rN)rread_proc_stderrrr2r2r3r s  zRunner.handle_stderrrc Csnd}t|r5z |t|}Wnty(}z |jtjkrWYd}~nd}~ww|r5t|tr5||}|S)a  Read & decode bytes from a local stdin stream. :param input_: Actual stream object to read from. Maps to ``in_stream`` in `run`, so will often be ``sys.stdin``, but might be any stream-like object. :returns: A Unicode string, the result of decoding the read bytes (this might be the empty string if the pipe has closed/reached EOF); or ``None`` if stdin wasn't ready for reading yet. .. versionadded:: 1.0 N) rreadrOSErrorerrnoEBADFribytesr)r1rbytes_rmr2r2r3read_our_stdins   zRunner.read_our_stdinFr?cCsd}t|H ||}|r(|||dur|||}|r'|j||dn|dur7|js7|s7|d}|jr?|s?nt |j qWddS1sQwYdS)a Read local stdin, copying into process' stdin as necessary. Intended for use as a thread target. .. note:: Because real terminal stdin streams have no well-defined "end", if such a stream is detected (based on existence of a callable ``.fileno()``) this method will wait until `program_finished` is set, before terminating. When the stream doesn't appear to be from a terminal, the same semantics as `handle_stdout` are used - the stream is simply ``read()`` from until it returns an empty value. :param input_: Stream (file-like object) from which to read. :param output: Stream (file-like object) to which echoing may occur. :param bool echo: User override option for stdin-stdout echoing. :returns: ``None``. .. versionadded:: 1.0 FTNr) rrwrite_proc_stdinshould_echo_stdinrr"close_proc_stdinr'is_settimesleepr*)r1rrr? closed_stdinrr2r2r3rBs*"      "zRunner.handle_stdincCs|j ot|S)aW Determine whether data read from ``input_`` should echo to ``output``. Used by `handle_stdin`; tests attributes of ``input_`` and ``output``. :param input_: Input stream (file-like object). :param output: Output stream (file-like object). :returns: A ``bool``. .. versionadded:: 1.0 )r"r)r1rrr2r2r3rs zRunner.should_echo_stdincCs4d|}|jD]}||D]}||qqdS)a Write to the program's stdin in response to patterns in ``buffer_``. The patterns and responses are driven by the `.StreamWatcher` instances from the ``watchers`` kwarg of `run` - see :doc:`/concepts/watchers` for a conceptual overview. :param buffer: The capture buffer for this thread's particular IO stream. :returns: ``None``. .. versionadded:: 1.0 rMN)rer,submitr)r1rrwatcherresponser2r2r3rs   zRunner.respondr@rAcCs|r|Sttjfi|S)a~ Return a suitable environment dict based on user input & behavior. :param dict env: Dict supplying overrides or full env, depending. :param bool replace_env: Whether ``env`` updates, or is used in place of, the value of `os.environ`. :returns: A dictionary of shell environment vars. .. versionadded:: 1.0 )rIosenviron)r1r@rAr2r2r3rGszRunner.generate_envrErxcCs|S)al Should execution attempt to use a pseudo-terminal? :param bool pty: Whether the user explicitly asked for a pty. :param bool fallback: Whether falling back to non-pty execution should be allowed, in situations where ``pty=True`` but a pty could not be allocated. .. versionadded:: 1.0 r2)r1rErxr2r2r3r zRunner.should_use_ptycCstdd|jDS)a Detect whether any IO threads appear to have terminated unexpectedly. Used during process-completion waiting (in `wait`) to ensure we don't deadlock our child process if our IO processing threads have errored/died. :returns: ``True`` if any threads appear to have terminated with an exception, ``False`` otherwise. .. versionadded:: 1.0 css|]}|jVqdSN)r).0xr2r2r3 sz*Runner.has_dead_threads..)anyrWrXr]r2r2r3has_dead_threadsszRunner.has_dead_threadscCs( |j}|j}|s |r dSt|jq)z Block until the running command appears to have exited. :returns: ``None``. .. versionadded:: 1.0 TN)process_is_finishedrrrr*)r1 proc_finished dead_threadsr2r2r3r`s z Runner.waitrcCs|||jdS)z Write encoded ``data`` to the running process' stdin. :param data: A Unicode string. :returns: ``None``. .. versionadded:: 1.0 N)_write_proc_stdinencoderBr1rr2r2r3rs zRunner.write_proc_stdincCs||jdS)z_ Decode some ``data`` bytes, returning Unicode. .. versionadded:: 1.0 r)rrBrr2r2r3rsz Runner.decodecCt)a^ Determine whether our subprocess has terminated. .. note:: The implementation of this method should be nonblocking, as it is used within a query/poll loop. :returns: ``True`` if the subprocess has finished running, ``False`` otherwise. .. versionadded:: 1.0 NotImplementedErrorr]r2r2r3rszRunner.process_is_finishedrCcCr)ai Initiate execution of ``command`` (via ``shell``, with ``env``). Typically this means use of a forked subprocess or requesting start of execution on a remote system. In most cases, this method will also set subclass-specific member variables used in other methods such as `wait` and/or `returncode`. :param str command: Command string to execute. :param str shell: Shell to use when executing ``command``. :param dict env: Environment dict used to prep shell environment. .. versionadded:: 1.0 r)r1r5rCr@r2r2r3rTsz Runner.startrRcCs*|durt||j|_|jdSdS)zS Start a timer to `kill` our subprocess after ``timeout`` seconds. N)r%Timerkillr-rT)r1rRr2r2r3rU-szRunner.start_timer num_bytescCr)z Read ``num_bytes`` from the running process' stdout stream. :param int num_bytes: Number of bytes to read at maximum. :returns: A string/bytes object. .. versionadded:: 1.0 rr1rr2r2r3r5 zRunner.read_proc_stdoutcCr)z Read ``num_bytes`` from the running process' stderr stream. :param int num_bytes: Number of bytes to read at maximum. :returns: A string/bytes object. .. versionadded:: 1.0 rrr2r2r3rArzRunner.read_proc_stderrcCr)aF Write ``data`` to running process' stdin. This should never be called directly; it's for subclasses to implement. See `write_proc_stdin` for the public API call. :param data: Already-encoded byte data suitable for writing. :returns: ``None``. .. versionadded:: 1.0 rrr2r2r3rMrzRunner._write_proc_stdincCr)zk Close running process' stdin. :returns: ``None``. .. versionadded:: 1.3 rr]r2r2r3r\szRunner.close_proc_stdincCstS)z Return a string naming the expected encoding of subprocess streams. This return value should be suitable for use by encode/decode methods. .. versionadded:: 1.0 )rHr]r2r2r3rHfs zRunner.default_encoding interruptracCs|ddS)a Submit an interrupt signal to the running subprocess. In almost all implementations, the default behavior is what will be desired: submit ```` to the subprocess' stdin pipe. However, we leave this as a public method in case this default needs to be augmented or replaced. :param interrupt: The locally-sourced ``KeyboardInterrupt`` causing the method call. :returns: ``None``. .. versionadded:: 1.0 N)r)r1rr2r2r3rbrszRunner.send_interruptcCr)a Return the numeric return/exit code resulting from command execution. :returns: `int`, if any reasonable return code could be determined, or ``None`` in corner cases where that was not possible. .. versionadded:: 1.0 rr]r2r2r3rrzRunner.returncodecCs|jr |jdSdS)aM Perform final cleanup, if necessary. This method is called within a ``finally`` clause inside the main `run` method. Depending on the subclass, it may be a no-op, or it may do things such as close network connections or open files. :returns: ``None`` .. versionadded:: 1.0 N)r-cancelr]r2r2r3r9s z Runner.stopcCr)aS Forcibly terminate the subprocess. Typically only used by the timeout functionality. This is often a "best-effort" attempt, e.g. remote subprocesses often must settle for simply shutting down the local side of the network connection and hoping the remote end eventually gets the message. rr]r2r2r3rrz Runner.killcCst|jo |j S)zq Returns ``True`` if the subprocess stopped because it timed out. .. versionadded:: 1.3 )boolr-is_aliver]r2r2r3rls zRunner.timed_outr#rr$Nr$r\)r$r7)Fr$N)rrar$N)>__name__ __module__ __qualname____doc__rstrr__annotations__rr)r*r4r r;r?rKr8rYrZrFr rrkrintrfr rrVrSr rr rrrrrrrrrGrpropertyrr`rrrrrTrUrrrrrHrbrr9rrlr2r2r2r3r =s   0  << * !   , B     "     r cseZdZdZd%fdd Zd&d ed edefd d Zdedee fddZ dedee fddZ de ddfddZ d'ddZ dededeeefddfddZd'ddZedefdd Zdeefd!d"Zd'fd#d$ ZZS)(LocalaF Execute a command on the local system in a subprocess. .. note:: When Invoke itself is executed without a controlling terminal (e.g. when ``sys.stdin`` lacks a useful ``fileno``), it's not possible to present a handle on our PTY to local subprocesses. In such situations, `Local` will fallback to behaving as if ``pty=False`` (on the theory that degraded execution is better than none at all) as well as printing a warning to stderr. To disable this behavior, say ``fallback=False``. .. versionadded:: 1.0 r#rr$Ncst|d|_dSNr)superr4statusr0r(r2r3r4s  zLocal.__init__FTrErxcCs>d}|rd}ttjs|r|jsd}tj|d|_d}|S)NFTzAWARNING: stdin has no fileno; falling back to non-pty execution! )rrrr+rPr)r1rErxuse_ptyrzr2r2r3rs zLocal.should_use_ptyrc s|jr5z t|j|}W|Sty4}zt|d}tfdd|Ds'd}WYd}~|Sd}~ww|jrH|jjrHt|jj |}|Sd}|S)N)zInput/output errorz I/O errorc3s|]}|vVqdSrr2)rerror stringifiedr2r3rsz)Local.read_proc_stdout..) r"rr parent_fdrrrprocessrOfileno)r1rrrm io_errorsr2rr3rs$zLocal.read_proc_stdoutcCs&|jr|jjrt|jj|SdSr)rrPrrrrr2r2r3rszLocal.read_proc_stderrrc Csz|jr|j}n|jr|jjr|jj}ntdz t||WdSty<}zdt |vr1WYd}~dSd}~ww)Nz/Unable to write to missing subprocess or stdin!z Broken pipe) r"rrrrrrrrr)r1rfdrmr2r2r3rs zLocal._write_proc_stdincCs4|jrtd|jr|jjr|jjdStd)Nz Cannot close stdin when pty=Truez,Unable to close missing subprocess or stdin!)r"rrrcloser]r2r2r3rszLocal.close_proc_stdinr5rCr@c Cs|jrBtdurd}t|t\}}t\|_|_|jdkr@t d||dd}t tj tj|t||d|g|dSdSt|d||tttd|_dS)NzKYou indicated pty=True, but your platform doesn't support the 'pty' module!rHHHHz-cT)rC executabler@rOrPr)r"rErexitrforkpidrstructpackfcntlioctlrOrtermios TIOCSWINSZrexecverrr)r1r5rCr@rzcolsrowswinsizer2r2r3rTs(     z Local.startcCs>|jr|jn|jj}z t|tjWdStyYdSwr)r"rrrrsignalSIGKILLProcessLookupError)r1rr2r2r3rCs  z Local.killcCs2|jrt|jtj\}|_|dkS|jduSr)r"rwaitpidrWNOHANGrrpoll)r1pid_valr2r2r3rLszLocal.process_is_finishedcCsR|jr%d}t|jrt|j}|St|jr#t|j}d|}|S|jjS)N) r"r WIFEXITEDr WEXITSTATUS WIFSIGNALEDWTERMSIGrr)r1coder2r2r3r[s   zLocal.returncodecs<t|jrz t|jWdStyYdSwdSr)rr9r"rrr Exceptionr]rr2r3r9ps  z Local.stopr)FTr)rrrrr4rrrr rrrrrrrrrTrrrrr9 __classcell__r2r2rr3rs  " ' rc@seZdZdZddddddddef dededeed ed ed eeeefd e d e de edffddZ e de fddZde fddZdefddZdefddZe de fddZe de fddZd$d ed!e defd"d#ZdS)%r7a A container for information about the result of a command execution. All params are exposed as attributes of the same name and type. :param str stdout: The subprocess' standard output. :param str stderr: Same as ``stdout`` but containing standard error (unless the process was invoked via a pty, in which case it will be empty; see `.Runner.run`.) :param str encoding: The string encoding used by the local shell environment. :param str command: The command which was executed. :param str shell: The shell binary used for execution. :param dict env: The shell environment used for execution. (Default is the empty dict, ``{}``, not ``None`` as displayed in the signature.) :param int exited: An integer representing the subprocess' exit/return code. .. note:: This may be ``None`` in situations where the subprocess did not run to completion, such as when auto-responding failed or a timeout was reached. :param bool pty: A boolean describing whether the subprocess was invoked with a pty or not; see `.Runner.run`. :param tuple hide: A tuple of stream names (none, one or both of ``('stdout', 'stderr')``) which were hidden from the user when the generating command executed; this is a normalized value derived from the ``hide`` parameter of `.Runner.run`. For example, ``run('command', hide='stdout')`` will yield a `Result` where ``result.hide == ('stdout',)``; ``hide=True`` or ``hide='both'`` results in ``result.hide == ('stdout', 'stderr')``; and ``hide=False`` (the default) generates ``result.hide == ()`` (the empty tuple.) .. note:: `Result` objects' truth evaluation is equivalent to their `.ok` attribute's value. Therefore, quick-and-dirty expressions like the following are possible:: if run("some shell command"): do_something() else: handle_problem() However, remember `Zen of Python #2 `_. .. versionadded:: 1.0 rMNrFrOrPrBr5rCr@rQrErD.c CsT||_||_|dur t}||_||_||_|durin||_||_||_| |_ dSr) rOrPrHrBr5rCr@rQrErD) r1rOrPrBr5rCr@rQrErDr2r2r3r4s  zResult.__init__r$cC|jS)zJ An alias for ``.exited``. .. versionadded:: 1.0 )rQr]r2r2r3 return_codeszResult.return_codecCrrokr]r2r2r3__bool__szResult.__bool__cCsd|jdur d|j}nd}|g}dD]}t||}||r&d||nd|qd|S)NzCommand exited with status {}.z4Command was not fully executed due to watcher error.)rOrPz=== {} === {} z(no {})r)rQr>getattrrjrstripre)r1descretrvalr2r2r3__str__s   zResult.__str__cCsd}||j|jS)Nz)r>r5rQ)r1templater2r2r3__repr__szResult.__repr__cCst|jdkS)zY A boolean equivalent to ``exited == 0``. .. versionadded:: 1.0 r)rrQr]r2r2r3rsz Result.okcCs|j S)z The inverse of ``ok``. I.e., ``True`` if the program exited with a nonzero return code, and ``False`` otherwise. .. versionadded:: 1.0 rr]r2r2r3faileds z Result.failed rcountcCs"ddt||| dS)a Return the last ``count`` lines of ``stream``, plus leading whitespace. :param str stream: Name of some captured stream attribute, eg ``"stdout"``. :param int count: Number of lines to preserve. .. versionadded:: 1.3 z rN)rer splitlines)r1rrr2r2r3tails"z Result.tail)r)rrrrtuplerr rrrrr r4rrrrrrrr!r2r2r2r3r7~sPD   r7c@sXeZdZdZdddZdefdd Zdd d Zd ee e d e dee ddfddZ dS)r\a4 A promise of some future `Result`, yielded from asynchronous execution. This class' primary API member is `join`; instances may also be used as context managers, which will automatically call `join` when the block exits. In such cases, the context manager yields ``self``. `Promise` also exposes copies of many `Result` attributes, specifically those that derive from `~Runner.run` kwargs and not the result of command execution. For example, ``command`` is replicated here, but ``stdout`` is not. .. versionadded:: 1.4 runnerr r$NcCs,||_|jjD] \}}t|||q dS)z Create a new promise. :param runner: An in-flight `Runner` instance making this promise. Must already have started the subprocess and spun up IO threads. N)r#rJrdsetattr)r1r#rrhr2r2r3r45s zPromise.__init__cCs$z |jW|jS|jw)ak Block until associated subprocess exits, returning/raising the result. This acts identically to the end of a synchronously executed ``run``, namely that: - various background threads (such as IO workers) are themselves joined; - if the subprocess exited normally, a `Result` is returned; - in any other case (unforeseen exceptions, IO sub-thread `.ThreadException`, `.Failure`, `.WatcherError`) the relevant exception is raised here. See `~Runner.run` docs, or those of the relevant classes, for further details. )r#rZr9r]r2r2r3reDs z Promise.joincCs|Srr2r]r2r2r3 __enter__ZszPromise.__enter__exc_type exc_valueexc_tbcCs |dSr)re)r1r&r'r(r2r2r3__exit__]s zPromise.__exit__)r#r r$Nr) rrrrr4r7rer%r r BaseExceptionrr)r2r2r2r3r\%s   r\rrurvr$.cCsd}||vrd}t||||dvrg}n|dvr ddg}n|dkr(dg}n |dkr0dg}n|g}|dur@d|vr@|d|durMd|vrM|dt|S) N)NFryrOrzrPbothTz$'hide' got {!r} which is not in {!r})NF)r+TrOrPryrz)rr>remover")rrurv hide_valsrzrDr2r2r3rfs$   rcCstd}|S)z Obtain apparent interpreter-local default text encoding. Often used as a baseline in situations where we must use SOME encoding for unknown-but-presumably-text bytes, and the user has not specified an override. F)localegetpreferredencoding)rBr2r2r3rHs rH)NN)8rr.rrrr%rr subprocessrrtypesrtypingrrrrr r r r r rrE ImportErrorrr exceptionsrrrrrr terminalsrrrrrutilrrrr#rr,rr rr7r\rrrHr2r2r2r3sv 0         H(C