xonsh.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.

The following implementations were forked from the IPython project: * Copyright (c) 2008-2014, IPython Development Team * Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu> * Copyright (c) 2001, Janko Hauser <jhauser@zscout.de> * Copyright (c) 2001, Nathaniel Gray <n8gray@caltech.edu>

Example Usage

To directly print the representation of an object use pprint:

from pretty import pretty_print
pretty_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 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):
    ...

copyright:

2007 by Armin Ronacher. Portions (c) 2009 by Robert Kern.

license:

BSD License.

class xonsh.lib.pretty.PrettyPrinter(output, max_width=79, newline='\n', max_seq_length=1000)

Baseclass for the RepresentationPrinter prettyprinter that is used to generate pretty reprs of objects. Contrary to the RepresentationPrinter this printer knows nothing about the default pprinters or the _repr_pretty_ callback method.

begin_group(indent=0, open='')

Begin a group. If you want support for python < 2.5 which doesn’t has the with statement this is the preferred way:

p.begin_group(1, ‘{‘) … p.end_group(1, ‘}’)

The python 2.5 expression would be this:

with p.group(1, ‘{’, ‘}’):

…

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.

group(indent=0, open='', close='')

like begin_group / end_group but for the with statement.

indent(indent)

with statement support for indenting/dedenting.

text(obj)

Add literal text to the output.

class xonsh.lib.pretty.RepresentationPrinter(output, verbose=False, max_width=79, newline='\n', singleton_pprinters=None, type_pprinters=None, deferred_pprinters=None, max_seq_length=1000)

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 reinstantiate 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.

begin_group(indent=0, open='')

Begin a group. If you want support for python < 2.5 which doesn’t has the with statement this is the preferred way:

p.begin_group(1, ‘{‘) … p.end_group(1, ‘}’)

The python 2.5 expression would be this:

with p.group(1, ‘{’, ‘}’):

…

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.

group(indent=0, open='', close='')

like begin_group / end_group but for the with statement.

indent(indent)

with statement support for indenting/dedenting.

pretty(obj)

Pretty print the given object.

text(obj)

Add literal text to the output.

xonsh.lib.pretty.for_type(typ, func)

Add a pretty printer for a given type.

xonsh.lib.pretty.for_type_by_name(type_module, type_name, func, dtp=None)

Add a pretty printer for a type specified by the module and name of a type rather than the type object itself.

xonsh.lib.pretty.pretty(obj, verbose=False, max_width=79, newline='\n', max_seq_length=1000)

Pretty print the object’s representation.

xonsh.lib.pretty.pretty_print(obj, verbose=False, max_width=79, newline='\n', max_seq_length=1000)

Like pretty() but print to stdout.