| | |
-
-- 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)
-
- | |