Usage

Install the package with pip:

pip install prettyprinter

Then, instead of

from pprint import pprint

do

from prettyprinter import cpprint

for colored output. For colorless output, remove the c prefix from the function name:

from prettyprinter import pprint

Usage in Python code

Call cpprint() for colored output or pprint() for uncolored output, just like pprint.pprint:

>>> from prettyprinter import cpprint
>>> cpprint({'a': 1, 'b': 2})
{'a': 1, 'b': 2}

The default style is meant for a dark background. If you’re on a light background, or want to set your own theme, you may do so with set_default_style()

>>> from prettyprinter import set_default_style
>>> set_default_style('light')

Possible values are 'light', 'dark', and any subclass of pygments.styles.Style.

Adding a pretty printer function to the global namespace

If you’re so inclined, you could add cpprint() to the global namespace in your application so you can use it in a similar way as the built in print function:

import builtins
import prettyprinter
builtins.pretty = prettyprinter.cpprint

pretty([1, 2, 3])

You’ll want to add this to a file that is executed during application initialization.

Usage with IPython

You can use prettyprinter with IPython so that values in the REPL will be printed with prettyprinter using syntax highlighting. You need to call prettyprinter initialization functions at the start of an IPython session, which IPython facilitates with profile startup files. To initialize prettyprinter in your default profile, add and edit a new startup file with the following commands:

touch "`ipython locate profile default`/startup/init_prettyprinter.py"
nano "`ipython locate profile default`/startup/init_prettyprinter.py"

The code in this file will be run upon entering the shell. Add these lines and comment out any extra packages you don’t need:

# Specify syntax higlighting theme in IPython;
# will be picked up by prettyprinter.
from pygments import styles

# For light terminal backgrounds.
from prettyprinter.color import GitHubLightStyle
ipy = get_ipython()
ipy.colors = 'LightBG'
ipy.highlighting_style = GitHubLightStyle

# For dark terminal background.
ipy = get_ipython()
ipy.colors = 'linux'
ipy.highlighting_style = styles.get_style_by_name('monokai')

import prettyprinter

prettyprinter.install_extras(
    # Comment out any packages you are not using.
    include=[
        'ipython',
        'ipython_repr_pretty',
        'attrs',
        'django',
        'requests',
        'dataclasses',
    ],
    warn_on_error=True
)

Usage in the default Python shell

PrettyPrinter integrates with the default shell by overriding sys.displayhook, so that values evaluated in the prompt will be printed using PrettyPrinter. The integration is set up as follows:

>>> from prettyprinter import install_extras
>>> install_extras(['python'])
>>> {'a': 1, 'b': 2}
{'a': 1, 'b': 2}  # <- this will be colored when run in a terminal.

If you don’t want to run this every time you open a shell, create a Python startup file that executes the above statements and point the environment variable PYTHONSTARTUP to that file in your shell initialization file (such as ~/.bashrc), and rerun ~/.bashrc to assign the correct PYTHONSTARTUP value in your current shell session. Here’s a bash script to do that for you:

echo 'import prettyprinter; prettyprinter.install_extras(["python"])\n' >> ~/python_startup.py
echo "\nexport PYTHONSTARTUP=~/python_startup.py" >> ~/.bashrc
source ~/.bashrc

If you’re using a light background in your terminal, run this to add a line to the Python startup file to change the color theme PrettyPrinter uses:

echo '\nprettyprinter.set_default_style("light")' >> ~/python_startup.py

Then, after starting the python shell,

python

values evaluated in the shell should be printed with PrettyPrinter without any other setup.

>>> {'a': 1, 'b': 2}
{'a': 1, 'b': 2} # <- the output should be colored when run in a terminal.

Pretty printing your own types

Given a custom class:

class MyClass(object):
    def __init__(self, one, two):
        self.one = one
        self.two = two

You can register a pretty printer:

from prettyprinter import register_pretty, pretty_call

@register_pretty(MyClass)
def pretty_myclass(value, ctx):
    return pretty_call(
        ctx,
        MyClass,
        one=value.one,
        two=value.two
    )

To get an output like this with simple data:

>>> prettyprinter.pprint(MyClass(1, 2))
MyClass(one=1, two=2)

The real utility is in how nested data pretty printing is handled for you, and how the function call is broken to multiple lines for easier legibility:

>>> prettyprinter.pprint(MyClass({'abc': 1, 'defg': 2, 'hijk': 3}, [1, 2]))
MyClass(
    one={
        'abc': 1,
        'defg': 2,
        'hijk': 3
    },
    two=[1, 2]
)

@register_pretty is a decorator that takes the type to register. Internally, functools.singledispatch is used to handle dispatch to the correct pretty printer. This means that any subclasses will also use the same printer.

The decorated function must accept exactly two positional arguments:

  • value to pretty print, and
  • ctx, a context value.

In most cases, you don’t need need to do anything with the context, except pass it along in nested calls. It can be used to affect rendering of nested data.

The function must return a Doc, which is either an instance of Doc or a str. pretty_call() returns a Doc that represents a function call. Given an arbitrary context ctx

pretty_call(ctx, round, 1.5)

Will be printed out as

round(1.5)

with syntax highlighting.