| | |
+
+- pexpect.ExceptionPexpect(exceptions.Exception)
+
-
+
+- ExceptionPxssh
+
+
+- pexpect.spawn(__builtin__.object)
+
-
+
+- pxssh
+
+
+
+
+
+
+
+
+class pxssh(pexpect.spawn) |
+
+| |
+This class extends pexpect.spawn to specialize setting up SSH
+connections. This adds methods for login, logout, and expecting the shell
+prompt. It does various tricky things to handle many situations in the SSH
+login process. For example, if the session is your first login, then pxssh
+automatically accepts the remote certificate; or if you have public key
+authentication setup then pxssh won't wait for the password prompt.
+
+pxssh uses the shell prompt to synchronize output from the remote host. In
+order to make this more robust it sets the shell prompt to something more
+unique than just $ or #. This should work on most Borne/Bash or Csh style
+shells.
+
+Example that runs a few commands on a remote server and prints the result::
+
+ import pxssh
+ import getpass
+ try:
+ s = pxssh.pxssh()
+ hostname = raw_input('hostname: ')
+ username = raw_input('username: ')
+ password = getpass.getpass('password: ')
+ s.login (hostname, username, password)
+ s.sendline ('uptime') # run a command
+ s.prompt() # match the prompt
+ print s.before # print everything before the prompt.
+ s.sendline ('ls -l')
+ s.prompt()
+ print s.before
+ s.sendline ('df')
+ s.prompt()
+ print s.before
+ s.logout()
+ except pxssh.ExceptionPxssh, e:
+ print "pxssh failed on login."
+ print str(e)
+
+Note that if you have ssh-agent running while doing development with pxssh
+then this can lead to a lot of confusion. Many X display managers (xdm,
+gdm, kdm, etc.) will automatically start a GUI agent. You may see a GUI
+dialog box popup asking for a password during development. You should turn
+off any key agents during testing. The 'force_password' attribute will turn
+off public key authentication. This will only work if the remote SSH server
+is configured to allow password logins. Example of using 'force_password'
+attribute::
+
+ s = pxssh.pxssh()
+ s.force_password = True
+ hostname = raw_input('hostname: ')
+ username = raw_input('username: ')
+ password = getpass.getpass('password: ')
+ s.login (hostname, username, password)
|
+| |
+- Method resolution order:
+- pxssh
+- pexpect.spawn
+- __builtin__.object
+
+
+Methods defined here:
+- __init__(self, timeout=30, maxread=2000, searchwindowsize=None, logfile=None, cwd=None, env=None)
+
+- levenshtein_distance(self, a, b)
- This calculates the Levenshtein distance between a and b.
+
+- login(self, server, username, password='', terminal_type='ansi', original_prompt='[#$]', login_timeout=10, port=None, auto_prompt_reset=True)
- This logs the user into the given server. It uses the
+'original_prompt' to try to find the prompt right after login. When it
+finds the prompt it immediately tries to reset the prompt to something
+more easily matched. The default 'original_prompt' is very optimistic
+and is easily fooled. It's more reliable to try to match the original
+prompt as exactly as possible to prevent false matches by server
+strings such as the "Message Of The Day". On many systems you can
+disable the MOTD on the remote server by creating a zero-length file
+called "~/.hushlogin" on the remote server. If a prompt cannot be found
+then this will not necessarily cause the login to fail. In the case of
+a timeout when looking for the prompt we assume that the original
+prompt was so weird that we could not match it, so we use a few tricks
+to guess when we have reached the prompt. Then we hope for the best and
+blindly try to reset the prompt to something more unique. If that fails
+then login() raises an ExceptionPxssh exception.
+
+In some situations it is not possible or desirable to reset the
+original prompt. In this case, set 'auto_prompt_reset' to False to
+inhibit setting the prompt to the UNIQUE_PROMPT. Remember that pxssh
+uses a unique prompt in the prompt() method. If the original prompt is
+not reset then this will disable the prompt() method unless you
+manually set the PROMPT attribute.
+
+- logout(self)
- This sends exit to the remote shell. If there are stopped jobs then
+this automatically sends exit twice.
+
+- prompt(self, timeout=20)
- This matches the shell prompt. This is little more than a short-cut
+to the expect() method. This returns True if the shell prompt was
+matched. This returns False if there was a timeout. Note that if you
+called login() with auto_prompt_reset set to False then you should have
+manually set the PROMPT attribute to a regex pattern for matching the
+prompt.
+
+- set_unique_prompt(self)
- This sets the remote prompt to something more unique than # or $.
+This makes it easier for the prompt() method to match the shell prompt
+unambiguously. This method is called automatically by the login()
+method, but you may want to call it manually if you somehow reset the
+shell prompt. For example, if you 'su' to a different user then you
+will need to manually reset the prompt. This sends shell commands to
+the remote host to set the prompt, so this assumes the remote host is
+ready to receive commands.
+
+Alternatively, you may use your own prompt pattern. Just set the PROMPT
+attribute to a regular expression that matches it. In this case you
+should call login() with auto_prompt_reset=False; then set the PROMPT
+attribute. After that the prompt() method will try to match your prompt
+pattern.
+
+- synch_original_prompt(self)
- This attempts to find the prompt. Basically, press enter and record
+the response; press enter again and record the response; if the two
+responses are similar then assume we are at the original prompt.
+
+
+Methods inherited from pexpect.spawn:
+- __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.
+
+- __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 inherited from pexpect.spawn:
+- __dict__
+- dictionary for instance variables (if defined)
+
+- __weakref__
+- list of weak references to the object (if defined)
+
+ | |