##// END OF EJS Templates
Improve input transformation docs
Thomas Kluyver -
Show More
@@ -13,25 +13,34 b' interactive interface. Using them carelessly can easily break IPython!'
13 13 String based transformations
14 14 ============================
15 15
16 .. currentmodule:: IPython.core.inputtransforms
17
16 18 When the user enters a line of code, it is first processed as a string. By the
17 19 end of this stage, it must be valid Python syntax.
18 20
19 21 These transformers all subclass :class:`IPython.core.inputtransformer.InputTransformer`,
20 and are used by :class:`IPython.core.inputsplitter.IPythonInputSplitter`,
21 the ``transform`` attribute of which is a list of instances.
22
23 By default, these transformers are skipped when :class:`~IPython.core.inputsplitter.IPythonInputSplitter`
24 detects that the line starts inside a multi-line string. Some transformers, such
25 as those that remove the prompt markers from pasted examples, need to look
26 inside multiline strings as well - these set the attribute ``look_in_string`` to
27 ``True``.
22 and are used by :class:`IPython.core.inputsplitter.IPythonInputSplitter`.
23
24 These transformers act in three groups, stored separately as lists of instances
25 in attributes of :class:`~IPython.core.inputsplitter.IPythonInputSplitter`:
26
27 * ``physical_line_transforms`` act on the lines as the user enters them. For
28 example, these strip Python prompts from examples pasted in.
29 * ``logical_line_transforms`` act on lines as connected by explicit line
30 continuations, i.e. ``\`` at the end of physical lines. They are skipped
31 inside multiline Python statements. This is the point where IPython recognises
32 ``%magic`` commands, for instance.
33 * ``python_line_transforms`` act on blocks containing complete Python statements.
34 Multi-line strings, lists and function calls are reassembled before being
35 passed to these, but note that function and class *definitions* are still a
36 series of separate statements. IPython does not use any of these by default.
28 37
29 38 Stateless transformations
30 39 -------------------------
31 40
32 41 The simplest kind of transformations work one line at a time. Write a function
33 42 which takes a line and returns a line, and decorate it with
34 :meth:`~IPython.core.inputtransformer.StatelessInputTransformer.wrap`::
43 :meth:`StatelessInputTransformer.wrap`::
35 44
36 45 @StatelessInputTransformer.wrap
37 46 def my_special_commands(line):
@@ -83,6 +92,15 b' line in a cell::'
83 92
84 93 leading_indent.look_in_string = True
85 94
95 Token-based transformers
96 ------------------------
97
98 There is an experimental framework that takes care of tokenizing and
99 untokenizing lines of code. Define a function that accepts a list of tokens, and
100 returns an iterable of output tokens, and decorate it with
101 :meth:`TokenInputTransformer.wrap`. These should only be used in
102 ``python_line_transforms``.
103
86 104 AST transformations
87 105 ===================
88 106
General Comments 0
You need to be logged in to leave comments. Login now