This function runs the given command; waits for it to finish; then returns all output as a string. STDERR is included in output. If the full path to the command is not given then the path is searched.

Note that lines are terminated by CR/LF (\r\n) combination even on UNIX-like systems because this is the standard for pseudo ttys. If you set 'withexitstatus' to true, then run will return a tuple of (command_output, exitstatus). If 'withexitstatus' is false then this returns just command_output.

The run() function can often be used instead of creating a spawn instance. For example, the following code uses spawn:

   from pexpect import * #@UnusedWildImport
   child = spawn('scp foo myname@host.example.com:.')
   child.expect ('(?i)password')
   child.sendline (mypassword)

The previous code can be replace with the following:

   from pexpect import * #@UnusedWildImport
   run ('scp foo myname@host.example.com:.', events={'(?i)password': mypassword})

Examples

Start the apache daemon on the local machine:

   from pexpect import * #@UnusedWildImport
   run ("/usr/local/apache/bin/apachectl start")

Check in a file using SVN:

   from pexpect import * #@UnusedWildImport
   run ("svn ci -m 'automatic commit' my_file.py")

Run a command and capture exit status:

   from pexpect import * #@UnusedWildImport
   (command_output, exitstatus) = run ('ls -l /bin', withexitstatus=1)

Tricky Examples

The following will run SSH and execute 'ls -l' on the remote machine. The password 'secret' will be sent if the '(?i)password' pattern is ever seen:

   run ("ssh username@machine.example.com 'ls -l'", events={'(?i)password':'secret\n'})

This will start mencoder to rip a video from DVD. This will also display progress ticks every 5 seconds as it runs. For example:

   from pexpect import * #@UnusedWildImport
   def print_ticks(d):
       print d['event_count'],
   run ("mencoder dvd://1 -o video.avi -oac copy -ovc copy", events={TIMEOUT:print_ticks}, timeout=5)

The 'events' argument should be a dictionary of patterns and responses. Whenever one of the patterns is seen in the command out run() will send the associated response string. Note that you should put newlines in your string if Enter is necessary. The responses may also contain callback functions. Any callback is function that takes a dictionary as an argument. The dictionary contains all the locals from the run() function, so you can access the child spawn object or any other variable defined in run() (event_count, child, and extra_args are the most useful). A callback may return True to stop the current run process otherwise run() continues until the next event. A callback may also return a string which will be sent to the child. 'extra_args' is not used by directly run(). It provides a way to pass data to a callback function through run() through the locals dictionary passed to a callback.

This takes a given filename; tries to find it in the environment path; then checks if it is executable. This returns the full path to the filename if found and executable. Otherwise this returns None.

This splits a command line into a list of arguments. It splits arguments on spaces, but handles embedded quotes, doublequotes, and escaped characters. It's impossible to do this with a regular expression, so I wrote a little state machine to parse the command line.