Warning
This documentation covers a development version of IPython. The development version may differ significantly from the latest stable release.
Important
This documentation covers IPython versions 6.0 and higher. Beginning with version 6.0, IPython stopped supporting compatibility with Python versions lower than 3.3 including all versions of Python 2.7.
If you are looking for an IPython version compatible with Python 2.7, please use the IPython 5.x LTS release and refer to its documentation (LTS is the long term support release).
Module: lib.pretty
¶
Python advanced pretty printer. This pretty printer is intended to
replace the old pprint
python module which does not allow developers
to provide their own pretty print callbacks.
This module is based on ruby’s prettyprint.rb
library by Tanaka Akira
.
Example Usage¶
To directly print the representation of an object use pprint
:
from pretty import pprint
pprint(complex_object)
To get a string of the output use pretty
:
from pretty import pretty
string = pretty(complex_object)
Extending¶
The pretty library allows developers to add pretty printing rules for their
own objects. This process is straightforward. All you have to do is to
add a _repr_pretty_
method to your object and call the methods on the
pretty printer passed:
class MyObject(object):
def _repr_pretty_(self, p, cycle):
...
Here’s an example for a class with a simple constructor:
class MySimpleObject:
def __init__(self, a, b, *, c=None):
self.a = a
self.b = b
self.c = c
def _repr_pretty_(self, p, cycle):
ctor = CallExpression.factory(self.__class__.__name__)
if self.c is None:
p.pretty(ctor(a, b))
else:
p.pretty(ctor(a, b, c=c))
Here is an example implementation of a _repr_pretty_
method for a list
subclass:
class MyList(list):
def _repr_pretty_(self, p, cycle):
if cycle:
p.text('MyList(...)')
else:
with p.group(8, 'MyList([', '])'):
for idx, item in enumerate(self):
if idx:
p.text(',')
p.breakable()
p.pretty(item)
The cycle
parameter is True
if pretty detected a cycle. You have to
react to that or the result is an infinite loop. p.text()
just adds
non breaking text to the output, p.breakable()
either adds a whitespace
or breaks here. If you pass it an argument it’s used instead of the
default space. p.pretty
prettyprints another object using the pretty print
method.
The first parameter to the group
function specifies the extra indentation
of the next line. In this example the next item will either be on the same
line (if the items are short enough) or aligned with the right edge of the
opening bracket of MyList
.
If you just want to indent something you can use the group function without open / close parameters. You can also use this code:
with p.indent(2):
...
Inheritance diagram:
- copyright:
2007 by Armin Ronacher. Portions (c) 2009 by Robert Kern.
- license:
BSD License.
10 Classes¶
- class IPython.lib.pretty.PrettyPrinter(output, max_width=79, newline='\n', max_seq_length=1000)¶
Bases:
_PrettyPrinterBase
Baseclass for the
RepresentationPrinter
prettyprinter that is used to generate pretty reprs of objects. Contrary to theRepresentationPrinter
this printer knows nothing about the default pprinters or the_repr_pretty_
callback method.- __init__(output, max_width=79, newline='\n', max_seq_length=1000)¶
- begin_group(indent=0, open='')¶
Begin a group. The first parameter specifies the indentation for the next line (usually the width of the opening text), the second the opening text. All parameters are optional.
- break_()¶
Explicitly insert a newline into the output, maintaining correct indentation.
- breakable(sep=' ')¶
Add a breakable separator to the output. This does not mean that it will automatically break here. If no breaking on this position takes place the
sep
is inserted which default to one space.
- end_group(dedent=0, close='')¶
End a group. See
begin_group
for more details.
- flush()¶
Flush data that is left in the buffer.
- text(obj)¶
Add literal text to the output.
- class IPython.lib.pretty.RepresentationPrinter(output, verbose=False, max_width=79, newline='\n', singleton_pprinters=None, type_pprinters=None, deferred_pprinters=None, max_seq_length=1000)¶
Bases:
PrettyPrinter
Special pretty printer that has a
pretty
method that calls the pretty printer for a python object.This class stores processing data on
self
so you must never use this class in a threaded environment. Always lock it or reinstanciate it.Instances also have a verbose flag callbacks can access to control their output. For example the default instance repr prints all attributes and methods that are not prefixed by an underscore if the printer is in verbose mode.
- __init__(output, verbose=False, max_width=79, newline='\n', singleton_pprinters=None, type_pprinters=None, deferred_pprinters=None, max_seq_length=1000)¶
- pretty(obj)¶
Pretty print the given object.
- class IPython.lib.pretty.Breakable(seq, width, pretty)¶
Bases:
Printable
- __init__(seq, width, pretty)¶
- class IPython.lib.pretty.RawText(value)¶
Bases:
object
Object such that
p.pretty(RawText(value))
is the same asp.text(value)
.An example usage of this would be to show a list as binary numbers, using
p.pretty([RawText(bin(i)) for i in integers])
.- __init__(value)¶
4 Functions¶
- IPython.lib.pretty.pretty(obj, verbose=False, max_width=79, newline='\n', max_seq_length=1000)¶
Pretty print the object’s representation.
- IPython.lib.pretty.pprint(obj, verbose=False, max_width=79, newline='\n', max_seq_length=1000)¶
Like
pretty
but print to stdout.
- IPython.lib.pretty.for_type(typ, func)¶
Add a pretty printer for a given type.
- IPython.lib.pretty.for_type_by_name(type_module, type_name, func)¶
Add a pretty printer for a type specified by the module and name of a type rather than the type object itself.