| | |
-
-- __builtin__.object
-
-
-
-- spawn
-
-
-- exceptions.Exception(exceptions.BaseException)
-
-
-
-- ExceptionPexpect
-
-
-
-- EOF
-
- TIMEOUT
-
-
-
-
-
-
-
-
-
-
-
-
-class spawn(__builtin__.object) |
-
-| |
-This is the main class interface for Pexpect. Use this class to start
-and control child applications.
|
-| |
-Methods defined here:
-- __del__(self)
- This makes sure that no system resources are left open. Python only
-garbage collects Python objects. OS file descriptors are not Python
-objects, so they must be handled explicitly. If the child file
-descriptor was opened outside of this class (passed to the constructor)
-then this does not close it.
-
-- __init__(self, command, args=[], timeout=30, maxread=2000, searchwindowsize=None, logfile=None, cwd=None, env=None)
- This is the constructor. The command parameter may be a string that
-includes a command and any arguments to the command. For example::
-
- child = pexpect.spawn ('/usr/bin/ftp')
- child = pexpect.spawn ('/usr/bin/ssh user@example.com')
- child = pexpect.spawn ('ls -latr /tmp')
-
-You may also construct it with a list of arguments like so::
-
- child = pexpect.spawn ('/usr/bin/ftp', [])
- child = pexpect.spawn ('/usr/bin/ssh', ['user@example.com'])
- child = pexpect.spawn ('ls', ['-latr', '/tmp'])
-
-After this the child application will be created and will be ready to
-talk to. For normal use, see expect() and send() and sendline().
-
-Remember that Pexpect does NOT interpret shell meta characters such as
-redirect, pipe, or wild cards (>, |, or *). 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)
-
-The maxread attribute sets the read buffer size. This is maximum number
-of bytes that Pexpect will try to read from a TTY at one time. Setting
-the maxread size to 1 will turn off buffering. Setting the maxread
-value higher may help performance in cases where large amounts of
-output are read back from the child. This feature is useful in
-conjunction with searchwindowsize.
-
-The searchwindowsize attribute sets the how far back in the incomming
-seach buffer Pexpect will search for pattern matches. Every time
-Pexpect reads some data from the child it will append the data to the
-incomming buffer. The default is to search from the beginning of the
-imcomming buffer each time new data is read from the child. But this is
-very inefficient if you are running a command that generates a large
-amount of data where you want to match The searchwindowsize does not
-effect the size of the incomming data buffer. You will still have
-access to the full buffer after expect() returns.
-
-The logfile member turns on or off logging. All input and output will
-be copied to the given file object. Set logfile to None to stop
-logging. This is the default. Set logfile to sys.stdout to echo
-everything to standard output. The logfile is flushed after each write.
-
-Example log input and output to a file::
-
- child = pexpect.spawn('some_command')
- fout = file('mylog.txt','w')
- child.logfile = fout
-
-Example log to stdout::
-
- child = pexpect.spawn('some_command')
- child.logfile = sys.stdout
-
-The logfile_read and logfile_send members can be used to separately log
-the input from the child and output sent to the child. Sometimes you
-don't want to see everything you write to the child. You only want to
-log what the child sends back. For example::
-
- child = pexpect.spawn('some_command')
- child.logfile_read = sys.stdout
-
-To separately log output sent to the child use logfile_send::
-
- self.logfile_send = fout
-
-The delaybeforesend helps overcome a weird behavior that many users
-were experiencing. The typical problem was that a user would expect() a
-"Password:" prompt and then immediately call sendline() to send the
-password. The user would then see that their password was echoed back
-to them. Passwords don't normally echo. The problem is caused by the
-fact that most applications print out the "Password" prompt and then
-turn off stdin echo, but if you send your password before the
-application turned off echo, then you get your password echoed.
-Normally this wouldn't be a problem when interacting with a human at a
-real keyboard. If you introduce a slight delay just before writing then
-this seems to clear up the problem. This was such a common problem for
-many users that I decided that the default pexpect behavior should be
-to sleep just before writing to the child application. 1/20th of a
-second (50 ms) seems to be enough to clear up the problem. You can set
-delaybeforesend to 0 to return to the old behavior. Most Linux machines
-don't like this to be below 0.03. I don't know why.
-
-Note that spawn is clever about finding commands on your path.
-It uses the same logic that "which" uses to find executables.
-
-If you wish to get the exit status of the child you must call the
-close() method. The exit or signal status of the child will be stored
-in self.exitstatus or self.signalstatus. If the child exited normally
-then exitstatus will store the exit return code and signalstatus will
-be None. If the child was terminated abnormally with a signal then
-signalstatus will store the signal value and exitstatus will be None.
-If you need more detail you can also read the self.status member which
-stores the status returned by os.waitpid. You can interpret this using
-os.WIFEXITED/os.WEXITSTATUS or os.WIFSIGNALED/os.TERMSIG.
-
-- __iter__(self)
- This is to support iterators over a file-like object.
-
-- __str__(self)
- This returns a human-readable string that represents the state of
-the object.
-
-- close(self, force=True)
- This closes the connection with the child application. Note that
-calling close() more than once is valid. This emulates standard Python
-behavior with files. Set force to True if you want to make sure that
-the child is terminated (SIGKILL is sent if the child ignores SIGHUP
-and SIGINT).
-
-- compile_pattern_list(self, patterns)
- This compiles a pattern-string or a list of pattern-strings.
-Patterns must be a StringType, EOF, TIMEOUT, SRE_Pattern, or a list of
-those. Patterns may also be None which results in an empty list (you
-might do this if waiting for an EOF or TIMEOUT condition without
-expecting any pattern).
-
-This is used by expect() when calling expect_list(). Thus expect() is
-nothing more than::
-
- cpl = compile_pattern_list(pl)
- return expect_list(cpl, timeout)
-
-If you are using expect() within a loop it may be more
-efficient to compile the patterns first and then call expect_list().
-This avoid calls in a loop to compile_pattern_list()::
-
- cpl = compile_pattern_list(my_pattern)
- while some_condition:
- ...
- i = expect_list(clp, timeout)
- ...
-
-- eof(self)
- This returns True if the EOF exception was ever raised.
-
-- expect(self, pattern, timeout=-1, searchwindowsize=None)
- This seeks through the stream until a pattern is matched. The
-pattern is overloaded and may take several types. The pattern can be a
-StringType, EOF, a compiled re, or a list of any of those types.
-Strings will be compiled to re types. This returns the index into the
-pattern list. If the pattern was not a list this returns index 0 on a
-successful match. This may raise exceptions for EOF or TIMEOUT. To
-avoid the EOF or TIMEOUT exceptions add EOF or TIMEOUT to the pattern
-list. That will cause expect to match an EOF or TIMEOUT condition
-instead of raising an exception.
-
-If you pass a list of patterns and more than one matches, the first match
-in the stream is chosen. If more than one pattern matches at that point,
-the leftmost in the pattern list is chosen. For example::
-
- # the input is 'foobar'
- index = p.expect (['bar', 'foo', 'foobar'])
- # returns 1 ('foo') even though 'foobar' is a "better" match
-
-Please note, however, that buffering can affect this behavior, since
-input arrives in unpredictable chunks. For example::
-
- # the input is 'foobar'
- index = p.expect (['foobar', 'foo'])
- # returns 0 ('foobar') if all input is available at once,
- # but returs 1 ('foo') if parts of the final 'bar' arrive late
-
-After a match is found the instance attributes 'before', 'after' and
-'match' will be set. You can see all the data read before the match in
-'before'. You can see the data that was matched in 'after'. The
-re.MatchObject used in the re match will be in 'match'. If an error
-occurred then 'before' will be set to all the data read so far and
-'after' and 'match' will be None.
-
-If timeout is -1 then timeout will be set to the self.timeout value.
-
-A list entry may be EOF or TIMEOUT instead of a string. This will
-catch these exceptions and return the index of the list entry instead
-of raising the exception. The attribute 'after' will be set to the
-exception type. The attribute 'match' will be None. This allows you to
-write code like this::
-
- index = p.expect (['good', 'bad', pexpect.EOF, pexpect.TIMEOUT])
- if index == 0:
- do_something()
- elif index == 1:
- do_something_else()
- elif index == 2:
- do_some_other_thing()
- elif index == 3:
- do_something_completely_different()
-
-instead of code like this::
-
- try:
- index = p.expect (['good', 'bad'])
- if index == 0:
- do_something()
- elif index == 1:
- do_something_else()
- except EOF:
- do_some_other_thing()
- except TIMEOUT:
- do_something_completely_different()
-
-These two forms are equivalent. It all depends on what you want. You
-can also just expect the EOF if you are waiting for all output of a
-child to finish. For example::
-
- p = pexpect.spawn('/bin/ls')
- p.expect (pexpect.EOF)
- print p.before
-
-If you are trying to optimize for speed then see expect_list().
-
-- expect_exact(self, pattern_list, timeout=-1, searchwindowsize=-1)
- This is similar to expect(), but uses plain string matching instead
-of compiled regular expressions in 'pattern_list'. The 'pattern_list'
-may be a string; a list or other sequence of strings; or TIMEOUT and
-EOF.
-
-This call might be faster than expect() for two reasons: string
-searching is faster than RE matching and it is possible to limit the
-search to just the end of the input buffer.
-
-This method is also useful when you don't want to have to worry about
-escaping regular expression characters that you want to match.
-
-- expect_list(self, pattern_list, timeout=-1, searchwindowsize=-1)
- This takes a list of compiled regular expressions and returns the
-index into the pattern_list that matched the child output. The list may
-also contain EOF or TIMEOUT (which are not compiled regular
-expressions). This method is similar to the expect() method except that
-expect_list() does not recompile the pattern list on every call. This
-may help if you are trying to optimize for speed, otherwise just use
-the expect() method. This is called by expect(). If timeout==-1 then
-the self.timeout value is used. If searchwindowsize==-1 then the
-self.searchwindowsize value is used.
-
-- expect_loop(self, searcher, timeout=-1, searchwindowsize=-1)
- This is the common loop used inside expect. The 'searcher' should be
-an instance of searcher_re or searcher_string, which describes how and what
-to search for in the input.
-
-See expect() for other arguments, return value and exceptions.
-
-- fileno(self)
- This returns the file descriptor of the pty for the child.
-
-- flush(self)
- This does nothing. It is here to support the interface for a
-File-like object.
-
-- getecho(self)
- This returns the terminal echo mode. This returns True if echo is
-on or False if echo is off. Child applications that are expecting you
-to enter a password often set ECHO False. See waitnoecho().
-
-- getwinsize(self)
- This returns the terminal window size of the child tty. The return
-value is a tuple of (rows, cols).
-
-- interact(self, escape_character='\x1d', input_filter=None, output_filter=None)
- This gives control of the child process to the interactive user (the
-human at the keyboard). Keystrokes are sent to the child process, and
-the stdout and stderr output of the child process is printed. This
-simply echos the child stdout and child stderr to the real stdout and
-it echos the real stdin to the child stdin. When the user types the
-escape_character this method will stop. The default for
-escape_character is ^]. This should not be confused with ASCII 27 --
-the ESC character. ASCII 29 was chosen for historical merit because
-this is the character used by 'telnet' as the escape character. The
-escape_character will not be sent to the child process.
-
-You may pass in optional input and output filter functions. These
-functions should take a string and return a string. The output_filter
-will be passed all the output from the child process. The input_filter
-will be passed all the keyboard input from the user. The input_filter
-is run BEFORE the check for the escape_character.
-
-Note that if you change the window size of the parent the SIGWINCH
-signal will not be passed through to the child. If you want the child
-window size to change when the parent's window size changes then do
-something like the following example::
-
- import pexpect, struct, fcntl, termios, signal, sys
- def sigwinch_passthrough (sig, data):
- s = struct.pack("HHHH", 0, 0, 0, 0)
- a = struct.unpack('hhhh', fcntl.ioctl(sys.stdout.fileno(), termios.TIOCGWINSZ , s))
- global p
- p.setwinsize(a[0],a[1])
- p = pexpect.spawn('/bin/bash') # Note this is global and used in sigwinch_passthrough.
- signal.signal(signal.SIGWINCH, sigwinch_passthrough)
- p.interact()
-
-- isalive(self)
- This tests if the child process is running or not. This is
-non-blocking. If the child was terminated then this will read the
-exitstatus or signalstatus of the child. This returns True if the child
-process appears to be running or False if not. It can take literally
-SECONDS for Solaris to return the right status.
-
-- isatty(self)
- This returns True if the file descriptor is open and connected to a
-tty(-like) device, else False.
-
-- kill(self, sig)
- This sends the given signal to the child application. In keeping
-with UNIX tradition it has a misleading name. It does not necessarily
-kill the child unless you send the right signal.
-
-- next(self)
- This is to support iterators over a file-like object.
-
-- read(self, size=-1)
- This reads at most "size" bytes from the file (less if the read hits
-EOF before obtaining size bytes). If the size argument is negative or
-omitted, read all data until EOF is reached. The bytes are returned as
-a string object. An empty string is returned when EOF is encountered
-immediately.
-
-- read_nonblocking(self, size=1, timeout=-1)
- This reads at most size characters from the child application. It
-includes a timeout. If the read does not complete within the timeout
-period then a TIMEOUT exception is raised. If the end of file is read
-then an EOF exception will be raised. If a log file was set using
-setlog() then all data will also be written to the log file.
-
-If timeout is None then the read may block indefinitely. If timeout is -1
-then the self.timeout value is used. If timeout is 0 then the child is
-polled and if there was no data immediately ready then this will raise
-a TIMEOUT exception.
-
-The timeout refers only to the amount of time to read at least one
-character. This is not effected by the 'size' parameter, so if you call
-read_nonblocking(size=100, timeout=30) and only one character is
-available right away then one character will be returned immediately.
-It will not wait for 30 seconds for another 99 characters to come in.
-
-This is a wrapper around os.read(). It uses select.select() to
-implement the timeout.
-
-- readline(self, size=-1)
- This reads and returns one entire line. A trailing newline is kept
-in the string, but may be absent when a file ends with an incomplete
-line. Note: This readline() looks for a \r\n pair even on UNIX
-because this is what the pseudo tty device returns. So contrary to what
-you may expect you will receive the newline as \r\n. An empty string
-is returned when EOF is hit immediately. Currently, the size argument is
-mostly ignored, so this behavior is not standard for a file-like
-object. If size is 0 then an empty string is returned.
-
-- readlines(self, sizehint=-1)
- This reads until EOF using readline() and returns a list containing
-the lines thus read. The optional "sizehint" argument is ignored.
-
-- send(self, s)
- This sends a string to the child process. This returns the number of
-bytes written. If a log file was set then the data is also written to
-the log.
-
-- sendcontrol(self, char)
- This sends a control character to the child such as Ctrl-C or
-Ctrl-D. For example, to send a Ctrl-G (ASCII 7)::
-
- child.sendcontrol('g')
-
-See also, sendintr() and sendeof().
-
-- sendeof(self)
- This sends an EOF to the child. This sends a character which causes
-the pending parent output buffer to be sent to the waiting child
-program without waiting for end-of-line. If it is the first character
-of the line, the read() in the user program returns 0, which signifies
-end-of-file. This means to work as expected a sendeof() has to be
-called at the beginning of a line. This method does not send a newline.
-It is the responsibility of the caller to ensure the eof is sent at the
-beginning of a line.
-
-- sendintr(self)
- This sends a SIGINT to the child. It does not require
-the SIGINT to be the first character on a line.
-
-- sendline(self, s='')
- This is like send(), but it adds a line feed (os.linesep). This
-returns the number of bytes written.
-
-- setecho(self, state)
- This sets the terminal echo mode on or off. Note that anything the
-child sent before the echo will be lost, so you should be sure that
-your input buffer is empty before you call setecho(). For example, the
-following will work as expected::
-
- p = pexpect.spawn('cat')
- p.sendline ('1234') # We will see this twice (once from tty echo and again from cat).
- p.expect (['1234'])
- p.expect (['1234'])
- p.setecho(False) # Turn off tty echo
- p.sendline ('abcd') # We will set this only once (echoed by cat).
- p.sendline ('wxyz') # We will set this only once (echoed by cat)
- p.expect (['abcd'])
- p.expect (['wxyz'])
-
-The following WILL NOT WORK because the lines sent before the setecho
-will be lost::
-
- p = pexpect.spawn('cat')
- p.sendline ('1234') # We will see this twice (once from tty echo and again from cat).
- p.setecho(False) # Turn off tty echo
- p.sendline ('abcd') # We will set this only once (echoed by cat).
- p.sendline ('wxyz') # We will set this only once (echoed by cat)
- p.expect (['1234'])
- p.expect (['1234'])
- p.expect (['abcd'])
- p.expect (['wxyz'])
-
-- setlog(self, fileobject)
- This method is no longer supported or allowed.
-
-- setmaxread(self, maxread)
- This method is no longer supported or allowed. I don't like getters
-and setters without a good reason.
-
-- setwinsize(self, r, c)
- This sets the terminal window size of the child tty. This will cause
-a SIGWINCH signal to be sent to the child. This does not change the
-physical window size. It changes the size reported to TTY-aware
-applications like vi or curses -- applications that respond to the
-SIGWINCH signal.
-
-- terminate(self, force=False)
- This forces a child process to terminate. It starts nicely with
-SIGHUP and SIGINT. If "force" is True then moves onto SIGKILL. This
-returns True if the child was terminated. This returns False if the
-child could not be terminated.
-
-- wait(self)
- This waits until the child exits. This is a blocking call. This will
-not read any data from the child, so this will block forever if the
-child has unread output and has terminated. In other words, the child
-may have printed output then called exit(); but, technically, the child
-is still alive until its output is read.
-
-- waitnoecho(self, timeout=-1)
- This waits until the terminal ECHO flag is set False. This returns
-True if the echo mode is off. This returns False if the ECHO flag was
-not set False before the timeout. This can be used to detect when the
-child is waiting for a password. Usually a child application will turn
-off echo mode when it is waiting for the user to enter a password. For
-example, instead of expecting the "password:" prompt you can wait for
-the child to set ECHO off::
-
- p = pexpect.spawn ('ssh user@example.com')
- p.waitnoecho()
- p.sendline(mypassword)
-
-If timeout is None then this method to block forever until ECHO flag is
-False.
-
-- write(self, s)
- This is similar to send() except that there is no return value.
-
-- writelines(self, sequence)
- This calls write() for each element in the sequence. The sequence
-can be any iterable object producing strings, typically a list of
-strings. This does not add line separators There is no return value.
-
-
-Data descriptors defined here:
-- __dict__
-- dictionary for instance variables (if defined)
-
-- __weakref__
-- list of weak references to the object (if defined)
-
- | |