Quick search

The main class in this module, InputSplitter, is designed to break
input from either interactive, line-by-line environments or block-based ones,
into standalone blocks that can be executed by Python as ‘single’ statements
(thus triggering sys.displayhook).

A companion, IPythonInputSplitter, provides the same functionality but
with full support for the extended IPython syntax (magics, system calls, etc).

One of the main jobs of the code in this file is to apply all syntax
transformations that make up ‘the IPython language’, i.e. magics, shell
escapes, etc. All transformations should be implemented as fully stateless
entities, that simply take one line as their input and return a line.
Internally for implementation purposes they may be a normal function or a
callable object, but the only input they receive will be a single line and they
should only return a line, without holding any data-dependent state between
calls.

As an example, the EscapedTransformer is a class so we can more clearly group
together the functionality of dispatching to individual functions based on the
starting escape character, but the only method for public use is its call
method.

Should we make push() actually raise an exception once push_accepts_more()
returns False?

Naming cleanups. The tr_* names aren’t the most elegant, though now they are
at least just attributes of a class so not really very exposed.

Think about the best way to support dynamic things: automagic, autocall,
macros, etc.

Think of a better heuristic for the application of the transforms in
IPythonInputSplitter.push() than looking at the buffer ending in ‘:’. Idea:
track indentation change events (indent, dedent, nothing) and apply them only
if the indentation went up, but not otherwise.

Think of the cleanest way for supporting user-specified transformations (the
user prefilters we had before).

This method is meant to be used by line-oriented frontends, who need to
guess whether a block is complete or not based solely on prior and
current input lines. The InputSplitter considers it has a complete
interactive block and will not accept more input only when either a
SyntaxError is raised, or all of the following are true:

The input compiles to a complete statement.

The indentation level is flush-left (because if we are indented,
like inside a function definition or for loop, we need to keep
reading new input).

There is one extra line consisting only of whitespace.

Because of condition #3, this method should be used only by
line-oriented frontends, since it means that intermediate blank lines
are not allowed in function definitions (or any other indented block).

If the current input produces a syntax error, this method immediately
returns False but does not raise the syntax error exception, as
typically clients will want to send invalid syntax to an execution
backend which might convert the invalid syntax into valid Python via
one of the dynamic IPython mechanisms.

An object that can accumulate lines of Python source before execution.

This object is designed to be fed python source line-by-line, using

push(). It will return on each push whether the currently pushed
code could be executed already. In addition, it provides a method called
push_accepts_more() that can be used to query whether more input
can be pushed into a single interactive block.

This is a simple example of how an interactive terminal-based client can use
this tool:

The input_mode parameter controls how new inputs are used when fed via :

the :meth:`push` method: :

- ‘line’: meant for line-oriented clients, inputs are appended one at a :

time to the internal buffer and the whole buffer is compiled.

- ‘cell’: meant for clients that can edit multi-line ‘cells’ of text at :

a time. A cell can contain one or more blocks that can be compile in
‘single’ mode by Python. In this mode, each new input new input
completely replaces all prior inputs. Cell mode is thus equivalent
to prepending a full reset() to every push() call.

This method is meant to be used by line-oriented frontends, who need to
guess whether a block is complete or not based solely on prior and
current input lines. The InputSplitter considers it has a complete
interactive block and will not accept more input only when either a
SyntaxError is raised, or all of the following are true:

The input compiles to a complete statement.

The indentation level is flush-left (because if we are indented,
like inside a function definition or for loop, we need to keep
reading new input).

There is one extra line consisting only of whitespace.

Because of condition #3, this method should be used only by
line-oriented frontends, since it means that intermediate blank lines
are not allowed in function definitions (or any other indented block).

If the current input produces a syntax error, this method immediately
returns False but does not raise the syntax error exception, as
typically clients will want to send invalid syntax to an execution
backend which might convert the invalid syntax into valid Python via
one of the dynamic IPython mechanisms.

This is a utility class that mostly wraps the output of
split_user_input() into a convenient object to be passed around
during input transformations.

Includes the following as properties:

line

The original, raw line

lspace

Any early whitespace before actual text starts.

esc

The initial esc character (or characters, for double-char escapes like
‘??’ or ‘!!’).

fpart

The ‘function part’, which is basically the maximal initial sequence
of valid python identifiers and the ‘.’ character. This is what is
checked for alias and magic transformations, used for auto-calling,
etc.