From 7d89dd513e22a0ae05b8363dc611153e79c3ec4c 2013-12-18 19:21:10
From: Thomas Kluyver <takowl@gmail.com>
Date: 2013-12-18 19:21:10
Subject: [PATCH] Update inputsplitter docstring

---

diff --git a/IPython/core/inputsplitter.py b/IPython/core/inputsplitter.py
index 315a7a9..aaea819 100644
--- a/IPython/core/inputsplitter.py
+++ b/IPython/core/inputsplitter.py
@@ -1,58 +1,24 @@
-"""Analysis of text input into executable blocks.
+"""Input handling and transformation machinery.
 
-The main class in this module, :class:`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).
+The first class in this module, :class:`InputSplitter`, is designed to tell when
+input from a line-oriented frontend is complete and should be executed, and when
+the user should be prompted for another line of code instead. The name 'input
+splitter' is largely for historical reasons.
 
 A companion, :class:`IPythonInputSplitter`, provides the same functionality but
 with full support for the extended IPython syntax (magics, system calls, etc).
+The code to actually do these transformations is in :mod:`IPython.core.inputtransformer`.
+:class:`IPythonInputSplitter` feeds the raw code to the transformers in order
+and stores the results.
 
-For more details, see the class docstring below.
-
-Syntax Transformations
-----------------------
-
-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.
-
-
-ToDo
-----
-
-- 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).
+For more details, see the class docstrings below.
 
 Authors
 -------
 
 * Fernando Perez
 * Brian Granger
+* Thomas Kluyver
 """
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2010  The IPython Development Team
@@ -598,9 +564,9 @@ class IPythonInputSplitter(InputSplitter):
         -------
         is_complete : boolean
           True if the current input source (the result of the current input
-        plus prior inputs) forms a complete Python execution block.  Note that
-        this value is also stored as a private attribute (_is_complete), so it
-        can be queried at any time.
+          plus prior inputs) forms a complete Python execution block.  Note that
+          this value is also stored as a private attribute (_is_complete), so it
+          can be queried at any time.
         """
 
         # We must ensure all input is pure unicode