Itpl

Module: Itpl

Inheritance diagram for IPython.Itpl:

String interpolation for Python (by Ka-Ping Yee, 14 Feb 2000).

This module lets you quickly and conveniently interpolate values into strings (in the flavour of Perl or Tcl, but with less extraneous punctuation). You get a bit more power than in the other languages, because this module allows subscripting, slicing, function calls, attribute lookup, or arbitrary expressions. Variables and expressions are evaluated in the namespace of the caller.

The itpl() function returns the result of interpolating a string, and printpl() prints out an interpolated string. Here are some examples:

from Itpl import printpl printpl(“Here is a $string.”) printpl(“Here is a $module.member.”) printpl(“Here is an $object.member.”) printpl(“Here is a $functioncall(with, arguments).”) printpl(“Here is an ${arbitrary + expression}.”) printpl(“Here is an $array[3] member.”) printpl(“Here is a $dictionary[‘member’].”)

The filter() function filters a file object so that output through it is interpolated. This lets you produce the illusion that Python knows how to do interpolation:

import Itpl sys.stdout = Itpl.filter() f = “fancy” print “Is this not $f?” print “Standard output has been replaced with a $sys.stdout object.” sys.stdout = Itpl.unfilter() print “Okay, back $to $normal.”

Under the hood, the Itpl class represents a string that knows how to interpolate values. An instance of the class parses the string once upon initialization; the evaluation and substitution can then be done each time the instance is evaluated with str(instance). For example:

from Itpl import Itpl s = Itpl(“Here is $foo.”) foo = 5 print str(s) foo = “bar” print str(s)

Classes

Itpl

class IPython.Itpl.Itpl(format, codec='UTF-8', encoding_errors='backslashreplace')

Class representing a string with interpolation abilities.

Upon creation, an instance works out what parts of the format string are literal and what parts need to be evaluated. The evaluation and substitution happens in the namespace of the caller when str(instance) is called.

__init__(format, codec='UTF-8', encoding_errors='backslashreplace')

The single mandatory argument to this constructor is a format string.

The format string is parsed according to the following rules:

1. A dollar sign and a name, possibly followed by any of:

   • an open-paren, and anything up to the matching paren
   • an open-bracket, and anything up to the matching bracket
   • a period and a name

   any number of times, is evaluated as a Python expression.

2. A dollar sign immediately followed by an open-brace, and anything up to the matching close-brace, is evaluated as a Python expression.

3. Outside of the expressions described in the above two rules, two dollar signs in a row give you one literal dollar sign.

Optional arguments:

• codec(‘utf_8’): a string containing the name of a valid Python

codec.

• encoding_errors(‘backslashreplace’): a string with a valid error handling

policy. See the codecs module documentation for details.

These are used to encode the format string if a call to str() fails on the expanded result.

ItplError

class IPython.Itpl.ItplError(text, pos)

Bases: exceptions.ValueError

__init__(text, pos)

ItplFile

class IPython.Itpl.ItplFile(file)

A file object that filters each write() through an interpolator.

__init__(file)

write(text)

ItplNS

class IPython.Itpl.ItplNS(format, globals, locals=None, codec='utf_8', encoding_errors='backslashreplace')

Bases: IPython.Itpl.Itpl

Class representing a string with interpolation abilities.

This inherits from Itpl, but at creation time a namespace is provided where the evaluation will occur. The interpolation becomes a bit more efficient, as no traceback needs to be extracte. It also allows the caller to supply a different namespace for the interpolation to occur than its own.

__init__(format, globals, locals=None, codec='utf_8', encoding_errors='backslashreplace')

ItplNS(format,globals[,locals]) -> interpolating string instance.

This constructor, besides a format string, takes a globals dictionary and optionally a locals (which defaults to globals if not provided).

For further details, see the Itpl constructor.

Functions

IPython.Itpl.filter(file=<open file '<stdout>', mode 'w' at 0x4021e070>)

Return an ItplFile that filters writes to the given file object.

‘file = filter(file)’ replaces ‘file’ with a filtered object that has a write() method. When called with no argument, this creates a filter to sys.stdout.

IPython.Itpl.itpl(text)

IPython.Itpl.itplns(text, globals, locals=None)

IPython.Itpl.matchorfail(text, pos)

IPython.Itpl.printpl(text)

IPython.Itpl.printplns(text, globals, locals=None)

IPython.Itpl.unfilter(ifile=None)

Return the original file that corresponds to the given ItplFile.

‘file = unfilter(file)’ undoes the effect of ‘file = filter(file)’. ‘sys.stdout = unfilter()’ undoes the effect of ‘sys.stdout = filter()’.