2 <!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
3 <html><head><title>Python: module pxssh</title>
4 </head><body bgcolor="#f0f0f8">
6 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="heading">
8 <td valign=bottom> <br>
9 <font color="#ffffff" face="helvetica, arial"> <br><big><big><strong>pxssh</strong></big></big> (version 2.3)</font></td
10 ><td align=right valign=bottom
11 ><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:/home/noah/pexpect/trunk/pexpect/pxssh.py">/home/noah/pexpect/trunk/pexpect/pxssh.py</a></font></td></tr></table>
12 <p><tt>This class extends pexpect.<a href="pexpect.html#spawn">spawn</a> to specialize setting up SSH connections.<br>
13 This adds methods for login, logout, and expecting the shell prompt.<br>
15 $Id: <a href="#pxssh">pxssh</a>.py 487 2007-08-29 22:33:29Z noah $</tt></p>
17 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
18 <tr bgcolor="#aa55cc">
19 <td colspan=3 valign=bottom> <br>
20 <font color="#fffff" face="helvetica, arial"><big><strong>Modules</strong></big></font></td></tr>
22 <tr><td bgcolor="#aa55cc"><tt> </tt></td><td> </td>
23 <td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="pexpect.html">pexpect</a><br>
24 </td><td width="25%" valign=top><a href="time.html">time</a><br>
25 </td><td width="25%" valign=top></td><td width="25%" valign=top></td></tr></table></td></tr></table><p>
26 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
27 <tr bgcolor="#ee77aa">
28 <td colspan=3 valign=bottom> <br>
29 <font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr>
31 <tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td>
33 <dt><font face="helvetica, arial"><a href="pexpect.html#ExceptionPexpect">pexpect.ExceptionPexpect</a>(<a href="exceptions.html#Exception">exceptions.Exception</a>)
36 <dt><font face="helvetica, arial"><a href="pxssh.html#ExceptionPxssh">ExceptionPxssh</a>
39 <dt><font face="helvetica, arial"><a href="pexpect.html#spawn">pexpect.spawn</a>(<a href="__builtin__.html#object">__builtin__.object</a>)
42 <dt><font face="helvetica, arial"><a href="pxssh.html#pxssh">pxssh</a>
47 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
48 <tr bgcolor="#ffc8d8">
49 <td colspan=3 valign=bottom> <br>
50 <font color="#000000" face="helvetica, arial"><a name="ExceptionPxssh">class <strong>ExceptionPxssh</strong></a>(<a href="pexpect.html#ExceptionPexpect">pexpect.ExceptionPexpect</a>)</font></td></tr>
52 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
53 <td colspan=2><tt>Raised for <a href="#pxssh">pxssh</a> exceptions.<br> </tt></td></tr>
55 <td width="100%"><dl><dt>Method resolution order:</dt>
56 <dd><a href="pxssh.html#ExceptionPxssh">ExceptionPxssh</a></dd>
57 <dd><a href="pexpect.html#ExceptionPexpect">pexpect.ExceptionPexpect</a></dd>
58 <dd><a href="exceptions.html#Exception">exceptions.Exception</a></dd>
59 <dd><a href="exceptions.html#BaseException">exceptions.BaseException</a></dd>
60 <dd><a href="__builtin__.html#object">__builtin__.object</a></dd>
63 Methods inherited from <a href="pexpect.html#ExceptionPexpect">pexpect.ExceptionPexpect</a>:<br>
64 <dl><dt><a name="ExceptionPxssh-__init__"><strong>__init__</strong></a>(self, value)</dt></dl>
66 <dl><dt><a name="ExceptionPxssh-__str__"><strong>__str__</strong></a>(self)</dt></dl>
68 <dl><dt><a name="ExceptionPxssh-get_trace"><strong>get_trace</strong></a>(self)</dt><dd><tt>This returns an abbreviated stack trace with lines that only concern<br>
69 the caller. In other words, the stack trace inside the Pexpect module<br>
70 is not included.</tt></dd></dl>
73 Data descriptors inherited from <a href="pexpect.html#ExceptionPexpect">pexpect.ExceptionPexpect</a>:<br>
74 <dl><dt><strong>__weakref__</strong></dt>
75 <dd><tt>list of weak references to the object (if defined)</tt></dd>
78 Data and other attributes inherited from <a href="exceptions.html#Exception">exceptions.Exception</a>:<br>
79 <dl><dt><strong>__new__</strong> = <built-in method __new__ of type object at 0x81400e0><dd><tt>T.<a href="#ExceptionPxssh-__new__">__new__</a>(S, ...) -> a new object with type S, a subtype of T</tt></dl>
82 Methods inherited from <a href="exceptions.html#BaseException">exceptions.BaseException</a>:<br>
83 <dl><dt><a name="ExceptionPxssh-__delattr__"><strong>__delattr__</strong></a>(...)</dt><dd><tt>x.<a href="#ExceptionPxssh-__delattr__">__delattr__</a>('name') <==> del x.name</tt></dd></dl>
85 <dl><dt><a name="ExceptionPxssh-__getattribute__"><strong>__getattribute__</strong></a>(...)</dt><dd><tt>x.<a href="#ExceptionPxssh-__getattribute__">__getattribute__</a>('name') <==> x.name</tt></dd></dl>
87 <dl><dt><a name="ExceptionPxssh-__getitem__"><strong>__getitem__</strong></a>(...)</dt><dd><tt>x.<a href="#ExceptionPxssh-__getitem__">__getitem__</a>(y) <==> x[y]</tt></dd></dl>
89 <dl><dt><a name="ExceptionPxssh-__getslice__"><strong>__getslice__</strong></a>(...)</dt><dd><tt>x.<a href="#ExceptionPxssh-__getslice__">__getslice__</a>(i, j) <==> x[i:j]<br>
91 Use of negative indices is not supported.</tt></dd></dl>
93 <dl><dt><a name="ExceptionPxssh-__reduce__"><strong>__reduce__</strong></a>(...)</dt></dl>
95 <dl><dt><a name="ExceptionPxssh-__repr__"><strong>__repr__</strong></a>(...)</dt><dd><tt>x.<a href="#ExceptionPxssh-__repr__">__repr__</a>() <==> repr(x)</tt></dd></dl>
97 <dl><dt><a name="ExceptionPxssh-__setattr__"><strong>__setattr__</strong></a>(...)</dt><dd><tt>x.<a href="#ExceptionPxssh-__setattr__">__setattr__</a>('name', value) <==> x.name = value</tt></dd></dl>
99 <dl><dt><a name="ExceptionPxssh-__setstate__"><strong>__setstate__</strong></a>(...)</dt></dl>
102 Data descriptors inherited from <a href="exceptions.html#BaseException">exceptions.BaseException</a>:<br>
103 <dl><dt><strong>__dict__</strong></dt>
105 <dl><dt><strong>args</strong></dt>
107 <dl><dt><strong>message</strong></dt>
108 <dd><tt>exception message</tt></dd>
110 </td></tr></table> <p>
111 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
112 <tr bgcolor="#ffc8d8">
113 <td colspan=3 valign=bottom> <br>
114 <font color="#000000" face="helvetica, arial"><a name="pxssh">class <strong>pxssh</strong></a>(<a href="pexpect.html#spawn">pexpect.spawn</a>)</font></td></tr>
116 <tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
117 <td colspan=2><tt>This class extends pexpect.<a href="pexpect.html#spawn">spawn</a> to specialize setting up SSH<br>
118 connections. This adds methods for login, logout, and expecting the shell<br>
119 prompt. It does various tricky things to handle many situations in the SSH<br>
120 login process. For example, if the session is your first login, then <a href="#pxssh">pxssh</a><br>
121 automatically accepts the remote certificate; or if you have public key<br>
122 authentication setup then <a href="#pxssh">pxssh</a> won't wait for the password prompt.<br>
124 <a href="#pxssh">pxssh</a> uses the shell prompt to synchronize output from the remote host. In<br>
125 order to make this more robust it sets the shell prompt to something more<br>
126 unique than just $ or #. This should work on most Borne/Bash or Csh style<br>
129 Example that runs a few commands on a remote server and prints the result::<br>
130 <br>
131 import <a href="#pxssh">pxssh</a><br>
132 import getpass<br>
133 try: <br>
134 s = <a href="#pxssh">pxssh</a>.<a href="#pxssh">pxssh</a>()<br>
135 hostname = raw_input('hostname: ')<br>
136 username = raw_input('username: ')<br>
137 password = getpass.getpass('password: ')<br>
138 s.login (hostname, username, password)<br>
139 s.sendline ('uptime') # run a command<br>
140 s.<a href="#pxssh-prompt">prompt</a>() # match the prompt<br>
141 print s.before # print everything before the prompt.<br>
142 s.sendline ('ls -l')<br>
143 s.<a href="#pxssh-prompt">prompt</a>()<br>
144 print s.before<br>
145 s.sendline ('df')<br>
146 s.<a href="#pxssh-prompt">prompt</a>()<br>
147 print s.before<br>
148 s.<a href="#pxssh-logout">logout</a>()<br>
149 except <a href="#pxssh">pxssh</a>.<a href="#ExceptionPxssh">ExceptionPxssh</a>, e:<br>
150 print "<a href="#pxssh">pxssh</a> failed on login."<br>
151 print str(e)<br>
153 Note that if you have ssh-agent running while doing development with <a href="#pxssh">pxssh</a><br>
154 then this can lead to a lot of confusion. Many X display managers (xdm,<br>
155 gdm, kdm, etc.) will automatically start a GUI agent. You may see a GUI<br>
156 dialog box popup asking for a password during development. You should turn<br>
157 off any key agents during testing. The 'force_password' attribute will turn<br>
158 off public key authentication. This will only work if the remote SSH server<br>
159 is configured to allow password logins. Example of using 'force_password'<br>
162 s = <a href="#pxssh">pxssh</a>.<a href="#pxssh">pxssh</a>()<br>
163 s.force_password = True<br>
164 hostname = raw_input('hostname: ')<br>
165 username = raw_input('username: ')<br>
166 password = getpass.getpass('password: ')<br>
167 s.login (hostname, username, password)<br> </tt></td></tr>
169 <td width="100%"><dl><dt>Method resolution order:</dt>
170 <dd><a href="pxssh.html#pxssh">pxssh</a></dd>
171 <dd><a href="pexpect.html#spawn">pexpect.spawn</a></dd>
172 <dd><a href="__builtin__.html#object">__builtin__.object</a></dd>
175 Methods defined here:<br>
176 <dl><dt><a name="pxssh-__init__"><strong>__init__</strong></a>(self, timeout<font color="#909090">=30</font>, maxread<font color="#909090">=2000</font>, searchwindowsize<font color="#909090">=None</font>, logfile<font color="#909090">=None</font>, cwd<font color="#909090">=None</font>, env<font color="#909090">=None</font>)</dt></dl>
178 <dl><dt><a name="pxssh-levenshtein_distance"><strong>levenshtein_distance</strong></a>(self, a, b)</dt><dd><tt>This calculates the Levenshtein distance between a and b.</tt></dd></dl>
180 <dl><dt><a name="pxssh-login"><strong>login</strong></a>(self, server, username, password<font color="#909090">=''</font>, terminal_type<font color="#909090">='ansi'</font>, original_prompt<font color="#909090">='[#$]'</font>, login_timeout<font color="#909090">=10</font>, port<font color="#909090">=None</font>, auto_prompt_reset<font color="#909090">=True</font>)</dt><dd><tt>This logs the user into the given server. It uses the<br>
181 'original_prompt' to try to find the prompt right after login. When it<br>
182 finds the prompt it immediately tries to reset the prompt to something<br>
183 more easily matched. The default 'original_prompt' is very optimistic<br>
184 and is easily fooled. It's more reliable to try to match the original<br>
185 prompt as exactly as possible to prevent false matches by server<br>
186 strings such as the "Message Of The Day". On many systems you can<br>
187 disable the MOTD on the remote server by creating a zero-length file<br>
188 called "~/.hushlogin" on the remote server. If a prompt cannot be found<br>
189 then this will not necessarily cause the login to fail. In the case of<br>
190 a timeout when looking for the prompt we assume that the original<br>
191 prompt was so weird that we could not match it, so we use a few tricks<br>
192 to guess when we have reached the prompt. Then we hope for the best and<br>
193 blindly try to reset the prompt to something more unique. If that fails<br>
194 then <a href="#pxssh-login">login</a>() raises an <a href="#ExceptionPxssh">ExceptionPxssh</a> exception.<br>
196 In some situations it is not possible or desirable to reset the<br>
197 original prompt. In this case, set 'auto_prompt_reset' to False to<br>
198 inhibit setting the prompt to the UNIQUE_PROMPT. Remember that <a href="#pxssh">pxssh</a><br>
199 uses a unique prompt in the <a href="#pxssh-prompt">prompt</a>() method. If the original prompt is<br>
200 not reset then this will disable the <a href="#pxssh-prompt">prompt</a>() method unless you<br>
201 manually set the PROMPT attribute.</tt></dd></dl>
203 <dl><dt><a name="pxssh-logout"><strong>logout</strong></a>(self)</dt><dd><tt>This sends exit to the remote shell. If there are stopped jobs then<br>
204 this automatically sends exit twice.</tt></dd></dl>
206 <dl><dt><a name="pxssh-prompt"><strong>prompt</strong></a>(self, timeout<font color="#909090">=20</font>)</dt><dd><tt>This matches the shell prompt. This is little more than a short-cut<br>
207 to the <a href="#pxssh-expect">expect</a>() method. This returns True if the shell prompt was<br>
208 matched. This returns False if there was a timeout. Note that if you<br>
209 called <a href="#pxssh-login">login</a>() with auto_prompt_reset set to False then you should have<br>
210 manually set the PROMPT attribute to a regex pattern for matching the<br>
211 prompt.</tt></dd></dl>
213 <dl><dt><a name="pxssh-set_unique_prompt"><strong>set_unique_prompt</strong></a>(self)</dt><dd><tt>This sets the remote prompt to something more unique than # or $.<br>
214 This makes it easier for the <a href="#pxssh-prompt">prompt</a>() method to match the shell prompt<br>
215 unambiguously. This method is called automatically by the <a href="#pxssh-login">login</a>()<br>
216 method, but you may want to call it manually if you somehow reset the<br>
217 shell prompt. For example, if you 'su' to a different user then you<br>
218 will need to manually reset the prompt. This sends shell commands to<br>
219 the remote host to set the prompt, so this assumes the remote host is<br>
220 ready to receive commands.<br>
222 Alternatively, you may use your own prompt pattern. Just set the PROMPT<br>
223 attribute to a regular expression that matches it. In this case you<br>
224 should call <a href="#pxssh-login">login</a>() with auto_prompt_reset=False; then set the PROMPT<br>
225 attribute. After that the <a href="#pxssh-prompt">prompt</a>() method will try to match your prompt<br>
226 pattern.</tt></dd></dl>
228 <dl><dt><a name="pxssh-synch_original_prompt"><strong>synch_original_prompt</strong></a>(self)</dt><dd><tt>This attempts to find the prompt. Basically, press enter and record<br>
229 the response; press enter again and record the response; if the two<br>
230 responses are similar then assume we are at the original prompt.</tt></dd></dl>
233 Methods inherited from <a href="pexpect.html#spawn">pexpect.spawn</a>:<br>
234 <dl><dt><a name="pxssh-__del__"><strong>__del__</strong></a>(self)</dt><dd><tt>This makes sure that no system resources are left open. Python only<br>
235 garbage collects Python objects. OS file descriptors are not Python<br>
236 objects, so they must be handled explicitly. If the child file<br>
237 descriptor was opened outside of this class (passed to the constructor)<br>
238 then this does not close it.</tt></dd></dl>
240 <dl><dt><a name="pxssh-__iter__"><strong>__iter__</strong></a>(self)</dt><dd><tt>This is to support iterators over a file-like object.</tt></dd></dl>
242 <dl><dt><a name="pxssh-__str__"><strong>__str__</strong></a>(self)</dt><dd><tt>This returns a human-readable string that represents the state of<br>
243 the object.</tt></dd></dl>
245 <dl><dt><a name="pxssh-close"><strong>close</strong></a>(self, force<font color="#909090">=True</font>)</dt><dd><tt>This closes the connection with the child application. Note that<br>
246 calling <a href="#pxssh-close">close</a>() more than once is valid. This emulates standard Python<br>
247 behavior with files. Set force to True if you want to make sure that<br>
248 the child is terminated (SIGKILL is sent if the child ignores SIGHUP<br>
249 and SIGINT).</tt></dd></dl>
251 <dl><dt><a name="pxssh-compile_pattern_list"><strong>compile_pattern_list</strong></a>(self, patterns)</dt><dd><tt>This compiles a pattern-string or a list of pattern-strings.<br>
252 Patterns must be a StringType, EOF, TIMEOUT, SRE_Pattern, or a list of<br>
253 those. Patterns may also be None which results in an empty list (you<br>
254 might do this if waiting for an EOF or TIMEOUT condition without<br>
255 expecting any pattern).<br>
257 This is used by <a href="#pxssh-expect">expect</a>() when calling <a href="#pxssh-expect_list">expect_list</a>(). Thus <a href="#pxssh-expect">expect</a>() is<br>
258 nothing more than::<br>
260 cpl = <a href="#pxssh-compile_pattern_list">compile_pattern_list</a>(pl)<br>
261 return <a href="#pxssh-expect_list">expect_list</a>(cpl, timeout)<br>
263 If you are using <a href="#pxssh-expect">expect</a>() within a loop it may be more<br>
264 efficient to compile the patterns first and then call <a href="#pxssh-expect_list">expect_list</a>().<br>
265 This avoid calls in a loop to <a href="#pxssh-compile_pattern_list">compile_pattern_list</a>()::<br>
267 cpl = <a href="#pxssh-compile_pattern_list">compile_pattern_list</a>(my_pattern)<br>
268 while some_condition:<br>
269 ...<br>
270 i = <a href="#pxssh-expect_list">expect_list</a>(clp, timeout)<br>
271 ...</tt></dd></dl>
273 <dl><dt><a name="pxssh-eof"><strong>eof</strong></a>(self)</dt><dd><tt>This returns True if the EOF exception was ever raised.</tt></dd></dl>
275 <dl><dt><a name="pxssh-expect"><strong>expect</strong></a>(self, pattern, timeout<font color="#909090">=-1</font>, searchwindowsize<font color="#909090">=None</font>)</dt><dd><tt>This seeks through the stream until a pattern is matched. The<br>
276 pattern is overloaded and may take several types. The pattern can be a<br>
277 StringType, EOF, a compiled re, or a list of any of those types.<br>
278 Strings will be compiled to re types. This returns the index into the<br>
279 pattern list. If the pattern was not a list this returns index 0 on a<br>
280 successful match. This may raise exceptions for EOF or TIMEOUT. To<br>
281 avoid the EOF or TIMEOUT exceptions add EOF or TIMEOUT to the pattern<br>
282 list. That will cause expect to match an EOF or TIMEOUT condition<br>
283 instead of raising an exception.<br>
285 If you pass a list of patterns and more than one matches, the first match<br>
286 in the stream is chosen. If more than one pattern matches at that point,<br>
287 the leftmost in the pattern list is chosen. For example::<br>
289 # the input is 'foobar'<br>
290 index = p.expect (['bar', 'foo', 'foobar'])<br>
291 # returns 1 ('foo') even though 'foobar' is a "better" match<br>
293 Please note, however, that buffering can affect this behavior, since<br>
294 input arrives in unpredictable chunks. For example::<br>
296 # the input is 'foobar'<br>
297 index = p.expect (['foobar', 'foo'])<br>
298 # returns 0 ('foobar') if all input is available at once,<br>
299 # but returs 1 ('foo') if parts of the final 'bar' arrive late<br>
301 After a match is found the instance attributes 'before', 'after' and<br>
302 'match' will be set. You can see all the data read before the match in<br>
303 'before'. You can see the data that was matched in 'after'. The<br>
304 re.MatchObject used in the re match will be in 'match'. If an error<br>
305 occurred then 'before' will be set to all the data read so far and<br>
306 'after' and 'match' will be None.<br>
308 If timeout is -1 then timeout will be set to the self.<strong>timeout</strong> value.<br>
310 A list entry may be EOF or TIMEOUT instead of a string. This will<br>
311 catch these exceptions and return the index of the list entry instead<br>
312 of raising the exception. The attribute 'after' will be set to the<br>
313 exception type. The attribute 'match' will be None. This allows you to<br>
314 write code like this::<br>
316 index = p.expect (['good', 'bad', pexpect.EOF, pexpect.TIMEOUT])<br>
317 if index == 0:<br>
318 do_something()<br>
319 elif index == 1:<br>
320 do_something_else()<br>
321 elif index == 2:<br>
322 do_some_other_thing()<br>
323 elif index == 3:<br>
324 do_something_completely_different()<br>
326 instead of code like this::<br>
328 try:<br>
329 index = p.expect (['good', 'bad'])<br>
330 if index == 0:<br>
331 do_something()<br>
332 elif index == 1:<br>
333 do_something_else()<br>
334 except EOF:<br>
335 do_some_other_thing()<br>
336 except TIMEOUT:<br>
337 do_something_completely_different()<br>
339 These two forms are equivalent. It all depends on what you want. You<br>
340 can also just expect the EOF if you are waiting for all output of a<br>
341 child to finish. For example::<br>
343 p = pexpect.<a href="pexpect.html#spawn">spawn</a>('/bin/ls')<br>
344 p.expect (pexpect.EOF)<br>
345 print p.before<br>
347 If you are trying to optimize for speed then see <a href="#pxssh-expect_list">expect_list</a>().</tt></dd></dl>
349 <dl><dt><a name="pxssh-expect_exact"><strong>expect_exact</strong></a>(self, pattern_list, timeout<font color="#909090">=-1</font>, searchwindowsize<font color="#909090">=-1</font>)</dt><dd><tt>This is similar to <a href="#pxssh-expect">expect</a>(), but uses plain string matching instead<br>
350 of compiled regular expressions in 'pattern_list'. The 'pattern_list'<br>
351 may be a string; a list or other sequence of strings; or TIMEOUT and<br>
354 This call might be faster than <a href="#pxssh-expect">expect</a>() for two reasons: string<br>
355 searching is faster than RE matching and it is possible to limit the<br>
356 search to just the end of the input buffer.<br>
358 This method is also useful when you don't want to have to worry about<br>
359 escaping regular expression characters that you want to match.</tt></dd></dl>
361 <dl><dt><a name="pxssh-expect_list"><strong>expect_list</strong></a>(self, pattern_list, timeout<font color="#909090">=-1</font>, searchwindowsize<font color="#909090">=-1</font>)</dt><dd><tt>This takes a list of compiled regular expressions and returns the<br>
362 index into the pattern_list that matched the child output. The list may<br>
363 also contain EOF or TIMEOUT (which are not compiled regular<br>
364 expressions). This method is similar to the <a href="#pxssh-expect">expect</a>() method except that<br>
365 <a href="#pxssh-expect_list">expect_list</a>() does not recompile the pattern list on every call. This<br>
366 may help if you are trying to optimize for speed, otherwise just use<br>
367 the <a href="#pxssh-expect">expect</a>() method. This is called by <a href="#pxssh-expect">expect</a>(). If timeout==-1 then<br>
368 the self.<strong>timeout</strong> value is used. If searchwindowsize==-1 then the<br>
369 self.<strong>searchwindowsize</strong> value is used.</tt></dd></dl>
371 <dl><dt><a name="pxssh-expect_loop"><strong>expect_loop</strong></a>(self, searcher, timeout<font color="#909090">=-1</font>, searchwindowsize<font color="#909090">=-1</font>)</dt><dd><tt>This is the common loop used inside expect. The 'searcher' should be<br>
372 an instance of searcher_re or searcher_string, which describes how and what<br>
373 to search for in the input.<br>
375 See <a href="#pxssh-expect">expect</a>() for other arguments, return value and exceptions.</tt></dd></dl>
377 <dl><dt><a name="pxssh-fileno"><strong>fileno</strong></a>(self)</dt><dd><tt>This returns the file descriptor of the pty for the child.</tt></dd></dl>
379 <dl><dt><a name="pxssh-flush"><strong>flush</strong></a>(self)</dt><dd><tt>This does nothing. It is here to support the interface for a<br>
380 File-like object.</tt></dd></dl>
382 <dl><dt><a name="pxssh-getecho"><strong>getecho</strong></a>(self)</dt><dd><tt>This returns the terminal echo mode. This returns True if echo is<br>
383 on or False if echo is off. Child applications that are expecting you<br>
384 to enter a password often set ECHO False. See <a href="#pxssh-waitnoecho">waitnoecho</a>().</tt></dd></dl>
386 <dl><dt><a name="pxssh-getwinsize"><strong>getwinsize</strong></a>(self)</dt><dd><tt>This returns the terminal window size of the child tty. The return<br>
387 value is a tuple of (rows, cols).</tt></dd></dl>
389 <dl><dt><a name="pxssh-interact"><strong>interact</strong></a>(self, escape_character<font color="#909090">='<font color="#c040c0">\x1d</font>'</font>, input_filter<font color="#909090">=None</font>, output_filter<font color="#909090">=None</font>)</dt><dd><tt>This gives control of the child process to the interactive user (the<br>
390 human at the keyboard). Keystrokes are sent to the child process, and<br>
391 the stdout and stderr output of the child process is printed. This<br>
392 simply echos the child stdout and child stderr to the real stdout and<br>
393 it echos the real stdin to the child stdin. When the user types the<br>
394 escape_character this method will stop. The default for<br>
395 escape_character is ^]. This should not be confused with ASCII 27 --<br>
396 the ESC character. ASCII 29 was chosen for historical merit because<br>
397 this is the character used by 'telnet' as the escape character. The<br>
398 escape_character will not be sent to the child process.<br>
400 You may pass in optional input and output filter functions. These<br>
401 functions should take a string and return a string. The output_filter<br>
402 will be passed all the output from the child process. The input_filter<br>
403 will be passed all the keyboard input from the user. The input_filter<br>
404 is run BEFORE the check for the escape_character.<br>
406 Note that if you change the window size of the parent the SIGWINCH<br>
407 signal will not be passed through to the child. If you want the child<br>
408 window size to change when the parent's window size changes then do<br>
409 something like the following example::<br>
411 import pexpect, struct, fcntl, termios, signal, sys<br>
412 def sigwinch_passthrough (sig, data):<br>
413 s = struct.pack("HHHH", 0, 0, 0, 0)<br>
414 a = struct.unpack('hhhh', fcntl.ioctl(sys.stdout.<a href="#pxssh-fileno">fileno</a>(), termios.TIOCGWINSZ , s))<br>
415 global p<br>
416 p.<a href="#pxssh-setwinsize">setwinsize</a>(a[0],a[1])<br>
417 p = pexpect.<a href="pexpect.html#spawn">spawn</a>('/bin/bash') # Note this is global and used in sigwinch_passthrough.<br>
418 signal.signal(signal.SIGWINCH, sigwinch_passthrough)<br>
419 p.<a href="#pxssh-interact">interact</a>()</tt></dd></dl>
421 <dl><dt><a name="pxssh-isalive"><strong>isalive</strong></a>(self)</dt><dd><tt>This tests if the child process is running or not. This is<br>
422 non-blocking. If the child was terminated then this will read the<br>
423 exitstatus or signalstatus of the child. This returns True if the child<br>
424 process appears to be running or False if not. It can take literally<br>
425 SECONDS for Solaris to return the right status.</tt></dd></dl>
427 <dl><dt><a name="pxssh-isatty"><strong>isatty</strong></a>(self)</dt><dd><tt>This returns True if the file descriptor is open and connected to a<br>
428 tty(-like) device, else False.</tt></dd></dl>
430 <dl><dt><a name="pxssh-kill"><strong>kill</strong></a>(self, sig)</dt><dd><tt>This sends the given signal to the child application. In keeping<br>
431 with UNIX tradition it has a misleading name. It does not necessarily<br>
432 kill the child unless you send the right signal.</tt></dd></dl>
434 <dl><dt><a name="pxssh-next"><strong>next</strong></a>(self)</dt><dd><tt>This is to support iterators over a file-like object.</tt></dd></dl>
436 <dl><dt><a name="pxssh-read"><strong>read</strong></a>(self, size<font color="#909090">=-1</font>)</dt><dd><tt>This reads at most "size" bytes from the file (less if the read hits<br>
437 EOF before obtaining size bytes). If the size argument is negative or<br>
438 omitted, read all data until EOF is reached. The bytes are returned as<br>
439 a string object. An empty string is returned when EOF is encountered<br>
440 immediately.</tt></dd></dl>
442 <dl><dt><a name="pxssh-read_nonblocking"><strong>read_nonblocking</strong></a>(self, size<font color="#909090">=1</font>, timeout<font color="#909090">=-1</font>)</dt><dd><tt>This reads at most size characters from the child application. It<br>
443 includes a timeout. If the read does not complete within the timeout<br>
444 period then a TIMEOUT exception is raised. If the end of file is read<br>
445 then an EOF exception will be raised. If a log file was set using<br>
446 <a href="#pxssh-setlog">setlog</a>() then all data will also be written to the log file.<br>
448 If timeout is None then the read may block indefinitely. If timeout is -1<br>
449 then the self.<strong>timeout</strong> value is used. If timeout is 0 then the child is<br>
450 polled and if there was no data immediately ready then this will raise<br>
451 a TIMEOUT exception.<br>
453 The timeout refers only to the amount of time to read at least one<br>
454 character. This is not effected by the 'size' parameter, so if you call<br>
455 <a href="#pxssh-read_nonblocking">read_nonblocking</a>(size=100, timeout=30) and only one character is<br>
456 available right away then one character will be returned immediately.<br>
457 It will not wait for 30 seconds for another 99 characters to come in.<br>
459 This is a wrapper around os.<a href="#pxssh-read">read</a>(). It uses select.select() to<br>
460 implement the timeout.</tt></dd></dl>
462 <dl><dt><a name="pxssh-readline"><strong>readline</strong></a>(self, size<font color="#909090">=-1</font>)</dt><dd><tt>This reads and returns one entire line. A trailing newline is kept<br>
463 in the string, but may be absent when a file ends with an incomplete<br>
464 line. Note: This <a href="#pxssh-readline">readline</a>() looks for a \r\n pair even on UNIX<br>
465 because this is what the pseudo tty device returns. So contrary to what<br>
466 you may expect you will receive the newline as \r\n. An empty string<br>
467 is returned when EOF is hit immediately. Currently, the size argument is<br>
468 mostly ignored, so this behavior is not standard for a file-like<br>
469 object. If size is 0 then an empty string is returned.</tt></dd></dl>
471 <dl><dt><a name="pxssh-readlines"><strong>readlines</strong></a>(self, sizehint<font color="#909090">=-1</font>)</dt><dd><tt>This reads until EOF using <a href="#pxssh-readline">readline</a>() and returns a list containing<br>
472 the lines thus read. The optional "sizehint" argument is ignored.</tt></dd></dl>
474 <dl><dt><a name="pxssh-send"><strong>send</strong></a>(self, s)</dt><dd><tt>This sends a string to the child process. This returns the number of<br>
475 bytes written. If a log file was set then the data is also written to<br>
476 the log.</tt></dd></dl>
478 <dl><dt><a name="pxssh-sendcontrol"><strong>sendcontrol</strong></a>(self, char)</dt><dd><tt>This sends a control character to the child such as Ctrl-C or<br>
479 Ctrl-D. For example, to send a Ctrl-G (ASCII 7)::<br>
481 child.<a href="#pxssh-sendcontrol">sendcontrol</a>('g')<br>
483 See also, <a href="#pxssh-sendintr">sendintr</a>() and <a href="#pxssh-sendeof">sendeof</a>().</tt></dd></dl>
485 <dl><dt><a name="pxssh-sendeof"><strong>sendeof</strong></a>(self)</dt><dd><tt>This sends an EOF to the child. This sends a character which causes<br>
486 the pending parent output buffer to be sent to the waiting child<br>
487 program without waiting for end-of-line. If it is the first character<br>
488 of the line, the <a href="#pxssh-read">read</a>() in the user program returns 0, which signifies<br>
489 end-of-file. This means to work as expected a <a href="#pxssh-sendeof">sendeof</a>() has to be<br>
490 called at the beginning of a line. This method does not send a newline.<br>
491 It is the responsibility of the caller to ensure the eof is sent at the<br>
492 beginning of a line.</tt></dd></dl>
494 <dl><dt><a name="pxssh-sendintr"><strong>sendintr</strong></a>(self)</dt><dd><tt>This sends a SIGINT to the child. It does not require<br>
495 the SIGINT to be the first character on a line.</tt></dd></dl>
497 <dl><dt><a name="pxssh-sendline"><strong>sendline</strong></a>(self, s<font color="#909090">=''</font>)</dt><dd><tt>This is like <a href="#pxssh-send">send</a>(), but it adds a line feed (os.linesep). This<br>
498 returns the number of bytes written.</tt></dd></dl>
500 <dl><dt><a name="pxssh-setecho"><strong>setecho</strong></a>(self, state)</dt><dd><tt>This sets the terminal echo mode on or off. Note that anything the<br>
501 child sent before the echo will be lost, so you should be sure that<br>
502 your input buffer is empty before you call <a href="#pxssh-setecho">setecho</a>(). For example, the<br>
503 following will work as expected::<br>
505 p = pexpect.<a href="pexpect.html#spawn">spawn</a>('cat')<br>
506 p.sendline ('1234') # We will see this twice (once from tty echo and again from cat).<br>
507 p.expect (['1234'])<br>
508 p.expect (['1234'])<br>
509 p.<a href="#pxssh-setecho">setecho</a>(False) # Turn off tty echo<br>
510 p.sendline ('abcd') # We will set this only once (echoed by cat).<br>
511 p.sendline ('wxyz') # We will set this only once (echoed by cat)<br>
512 p.expect (['abcd'])<br>
513 p.expect (['wxyz'])<br>
515 The following WILL NOT WORK because the lines sent before the setecho<br>
516 will be lost::<br>
518 p = pexpect.<a href="pexpect.html#spawn">spawn</a>('cat')<br>
519 p.sendline ('1234') # We will see this twice (once from tty echo and again from cat).<br>
520 p.<a href="#pxssh-setecho">setecho</a>(False) # Turn off tty echo<br>
521 p.sendline ('abcd') # We will set this only once (echoed by cat).<br>
522 p.sendline ('wxyz') # We will set this only once (echoed by cat)<br>
523 p.expect (['1234'])<br>
524 p.expect (['1234'])<br>
525 p.expect (['abcd'])<br>
526 p.expect (['wxyz'])</tt></dd></dl>
528 <dl><dt><a name="pxssh-setlog"><strong>setlog</strong></a>(self, fileobject)</dt><dd><tt>This method is no longer supported or allowed.</tt></dd></dl>
530 <dl><dt><a name="pxssh-setmaxread"><strong>setmaxread</strong></a>(self, maxread)</dt><dd><tt>This method is no longer supported or allowed. I don't like getters<br>
531 and setters without a good reason.</tt></dd></dl>
533 <dl><dt><a name="pxssh-setwinsize"><strong>setwinsize</strong></a>(self, r, c)</dt><dd><tt>This sets the terminal window size of the child tty. This will cause<br>
534 a SIGWINCH signal to be sent to the child. This does not change the<br>
535 physical window size. It changes the size reported to TTY-aware<br>
536 applications like vi or curses -- applications that respond to the<br>
537 SIGWINCH signal.</tt></dd></dl>
539 <dl><dt><a name="pxssh-terminate"><strong>terminate</strong></a>(self, force<font color="#909090">=False</font>)</dt><dd><tt>This forces a child process to terminate. It starts nicely with<br>
540 SIGHUP and SIGINT. If "force" is True then moves onto SIGKILL. This<br>
541 returns True if the child was terminated. This returns False if the<br>
542 child could not be terminated.</tt></dd></dl>
544 <dl><dt><a name="pxssh-wait"><strong>wait</strong></a>(self)</dt><dd><tt>This waits until the child exits. This is a blocking call. This will<br>
545 not read any data from the child, so this will block forever if the<br>
546 child has unread output and has terminated. In other words, the child<br>
547 may have printed output then called exit(); but, technically, the child<br>
548 is still alive until its output is read.</tt></dd></dl>
550 <dl><dt><a name="pxssh-waitnoecho"><strong>waitnoecho</strong></a>(self, timeout<font color="#909090">=-1</font>)</dt><dd><tt>This waits until the terminal ECHO flag is set False. This returns<br>
551 True if the echo mode is off. This returns False if the ECHO flag was<br>
552 not set False before the timeout. This can be used to detect when the<br>
553 child is waiting for a password. Usually a child application will turn<br>
554 off echo mode when it is waiting for the user to enter a password. For<br>
555 example, instead of expecting the "password:" prompt you can wait for<br>
556 the child to set ECHO off::<br>
558 p = pexpect.<a href="pexpect.html#spawn">spawn</a> ('ssh
[email protected]')<br>
559 p.<a href="#pxssh-waitnoecho">waitnoecho</a>()<br>
560 p.<a href="#pxssh-sendline">sendline</a>(mypassword)<br>
562 If timeout is None then this method to block forever until ECHO flag is<br>
563 False.</tt></dd></dl>
565 <dl><dt><a name="pxssh-write"><strong>write</strong></a>(self, s)</dt><dd><tt>This is similar to <a href="#pxssh-send">send</a>() except that there is no return value.</tt></dd></dl>
567 <dl><dt><a name="pxssh-writelines"><strong>writelines</strong></a>(self, sequence)</dt><dd><tt>This calls <a href="#pxssh-write">write</a>() for each element in the sequence. The sequence<br>
568 can be any iterable object producing strings, typically a list of<br>
569 strings. This does not add line separators There is no return value.</tt></dd></dl>
572 Data descriptors inherited from <a href="pexpect.html#spawn">pexpect.spawn</a>:<br>
573 <dl><dt><strong>__dict__</strong></dt>
574 <dd><tt>dictionary for instance variables (if defined)</tt></dd>
576 <dl><dt><strong>__weakref__</strong></dt>
577 <dd><tt>list of weak references to the object (if defined)</tt></dd>
579 </td></tr></table></td></tr></table><p>
580 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
581 <tr bgcolor="#55aa55">
582 <td colspan=3 valign=bottom> <br>
583 <font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
585 <tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td>
586 <td width="100%"><strong>__all__</strong> = ['ExceptionPxssh', 'pxssh']<br>
587 <strong>__revision__</strong> = '$Revision: 399 $'<br>
588 <strong>__version__</strong> = '2.3'</td></tr></table>
git.ucc.asn.au / progcomp10.git / blob
UCC git Repository :: git.ucc.asn.au