1 '''Pexpect is a Python module for spawning child applications and controlling
2 them automatically. Pexpect can be used for automating interactive applications
3 such as ssh, ftp, passwd, telnet, etc. It can be used to a automate setup
4 scripts for duplicating software package installations on different servers. It
5 can be used for automated software testing. Pexpect is in the spirit of Don
6 Libes' Expect, but Pexpect is pure Python. Other Expect-like modules for Python
7 require TCL and Expect or require C extensions to be compiled. Pexpect does not
8 use C, Expect, or TCL extensions. It should work on any platform that supports
9 the standard Python pty module. The Pexpect interface focuses on ease of use so
10 that simple tasks are easy.
12 There are two main interfaces to the Pexpect system; these are the function,
13 run() and the class, spawn. The spawn class is more powerful. The run()
14 function is simpler than spawn, and is good for quickly calling program. When
15 you call the run() function it executes a given program and then returns the
16 output. This is a handy replacement for os.system().
22 The spawn class is the more powerful interface to the Pexpect system. You can
23 use this to spawn a child program then interact with it by sending input and
24 expecting responses (waiting for patterns in the child's output).
28 child = pexpect.spawn('scp foo user@example.com:.')
29 child.expect('Password:')
30 child.sendline(mypassword)
32 This works even for commands that ask for passwords or other input outside of
33 the normal stdio streams. For example, ssh reads input directly from the TTY
34 device which bypasses stdin.
36 Credits: Noah Spurrier, Richard Holden, Marco Molteni, Kimberley Burchett,
37 Robert Stone, Hartmut Goebel, Chad Schroeder, Erick Tryzelaar, Dave Kirby, Ids
38 vander Molen, George Todd, Noel Taylor, Nicolas D. Cesar, Alexander Gattin,
39 Jacques-Etienne Baudoux, Geoffrey Marshall, Francisco Lourenco, Glen Mabey,
40 Karthik Gurusamy, Fernando Perez, Corey Minyard, Jon Cohen, Guillaume
41 Chazarain, Andrew Ryan, Nick Craig-Wood, Andrew Stone, Jorgen Grahn, John
42 Spiegel, Jan Grant, and Shane Kerr. Let me know if I forgot anyone.
44 Pexpect is free, open source, and all that good stuff.
45 http://pexpect.sourceforge.net/
49 This license is approved by the OSI and FSF as GPL-compatible.
50 http://opensource.org/licenses/isc-license.txt
52 Copyright (c) 2012, Noah Spurrier <noah@noah.org>
53 PERMISSION TO USE, COPY, MODIFY, AND/OR DISTRIBUTE THIS SOFTWARE FOR ANY
54 PURPOSE WITH OR WITHOUT FEE IS HEREBY GRANTED, PROVIDED THAT THE ABOVE
55 COPYRIGHT NOTICE AND THIS PERMISSION NOTICE APPEAR IN ALL COPIES.
56 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
57 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
58 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
59 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
60 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
61 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
62 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
81 except ImportError: # pragma: no cover
82 err = sys.exc_info()[1]
83 raise ImportError(str(err) + '''
85 A critical module was not found. Probably this operating system does not
86 support it. Pexpect is intended for UNIX-like operating systems.''')
91 raise # For now. Work out what to do for Windows support here.
93 from .expect import Expecter
97 __all__ = ['ExceptionPexpect', 'EOF', 'TIMEOUT', 'spawn', 'spawnu', 'run', 'runu',
98 'which', 'split_command_line', '__version__', '__revision__']
100 PY3 = (sys.version_info[0] >= 3)
102 # Exception classes used by this module.
103 class ExceptionPexpect(Exception):
104 '''Base class for all exceptions raised by this module.
107 def __init__(self, value):
108 super(ExceptionPexpect, self).__init__(value)
112 return str(self.value)
115 '''This returns an abbreviated stack trace with lines that only concern
116 the caller. In other words, the stack trace inside the Pexpect module
119 tblist = traceback.extract_tb(sys.exc_info()[2])
120 tblist = [item for item in tblist if ('pexpect/__init__' not in item[0])
121 and ('pexpect/expect' not in item[0])]
122 tblist = traceback.format_list(tblist)
123 return ''.join(tblist)
126 class EOF(ExceptionPexpect):
127 '''Raised when EOF is read from a child.
128 This usually means the child has exited.'''
131 class TIMEOUT(ExceptionPexpect):
132 '''Raised when a read time exceeds the timeout. '''
134 ##class TIMEOUT_PATTERN(TIMEOUT):
135 ## '''Raised when the pattern match time exceeds the timeout.
136 ## This is different than a read TIMEOUT because the child process may
137 ## give output, thus never give a TIMEOUT, but the output
138 ## may never match a pattern.
140 ##class MAXBUFFER(ExceptionPexpect):
141 ## '''Raised when a buffer fills before matching an expected pattern.'''
144 def run(command, timeout=-1, withexitstatus=False, events=None,
145 extra_args=None, logfile=None, cwd=None, env=None):
148 This function runs the given command; waits for it to finish; then
149 returns all output as a string. STDERR is included in output. If the full
150 path to the command is not given then the path is searched.
152 Note that lines are terminated by CR/LF (\\r\\n) combination even on
153 UNIX-like systems because this is the standard for pseudottys. If you set
154 'withexitstatus' to true, then run will return a tuple of (command_output,
155 exitstatus). If 'withexitstatus' is false then this returns just
158 The run() function can often be used instead of creating a spawn instance.
159 For example, the following code uses spawn::
161 from pexpect import *
162 child = spawn('scp foo user@example.com:.')
163 child.expect('(?i)password')
164 child.sendline(mypassword)
166 The previous code can be replace with the following::
168 from pexpect import *
169 run('scp foo user@example.com:.', events={'(?i)password': mypassword})
173 Start the apache daemon on the local machine::
175 from pexpect import *
176 run("/usr/local/apache/bin/apachectl start")
178 Check in a file using SVN::
180 from pexpect import *
181 run("svn ci -m 'automatic commit' my_file.py")
183 Run a command and capture exit status::
185 from pexpect import *
186 (command_output, exitstatus) = run('ls -l /bin', withexitstatus=1)
188 The following will run SSH and execute 'ls -l' on the remote machine. The
189 password 'secret' will be sent if the '(?i)password' pattern is ever seen::
191 run("ssh username@machine.example.com 'ls -l'",
192 events={'(?i)password':'secret\\n'})
194 This will start mencoder to rip a video from DVD. This will also display
195 progress ticks every 5 seconds as it runs. For example::
197 from pexpect import *
199 print d['event_count'],
200 run("mencoder dvd://1 -o video.avi -oac copy -ovc copy",
201 events={TIMEOUT:print_ticks}, timeout=5)
203 The 'events' argument should be either a dictionary or a tuple list that
204 contains patterns and responses. Whenever one of the patterns is seen
205 in the command output, run() will send the associated response string.
206 So, run() in the above example can be also written as:
208 run("mencoder dvd://1 -o video.avi -oac copy -ovc copy",
209 events=[(TIMEOUT,print_ticks)], timeout=5)
211 Use a tuple list for events if the command output requires a delicate
212 control over what pattern should be matched, since the tuple list is passed
213 to pexpect() as its pattern list, with the order of patterns preserved.
215 Note that you should put newlines in your string if Enter is necessary.
217 Like the example above, the responses may also contain callback functions.
218 Any callback is a function that takes a dictionary as an argument.
219 The dictionary contains all the locals from the run() function, so you can
220 access the child spawn object or any other variable defined in run()
221 (event_count, child, and extra_args are the most useful). A callback may
222 return True to stop the current run process. Otherwise run() continues
223 until the next event. A callback may also return a string which will be
224 sent to the child. 'extra_args' is not used by directly run(). It provides
225 a way to pass data to a callback function through run() through the locals
226 dictionary passed to a callback.
228 return _run(command, timeout=timeout, withexitstatus=withexitstatus,
229 events=events, extra_args=extra_args, logfile=logfile, cwd=cwd,
230 env=env, _spawn=spawn)
232 def runu(command, timeout=-1, withexitstatus=False, events=None,
233 extra_args=None, logfile=None, cwd=None, env=None, **kwargs):
234 """This offers the same interface as :func:`run`, but using unicode.
236 Like :class:`spawnu`, you can pass ``encoding`` and ``errors`` parameters,
237 which will be used for both input and output.
239 return _run(command, timeout=timeout, withexitstatus=withexitstatus,
240 events=events, extra_args=extra_args, logfile=logfile, cwd=cwd,
241 env=env, _spawn=spawnu, **kwargs)
243 def _run(command, timeout, withexitstatus, events, extra_args, logfile, cwd,
244 env, _spawn, **kwargs):
246 child = _spawn(command, maxread=2000, logfile=logfile, cwd=cwd, env=env,
249 child = _spawn(command, timeout=timeout, maxread=2000, logfile=logfile,
250 cwd=cwd, env=env, **kwargs)
251 if isinstance(events, list):
252 patterns= [x for x,y in events]
253 responses = [y for x,y in events]
254 elif isinstance(events, dict):
255 patterns = list(events.keys())
256 responses = list(events.values())
258 # This assumes EOF or TIMEOUT will eventually cause run to terminate.
261 child_result_list = []
265 index = child.expect(patterns)
266 if isinstance(child.after, child.allowed_string_types):
267 child_result_list.append(child.before + child.after)
269 # child.after may have been a TIMEOUT or EOF,
270 # which we don't want appended to the list.
271 child_result_list.append(child.before)
272 if isinstance(responses[index], child.allowed_string_types):
273 child.send(responses[index])
274 elif isinstance(responses[index], types.FunctionType):
275 callback_result = responses[index](locals())
277 if isinstance(callback_result, child.allowed_string_types):
278 child.send(callback_result)
279 elif callback_result:
282 raise TypeError('The callback must be a string or function.')
283 event_count = event_count + 1
285 child_result_list.append(child.before)
288 child_result_list.append(child.before)
290 child_result = child.string_type().join(child_result_list)
293 return (child_result, child.exitstatus)
298 '''This is the main class interface for Pexpect. Use this class to start
299 and control child applications. '''
302 allowed_string_types = (bytes, str)
306 linesep = os.linesep.encode('ascii')
307 crlf = '\r\n'.encode('ascii')
310 def write_to_stdout(b):
312 return sys.stdout.buffer.write(b)
313 except AttributeError:
314 # If stdout has been replaced, it may not have .buffer
315 return sys.stdout.write(b.decode('ascii', 'replace'))
317 allowed_string_types = (basestring,) # analysis:ignore
318 _chr = staticmethod(chr)
321 write_to_stdout = sys.stdout.write
323 ptyprocess_class = ptyprocess.PtyProcess
326 def __init__(self, command, args=[], timeout=30, maxread=2000,
327 searchwindowsize=None, logfile=None, cwd=None, env=None,
328 ignore_sighup=True, echo=True):
330 '''This is the constructor. The command parameter may be a string that
331 includes a command and any arguments to the command. For example::
333 child = pexpect.spawn('/usr/bin/ftp')
334 child = pexpect.spawn('/usr/bin/ssh user@example.com')
335 child = pexpect.spawn('ls -latr /tmp')
337 You may also construct it with a list of arguments like so::
339 child = pexpect.spawn('/usr/bin/ftp', [])
340 child = pexpect.spawn('/usr/bin/ssh', ['user@example.com'])
341 child = pexpect.spawn('ls', ['-latr', '/tmp'])
343 After this the child application will be created and will be ready to
344 talk to. For normal use, see expect() and send() and sendline().
346 Remember that Pexpect does NOT interpret shell meta characters such as
347 redirect, pipe, or wild cards (``>``, ``|``, or ``*``). This is a
348 common mistake. If you want to run a command and pipe it through
349 another command then you must also start a shell. For example::
351 child = pexpect.spawn('/bin/bash -c "ls -l | grep LOG > logs.txt"')
352 child.expect(pexpect.EOF)
354 The second form of spawn (where you pass a list of arguments) is useful
355 in situations where you wish to spawn a command and pass it its own
356 argument list. This can make syntax more clear. For example, the
357 following is equivalent to the previous example::
359 shell_cmd = 'ls -l | grep LOG > logs.txt'
360 child = pexpect.spawn('/bin/bash', ['-c', shell_cmd])
361 child.expect(pexpect.EOF)
363 The maxread attribute sets the read buffer size. This is maximum number
364 of bytes that Pexpect will try to read from a TTY at one time. Setting
365 the maxread size to 1 will turn off buffering. Setting the maxread
366 value higher may help performance in cases where large amounts of
367 output are read back from the child. This feature is useful in
368 conjunction with searchwindowsize.
370 The searchwindowsize attribute sets the how far back in the incoming
371 seach buffer Pexpect will search for pattern matches. Every time
372 Pexpect reads some data from the child it will append the data to the
373 incoming buffer. The default is to search from the beginning of the
374 incoming buffer each time new data is read from the child. But this is
375 very inefficient if you are running a command that generates a large
376 amount of data where you want to match. The searchwindowsize does not
377 affect the size of the incoming data buffer. You will still have
378 access to the full buffer after expect() returns.
380 The logfile member turns on or off logging. All input and output will
381 be copied to the given file object. Set logfile to None to stop
382 logging. This is the default. Set logfile to sys.stdout to echo
383 everything to standard output. The logfile is flushed after each write.
385 Example log input and output to a file::
387 child = pexpect.spawn('some_command')
388 fout = open('mylog.txt','wb')
391 Example log to stdout::
394 child = pexpect.spawn('some_command')
395 child.logfile = sys.stdout
397 # In Python 3, spawnu should be used to give str to stdout:
398 child = pexpect.spawnu('some_command')
399 child.logfile = sys.stdout
401 The logfile_read and logfile_send members can be used to separately log
402 the input from the child and output sent to the child. Sometimes you
403 don't want to see everything you write to the child. You only want to
404 log what the child sends back. For example::
406 child = pexpect.spawn('some_command')
407 child.logfile_read = sys.stdout
409 Remember to use spawnu instead of spawn for the above code if you are
412 To separately log output sent to the child use logfile_send::
414 child.logfile_send = fout
416 If ``ignore_sighup`` is True, the child process will ignore SIGHUP
417 signals. For now, the default is True, to preserve the behaviour of
418 earlier versions of Pexpect, but you should pass this explicitly if you
421 The delaybeforesend helps overcome a weird behavior that many users
422 were experiencing. The typical problem was that a user would expect() a
423 "Password:" prompt and then immediately call sendline() to send the
424 password. The user would then see that their password was echoed back
425 to them. Passwords don't normally echo. The problem is caused by the
426 fact that most applications print out the "Password" prompt and then
427 turn off stdin echo, but if you send your password before the
428 application turned off echo, then you get your password echoed.
429 Normally this wouldn't be a problem when interacting with a human at a
430 real keyboard. If you introduce a slight delay just before writing then
431 this seems to clear up the problem. This was such a common problem for
432 many users that I decided that the default pexpect behavior should be
433 to sleep just before writing to the child application. 1/20th of a
434 second (50 ms) seems to be enough to clear up the problem. You can set
435 delaybeforesend to 0 to return to the old behavior. Most Linux machines
436 don't like this to be below 0.03. I don't know why.
438 Note that spawn is clever about finding commands on your path.
439 It uses the same logic that "which" uses to find executables.
441 If you wish to get the exit status of the child you must call the
442 close() method. The exit or signal status of the child will be stored
443 in self.exitstatus or self.signalstatus. If the child exited normally
444 then exitstatus will store the exit return code and signalstatus will
445 be None. If the child was terminated abnormally with a signal then
446 signalstatus will store the signal value and exitstatus will be None.
447 If you need more detail you can also read the self.status member which
448 stores the status returned by os.waitpid. You can interpret this using
449 os.WIFEXITED/os.WEXITSTATUS or os.WIFSIGNALED/os.TERMSIG.
451 The echo attribute may be set to False to disable echoing of input.
452 As a pseudo-terminal, all input echoed by the "keyboard" (send()
453 or sendline()) will be repeated to output. For many cases, it is
454 not desirable to have echo enabled, and it may be later disabled
455 using setecho(False) followed by waitnoecho(). However, for some
456 platforms such as Solaris, this is not possible, and should be
457 disabled immediately on spawn.
460 self.STDIN_FILENO = pty.STDIN_FILENO
461 self.STDOUT_FILENO = pty.STDOUT_FILENO
462 self.STDERR_FILENO = pty.STDERR_FILENO
463 self.stdin = sys.stdin
464 self.stdout = sys.stdout
465 self.stderr = sys.stderr
468 self.ignorecase = False
472 self.match_index = None
473 self.terminated = True
474 self.exitstatus = None
475 self.signalstatus = None
476 # status returned by os.waitpid
478 self.flag_eof = False
480 # the child file descriptor is initially closed
482 self.timeout = timeout
484 self.logfile = logfile
485 # input from child (read_nonblocking)
486 self.logfile_read = None
487 # output to send (send, sendline)
488 self.logfile_send = None
489 # max bytes to read at one time into buffer
490 self.maxread = maxread
491 # This is the read buffer. See maxread.
492 self.buffer = self.string_type()
493 # Data before searchwindowsize point is preserved, but not searched.
494 self.searchwindowsize = searchwindowsize
495 # Delay used before sending data to child. Time in seconds.
496 # Most Linux machines don't like this to be below 0.03 (30 ms).
497 self.delaybeforesend = 0.05
498 # Used by close() to give kernel time to update process status.
500 self.delayafterclose = 0.1
501 # Used by terminate() to give kernel time to update process status.
503 self.delayafterterminate = 0.1
504 self.softspace = False
505 self.name = '<' + repr(self) + '>'
510 self.ignore_sighup = ignore_sighup
511 _platform = sys.platform.lower()
512 # This flags if we are running on irix
513 self.__irix_hack = _platform.startswith('irix')
514 # Solaris uses internal __fork_pty(). All others use pty.fork().
515 self.use_native_pty_fork = not (
516 _platform.startswith('solaris') or
517 _platform.startswith('sunos'))
518 # inherit EOF and INTR definitions from controlling process.
520 from termios import VEOF, VINTR
522 fd = sys.__stdin__.fileno()
524 # ValueError: I/O operation on closed file
525 fd = sys.__stdout__.fileno()
526 self._INTR = ord(termios.tcgetattr(fd)[6][VINTR])
527 self._EOF = ord(termios.tcgetattr(fd)[6][VEOF])
528 except (ImportError, OSError, IOError, ValueError, termios.error):
529 # unless the controlling process is also not a terminal,
530 # such as cron(1), or when stdin and stdout are both closed.
531 # Fall-back to using CEOF and CINTR. There
533 from termios import CEOF, CINTR
534 (self._INTR, self._EOF) = (CINTR, CEOF)
537 (self._INTR, self._EOF) = (3, 4)
538 # Support subclasses that do not use command or args.
542 self.name = '<pexpect factory incomplete>'
544 self._spawn(command, args)
547 def _coerce_expect_string(s):
548 if not isinstance(s, bytes):
549 return s.encode('ascii')
553 def _coerce_send_string(s):
554 if not isinstance(s, bytes):
555 return s.encode('utf-8')
559 def _coerce_read_string(s):
563 '''This makes sure that no system resources are left open. Python only
564 garbage collects Python objects. OS file descriptors are not Python
565 objects, so they must be handled explicitly. If the child file
566 descriptor was opened outside of this class (passed to the constructor)
567 then this does not close it. '''
570 # It is possible for __del__ methods to execute during the
571 # teardown of the Python VM itself. Thus self.close() may
572 # trigger an exception because os.close may be None.
575 # which exception, shouldnt' we catch explicitly .. ?
580 '''This returns a human-readable string that represents the state of
585 s.append('version: ' + __version__)
586 s.append('command: ' + str(self.command))
587 s.append('args: %r' % (self.args,))
588 s.append('searcher: %r' % (self.searcher,))
589 s.append('buffer (last 100 chars): %r' % (
590 self.buffer[-100:] if self.buffer else self.buffer,))
591 s.append('before (last 100 chars): %r' % (
592 self.before[-100:] if self.before else self.before,))
593 s.append('after: %r' % (self.after,))
594 s.append('match: %r' % (self.match,))
595 s.append('match_index: ' + str(self.match_index))
596 s.append('exitstatus: ' + str(self.exitstatus))
597 s.append('flag_eof: ' + str(self.flag_eof))
598 s.append('pid: ' + str(self.pid))
599 s.append('child_fd: ' + str(self.child_fd))
600 s.append('closed: ' + str(self.closed))
601 s.append('timeout: ' + str(self.timeout))
602 s.append('delimiter: ' + str(self.delimiter))
603 s.append('logfile: ' + str(self.logfile))
604 s.append('logfile_read: ' + str(self.logfile_read))
605 s.append('logfile_send: ' + str(self.logfile_send))
606 s.append('maxread: ' + str(self.maxread))
607 s.append('ignorecase: ' + str(self.ignorecase))
608 s.append('searchwindowsize: ' + str(self.searchwindowsize))
609 s.append('delaybeforesend: ' + str(self.delaybeforesend))
610 s.append('delayafterclose: ' + str(self.delayafterclose))
611 s.append('delayafterterminate: ' + str(self.delayafterterminate))
614 def _spawn(self, command, args=[]):
615 '''This starts the given command in a child process. This does all the
616 fork/exec type of stuff for a pty. This is called by __init__. If args
617 is empty then command will be parsed (split on spaces) and args will be
618 set to parsed arguments. '''
620 # The pid and child_fd of this object get set by this method.
621 # Note that it is difficult for this method to fail.
622 # You cannot detect if the child process cannot start.
623 # So the only way you can tell if the child process started
624 # or not is to try to read from the file descriptor. If you get
625 # EOF immediately then it means that the child is already dead.
626 # That may not necessarily be bad because you may have spawned a child
627 # that performs some task; creates no stdout output; and then dies.
629 # If command is an int type then it may represent a file descriptor.
630 if isinstance(command, type(0)):
631 raise ExceptionPexpect('Command is an int type. ' +
632 'If this is a file descriptor then maybe you want to ' +
633 'use fdpexpect.fdspawn which takes an existing ' +
634 'file descriptor instead of a command string.')
636 if not isinstance(args, type([])):
637 raise TypeError('The argument, args, must be a list.')
640 self.args = split_command_line(command)
641 self.command = self.args[0]
643 # Make a shallow copy of the args list.
645 self.args.insert(0, command)
646 self.command = command
648 command_with_path = which(self.command)
649 if command_with_path is None:
650 raise ExceptionPexpect('The command was not found or was not ' +
651 'executable: %s.' % self.command)
652 self.command = command_with_path
653 self.args[0] = self.command
655 self.name = '<' + ' '.join(self.args) + '>'
657 assert self.pid is None, 'The pid member must be None.'
658 assert self.command is not None, 'The command member must not be None.'
660 kwargs = {'echo': self.echo}
661 if self.ignore_sighup:
662 kwargs['before_exec'] = [lambda: signal.signal(signal.SIGHUP, signal.SIG_IGN)]
663 self.ptyproc = self.ptyprocess_class.spawn(self.args, env=self.env,
664 cwd=self.cwd, **kwargs)
666 self.pid = self.ptyproc.pid
667 self.child_fd = self.ptyproc.fd
670 self.terminated = False
674 '''This returns the file descriptor of the pty for the child.
678 def close(self, force=True):
679 '''This closes the connection with the child application. Note that
680 calling close() more than once is valid. This emulates standard Python
681 behavior with files. Set force to True if you want to make sure that
682 the child is terminated (SIGKILL is sent if the child ignores SIGHUP
687 os.close(self.child_fd)
688 # Give kernel time to update process status.
689 time.sleep(self.delayafterclose)
691 if not self.terminate(force):
692 raise ExceptionPexpect('Could not terminate the child.')
698 '''This does nothing. It is here to support the interface for a
699 File-like object. '''
704 '''This returns True if the file descriptor is open and connected to a
705 tty(-like) device, else False.
707 On SVR4-style platforms implementing streams, such as SunOS and HP-UX,
708 the child pty may not appear as a terminal device. This means
709 methods such as setecho(), setwinsize(), getwinsize() may raise an
712 return os.isatty(self.child_fd)
714 def waitnoecho(self, timeout=-1):
715 '''This waits until the terminal ECHO flag is set False. This returns
716 True if the echo mode is off. This returns False if the ECHO flag was
717 not set False before the timeout. This can be used to detect when the
718 child is waiting for a password. Usually a child application will turn
719 off echo mode when it is waiting for the user to enter a password. For
720 example, instead of expecting the "password:" prompt you can wait for
721 the child to set ECHO off::
723 p = pexpect.spawn('ssh user@example.com')
725 p.sendline(mypassword)
727 If timeout==-1 then this method will use the value in self.timeout.
728 If timeout==None then this method to block until ECHO flag is False.
732 timeout = self.timeout
733 if timeout is not None:
734 end_time = time.time() + timeout
736 if not self.getecho():
738 if timeout < 0 and timeout is not None:
740 if timeout is not None:
741 timeout = end_time - time.time()
745 '''This returns the terminal echo mode. This returns True if echo is
746 on or False if echo is off. Child applications that are expecting you
747 to enter a password often set ECHO False. See waitnoecho().
749 Not supported on platforms where ``isatty()`` returns False. '''
750 return self.ptyproc.getecho()
752 def setecho(self, state):
753 '''This sets the terminal echo mode on or off. Note that anything the
754 child sent before the echo will be lost, so you should be sure that
755 your input buffer is empty before you call setecho(). For example, the
756 following will work as expected::
758 p = pexpect.spawn('cat') # Echo is on by default.
759 p.sendline('1234') # We expect see this twice from the child...
760 p.expect(['1234']) # ... once from the tty echo...
761 p.expect(['1234']) # ... and again from cat itself.
762 p.setecho(False) # Turn off tty echo
763 p.sendline('abcd') # We will set this only once (echoed by cat).
764 p.sendline('wxyz') # We will set this only once (echoed by cat)
768 The following WILL NOT WORK because the lines sent before the setecho
771 p = pexpect.spawn('cat')
773 p.setecho(False) # Turn off tty echo
774 p.sendline('abcd') # We will set this only once (echoed by cat).
775 p.sendline('wxyz') # We will set this only once (echoed by cat)
782 Not supported on platforms where ``isatty()`` returns False.
784 return self.ptyproc.setecho(state)
788 def _log(self, s, direction):
789 if self.logfile is not None:
790 self.logfile.write(s)
792 second_log = self.logfile_send if (direction=='send') else self.logfile_read
793 if second_log is not None:
797 def read_nonblocking(self, size=1, timeout=-1):
798 '''This reads at most size characters from the child application. It
799 includes a timeout. If the read does not complete within the timeout
800 period then a TIMEOUT exception is raised. If the end of file is read
801 then an EOF exception will be raised. If a log file was set using
802 setlog() then all data will also be written to the log file.
804 If timeout is None then the read may block indefinitely.
805 If timeout is -1 then the self.timeout value is used. If timeout is 0
806 then the child is polled and if there is no data immediately ready
807 then this will raise a TIMEOUT exception.
809 The timeout refers only to the amount of time to read at least one
810 character. This is not effected by the 'size' parameter, so if you call
811 read_nonblocking(size=100, timeout=30) and only one character is
812 available right away then one character will be returned immediately.
813 It will not wait for 30 seconds for another 99 characters to come in.
815 This is a wrapper around os.read(). It uses select.select() to
816 implement the timeout. '''
819 raise ValueError('I/O operation on closed file.')
822 timeout = self.timeout
824 # Note that some systems such as Solaris do not give an EOF when
825 # the child dies. In fact, you can still try to read
826 # from the child_fd -- it will block forever or until TIMEOUT.
827 # For this case, I test isalive() before doing any reading.
828 # If isalive() is false, then I pretend that this is the same as EOF.
829 if not self.isalive():
830 # timeout of 0 means "poll"
831 r, w, e = self.__select([self.child_fd], [], [], 0)
834 raise EOF('End Of File (EOF). Braindead platform.')
835 elif self.__irix_hack:
836 # Irix takes a long time before it realizes a child was terminated.
837 # FIXME So does this mean Irix systems are forced to always have
838 # FIXME a 2 second delay when calling read_nonblocking? That sucks.
839 r, w, e = self.__select([self.child_fd], [], [], 2)
840 if not r and not self.isalive():
842 raise EOF('End Of File (EOF). Slow platform.')
844 r, w, e = self.__select([self.child_fd], [], [], timeout)
847 if not self.isalive():
848 # Some platforms, such as Irix, will claim that their
849 # processes are alive; timeout on the select; and
850 # then finally admit that they are not alive.
852 raise EOF('End of File (EOF). Very slow platform.')
854 raise TIMEOUT('Timeout exceeded.')
856 if self.child_fd in r:
858 s = os.read(self.child_fd, size)
859 except OSError as err:
860 if err.args[0] == errno.EIO:
863 raise EOF('End Of File (EOF). Exception style platform.')
868 raise EOF('End Of File (EOF). Empty string style platform.')
870 s = self._coerce_read_string(s)
874 raise ExceptionPexpect('Reached an unexpected state.') # pragma: no cover
876 def read(self, size=-1):
877 '''This reads at most "size" bytes from the file (less if the read hits
878 EOF before obtaining size bytes). If the size argument is negative or
879 omitted, read all data until EOF is reached. The bytes are returned as
880 a string object. An empty string is returned when EOF is encountered
884 return self.string_type()
886 # delimiter default is EOF
887 self.expect(self.delimiter)
890 # I could have done this more directly by not using expect(), but
891 # I deliberately decided to couple read() to expect() so that
892 # I would catch any bugs early and ensure consistant behavior.
893 # It's a little less efficient, but there is less for me to
894 # worry about if I have to later modify read() or expect().
895 # Note, it's OK if size==-1 in the regex. That just means it
896 # will never match anything in which case we stop only on EOF.
897 cre = re.compile(self._coerce_expect_string('.{%d}' % size), re.DOTALL)
898 # delimiter default is EOF
899 index = self.expect([cre, self.delimiter])
901 ### FIXME self.before should be ''. Should I assert this?
905 def readline(self, size=-1):
906 '''This reads and returns one entire line. The newline at the end of
907 line is returned as part of the string, unless the file ends without a
908 newline. An empty string is returned if EOF is encountered immediately.
909 This looks for a newline as a CR/LF pair (\\r\\n) even on UNIX because
910 this is what the pseudotty device returns. So contrary to what you may
911 expect you will receive newlines as \\r\\n.
913 If the size argument is 0 then an empty string is returned. In all
914 other cases the size argument is ignored, which is not standard
915 behavior for a file-like object. '''
918 return self.string_type()
919 # delimiter default is EOF
920 index = self.expect([self.crlf, self.delimiter])
922 return self.before + self.crlf
927 '''This is to support iterators over a file-like object.
929 return iter(self.readline, self.string_type())
931 def readlines(self, sizehint=-1):
932 '''This reads until EOF using readline() and returns a list containing
933 the lines thus read. The optional 'sizehint' argument is ignored.
934 Remember, because this reads until EOF that means the child
935 process should have closed its stdout. If you run this method on
936 a child that is still running with its stdout open then this
937 method will block until it timesout.'''
941 line = self.readline()
948 '''This is similar to send() except that there is no return value.
953 def writelines(self, sequence):
954 '''This calls write() for each element in the sequence. The sequence
955 can be any iterable object producing strings, typically a list of
956 strings. This does not add line separators. There is no return value.
963 '''Sends string ``s`` to the child process, returning the number of
964 bytes written. If a logfile is specified, a copy is written to that
967 time.sleep(self.delaybeforesend)
969 s = self._coerce_send_string(s)
975 return os.write(self.child_fd, s)
977 def sendline(self, s=''):
978 '''Wraps send(), sending string ``s`` to child process, with os.linesep
979 automatically appended. Returns number of bytes written. '''
982 n = n + self.send(self.linesep)
985 def sendcontrol(self, char):
987 '''Helper method that wraps send() with mnemonic access for sending control
988 character to the child (such as Ctrl-C or Ctrl-D). For example, to send
989 Ctrl-G (ASCII 7, bell, '\a')::
991 child.sendcontrol('g')
993 See also, sendintr() and sendeof().
998 if a >= 97 and a <= 122:
1000 return self.send(self._chr(a))
1001 d = {'@': 0, '`': 0,
1010 return self.send(self._chr(d[char]))
1014 '''This sends an EOF to the child. This sends a character which causes
1015 the pending parent output buffer to be sent to the waiting child
1016 program without waiting for end-of-line. If it is the first character
1017 of the line, the read() in the user program returns 0, which signifies
1018 end-of-file. This means to work as expected a sendeof() has to be
1019 called at the beginning of a line. This method does not send a newline.
1020 It is the responsibility of the caller to ensure the eof is sent at the
1021 beginning of a line. '''
1023 self.send(self._chr(self._EOF))
1027 '''This sends a SIGINT to the child. It does not require
1028 the SIGINT to be the first character on a line. '''
1030 self.send(self._chr(self._INTR))
1034 '''This returns True if the EOF exception was ever raised.
1037 return self.flag_eof
1039 def terminate(self, force=False):
1041 '''This forces a child process to terminate. It starts nicely with
1042 SIGHUP and SIGINT. If "force" is True then moves onto SIGKILL. This
1043 returns True if the child was terminated. This returns False if the
1044 child could not be terminated. '''
1046 if not self.isalive():
1049 self.kill(signal.SIGHUP)
1050 time.sleep(self.delayafterterminate)
1051 if not self.isalive():
1053 self.kill(signal.SIGCONT)
1054 time.sleep(self.delayafterterminate)
1055 if not self.isalive():
1057 self.kill(signal.SIGINT)
1058 time.sleep(self.delayafterterminate)
1059 if not self.isalive():
1062 self.kill(signal.SIGKILL)
1063 time.sleep(self.delayafterterminate)
1064 if not self.isalive():
1070 # I think there are kernel timing issues that sometimes cause
1071 # this to happen. I think isalive() reports True, but the
1072 # process is dead to the kernel.
1073 # Make one last attempt to see if the kernel is up to date.
1074 time.sleep(self.delayafterterminate)
1075 if not self.isalive():
1082 '''This waits until the child exits. This is a blocking call. This will
1083 not read any data from the child, so this will block forever if the
1084 child has unread output and has terminated. In other words, the child
1085 may have printed output then called exit(), but, the child is
1086 technically still alive until its output is read by the parent. '''
1089 pid, status = os.waitpid(self.pid, 0)
1091 raise ExceptionPexpect('Cannot wait for dead child process.')
1092 self.exitstatus = os.WEXITSTATUS(status)
1093 if os.WIFEXITED(status):
1094 self.status = status
1095 self.exitstatus = os.WEXITSTATUS(status)
1096 self.signalstatus = None
1097 self.terminated = True
1098 elif os.WIFSIGNALED(status):
1099 self.status = status
1100 self.exitstatus = None
1101 self.signalstatus = os.WTERMSIG(status)
1102 self.terminated = True
1103 elif os.WIFSTOPPED(status): # pragma: no cover
1104 # You can't call wait() on a child process in the stopped state.
1105 raise ExceptionPexpect('Called wait() on a stopped child ' +
1106 'process. This is not supported. Is some other ' +
1107 'process attempting job control with our child pid?')
1108 return self.exitstatus
1112 '''This tests if the child process is running or not. This is
1113 non-blocking. If the child was terminated then this will read the
1114 exitstatus or signalstatus of the child. This returns True if the child
1115 process appears to be running or False if not. It can take literally
1116 SECONDS for Solaris to return the right status. '''
1122 # This is for Linux, which requires the blocking form
1123 # of waitpid to get the status of a defunct process.
1124 # This is super-lame. The flag_eof would have been set
1125 # in read_nonblocking(), so this should be safe.
1128 waitpid_options = os.WNOHANG
1131 pid, status = os.waitpid(self.pid, waitpid_options)
1133 err = sys.exc_info()[1]
1134 # No child processes
1135 if err.errno == errno.ECHILD:
1136 raise ExceptionPexpect('isalive() encountered condition ' +
1137 'where "terminated" is 0, but there was no child ' +
1138 'process. Did someone else call waitpid() ' +
1143 # I have to do this twice for Solaris.
1144 # I can't even believe that I figured this out...
1145 # If waitpid() returns 0 it means that no child process
1146 # wishes to report, and the value of status is undefined.
1149 ### os.WNOHANG) # Solaris!
1150 pid, status = os.waitpid(self.pid, waitpid_options)
1151 except OSError as e: # pragma: no cover
1152 # This should never happen...
1153 if e.errno == errno.ECHILD:
1154 raise ExceptionPexpect('isalive() encountered condition ' +
1155 'that should never happen. There was no child ' +
1156 'process. Did someone else call waitpid() ' +
1161 # If pid is still 0 after two calls to waitpid() then the process
1162 # really is alive. This seems to work on all platforms, except for
1163 # Irix which seems to require a blocking call on waitpid or select,
1164 # so I let read_nonblocking take care of this situation
1165 # (unfortunately, this requires waiting through the timeout).
1172 if os.WIFEXITED(status):
1173 self.status = status
1174 self.exitstatus = os.WEXITSTATUS(status)
1175 self.signalstatus = None
1176 self.terminated = True
1177 elif os.WIFSIGNALED(status):
1178 self.status = status
1179 self.exitstatus = None
1180 self.signalstatus = os.WTERMSIG(status)
1181 self.terminated = True
1182 elif os.WIFSTOPPED(status):
1183 raise ExceptionPexpect('isalive() encountered condition ' +
1184 'where child process is stopped. This is not ' +
1185 'supported. Is some other process attempting ' +
1186 'job control with our child pid?')
1189 def kill(self, sig):
1191 '''This sends the given signal to the child application. In keeping
1192 with UNIX tradition it has a misleading name. It does not necessarily
1193 kill the child unless you send the right signal. '''
1195 # Same as os.kill, but the pid is given for you.
1197 os.kill(self.pid, sig)
1199 def _pattern_type_err(self, pattern):
1200 raise TypeError('got {badtype} ({badobj!r}) as pattern, must be one'
1201 ' of: {goodtypes}, pexpect.EOF, pexpect.TIMEOUT'\
1202 .format(badtype=type(pattern),
1204 goodtypes=', '.join([str(ast)\
1205 for ast in self.allowed_string_types])
1209 def compile_pattern_list(self, patterns):
1211 '''This compiles a pattern-string or a list of pattern-strings.
1212 Patterns must be a StringType, EOF, TIMEOUT, SRE_Pattern, or a list of
1213 those. Patterns may also be None which results in an empty list (you
1214 might do this if waiting for an EOF or TIMEOUT condition without
1215 expecting any pattern).
1217 This is used by expect() when calling expect_list(). Thus expect() is
1220 cpl = self.compile_pattern_list(pl)
1221 return self.expect_list(cpl, timeout)
1223 If you are using expect() within a loop it may be more
1224 efficient to compile the patterns first and then call expect_list().
1225 This avoid calls in a loop to compile_pattern_list()::
1227 cpl = self.compile_pattern_list(my_pattern)
1228 while some_condition:
1230 i = self.expect_list(cpl, timeout)
1234 if patterns is None:
1236 if not isinstance(patterns, list):
1237 patterns = [patterns]
1239 # Allow dot to match \n
1240 compile_flags = re.DOTALL
1242 compile_flags = compile_flags | re.IGNORECASE
1243 compiled_pattern_list = []
1244 for idx, p in enumerate(patterns):
1245 if isinstance(p, self.allowed_string_types):
1246 p = self._coerce_expect_string(p)
1247 compiled_pattern_list.append(re.compile(p, compile_flags))
1249 compiled_pattern_list.append(EOF)
1251 compiled_pattern_list.append(TIMEOUT)
1252 elif isinstance(p, type(re.compile(''))):
1253 compiled_pattern_list.append(p)
1255 self._pattern_type_err(p)
1256 return compiled_pattern_list
1258 def expect(self, pattern, timeout=-1, searchwindowsize=-1, async=False):
1260 '''This seeks through the stream until a pattern is matched. The
1261 pattern is overloaded and may take several types. The pattern can be a
1262 StringType, EOF, a compiled re, or a list of any of those types.
1263 Strings will be compiled to re types. This returns the index into the
1264 pattern list. If the pattern was not a list this returns index 0 on a
1265 successful match. This may raise exceptions for EOF or TIMEOUT. To
1266 avoid the EOF or TIMEOUT exceptions add EOF or TIMEOUT to the pattern
1267 list. That will cause expect to match an EOF or TIMEOUT condition
1268 instead of raising an exception.
1270 If you pass a list of patterns and more than one matches, the first
1271 match in the stream is chosen. If more than one pattern matches at that
1272 point, the leftmost in the pattern list is chosen. For example::
1274 # the input is 'foobar'
1275 index = p.expect(['bar', 'foo', 'foobar'])
1276 # returns 1('foo') even though 'foobar' is a "better" match
1278 Please note, however, that buffering can affect this behavior, since
1279 input arrives in unpredictable chunks. For example::
1281 # the input is 'foobar'
1282 index = p.expect(['foobar', 'foo'])
1283 # returns 0('foobar') if all input is available at once,
1284 # but returs 1('foo') if parts of the final 'bar' arrive late
1286 After a match is found the instance attributes 'before', 'after' and
1287 'match' will be set. You can see all the data read before the match in
1288 'before'. You can see the data that was matched in 'after'. The
1289 re.MatchObject used in the re match will be in 'match'. If an error
1290 occurred then 'before' will be set to all the data read so far and
1291 'after' and 'match' will be None.
1293 If timeout is -1 then timeout will be set to the self.timeout value.
1295 A list entry may be EOF or TIMEOUT instead of a string. This will
1296 catch these exceptions and return the index of the list entry instead
1297 of raising the exception. The attribute 'after' will be set to the
1298 exception type. The attribute 'match' will be None. This allows you to
1299 write code like this::
1301 index = p.expect(['good', 'bad', pexpect.EOF, pexpect.TIMEOUT])
1307 do_some_other_thing()
1309 do_something_completely_different()
1311 instead of code like this::
1314 index = p.expect(['good', 'bad'])
1320 do_some_other_thing()
1322 do_something_completely_different()
1324 These two forms are equivalent. It all depends on what you want. You
1325 can also just expect the EOF if you are waiting for all output of a
1326 child to finish. For example::
1328 p = pexpect.spawn('/bin/ls')
1329 p.expect(pexpect.EOF)
1332 If you are trying to optimize for speed then see expect_list().
1334 On Python 3.4, or Python 3.3 with asyncio installed, passing
1335 ``async=True`` will make this return an :mod:`asyncio` coroutine,
1336 which you can yield from to get the same result that this method would
1337 normally give directly. So, inside a coroutine, you can replace this code::
1339 index = p.expect(patterns)
1341 With this non-blocking form::
1343 index = yield from p.expect(patterns, async=True)
1346 compiled_pattern_list = self.compile_pattern_list(pattern)
1347 return self.expect_list(compiled_pattern_list,
1348 timeout, searchwindowsize, async)
1350 def expect_list(self, pattern_list, timeout=-1, searchwindowsize=-1,
1352 '''This takes a list of compiled regular expressions and returns the
1353 index into the pattern_list that matched the child output. The list may
1354 also contain EOF or TIMEOUT(which are not compiled regular
1355 expressions). This method is similar to the expect() method except that
1356 expect_list() does not recompile the pattern list on every call. This
1357 may help if you are trying to optimize for speed, otherwise just use
1358 the expect() method. This is called by expect(). If timeout==-1 then
1359 the self.timeout value is used. If searchwindowsize==-1 then the
1360 self.searchwindowsize value is used.
1362 Like :meth:`expect`, passing ``async=True`` will make this return an
1366 timeout = self.timeout
1368 exp = Expecter(self, searcher_re(pattern_list), searchwindowsize)
1370 from .async import expect_async
1371 return expect_async(exp, timeout)
1373 return exp.expect_loop(timeout)
1375 def expect_exact(self, pattern_list, timeout=-1, searchwindowsize=-1,
1378 '''This is similar to expect(), but uses plain string matching instead
1379 of compiled regular expressions in 'pattern_list'. The 'pattern_list'
1380 may be a string; a list or other sequence of strings; or TIMEOUT and
1383 This call might be faster than expect() for two reasons: string
1384 searching is faster than RE matching and it is possible to limit the
1385 search to just the end of the input buffer.
1387 This method is also useful when you don't want to have to worry about
1388 escaping regular expression characters that you want to match.
1390 Like :meth:`expect`, passing ``async=True`` will make this return an
1394 timeout = self.timeout
1396 if (isinstance(pattern_list, self.allowed_string_types) or
1397 pattern_list in (TIMEOUT, EOF)):
1398 pattern_list = [pattern_list]
1400 def prepare_pattern(pattern):
1401 if pattern in (TIMEOUT, EOF):
1403 if isinstance(pattern, self.allowed_string_types):
1404 return self._coerce_expect_string(pattern)
1405 self._pattern_type_err(pattern)
1408 pattern_list = iter(pattern_list)
1410 self._pattern_type_err(pattern_list)
1411 pattern_list = [prepare_pattern(p) for p in pattern_list]
1413 exp = Expecter(self, searcher_string(pattern_list), searchwindowsize)
1415 from .async import expect_async
1416 return expect_async(exp, timeout)
1418 return exp.expect_loop(timeout)
1420 def expect_loop(self, searcher, timeout=-1, searchwindowsize=-1):
1421 '''This is the common loop used inside expect. The 'searcher' should be
1422 an instance of searcher_re or searcher_string, which describes how and
1423 what to search for in the input.
1425 See expect() for other arguments, return value and exceptions. '''
1427 exp = Expecter(self, searcher, searchwindowsize)
1428 return exp.expect_loop(timeout)
1430 def getwinsize(self):
1431 '''This returns the terminal window size of the child tty. The return
1432 value is a tuple of (rows, cols). '''
1433 return self.ptyproc.getwinsize()
1435 def setwinsize(self, rows, cols):
1436 '''This sets the terminal window size of the child tty. This will cause
1437 a SIGWINCH signal to be sent to the child. This does not change the
1438 physical window size. It changes the size reported to TTY-aware
1439 applications like vi or curses -- applications that respond to the
1440 SIGWINCH signal. '''
1441 return self.ptyproc.setwinsize(rows, cols)
1444 def interact(self, escape_character=chr(29),
1445 input_filter=None, output_filter=None):
1447 '''This gives control of the child process to the interactive user (the
1448 human at the keyboard). Keystrokes are sent to the child process, and
1449 the stdout and stderr output of the child process is printed. This
1450 simply echos the child stdout and child stderr to the real stdout and
1451 it echos the real stdin to the child stdin. When the user types the
1452 escape_character this method will stop. The default for
1453 escape_character is ^]. This should not be confused with ASCII 27 --
1454 the ESC character. ASCII 29 was chosen for historical merit because
1455 this is the character used by 'telnet' as the escape character. The
1456 escape_character will not be sent to the child process.
1458 You may pass in optional input and output filter functions. These
1459 functions should take a string and return a string. The output_filter
1460 will be passed all the output from the child process. The input_filter
1461 will be passed all the keyboard input from the user. The input_filter
1462 is run BEFORE the check for the escape_character.
1464 Note that if you change the window size of the parent the SIGWINCH
1465 signal will not be passed through to the child. If you want the child
1466 window size to change when the parent's window size changes then do
1467 something like the following example::
1469 import pexpect, struct, fcntl, termios, signal, sys
1470 def sigwinch_passthrough (sig, data):
1471 s = struct.pack("HHHH", 0, 0, 0, 0)
1472 a = struct.unpack('hhhh', fcntl.ioctl(sys.stdout.fileno(),
1473 termios.TIOCGWINSZ , s))
1475 p.setwinsize(a[0],a[1])
1476 # Note this 'p' global and used in sigwinch_passthrough.
1477 p = pexpect.spawn('/bin/bash')
1478 signal.signal(signal.SIGWINCH, sigwinch_passthrough)
1483 self.write_to_stdout(self.buffer)
1485 self.buffer = self.string_type()
1486 mode = tty.tcgetattr(self.STDIN_FILENO)
1487 tty.setraw(self.STDIN_FILENO)
1489 escape_character = escape_character.encode('latin-1')
1491 self.__interact_copy(escape_character, input_filter, output_filter)
1493 tty.tcsetattr(self.STDIN_FILENO, tty.TCSAFLUSH, mode)
1495 def __interact_writen(self, fd, data):
1496 '''This is used by the interact() method.
1499 while data != b'' and self.isalive():
1500 n = os.write(fd, data)
1503 def __interact_read(self, fd):
1504 '''This is used by the interact() method.
1507 return os.read(fd, 1000)
1509 def __interact_copy(self, escape_character=None,
1510 input_filter=None, output_filter=None):
1512 '''This is used by the interact() method.
1515 while self.isalive():
1516 r, w, e = self.__select([self.child_fd, self.STDIN_FILENO], [], [])
1517 if self.child_fd in r:
1519 data = self.__interact_read(self.child_fd)
1520 except OSError as err:
1521 if err.args[0] == errno.EIO:
1529 data = output_filter(data)
1530 if self.logfile is not None:
1531 self.logfile.write(data)
1532 self.logfile.flush()
1533 os.write(self.STDOUT_FILENO, data)
1534 if self.STDIN_FILENO in r:
1535 data = self.__interact_read(self.STDIN_FILENO)
1537 data = input_filter(data)
1538 i = data.rfind(escape_character)
1541 self.__interact_writen(self.child_fd, data)
1543 self.__interact_writen(self.child_fd, data)
1545 def __select(self, iwtd, owtd, ewtd, timeout=None):
1547 '''This is a wrapper around select.select() that ignores signals. If
1548 select.select raises a select.error exception and errno is an EINTR
1549 error then it is ignored. Mainly this is used to ignore sigwinch
1550 (terminal resize). '''
1552 # if select() is interrupted by a signal (errno==EINTR) then
1553 # we loop back and enter the select() again.
1554 if timeout is not None:
1555 end_time = time.time() + timeout
1558 return select.select(iwtd, owtd, ewtd, timeout)
1559 except select.error:
1560 err = sys.exc_info()[1]
1561 if err.args[0] == errno.EINTR:
1562 # if we loop back we have to subtract the
1563 # amount of time we already waited.
1564 if timeout is not None:
1565 timeout = end_time - time.time()
1569 # something else caused the select.error, so
1570 # this actually is an exception.
1573 ##############################################################################
1574 # The following methods are no longer supported or allowed.
1576 def setmaxread(self, maxread): # pragma: no cover
1578 '''This method is no longer supported or allowed. I don't like getters
1579 and setters without a good reason. '''
1581 raise ExceptionPexpect('This method is no longer supported ' +
1582 'or allowed. Just assign a value to the ' +
1583 'maxread member variable.')
1585 def setlog(self, fileobject): # pragma: no cover
1587 '''This method is no longer supported or allowed.
1590 raise ExceptionPexpect('This method is no longer supported ' +
1591 'or allowed. Just assign a value to the logfile ' +
1594 ##############################################################################
1595 # End of spawn class
1596 ##############################################################################
1598 class spawnu(spawn):
1599 """Works like spawn, but accepts and returns unicode strings.
1603 :param encoding: The encoding to use for communications (default: 'utf-8')
1604 :param errors: How to handle encoding/decoding errors; one of 'strict'
1605 (the default), 'ignore', or 'replace', as described
1606 for :meth:`~bytes.decode` and :meth:`~str.encode`.
1610 allowed_string_types = (str, )
1611 _chr = staticmethod(chr)
1612 linesep = os.linesep
1615 string_type = unicode
1616 allowed_string_types = (unicode, )
1617 _chr = staticmethod(unichr)
1618 linesep = os.linesep.decode('ascii')
1619 crlf = '\r\n'.decode('ascii')
1620 # This can handle unicode in both Python 2 and 3
1621 write_to_stdout = sys.stdout.write
1622 ptyprocess_class = ptyprocess.PtyProcessUnicode
1624 def __init__(self, *args, **kwargs):
1625 self.encoding = kwargs.pop('encoding', 'utf-8')
1626 self.errors = kwargs.pop('errors', 'strict')
1627 self._decoder = codecs.getincrementaldecoder(self.encoding)(errors=self.errors)
1628 super(spawnu, self).__init__(*args, **kwargs)
1631 def _coerce_expect_string(s):
1635 def _coerce_send_string(s):
1638 def _coerce_read_string(self, s):
1639 return self._decoder.decode(s, final=False)
1642 return os.write(self.child_fd, s.encode(self.encoding, self.errors))
1645 class searcher_string(object):
1647 '''This is a plain string search helper for the spawn.expect_any() method.
1648 This helper class is for speed. For more powerful regex patterns
1649 see the helper class, searcher_re.
1653 eof_index - index of EOF, or -1
1654 timeout_index - index of TIMEOUT, or -1
1656 After a successful match by the search() method the following attributes
1659 start - index into the buffer, first byte of match
1660 end - index into the buffer, first byte after match
1661 match - the matching string itself
1665 def __init__(self, strings):
1667 '''This creates an instance of searcher_string. This argument 'strings'
1668 may be a list; a sequence of strings; or the EOF or TIMEOUT types. '''
1671 self.timeout_index = -1
1673 for n, s in enumerate(strings):
1678 self.timeout_index = n
1680 self._strings.append((n, s))
1684 '''This returns a human-readable string that represents the state of
1687 ss = [(ns[0], ' %d: "%s"' % ns) for ns in self._strings]
1688 ss.append((-1, 'searcher_string:'))
1689 if self.eof_index >= 0:
1690 ss.append((self.eof_index, ' %d: EOF' % self.eof_index))
1691 if self.timeout_index >= 0:
1692 ss.append((self.timeout_index,
1693 ' %d: TIMEOUT' % self.timeout_index))
1695 ss = list(zip(*ss))[1]
1696 return '\n'.join(ss)
1698 def search(self, buffer, freshlen, searchwindowsize=None):
1700 '''This searches 'buffer' for the first occurence of one of the search
1701 strings. 'freshlen' must indicate the number of bytes at the end of
1702 'buffer' which have not been searched before. It helps to avoid
1703 searching the same, possibly big, buffer over and over again.
1705 See class spawn for the 'searchwindowsize' argument.
1707 If there is a match this returns the index of that string, and sets
1708 'start', 'end' and 'match'. Otherwise, this returns -1. '''
1712 # 'freshlen' helps a lot here. Further optimizations could
1715 # using something like the Boyer-Moore Fast String Searching
1716 # Algorithm; pre-compiling the search through a list of
1717 # strings into something that can scan the input once to
1718 # search for all N strings; realize that if we search for
1719 # ['bar', 'baz'] and the input is '...foo' we need not bother
1720 # rescanning until we've read three more bytes.
1722 # Sadly, I don't know enough about this interesting topic. /grahn
1724 for index, s in self._strings:
1725 if searchwindowsize is None:
1726 # the match, if any, can only be in the fresh data,
1727 # or at the very end of the old data
1728 offset = -(freshlen + len(s))
1730 # better obey searchwindowsize
1731 offset = -searchwindowsize
1732 n = buffer.find(s, offset)
1733 if n >= 0 and (first_match is None or n < first_match):
1735 best_index, best_match = index, s
1736 if first_match is None:
1738 self.match = best_match
1739 self.start = first_match
1740 self.end = self.start + len(self.match)
1744 class searcher_re(object):
1746 '''This is regular expression string search helper for the
1747 spawn.expect_any() method. This helper class is for powerful
1748 pattern matching. For speed, see the helper class, searcher_string.
1752 eof_index - index of EOF, or -1
1753 timeout_index - index of TIMEOUT, or -1
1755 After a successful match by the search() method the following attributes
1758 start - index into the buffer, first byte of match
1759 end - index into the buffer, first byte after match
1760 match - the re.match object returned by a succesful re.search
1764 def __init__(self, patterns):
1766 '''This creates an instance that searches for 'patterns' Where
1767 'patterns' may be a list or other sequence of compiled regular
1768 expressions, or the EOF or TIMEOUT types.'''
1771 self.timeout_index = -1
1773 for n, s in zip(list(range(len(patterns))), patterns):
1778 self.timeout_index = n
1780 self._searches.append((n, s))
1784 '''This returns a human-readable string that represents the state of
1787 #ss = [(n, ' %d: re.compile("%s")' %
1788 # (n, repr(s.pattern))) for n, s in self._searches]
1790 for n, s in self._searches:
1792 ss.append((n, ' %d: re.compile("%s")' % (n, s.pattern)))
1793 except UnicodeEncodeError:
1794 # for test cases that display __str__ of searches, dont throw
1795 # another exception just because stdout is ascii-only, using
1797 ss.append((n, ' %d: re.compile(%r)' % (n, s.pattern)))
1798 ss.append((-1, 'searcher_re:'))
1799 if self.eof_index >= 0:
1800 ss.append((self.eof_index, ' %d: EOF' % self.eof_index))
1801 if self.timeout_index >= 0:
1802 ss.append((self.timeout_index, ' %d: TIMEOUT' %
1803 self.timeout_index))
1805 ss = list(zip(*ss))[1]
1806 return '\n'.join(ss)
1808 def search(self, buffer, freshlen, searchwindowsize=None):
1810 '''This searches 'buffer' for the first occurence of one of the regular
1811 expressions. 'freshlen' must indicate the number of bytes at the end of
1812 'buffer' which have not been searched before.
1814 See class spawn for the 'searchwindowsize' argument.
1816 If there is a match this returns the index of that string, and sets
1817 'start', 'end' and 'match'. Otherwise, returns -1.'''
1820 # 'freshlen' doesn't help here -- we cannot predict the
1821 # length of a match, and the re module provides no help.
1822 if searchwindowsize is None:
1825 searchstart = max(0, len(buffer) - searchwindowsize)
1826 for index, s in self._searches:
1827 match = s.search(buffer, searchstart)
1831 if first_match is None or n < first_match:
1835 if first_match is None:
1837 self.start = first_match
1838 self.match = the_match
1839 self.end = self.match.end()
1843 def is_executable_file(path):
1844 """Checks that path is an executable regular file (or a symlink to a file).
1846 This is roughly ``os.path isfile(path) and os.access(path, os.X_OK)``, but
1847 on some platforms :func:`os.access` gives us the wrong answer, so this
1848 checks permission bits directly.
1851 fpath = os.path.realpath(path)
1853 # return False for non-files (directories, fifo, etc.)
1854 if not os.path.isfile(fpath):
1857 # On Solaris, etc., "If the process has appropriate privileges, an
1858 # implementation may indicate success for X_OK even if none of the
1859 # execute file permission bits are set."
1861 # For this reason, it is necessary to explicitly check st_mode
1863 # get file mode using os.stat, and check if `other',
1864 # that is anybody, may read and execute.
1865 mode = os.stat(fpath).st_mode
1866 if mode & stat.S_IROTH and mode & stat.S_IXOTH:
1869 # get current user's group ids, and check if `group',
1870 # when matching ours, may read and execute.
1871 user_gids = os.getgroups() + [os.getgid()]
1872 if (os.stat(fpath).st_gid in user_gids and
1873 mode & stat.S_IRGRP and mode & stat.S_IXGRP):
1876 # finally, if file owner matches our effective userid,
1877 # check if `user', may read and execute.
1878 user_gids = os.getgroups() + [os.getgid()]
1879 if (os.stat(fpath).st_uid == os.geteuid() and
1880 mode & stat.S_IRUSR and mode & stat.S_IXUSR):
1885 def which(filename):
1886 '''This takes a given filename; tries to find it in the environment path;
1887 then checks if it is executable. This returns the full path to the filename
1888 if found and executable. Otherwise this returns None.'''
1890 # Special case where filename contains an explicit path.
1891 if os.path.dirname(filename) != '' and is_executable_file(filename):
1893 if 'PATH' not in os.environ or os.environ['PATH'] == '':
1896 p = os.environ['PATH']
1897 pathlist = p.split(os.pathsep)
1898 for path in pathlist:
1899 ff = os.path.join(path, filename)
1900 if is_executable_file(ff):
1905 def split_command_line(command_line):
1907 '''This splits a command line into a list of arguments. It splits arguments
1908 on spaces, but handles embedded quotes, doublequotes, and escaped
1909 characters. It's impossible to do this with a regular expression, so I
1910 wrote a little state machine to parse the command line. '''
1915 # Constants to name the states we can be in.
1918 state_singlequote = 2
1919 state_doublequote = 3
1920 # The state when consuming whitespace between commands.
1921 state_whitespace = 4
1924 for c in command_line:
1925 if state == state_basic or state == state_whitespace:
1927 # Escape the next character
1930 # Handle single quote
1931 state = state_singlequote
1933 # Handle double quote
1934 state = state_doublequote
1936 # Add arg to arg_list if we aren't in the middle of whitespace.
1937 if state == state_whitespace:
1941 arg_list.append(arg)
1943 state = state_whitespace
1947 elif state == state_esc:
1950 elif state == state_singlequote:
1955 elif state == state_doublequote:
1962 arg_list.append(arg)
1965 # vim: set shiftround expandtab tabstop=4 shiftwidth=4 ft=python autoindent :