diff options
Diffstat (limited to 'lldb/third_party/Python/module/pexpect-4.6/doc')
19 files changed, 2072 insertions, 0 deletions
diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/FAQ.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/FAQ.rst new file mode 100644 index 00000000000..1964b12002a --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/FAQ.rst @@ -0,0 +1,145 @@ +FAQ +=== + +**Q: Where can I get help with pexpect? Is there a mailing list?** + +A: You can use the `pexpect tag on Stackoverflow <http://stackoverflow.com/questions/tagged/pexpect>`__ +to ask questions specifically related to Pexpect. For more general Python +support, there's the python-list_ mailing list, and the `#python`_ +IRC channel. Please refrain from using github for general +python or systems scripting support. + +.. _python-list: https://mail.python.org/mailman/listinfo/python-list +.. _#python: https://www.python.org/community/irc/ + +**Q: Why don't shell pipe and redirect (| and >) work when I spawn a command?** + +A: Remember that Pexpect does NOT interpret shell meta characters such as +redirect, pipe, or wild cards (``>``, ``|``, or ``*``). That's done by a shell not +the command you are spawning. This is a common mistake. If you want to run a +command and pipe it through another command then you must also start a shell. +For example:: + + child = pexpect.spawn('/bin/bash -c "ls -l | grep LOG > log_list.txt"') + child.expect(pexpect.EOF) + +The second form of spawn (where you pass a list of arguments) is useful in +situations where you wish to spawn a command and pass it its own argument list. +This can make syntax more clear. For example, the following is equivalent to the +previous example:: + + shell_cmd = 'ls -l | grep LOG > log_list.txt' + child = pexpect.spawn('/bin/bash', ['-c', shell_cmd]) + child.expect(pexpect.EOF) + +**Q: The `before` and `after` properties sound weird.** + +A: This is how the -B and -A options in grep works, so that made it +easier for me to remember. Whatever makes my life easier is what's best. +Originally I was going to model Pexpect after Expect, but then I found +that I didn't actually like the way Expect did some things. It was more +confusing. The `after` property can be a little confusing at first, +because it will actually include the matched string. The `after` means +after the point of match, not after the matched string. + +**Q: Why not just use Expect?** + +A: I love it. It's great. I has bailed me out of some real jams, but I +wanted something that would do 90% of what I need from Expect; be 10% of +the size; and allow me to write my code in Python instead of TCL. +Pexpect is not nearly as big as Expect, but Pexpect does everything I +have ever used Expect for. + +.. _whynotpipe: + +**Q: Why not just use a pipe (popen())?** + +A: A pipe works fine for getting the output to non-interactive programs. +If you just want to get the output from ls, uname, or ping then this +works. Pipes do not work very well for interactive programs and pipes +will almost certainly fail for most applications that ask for passwords +such as telnet, ftp, or ssh. + +There are two reasons for this. + +* First an application may bypass stdout and print directly to its + controlling TTY. Something like SSH will do this when it asks you for + a password. This is why you cannot redirect the password prompt because + it does not go through stdout or stderr. + +* The second reason is because most applications are built using the C + Standard IO Library (anything that uses ``#include <stdio.h>``). One + of the features of the stdio library is that it buffers all input and + output. Normally output is line buffered when a program is printing to + a TTY (your terminal screen). Everytime the program prints a line-feed + the currently buffered data will get printed to your screen. The + problem comes when you connect a pipe. The stdio library is smart and + can tell that it is printing to a pipe instead of a TTY. In that case + it switches from line buffer mode to block buffered. In this mode the + currently buffered data is flushed when the buffer is full. This + causes most interactive programs to deadlock. Block buffering is more + efficient when writing to disks and pipes. Take the situation where a + program prints a message ``"Enter your user name:\n"`` and then waits + for you type type something. In block buffered mode, the stdio library + will not put the message into the pipe even though a linefeed is + printed. The result is that you never receive the message, yet the + child application will sit and wait for you to type a response. Don't + confuse the stdio lib's buffer with the pipe's buffer. The pipe buffer + is another area that can cause problems. You could flush the input + side of a pipe, whereas you have no control over the stdio library buffer. + +More information: the Standard IO library has three states for a +``FILE *``. These are: _IOFBF for block buffered; _IOLBF for line buffered; +and _IONBF for unbuffered. The STDIO lib will use block buffering when +talking to a block file descriptor such as a pipe. This is usually not +helpful for interactive programs. Short of recompiling your program to +include fflush() everywhere or recompiling a custom stdio library there +is not much a controlling application can do about this if talking over +a pipe. + +The program may have put data in its output that remains unflushed +because the output buffer is not full; then the program will go and +deadlock while waiting for input -- because you never send it any +because you are still waiting for its output (still stuck in the STDIO's +output buffer). + +The answer is to use a pseudo-tty. A TTY device will force line +buffering (as opposed to block buffering). Line buffering means that you +will get each line when the child program sends a line feed. This +corresponds to the way most interactive programs operate -- send a line +of output then wait for a line of input. + +I put "answer" in quotes because it's ugly solution and because there is +no POSIX standard for pseudo-TTY devices (even though they have a TTY +standard...). What would make more sense to me would be to have some way +to set a mode on a file descriptor so that it will tell the STDIO to be +line-buffered. I have investigated, and I don't think there is a way to +set the buffered state of a child process. The STDIO Library does not +maintain any external state in the kernel or whatnot, so I don't think +there is any way for you to alter it. I'm not quite sure how this +line-buffered/block-buffered state change happens internally in the +STDIO library. I think the STDIO lib looks at the file descriptor and +decides to change behavior based on whether it's a TTY or a block file +(see isatty()). + +I hope that this qualifies as helpful. Don't use a pipe to control +another application. + +**Q: Can I do screen scraping with this thing?** + +A: That depends. If your application just does line-oriented output then +this is easy. If a program emits many terminal sequences, from video +attributes to screen addressing, such as programs using curses, then +it may become very difficult to ascertain what text is displayed on a screen. + +We suggest using the `pyte <https://github.com/selectel/pyte>`_ library to +screen-scrape. The module :mod:`pexpect.ANSI` released with previous versions +of pexpect is now marked deprecated and may be removed in the future. + +**Q: I get strange behavior with pexect and gevent** + +A: Pexpect uses fork(2), exec(2), select(2), waitpid(2), and implements its +own selector in expect family of calls. pexpect has been known to misbehave +when paired with gevent. A solution might be to isolate your pexpect +dependent code from any frameworks that manipulate event selection behavior +by running it in an another process entirely. diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/Makefile b/lldb/third_party/Python/module/pexpect-4.6/doc/Makefile new file mode 100644 index 00000000000..ced8a685263 --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Pexpect.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Pexpect.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Pexpect" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Pexpect" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/api/fdpexpect.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/api/fdpexpect.rst new file mode 100644 index 00000000000..3ddf2cdb228 --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/api/fdpexpect.rst @@ -0,0 +1,20 @@ +fdpexpect - use pexpect with a file descriptor +============================================== + +.. automodule:: pexpect.fdpexpect + +fdspawn class +------------- + +.. autoclass:: fdspawn + :show-inheritance: + + .. automethod:: __init__ + .. automethod:: isalive + .. automethod:: close + + .. method:: expect + expect_exact + expect_list + + As :class:`pexpect.spawn`. diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/api/index.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/api/index.rst new file mode 100644 index 00000000000..5277d1cd00a --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/api/index.rst @@ -0,0 +1,18 @@ +API documentation +================= + +.. toctree:: + :maxdepth: 2 + + pexpect + fdpexpect + popen_spawn + replwrap + pxssh + +The modules ``pexpect.screen`` and ``pexpect.ANSI`` have been deprecated in +Pexpect version 4. They were separate from the main use cases for Pexpect, and +there are better maintained Python terminal emulator packages, such as +`pyte <https://pypi.python.org/pypi/pyte>`__. +These modules are still present for now, but we don't advise using them in new +code. diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/api/pexpect.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/api/pexpect.rst new file mode 100644 index 00000000000..79bbcefffc5 --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/api/pexpect.rst @@ -0,0 +1,115 @@ +Core pexpect components +======================= + +.. automodule:: pexpect + +spawn class +----------- + +.. autoclass:: spawn + + .. automethod:: __init__ + .. automethod:: expect + .. automethod:: expect_exact + .. automethod:: expect_list + .. automethod:: compile_pattern_list + .. automethod:: send + .. automethod:: sendline + .. automethod:: write + .. automethod:: writelines + .. automethod:: sendcontrol + .. automethod:: sendeof + .. automethod:: sendintr + .. automethod:: read + .. automethod:: readline + .. automethod:: read_nonblocking + .. automethod:: eof + .. automethod:: interact + + .. attribute:: logfile + logfile_read + logfile_send + + Set these to a Python file object (or :data:`sys.stdout`) to log all + communication, data read from the child process, or data sent to the child + process. + + .. note:: + + With :class:`spawn` in bytes mode, the log files should be open for + writing binary data. In unicode mode, they should + be open for writing unicode text. See :ref:`unicode`. + +Controlling the child process +````````````````````````````` + +.. class:: spawn + + .. automethod:: kill + .. automethod:: terminate + .. automethod:: isalive + .. automethod:: wait + .. automethod:: close + .. automethod:: getwinsize + .. automethod:: setwinsize + .. automethod:: getecho + .. automethod:: setecho + .. automethod:: waitnoecho + + .. attribute:: pid + + The process ID of the child process. + + .. attribute:: child_fd + + The file descriptor used to communicate with the child process. + +.. _unicode: + +Handling unicode +```````````````` + +By default, :class:`spawn` is a bytes interface: its read methods return bytes, +and its write/send and expect methods expect bytes. If you pass the *encoding* +parameter to the constructor, it will instead act as a unicode interface: +strings you send will be encoded using that encoding, and bytes received will +be decoded before returning them to you. In this mode, patterns for +:meth:`~spawn.expect` and :meth:`~spawn.expect_exact` should also be unicode. + +.. versionchanged:: 4.0 + + :class:`spawn` provides both the bytes and unicode interfaces. In Pexpect + 3.x, the unicode interface was provided by a separate ``spawnu`` class. + +For backwards compatibility, some Unicode is allowed in bytes mode: the +send methods will encode arbitrary unicode as UTF-8 before sending it to the +child process, and its expect methods can accept ascii-only unicode strings. + +.. note:: + + Unicode handling with pexpect works the same way on Python 2 and 3, despite + the difference in names. I.e.: + + - Bytes mode works with ``str`` on Python 2, and :class:`bytes` on Python 3, + - Unicode mode works with ``unicode`` on Python 2, and :class:`str` on Python 3. + +run function +------------ + +.. autofunction:: run + +Exceptions +---------- + +.. autoclass:: EOF + +.. autoclass:: TIMEOUT + +.. autoclass:: ExceptionPexpect + +Utility functions +----------------- + +.. autofunction:: which + +.. autofunction:: split_command_line diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/api/popen_spawn.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/api/popen_spawn.rst new file mode 100644 index 00000000000..64cae1561ea --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/api/popen_spawn.rst @@ -0,0 +1,24 @@ +popen_spawn - use pexpect with a piped subprocess +================================================= + +.. automodule:: pexpect.popen_spawn + +PopenSpawn class +---------------- + +.. autoclass:: PopenSpawn + + .. automethod:: __init__ + .. automethod:: send + .. automethod:: sendline + .. automethod:: write + .. automethod:: writelines + .. automethod:: kill + .. automethod:: sendeof + .. automethod:: wait + + .. method:: expect + expect_exact + expect_list + + As :class:`pexpect.spawn`. diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/api/pxssh.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/api/pxssh.rst new file mode 100644 index 00000000000..b947f4b5ace --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/api/pxssh.rst @@ -0,0 +1,34 @@ +pxssh - control an SSH session +============================== + +.. automodule:: pexpect.pxssh + +.. autoclass:: ExceptionPxssh + +pxssh class +----------- + +.. autoclass:: pxssh + + .. automethod:: __init__ + + .. attribute:: PROMPT + + The regex pattern to search for to find the prompt. If you call :meth:`login` + with ``auto_prompt_reset=False``, you must set this attribute manually. + + .. attribute:: force_password + + If this is set to True, public key authentication is disabled, forcing the + server to ask for a password. Note that the sysadmin can disable password + logins, in which case this won't work. + + .. attribute:: options + + The dictionary of user specified SSH options, eg, ``options = dict(StrictHostKeyChecking="no", UserKnownHostsFile="/dev/null")`` + + .. automethod:: login + .. automethod:: logout + .. automethod:: prompt + .. automethod:: sync_original_prompt + .. automethod:: set_unique_prompt diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/api/replwrap.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/api/replwrap.rst new file mode 100644 index 00000000000..bf44a948db8 --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/api/replwrap.rst @@ -0,0 +1,26 @@ +replwrap - Control read-eval-print-loops +======================================== + +.. automodule:: pexpect.replwrap + +.. versionadded:: 3.3 + +.. autoclass:: REPLWrapper + + .. automethod:: run_command + +.. data:: PEXPECT_PROMPT + + A string that can be used as a prompt, and is unlikely to be found in output. + +Using the objects above, it is easy to wrap a REPL. For instance, to use a +Python shell:: + + py = REPLWrapper("python", ">>> ", "import sys; sys.ps1={!r}; sys.ps2={!r}") + py.run_command("4+7") + +Convenience functions are provided for Python and bash shells: + +.. autofunction:: python + +.. autofunction:: bash diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/clean.css b/lldb/third_party/Python/module/pexpect-4.6/doc/clean.css new file mode 100644 index 00000000000..e8d98ddb2e5 --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/clean.css @@ -0,0 +1,103 @@ + +body { + margin:0px; + padding:0px; + font-family:verdana, arial, helvetica, sans-serif; + color:#333; + background-color:white; + } +pre { + background: #eeeeee; + border: 1px solid #888888; + color: black; + padding: 1em; + white-space: pre; +} +h1 { + margin:5px 0px 5px 0px; + padding:0px; + font-size:20px; + line-height:28px; + font-weight:900; + color:#44f; + } +h2 { + margin:5px 0px 5px 0px; + padding:0px; + font-size:17px; + line-height:28px; + font-weight:900; + color:#226; + } +h3 { + margin:5px 0px 5px 0px; + padding:0px; + font-size:15px; + line-height:28px; + font-weight:900; + } +p +{ + margin:0px 0px 16px 0px; + font:11px/20px verdana, arial, helvetica, sans-serif; + padding:0px; +} +table +{ + font-size: 10pt; + color: #000000; +} +td{border:1px solid #999;} + +table.pymenu {color: #000000; background-color: #99ccff} +th.pymenu {color: #ffffff; background-color: #003366} + +.code +{ + font-family: "Lucida Console", monospace; font-weight: bold; + color: #007700; background-color: #eeeeee +} + +#Content>p {margin:0px;} +#Content>p+p {text-indent:30px;} + +a { + text-decoration:none; + font-weight:600; + font-family:verdana, arial, helvetica, sans-serif; + color: #900; +} +//a:link {color:#09c;} +//a x:visited {color:#07a;} +a:hover {background-color:#ee0;} + +#Header { + margin:10px 0px 10px 0px; + padding:10px 0px 10px 20px; + /* For IE5/Win's benefit height = [correct height] + [top padding] + [top and bottom border widths] */ + height:33px; /* 14px + 17px + 2px = 33px */ + border-style:solid; + border-color:black; + border-width:1px 0px; /* top and bottom borders: 1px; left and right borders: 0px */ + line-height:33px; + background-color:#eee; + height:66px; /* the correct height */ + } + +#Content { + margin:0px 210px 50px 10px; + padding:10px; + } + +#Menu { + position:absolute; + top:100px; + right:20px; + width:172px; + padding:10px; + background-color:#eee; + border:1px solid #999; // dashed #999; + line-height:17px; + width:150px; + font-size:11px; + } diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/commonissues.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/commonissues.rst new file mode 100644 index 00000000000..f60085e2aaa --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/commonissues.rst @@ -0,0 +1,101 @@ +Common problems +=============== + +Threads +------- + +On Linux (RH 8) you cannot spawn a child from a different thread and pass the +handle back to a worker thread. The child is successfully spawned but you can't +interact with it. The only way to make it work is to spawn and interact with the +child all in the same thread. [Adam Kerrison] + +Timing issue with send() and sendline() +--------------------------------------- + +This problem has been addressed and should not affect most users. + +It is sometimes possible to read an echo of the string sent with +:meth:`~pexpect.spawn.send` and :meth:`~pexpect.spawn.sendline`. If you call +:meth:`~pexpect.spawn.send` and then immediately call :meth:`~pexpect.spawn.readline`, +you may get part of your output echoed back. You may read back what you just +wrote even if the child application does not explicitly echo it. Timing is +critical. This could be a security issue when talking to an application that +asks for a password; otherwise, this does not seem like a big deal. But why do +TTYs do this? + +People usually report this when they are trying to control SSH or some other +login. For example, if your code looks something like this:: + + child.expect ('[pP]assword:') + child.sendline (my_password) + + +1. SSH prints "password:" prompt to the user. +2. SSH turns off echo on the TTY device. +3. SSH waits for user to enter a password. + +When scripting with Pexpect what can happen is that Pexpect will respond to the +"password:" prompt before SSH has had time to turn off TTY echo. In other words, +Pexpect sends the password between steps 1. and 2., so the password gets echoed +back to the TTY. I would call this an SSH bug. + +Pexpect now automatically adds a short delay before sending data to a child +process. This more closely mimics what happens in the usual human-to-app +interaction. The delay can be tuned with the ``delaybeforesend`` attribute of the +spawn class. In general, this fixes the problem for everyone and so this should +not be an issue for most users. For some applications you might with to turn it +off:: + + child = pexpect.spawn ("ssh user@example.com") + child.delaybeforesend = None + +Truncated output just before child exits +---------------------------------------- + +So far I have seen this only on older versions of Apple's MacOS X. If the child +application quits it may not flush its output buffer. This means that your +Pexpect application will receive an EOF even though it should have received a +little more data before the child died. This is not generally a problem when +talking to interactive child applications. One example where it is a problem is +when trying to read output from a program like *ls*. You may receive most of the +directory listing, but the last few lines will get lost before you receive an EOF. +The reason for this is that *ls* runs; completes its task; and then exits. The +buffer is not flushed before exit so the last few lines are lost. The following +example demonstrates the problem:: + + child = pexpect.spawn('ls -l') + child.expect(pexpect.EOF) + print child.before + +Controlling SSH on Solaris +-------------------------- + +Pexpect does not yet work perfectly on Solaris. One common problem is that SSH +sometimes will not allow TTY password authentication. For example, you may +expect SSH to ask you for a password using code like this:: + + child = pexpect.spawn('ssh user@example.com') + child.expect('password') + child.sendline('mypassword') + +You may see the following error come back from a spawned child SSH:: + + Permission denied (publickey,keyboard-interactive). + +This means that SSH thinks it can't access the TTY to ask you for your password. +The only solution I have found is to use public key authentication with SSH. +This bypasses the need for a password. I'm not happy with this solution. The +problem is due to poor support for Solaris Pseudo TTYs in the Python Standard +Library. + +child does not receive full input, emits BEL +-------------------------------------------- + +You may notice when running for example cat(1) or base64(1), when sending a +very long input line, that it is not fully received, and the BEL ('\a') may +be found in output. + +By default the child terminal matches the parent, which is often in "canonical +mode processing". You may wish to disable this mode. The exact limit of a line +varies by operating system, and details of disabling canonical mode may be +found in the docstring of :meth:`~pexpect.spawn.send`. diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/conf.py b/lldb/third_party/Python/module/pexpect-4.6/doc/conf.py new file mode 100644 index 00000000000..a7341473b69 --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/conf.py @@ -0,0 +1,250 @@ +# -*- coding: utf-8 -*- +# +# Pexpect documentation build configuration file, created by +# sphinx-quickstart on Tue Sep 17 11:05:11 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('sphinxext')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', + 'sphinx.ext.viewcode', 'github', # for easy GitHub links + ] + +github_project_url = "https://github.com/pexpect/pexpect" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Pexpect' +copyright = u'2013, Noah Spurrier and contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '4.6' +# The full version, including alpha/beta/rc tags. +release = version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Pexpectdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Pexpect.tex', u'Pexpect Documentation', + u'Noah Spurrier and contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'pexpect', u'Pexpect Documentation', + [u'Noah Spurrier and contributors'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'Pexpect', u'Pexpect Documentation', + u'Noah Spurrier and contributors', 'Pexpect', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/3/': None} diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/examples.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/examples.rst new file mode 100644 index 00000000000..6338b5c01cd --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/examples.rst @@ -0,0 +1,63 @@ +Examples +======== + +Under the distribution tarball directory you should find an "examples" directory. +This is the best way to learn to use Pexpect. See the descriptions of Pexpect +Examples. + +`topip.py <https://github.com/pexpect/pexpect/blob/master/examples/topip.py>`_ + This runs `netstat` on a local or remote server. It calculates some simple + statistical information on the number of external inet connections. This can + be used to detect if one IP address is taking up an excessive number of + connections. It can also send an email alert if a given IP address exceeds a + threshold between runs of the script. This script can be used as a drop-in + Munin plugin or it can be used stand-alone from cron. I used this on a busy + web server that would sometimes get hit with denial of service attacks. This + made it easy to see if a script was opening many multiple connections. A + typical browser would open fewer than 10 connections at once. A script might + open over 100 simultaneous connections. + +`hive.py <https://github.com/pexpect/pexpect/blob/master/examples/hive.py>`_ + This script creates SSH connections to a list of hosts that you provide. + Then you are given a command line prompt. Each shell command that you + enter is sent to all the hosts. The response from each host is collected + and printed. For example, you could connect to a dozen different + machines and reboot them all at once. + +`script.py <https://github.com/pexpect/pexpect/blob/master/examples/script.py>`_ + This implements a command similar to the classic BSD "script" command. + This will start a subshell and log all input and output to a file. + This demonstrates the :meth:`~pexpect.spawn.interact` method of Pexpect. + +`ftp.py <https://github.com/pexpect/pexpect/blob/master/examples/ftp.py>`_ + This demonstrates an FTP "bookmark". This connects to an ftp site; + does a few ftp tasks; and then gives the user interactive control over + the session. In this case the "bookmark" is to a directory on the + OpenBSD ftp server. It puts you in the i386 packages directory. You + can easily modify this for other sites. This demonstrates the + :meth:`~pexpect.spawn.interact` method of Pexpect. + +`monitor.py <https://github.com/pexpect/pexpect/blob/master/examples/monitor.py>`_ + This runs a sequence of commands on a remote host using SSH. It runs a + simple system checks such as uptime and free to monitor the state of + the remote host. + +`passmass.py <https://github.com/pexpect/pexpect/blob/master/examples/passmass.py>`_ + This will login to each given server and change the password of the + given user. This demonstrates scripting logins and passwords. + +`python.py <https://github.com/pexpect/pexpect/blob/master/examples/python.py>`_ + This starts the python interpreter and prints the greeting message + backwards. It then gives the user iteractive control of Python. It's + pretty useless! + +`ssh_tunnel.py <https://github.com/pexpect/pexpect/blob/master/examples/ssh_tunnel.py>`_ + This starts an SSH tunnel to a remote machine. It monitors the + connection and restarts the tunnel if it goes down. + +`uptime.py <https://github.com/pexpect/pexpect/blob/master/examples/uptime.py>`_ + This will run the uptime command and parse the output into variables. + This demonstrates using a single regular expression to match the + output of a command and capturing different variable in match groups. + The grouping regular expression handles a wide variety of different + uptime formats. diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/history.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/history.rst new file mode 100644 index 00000000000..41a591819b3 --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/history.rst @@ -0,0 +1,338 @@ +History +======= + +Releases +-------- + +Version 4.6 +``````````` + +* The :meth:`.pxssh.login` method now supports an ``ssh_config`` parameter, + which can be used to specify a file path to an SSH config file + (:ghpull:`490`). +* Improved compatability for the ``crlf`` parameter of :class:`~.PopenSpawn` + (:ghpull:`493`) +* Fixed an issue in read timeout handling when using :class:`~.spawn` and + :class:`~.fdspawn` with the ``use_poll`` parameter (:ghpull:`492`). + +Version 4.5 +``````````` + +* :class:`~.spawn` and :class:`~.fdspawn` now have a ``use_poll`` parameter. + If this is True, they will use :func:`select.poll` instead of :func:`select.select`. + ``poll()`` allows file descriptors above 1024, but it must be explicitly + enabled due to compatibility concerns (:ghpull:`474`). +* The :meth:`.pxssh.login` method has several new and changed options: + + * The option ``password_regex`` allows changing + the password prompt regex, for servers that include ``password:`` in a banner + before reaching a prompt (:ghpull:`468`). + * :meth:`~.pxssh.login` now allows for setting up SSH tunnels to be requested once + logged in to the remote server. This option is ``ssh_tunnels`` (:ghpull:`473`). + The structure should be like this:: + + { + 'local': ['2424:localhost:22'], # Local SSH tunnels + 'remote': ['2525:localhost:22'], # Remote SSH tunnels + 'dynamic': [8888], # Dynamic/SOCKS tunnels + } + + * The option ``spawn_local_ssh=False`` allows subsequent logins from the + remote session and treats the session as if it was local (:ghpull:`472`). + * Setting ``sync_original_prompt=False`` will prevent changing the prompt to + something unique, in case the remote server is sensitive to new lines at login + (:ghpull:`468`). + * If ``ssh_key=True`` is passed, the SSH client forces forwarding the authentication + agent to the remote server instead of providing a key (:ghpull:`473`). + +Version 4.4 +``````````` + +* :class:`~.PopenSpawn` now has a ``preexec_fn`` parameter, like :class:`~.spawn` + and :class:`subprocess.Popen`, for a function to be called in the child + process before executing the new command. Like in ``Popen``, this works only + in POSIX, and can cause issues if your application also uses threads + (:ghpull:`460`). +* Significant performance improvements when processing large amounts of data + (:ghpull:`464`). +* Ensure that ``spawn.closed`` gets set by :meth:`~.spawn.close`, and improve + an example for passing ``SIGWINCH`` through to a child process (:ghpull:`466`). + +Version 4.3.1 +````````````` + +* When launching bash for :mod:`pexpect.replwrap`, load the system ``bashrc`` + from a couple of different common locations (:ghpull:`457`), and then unset + the ``PROMPT_COMMAND`` environment variable, which can interfere with the + prompt we're expecting (:ghpull:`459`). + +Version 4.3 +``````````` + +* The ``async=`` parameter to integrate with asyncio has become ``async_=`` + (:ghpull:`431`), as *async* is becoming a Python keyword from Python 3.6. + Pexpect will still recognise ``async`` as an alternative spelling. +* Similarly, the module ``pexpect.async`` became ``pexpect._async`` + (:ghpull:`450`). This module is not part of the public API. +* Fix problems with asyncio objects closing file descriptors during garbage + collection (:ghissue:`347`, :ghpull:`376`). +* Set the ``.pid`` attribute of a :class:`~.PopenSpawn` object (:ghpull:`417`). +* Fix passing Windows paths to :class:`~.PopenSpawn` (:ghpull:`446`). +* :class:`~.PopenSpawn` on Windows can pass string commands through to ``Popen`` + without splitting them into a list (:ghpull:`447`). +* Stop ``shlex`` trying to read from stdin when :class:`~.PopenSpawn` is + passed ``cmd=None`` (:ghissue:`433`, :ghpull:`434`). +* Ensure that an error closing a Pexpect spawn object raises a Pexpect error, + rather than a Ptyprocess error (:ghissue:`383`, :ghpull:`386`). +* Cleaned up invalid backslash escape sequences in strings (:ghpull:`430`, + :ghpull:`445`). +* The pattern for a password prompt in :mod:`pexpect.pxssh` changed from + ``password`` to ``password:`` (:ghpull:`452`). +* Correct docstring for using unicode with spawn (:ghpull:`395`). +* Various other improvements to documentation. + +Version 4.2.1 +````````````` + +* Fix to allow running ``env`` in replwrap-ed bash. +* Raise more informative exception from pxssh if it fails to connect. +* Change ``passmass`` example to not log passwords entered. + +Version 4.2 +``````````` + +* Change: When an ``env`` parameter is specified to the :class:`~.spawn` or + :class:`~.run` family of calls containing a value for ``PATH``, its value is + used to discover the target executable from a relative path, rather than the + current process's environment ``PATH``. This mirrors the behavior of + :func:`subprocess.Popen` in the standard library (:ghissue:`348`). + +* Regression: Re-introduce capability for :meth:`read_nonblocking` in class + :class:`fdspawn` as previously supported in version 3.3 (:ghissue:`359`). + +Version 4.0 +``````````` + +* Integration with :mod:`asyncio`: passing ``async=True`` to :meth:`~.spawn.expect`, + :meth:`~.spawn.expect_exact` or :meth:`~.spawn.expect_list` will make them return a + coroutine. You can get the result using ``yield from``, or wrap it in an + :class:`asyncio.Task`. This allows the event loop to do other things while + waiting for output that matches a pattern. +* Experimental support for Windows (with some caveats)—see :ref:`windows`. +* Enhancement: allow method as callbacks of argument ``events`` for + :func:`pexpect.run` (:ghissue:`176`). +* It is now possible to call :meth:`~.spawn.wait` multiple times, or after a process + is already determined to be terminated without raising an exception + (:ghpull:`211`). +* New :class:`pexpect.spawn` keyword argument, ``dimensions=(rows, columns)`` + allows setting terminal screen dimensions before launching a program + (:ghissue:`122`). +* Fix regression that prevented executable, but unreadable files from + being found when not specified by absolute path -- such as + /usr/bin/sudo (:ghissue:`104`). +* Fixed regression when executing pexpect with some prior releases of + the multiprocessing module where stdin has been closed (:ghissue:`86`). + +Backwards incompatible changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Deprecated ``pexpect.screen`` and ``pexpect.ANSI``. Please use other packages + such as `pyte <https://pypi.python.org/pypi/pyte>`__ to emulate a terminal. +* Removed the independent top-level modules (``pxssh fdpexpect FSM screen ANSI``) + which were installed alongside Pexpect. These were moved into the Pexpect + package in 3.0, but the old names were left as aliases. +* Child processes created by Pexpect no longer ignore SIGHUP by default: the + ``ignore_sighup`` parameter of :class:`pexpect.spawn` defaults to False. To + get the old behaviour, pass ``ignore_sighup=True``. + +Version 3.3 +``````````` + +* Added a mechanism to wrap REPLs, or shells, in an object which can conveniently + be used to send commands and wait for the output (:mod:`pexpect.replwrap`). +* Fixed issue where pexpect would attempt to execute a directory because + it has the 'execute' bit set (:ghissue:`37`). +* Removed the ``pexpect.psh`` module. This was never documented, and we found + no evidence that people use it. The new :mod:`pexpect.replwrap` module + provides a more flexible alternative. +* Fixed ``TypeError: got <type 'str'> ('\r\n') as pattern`` in :meth:`spawnu.readline` + method (:ghissue:`67`). +* Fixed issue where EOF was not correctly detected in :meth:`~.interact`, causing + a repeating loop of output on Linux, and blocking before EOF on BSD and + Solaris (:ghissue:`49`). +* Several Solaris (SmartOS) bugfixes, preventing :exc:`IOError` exceptions, especially + when used with cron(1) (:ghissue:`44`). +* Added new keyword argument ``echo=True`` for :class:`spawn`. On SVR4-like + systems, the method :meth:`~.isatty` will always return *False*: the child pty + does not appear as a terminal. Therefore, :meth:`~.setecho`, :meth:`~.getwinsize`, + :meth:`~.setwinsize`, and :meth:`~.waitnoecho` are not supported on those platforms. + +After this, we intend to start working on a bigger refactoring of the code, to +be released as Pexpect 4. There may be more bugfix 3.x releases, however. + +Version 3.2 +``````````` + +* Fix exception handling from :func:`select.select` on Python 2 (:ghpull:`38`). + This was accidentally broken in the previous release when it was fixed for + Python 3. +* Removed a workaround for ``TIOCSWINSZ`` on very old systems, which was causing + issues on some BSD systems (:ghpull:`40`). +* Fixed an issue with exception handling in :mod:`~pexpect.pxssh` (:ghpull:`43`) + +The documentation for :mod:`~pexpect.pxssh` was improved. + +Version 3.1 +``````````` + +* Fix an issue that prevented importing pexpect on Python 3 when ``sys.stdout`` + was reassigned (:ghissue:`30`). +* Improve prompt synchronisation in :mod:`~pexpect.pxssh` (:ghpull:`28`). +* Fix pickling exception instances (:ghpull:`34`). +* Fix handling exceptions from :func:`select.select` on Python 3 (:ghpull:`33`). + +The examples have also been cleaned up somewhat - this will continue in future +releases. + +Version 3.0 +``````````` + +The new major version number doesn't indicate any deliberate API incompatibility. +We have endeavoured to avoid breaking existing APIs. However, pexpect is under +new maintenance after a long dormancy, so some caution is warranted. + +* A new :ref:`unicode API <unicode>` was introduced. +* Python 3 is now supported, using a single codebase. +* Pexpect now requires at least Python 2.6 or 3.2. +* The modules other than pexpect, such as :mod:`pexpect.fdpexpect` and + :mod:`pexpect.pxssh`, were moved into the pexpect package. For now, wrapper + modules are installed to the old locations for backwards compatibility (e.g. + ``import pxssh`` will still work), but these will be removed at some point in + the future. +* Ignoring ``SIGHUP`` is now optional - thanks to Kimmo Parviainen-Jalanko for + the patch. + +We also now have `docs on ReadTheDocs <https://pexpect.readthedocs.io/>`_, +and `continuous integration on Travis CI <https://travis-ci.org/pexpect/pexpect>`_. + +Version 2.4 +``````````` + +* Fix a bug regarding making the pty the controlling terminal when the process + spawning it is not, actually, a terminal (such as from cron) + +Version 2.3 +``````````` + +* Fixed OSError exception when a pexpect object is cleaned up. Previously, you + might have seen this exception:: + + Exception exceptions.OSError: (10, 'No child processes') + in <bound method spawn.__del__ of <pexpect.spawn instance at 0xd248c>> ignored + + You should not see that anymore. Thanks to Michael Surette. +* Added support for buffering reads. This greatly improves speed when trying to + match long output from a child process. When you create an instance of the spawn + object you can then set a buffer size. For now you MUST do the following to turn + on buffering -- it may be on by default in future version:: + + child = pexpect.spawn ('my_command') + child.maxread=1000 # Sets buffer to 1000 characters. + +* I made a subtle change to the way TIMEOUT and EOF exceptions behave. + Previously you could either expect these states in which case pexpect + will not raise an exception, or you could just let pexpect raise an + exception when these states were encountered. If you expected the + states then the ``before`` property was set to everything before the + state was encountered, but if you let pexpect raise the exception then + ``before`` was not set. Now, the ``before`` property will get set either + way you choose to handle these states. +* The spawn object now provides iterators for a *file-like interface*. + This makes Pexpect a more complete file-like object. You can now write + code like this:: + + child = pexpect.spawn ('ls -l') + for line in child: + print line + +* write and writelines() no longer return a value. Use send() if you need that + functionality. I did this to make the Spawn object more closely match a + file-like object. +* Added the attribute ``exitstatus``. This will give the exit code returned + by the child process. This will be set to ``None`` while the child is still + alive. When ``isalive()`` returns 0 then ``exitstatus`` will be set. +* Made a few more tweaks to ``isalive()`` so that it will operate more + consistently on different platforms. Solaris is the most difficult to support. +* You can now put ``TIMEOUT`` in a list of expected patterns. This is just like + putting ``EOF`` in the pattern list. Expecting for a ``TIMEOUT`` may not be + used as often as ``EOF``, but this makes Pexpect more consistent. +* Thanks to a suggestion and sample code from Chad J. Schroeder I added the ability + for Pexpect to operate on a file descriptor that is already open. This means that + Pexpect can be used to control streams such as those from serial port devices. Now, + you just pass the integer file descriptor as the "command" when constructing a + spawn open. For example on a Linux box with a modem on ttyS1:: + + fd = os.open("/dev/ttyS1", os.O_RDWR|os.O_NONBLOCK|os.O_NOCTTY) + m = pexpect.spawn(fd) # Note integer fd is used instead of usual string. + m.send("+++") # Escape sequence + m.send("ATZ0\r") # Reset modem to profile 0 + rval = m.expect(["OK", "ERROR"]) + +* ``read()`` was renamed to ``read_nonblocking()``. Added new ``read()`` method + that matches file-like object interface. In general, you should not notice + the difference except that ``read()`` no longer allows you to directly set the + timeout value. I hope this will not effect any existing code. Switching to + ``read_nonblocking()`` should fix existing code. +* Changed the name of ``set_echo()`` to ``setecho()``. +* Changed the name of ``send_eof()`` to ``sendeof()``. +* Modified ``kill()`` so that it checks to make sure the pid ``isalive()``. +* modified ``spawn()`` (really called from ``__spawn()``) so that it does not + raise an exception if ``setwinsize()`` fails. Some platforms such as Cygwin + do not like setwinsize. This was a constant problem and since it is not a + critical feature I decided to just silence the error. Normally I don't like + to do that, but in this case I'm making an exception. +* Added a method ``close()`` that does what you think. It closes the file + descriptor of the child application. It makes no attempt to actually kill the + child or wait for its status. +* Add variables ``__version__`` and ``__revision__`` (from cvs) to the pexpect + modules. This is mainly helpful to me so that I can make sure that I'm testing + with the right version instead of one already installed. +* ``log_open()`` and ``log_close(`` have been removed. Now use ``setlog()``. + The ``setlog()`` method takes a file object. This is far more flexible than + the previous log method. Each time data is written to the file object it will + be flushed. To turn logging off simply call ``setlog()`` with None. +* renamed the ``isAlive()`` method to ``isalive()`` to match the more typical + naming style in Python. Also the technique used to detect child process + status has been drastically modified. Previously I did some funky stuff + with signals which caused indigestion in other Python modules on some + platforms. It was a big headache. It still is, but I think it works + better now. +* attribute ``matched`` renamed to ``after`` +* new attribute ``match`` +* The ``expect_eof()`` method is gone. You can now simply use the + ``expect()`` method to look for EOF. +* **Pexpect works on OS X**, but the nature of the quirks cause many of the + tests to fail. See bugs. (Incomplete Child Output). The problem is more + than minor, but Pexpect is still more than useful for most tasks. +* **Solaris**: For some reason, the *second* time a pty file descriptor is created and + deleted it never gets returned for use. It does not effect the first time + or the third time or any time after that. It's only the second time. This + is weird... This could be a file descriptor leak, or it could be some + peculiarity of how Solaris recycles them. I thought it was a UNIX requirement + for the OS to give you the lowest available filedescriptor number. In any case, + this should not be a problem unless you create hundreds of pexpect instances... + It may also be a pty module bug. + + +Moves and forks +--------------- + +* Pexpect development used to be hosted on Sourceforge. +* In 2011, Thomas Kluyver forked pexpect as 'pexpect-u', to support + Python 3. He later decided he had taken the wrong approach with this. +* In 2012, Noah Spurrier, the original author of Pexpect, moved the + project to Github, but was still too busy to develop it much. +* In 2013, Thomas Kluyver and Jeff Quast forked Pexpect again, intending + to call the new fork Pexpected. Noah Spurrier agreed to let them use + the name Pexpect, so Pexpect versions 3 and above are based on this + fork, which now lives `here on Github <https://github.com/pexpect/pexpect>`_. diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/index.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/index.rst new file mode 100644 index 00000000000..0bcf862dd4d --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/index.rst @@ -0,0 +1,50 @@ +Pexpect version |version| +========================= + +.. image:: https://travis-ci.org/pexpect/pexpect.png?branch=master + :target: https://travis-ci.org/pexpect/pexpect + :align: right + :alt: Build status + +Pexpect makes Python a better tool for controlling other +applications. + +Pexpect is a pure Python module for spawning child applications; +controlling them; and responding to expected patterns in their output. +Pexpect works like Don Libes' Expect. Pexpect allows your script to +spawn a child application and control it as if a human were typing +commands. + +Pexpect can be used for automating interactive applications such as +ssh, ftp, passwd, telnet, etc. It can be used to a automate setup +scripts for duplicating software package installations on different +servers. It can be used for automated software testing. Pexpect is in +the spirit of Don Libes' Expect, but Pexpect is pure Python. Unlike +other Expect-like modules for Python, Pexpect does not require TCL or +Expect nor does it require C extensions to be compiled. It should work +on any platform that supports the standard Python pty module. The +Pexpect interface was designed to be easy to use. + +Contents: + +.. toctree:: + :maxdepth: 2 + + install + overview + api/index + examples + FAQ + commonissues + history + +Pexpect is developed `on Github <http://github.com/pexpect/pexpect>`_. Please +report `issues <https://github.com/pexpect/pexpect/issues>`_ there as well. + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/install.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/install.rst new file mode 100644 index 00000000000..6f7e36af62d --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/install.rst @@ -0,0 +1,20 @@ +Installation +============ + +Pexpect is on PyPI, and can be installed with standard tools:: + + pip install pexpect + +Or:: + + easy_install pexpect + +Requirements +------------ + +This version of Pexpect requires Python 3.3 or above, or Python 2.7. + +As of version 4.0, Pexpect can be used on Windows and POSIX systems. However, +:class:`pexpect.spawn` and :func:`pexpect.run` are only available on POSIX, +where the :mod:`pty` module is present in the standard library. See +:ref:`windows` for more information. diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/make.bat b/lldb/third_party/Python/module/pexpect-4.6/doc/make.bat new file mode 100644 index 00000000000..448f1470824 --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/make.bat @@ -0,0 +1,190 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^<target^>` where ^<target^> is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Pexpect.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Pexpect.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/overview.rst b/lldb/third_party/Python/module/pexpect-4.6/doc/overview.rst new file mode 100644 index 00000000000..e52809cdc68 --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/overview.rst @@ -0,0 +1,266 @@ +API Overview +============ + +Pexpect can be used for automating interactive applications such as ssh, ftp, +mencoder, passwd, etc. The Pexpect interface was designed to be easy to use. + +Here is an example of Pexpect in action:: + + # This connects to the openbsd ftp site and + # downloads the recursive directory listing. + import pexpect + child = pexpect.spawn('ftp ftp.openbsd.org') + child.expect('Name .*: ') + child.sendline('anonymous') + child.expect('Password:') + child.sendline('noah@example.com') + child.expect('ftp> ') + child.sendline('lcd /tmp') + child.expect('ftp> ') + child.sendline('cd pub/OpenBSD') + child.expect('ftp> ') + child.sendline('get README') + child.expect('ftp> ') + child.sendline('bye') + +Obviously you could write an ftp client using Python's own :mod:`ftplib` module, +but this is just a demonstration. You can use this technique with any application. +This is especially handy if you are writing automated test tools. + +There are two important methods in Pexpect -- :meth:`~pexpect.spawn.expect` and +:meth:`~pexpect.spawn.send` (or :meth:`~pexpect.spawn.sendline` which is +like :meth:`~pexpect.spawn.send` with a linefeed). The :meth:`~pexpect.spawn.expect` +method waits for the child application to return a given string. The string you +specify is a regular expression, so you can match complicated patterns. The +:meth:`~pexpect.spawn.send` method writes a string to the child application. +From the child's point of view it looks just like someone typed the text from a +terminal. After each call to :meth:`~pexpect.spawn.expect` the ``before`` and ``after`` +properties will be set to the text printed by child application. The ``before`` +property will contain all text up to the expected string pattern. The ``after`` +string will contain the text that was matched by the expected pattern. +The match property is set to the `re match object <http://docs.python.org/3/library/re#match-objects>`_. + +An example of Pexpect in action may make things more clear. This example uses +ftp to login to the OpenBSD site; list files in a directory; and then pass +interactive control of the ftp session to the human user:: + + import pexpect + child = pexpect.spawn ('ftp ftp.openbsd.org') + child.expect ('Name .*: ') + child.sendline ('anonymous') + child.expect ('Password:') + child.sendline ('noah@example.com') + child.expect ('ftp> ') + child.sendline ('ls /pub/OpenBSD/') + child.expect ('ftp> ') + print child.before # Print the result of the ls command. + child.interact() # Give control of the child to the user. + +Special EOF and TIMEOUT patterns +-------------------------------- + +There are two special patterns to match the End Of File (:class:`~pexpect.EOF`) +or a Timeout condition (:class:`~pexpect.TIMEOUT`). You can pass these +patterns to :meth:`~pexpect.spawn.expect`. These patterns are not regular +expressions. Use them like predefined constants. + +If the child has died and you have read all the child's output then ordinarily +:meth:`~pexpect.spawn.expect` will raise an :class:`~pexpect.EOF` exception. +You can read everything up to the EOF without generating an exception by using +the EOF pattern expect. In this case everything the child has output will be +available in the ``before`` property. + +The pattern given to :meth:`~pexpect.spawn.expect` may be a regular expression +or it may also be a list of regular expressions. This allows you to match +multiple optional responses. The :meth:`~pexpect.spawn.expect` method returns +the index of the pattern that was matched. For example, say you wanted to login +to a server. After entering a password you could get various responses from the +server -- your password could be rejected; or you could be allowed in and asked +for your terminal type; or you could be let right in and given a command prompt. +The following code fragment gives an example of this:: + + child.expect('password:') + child.sendline(my_secret_password) + # We expect any of these three patterns... + i = child.expect (['Permission denied', 'Terminal type', '[#\$] ']) + if i==0: + print('Permission denied on host. Can\'t login') + child.kill(0) + elif i==1: + print('Login OK... need to send terminal type.') + child.sendline('vt100') + child.expect('[#\$] ') + elif i==2: + print('Login OK.') + print('Shell command prompt', child.after) + +If nothing matches an expected pattern then :meth:`~pexpect.spawn.expect` will +eventually raise a :class:`~pexpect.TIMEOUT` exception. The default time is 30 +seconds, but you can change this by passing a timeout argument to +:meth:`~pexpect.spawn.expect`:: + + # Wait no more than 2 minutes (120 seconds) for password prompt. + child.expect('password:', timeout=120) + +Find the end of line -- CR/LF conventions +----------------------------------------- + +Pexpect matches regular expressions a little differently than what you might be +used to. + +The :regexp:`$` pattern for end of line match is useless. The :regexp:`$` +matches the end of string, but Pexpect reads from the child one character at a +time, so each character looks like the end of a line. Pexpect can't do a +look-ahead into the child's output stream. In general you would have this +situation when using regular expressions with any stream. + +.. note:: + + Pexpect does have an internal buffer, so reads are faster than one character + at a time, but from the user's perspective the regex patterns test happens + one character at a time. + +The best way to match the end of a line is to look for the newline: ``"\r\n"`` +(CR/LF). Yes, that does appear to be DOS-style. It may surprise some UNIX people +to learn that terminal TTY device drivers (dumb, vt100, ANSI, xterm, etc.) all +use the CR/LF combination to signify the end of line. Pexpect uses a Pseudo-TTY +device to talk to the child application, so when the child app prints ``"\n"`` +you actually see ``"\r\n"``. + +UNIX uses just linefeeds to end lines of text, but not when it comes to TTY +devices! TTY devices are more like the Windows world. Each line of text ends +with a CR/LF combination. When you intercept data from a UNIX command from a +TTY device you will find that the TTY device outputs a CR/LF combination. A +UNIX command may only write a linefeed (``\n``), but the TTY device driver +converts it to CR/LF. This means that your terminal will see lines end with +CR/LF (hex ``0D 0A``). Since Pexpect emulates a terminal, to match ends of +lines you have to expect the CR/LF combination:: + + child.expect('\r\n') + +If you just need to skip past a new line then ``expect('\n')`` by itself will +work, but if you are expecting a specific pattern before the end of line then +you need to explicitly look for the ``\r``. For example the following expects a +word at the end of a line:: + + child.expect('\w+\r\n') + +But the following would both fail:: + + child.expect('\w+\n') + +And as explained before, trying to use :regexp:`$` to match the end of line +would not work either:: + + child.expect ('\w+$') + +So if you need to explicitly look for the END OF LINE, you want to look for the +CR/LF combination -- not just the LF and not the $ pattern. + +This problem is not limited to Pexpect. This problem happens any time you try +to perform a regular expression match on a stream. Regular expressions need to +look ahead. With a stream it is hard to look ahead because the process +generating the stream may not be finished. There is no way to know if the +process has paused momentarily or is finished and waiting for you. Pexpect must +implicitly always do a NON greedy match (minimal) at the end of a input. + +Pexpect compiles all regular expressions with the :data:`re.DOTALL` flag. +With the :data:`~re.DOTALL` flag, a ``"."`` will match a newline. + +Beware of + and * at the end of patterns +---------------------------------------- + +Remember that any time you try to match a pattern that needs look-ahead that +you will always get a minimal match (non greedy). For example, the following +will always return just one character:: + + child.expect ('.+') + +This example will match successfully, but will always return no characters:: + + child.expect ('.*') + +Generally any star * expression will match as little as possible. + +One thing you can do is to try to force a non-ambiguous character at the end of +your :regexp:`\\d+` pattern. Expect that character to delimit the string. For +example, you might try making the end of your pattern be :regexp:`\\D+` instead +of :regexp:`\\D*`. Number digits alone would not satisfy the :regexp:`(\\d+)\\D+` +pattern. You would need some numbers and at least one non-number at the end. + + +Debugging +--------- + +If you get the string value of a :class:`pexpect.spawn` object you will get lots +of useful debugging information. For debugging it's very useful to use the +following pattern:: + + try: + i = child.expect ([pattern1, pattern2, pattern3, etc]) + except: + print("Exception was thrown") + print("debug information:") + print(str(child)) + +It is also useful to log the child's input and out to a file or the screen. The +following will turn on logging and send output to stdout (the screen):: + + child = pexpect.spawn(foo) + child.logfile = sys.stdout + +Exceptions +---------- + +:class:`~pexpect.EOF` + +Note that two flavors of EOF Exception may be thrown. They are virtually +identical except for the message string. For practical purposes you should have +no need to distinguish between them, but they do give a little extra information +about what type of platform you are running. The two messages are: + +- "End Of File (EOF) in read(). Exception style platform." +- "End Of File (EOF) in read(). Empty string style platform." + +Some UNIX platforms will throw an exception when you try to read from a file +descriptor in the EOF state. Other UNIX platforms instead quietly return an +empty string to indicate that the EOF state has been reached. + +If you wish to read up to the end of the child's output without generating an +:class:`~pexpect.EOF` exception then use the ``expect(pexpect.EOF)`` method. + +:class:`~pexpect.TIMEOUT` + +The :meth:`~pexpect.spawn.expect` and :meth:`~pexpect.spawn.read` methods will +also timeout if the child does not generate any output for a given amount of +time. If this happens they will raise a :class:`~pexpect.TIMEOUT` exception. +You can have these methods ignore timeout and block indefinitely by passing +``None`` for the timeout parameter:: + + child.expect(pexpect.EOF, timeout=None) + +.. _windows: + +Pexpect on Windows +------------------ + +.. versionadded:: 4.0 + Windows support + +Pexpect can be used on Windows to wait for a pattern to be produced by a child +process, using :class:`pexpect.popen_spawn.PopenSpawn`, or a file descriptor, +using :class:`pexpect.fdpexpect.fdspawn`. + +:class:`pexpect.spawn` and :func:`pexpect.run` are *not* available on Windows, +as they rely on Unix pseudoterminals (ptys). Cross platform code must not use +these. + +``PopenSpawn`` is not a direct replacement for ``spawn``. Many programs only +offer interactive behaviour if they detect that they are running in a terminal. +When run by ``PopenSpawn``, they may behave differently. + +.. seealso:: + + `winpexpect <https://pypi.python.org/pypi/winpexpect>`__ and `wexpect <https://gist.github.com/anthonyeden/8488763>`__ + Two unmaintained pexpect-like modules for Windows, which work with a + hidden console. diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/requirements.txt b/lldb/third_party/Python/module/pexpect-4.6/doc/requirements.txt new file mode 100644 index 00000000000..57ebb2d6bdd --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/requirements.txt @@ -0,0 +1 @@ +ptyprocess diff --git a/lldb/third_party/Python/module/pexpect-4.6/doc/sphinxext/github.py b/lldb/third_party/Python/module/pexpect-4.6/doc/sphinxext/github.py new file mode 100644 index 00000000000..519e146d198 --- /dev/null +++ b/lldb/third_party/Python/module/pexpect-4.6/doc/sphinxext/github.py @@ -0,0 +1,155 @@ +"""Define text roles for GitHub + +* ghissue - Issue +* ghpull - Pull Request +* ghuser - User + +Adapted from bitbucket example here: +https://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/bitbucket/sphinxcontrib/bitbucket.py + +Authors +------- + +* Doug Hellmann +* Min RK +""" +# +# Original Copyright (c) 2010 Doug Hellmann. All rights reserved. +# + +from docutils import nodes, utils +from docutils.parsers.rst.roles import set_classes + +def make_link_node(rawtext, app, type, slug, options): + """Create a link to a github resource. + + :param rawtext: Text being replaced with link node. + :param app: Sphinx application context + :param type: Link type (issues, changeset, etc.) + :param slug: ID of the thing to link to + :param options: Options dictionary passed to role func. + """ + + try: + base = app.config.github_project_url + if not base: + raise AttributeError + if not base.endswith('/'): + base += '/' + except AttributeError as err: + raise ValueError('github_project_url configuration value is not set (%s)' % str(err)) + + ref = base + type + '/' + slug + '/' + set_classes(options) + prefix = "#" + if type == 'pull': + prefix = "PR " + prefix + node = nodes.reference(rawtext, prefix + utils.unescape(slug), refuri=ref, + **options) + return node + +def ghissue_role(name, rawtext, text, lineno, inliner, options={}, content=[]): + """Link to a GitHub issue. + + Returns 2 part tuple containing list of nodes to insert into the + document and a list of system messages. Both are allowed to be + empty. + + :param name: The role name used in the document. + :param rawtext: The entire markup snippet, with role. + :param text: The text marked with the role. + :param lineno: The line number where rawtext appears in the input. + :param inliner: The inliner instance that called us. + :param options: Directive options for customization. + :param content: The directive content for customization. + """ + + try: + issue_num = int(text) + if issue_num <= 0: + raise ValueError + except ValueError: + msg = inliner.reporter.error( + 'GitHub issue number must be a number greater than or equal to 1; ' + '"%s" is invalid.' % text, line=lineno) + prb = inliner.problematic(rawtext, rawtext, msg) + return [prb], [msg] + app = inliner.document.settings.env.app + #app.info('issue %r' % text) + if 'pull' in name.lower(): + category = 'pull' + elif 'issue' in name.lower(): + category = 'issues' + else: + msg = inliner.reporter.error( + 'GitHub roles include "ghpull" and "ghissue", ' + '"%s" is invalid.' % name, line=lineno) + prb = inliner.problematic(rawtext, rawtext, msg) + return [prb], [msg] + node = make_link_node(rawtext, app, category, str(issue_num), options) + return [node], [] + +def ghuser_role(name, rawtext, text, lineno, inliner, options={}, content=[]): + """Link to a GitHub user. + + Returns 2 part tuple containing list of nodes to insert into the + document and a list of system messages. Both are allowed to be + empty. + + :param name: The role name used in the document. + :param rawtext: The entire markup snippet, with role. + :param text: The text marked with the role. + :param lineno: The line number where rawtext appears in the input. + :param inliner: The inliner instance that called us. + :param options: Directive options for customization. + :param content: The directive content for customization. + """ + app = inliner.document.settings.env.app + #app.info('user link %r' % text) + ref = 'https://www.github.com/' + text + node = nodes.reference(rawtext, text, refuri=ref, **options) + return [node], [] + +def ghcommit_role(name, rawtext, text, lineno, inliner, options={}, content=[]): + """Link to a GitHub commit. + + Returns 2 part tuple containing list of nodes to insert into the + document and a list of system messages. Both are allowed to be + empty. + + :param name: The role name used in the document. + :param rawtext: The entire markup snippet, with role. + :param text: The text marked with the role. + :param lineno: The line number where rawtext appears in the input. + :param inliner: The inliner instance that called us. + :param options: Directive options for customization. + :param content: The directive content for customization. + """ + app = inliner.document.settings.env.app + #app.info('user link %r' % text) + try: + base = app.config.github_project_url + if not base: + raise AttributeError + if not base.endswith('/'): + base += '/' + except AttributeError as err: + raise ValueError('github_project_url configuration value is not set (%s)' % str(err)) + + ref = base + text + node = nodes.reference(rawtext, text[:6], refuri=ref, **options) + return [node], [] + + +def setup(app): + """Install the plugin. + + :param app: Sphinx application context. + """ + app.info('Initializing GitHub plugin') + app.add_role('ghissue', ghissue_role) + app.add_role('ghpull', ghissue_role) + app.add_role('ghuser', ghuser_role) + app.add_role('ghcommit', ghcommit_role) + app.add_config_value('github_project_url', None, 'env') + return |
