This documentation is for an old version of IPython. You can find docs for newer versions here.
Module for interactively running scripts.
This module implements classes for interactively running scripts written for any system with a prompt which can be matched by a regexp suitable for pexpect. It can be used to run as if they had been typed up interactively, an arbitrary series of commands for the target system.
The module includes classes ready for IPython (with the default prompts), plain Python and SAGE, but making a new one is trivial. To see how to use it, simply run the module as a script:
This is an extension of Ken Schutte <kschutte-AT-csail.mit.edu>’s script contributed on the ipython-user list:
- This module requires pexpect, available in most linux distros, or which can be downloaded from http://pexpect.sourceforge.net
- Because pexpect only works under Unix or Windows-Cygwin, this has the same limitations. This means that it will NOT work under native windows Python.
Class to run a sequence of commands through an interactive program.
Construct a runner.
- program: command to execute the given program.
- prompts: a list of patterns to match as valid prompts, in the
format used by pexpect. This basically means that it can be either a string (to be compiled as a regular expression) or a list of such (it must be a true list, as pexpect does type checks).
If more than one prompt is given, the first is treated as the main program prompt and the others as ‘continuation’ prompts, like python’s. This means that blank lines in the input source are ommitted when the first prompt is matched, but are NOT ommitted when the continuation one matches, since this is how python signals the end of multiline input interactively.
- args(None): optional list of strings to pass as arguments to the
- out(sys.stdout): if given, an output stream to be used when writing
output. The only requirement is that it must have a .write() method.
Public members not parameterized in the constructor:
- delaybeforesend(0): Newer versions of pexpect have a delay before
sending each new input. For our purposes here, it’s typically best to just set this to zero, but if you encounter reliability problems or want an interactive run to pause briefly at each prompt, just increase this value (it is measured in seconds). Note that this variable is not honored at all by older versions of pexpect.
close child process
Run as a command-line script.
Run the given file interactively.
-fname: name of the file to execute.
See the run_source docstring for the meaning of the optional arguments.
Run the given source code interactively.
- source: a string of code to be executed, or an open file object we
can iterate over.
- interact(False): if true, start to interact with the running
program at the end of the script. Otherwise, just exit.
- get_output(False): if true, capture the output of the child process
(filtering the input commands out) and return it as a string.
Interactive IPython runner.
This initalizes IPython in ‘nocolor’ mode for simplicity. This lets us avoid having to write a regexp that matches ANSI sequences, though pexpect does support them. If anyone contributes patches for ANSI color support, they will be welcome.
It also sets the prompts manually, since the prompt regexps for pexpect need to be matched to the actual prompts, so user-customized prompts would break this.
New runner, optionally passing the ipython command to use.
Interactive Python runner.
New runner, optionally passing the python command to use.
Interactive SAGE runner.
WARNING: this runner only works if you manually adjust your SAGE configuration so that the ‘color’ option in the configuration file is set to ‘NoColor’, because currently the prompt matching regexp does not identify color sequences.
New runner, optionally passing the sage command to use.
Code runner factory.
This class provides an IPython code runner, but enforces that only one runner is ever instantiated. The runner is created based on the extension of the first file to run, and it raises an exception if a runner is later requested for a different extension type.
This ensures that we don’t generate example files for doctest with a mix of python and ipython syntax.
Instantiate a code runner.
Patch pexpect to prevent unhandled exceptions at VM teardown.
Calling this function will monkeypatch the pexpect.spawn class and modify its __del__ method to make it more robust in the face of failures that can occur if it is called when the Python VM is shutting down.
Since Python may fire __del__ methods arbitrarily late, it’s possible for them to execute during the teardown of the Python VM itself. At this point, various builtin modules have been reset to None. Thus, the call to self.close() will trigger an exception because it tries to call os.close(), and os is now None.
Run as a command-line script.