### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »

# lib.irunner

## Module: `lib.irunner`

Inheritance diagram for `IPython.lib.irunner`:

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:

./irunner.py –help

This is an extension of Ken Schutte <kschutte-AT-csail.mit.edu>’s script contributed on the ipython-user list:

http://mail.scipy.org/pipermail/ipython-user/2006-May/003539.html

NOTES:

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

## Classes

### `IPythonRunner`

class `IPython.lib.irunner.``IPythonRunner`(program='ipython', args=None, out=<open file '<stdout>', mode 'w' at 0x2b718392d150>, echo=True)

  Bases: `IPython.lib.irunner.InteractiveRunner`

  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.

  `__init__`(program='ipython', args=None, out=<open file '<stdout>', mode 'w' at 0x2b718392d150>, echo=True)

    New runner, optionally passing the ipython command to use.

  `close`()

    close child process

  `main`(argv=None)

    Run as a command-line script.

  `run_file`(fname, interact=False, get_output=False)

    Run the given file interactively.

    Inputs:

    > -fname: name of the file to execute.

    See the run_source docstring for the meaning of the optional arguments.

  `run_source`(source, interact=False, get_output=False)

    Run the given source code interactively.

    Inputs:

    > - source: a string of code to be executed, or an open file object we

    > can iterate over.

    Optional inputs:

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

    Returns:
      A string containing the process output, but only if requested.

### `InteractiveRunner`

class `IPython.lib.irunner.``InteractiveRunner`(program, prompts, args=None, out=<open file '<stdout>', mode 'w' at 0x2b718392d150>, echo=True)

  Bases: `object`

  Class to run a sequence of commands through an interactive program.

  `__init__`(program, prompts, args=None, out=<open file '<stdout>', mode 'w' at 0x2b718392d150>, echo=True)

    Construct a runner.

    Inputs:

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

    Optional inputs:

    > - args(None): optional list of strings to pass as arguments to the

    > child program.

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

    close child process

  `main`(argv=None)

    Run as a command-line script.

  `run_file`(fname, interact=False, get_output=False)

    Run the given file interactively.

    Inputs:

    > -fname: name of the file to execute.

    See the run_source docstring for the meaning of the optional arguments.

  `run_source`(source, interact=False, get_output=False)

    Run the given source code interactively.

    Inputs:

    > - source: a string of code to be executed, or an open file object we

    > can iterate over.

    Optional inputs:

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

    Returns:
      A string containing the process output, but only if requested.

### `PythonRunner`

class `IPython.lib.irunner.``PythonRunner`(program='python', args=None, out=<open file '<stdout>', mode 'w' at 0x2b718392d150>, echo=True)

  Bases: `IPython.lib.irunner.InteractiveRunner`

  Interactive Python runner.

  `__init__`(program='python', args=None, out=<open file '<stdout>', mode 'w' at 0x2b718392d150>, echo=True)

    New runner, optionally passing the python command to use.

  `close`()

    close child process

  `main`(argv=None)

    Run as a command-line script.

  `run_file`(fname, interact=False, get_output=False)

    Run the given file interactively.

    Inputs:

    > -fname: name of the file to execute.

    See the run_source docstring for the meaning of the optional arguments.

  `run_source`(source, interact=False, get_output=False)

    Run the given source code interactively.

    Inputs:

    > - source: a string of code to be executed, or an open file object we

    > can iterate over.

    Optional inputs:

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

    Returns:
      A string containing the process output, but only if requested.

### `RunnerFactory`

class `IPython.lib.irunner.``RunnerFactory`(out=<open file '<stdout>', mode 'w' at 0x2b718392d150>)

  Bases: `object`

  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.

  `__init__`(out=<open file '<stdout>', mode 'w' at 0x2b718392d150>)

    Instantiate a code runner.

### `SAGERunner`

class `IPython.lib.irunner.``SAGERunner`(program='sage', args=None, out=<open file '<stdout>', mode 'w' at 0x2b718392d150>, echo=True)

  Bases: `IPython.lib.irunner.InteractiveRunner`

  Interactive SAGE runner.

  WARNING: this runner only works if you manually configure your SAGE copy to use ‘colors NoColor’ in the ipythonrc config file, since currently the prompt matching regexp does not identify color sequences.

  `__init__`(program='sage', args=None, out=<open file '<stdout>', mode 'w' at 0x2b718392d150>, echo=True)

    New runner, optionally passing the sage command to use.

  `close`()

    close child process

  `main`(argv=None)

    Run as a command-line script.

  `run_file`(fname, interact=False, get_output=False)

    Run the given file interactively.

    Inputs:

    > -fname: name of the file to execute.

    See the run_source docstring for the meaning of the optional arguments.

  `run_source`(source, interact=False, get_output=False)

    Run the given source code interactively.

    Inputs:

    > - source: a string of code to be executed, or an open file object we

    > can iterate over.

    Optional inputs:

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

    Returns:
      A string containing the process output, but only if requested.

## Functions

`IPython.lib.irunner.``main`()

  Run as a command-line script.

`IPython.lib.irunner.``pexpect_monkeypatch`()

  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.

### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »