Posted on by & filed under Content - Highlights and Reviews, Programming & Development.

codeA guest post by Anton I. Sipos, who has been programming computers since they were 8 bits old. He is a happy participant in the open source community, including contributions to IPython itself. His open source contributions can be found at, short quips at @aisipos, and longer musings at Email him at

The Python language has always had a strong history of being able to customize the way a class is ‘represented’ (formatted) for display in the interactive interpreter. The built-in repr function, which defers to __repr__ methods of your own objects, is well known. IPython takes this a step further by allowing other representations than just text. However, what if you want to change the formatting of a class that you didn’t write? What if you want to change the formatting of built-in classes? Luckily, IPython supports this very feature. IPython uses this feature to update the display format of many built in types. I’ll show you how to use this feature yourself to update the display format of any class you like.

Changing the format of defaultdict

Let’s look at an example of the type defaultdict. Let’s first create an example dictionary, and see how IPython formats it:

Note that how by default IPython renders this dictionary in an easy to read, one key-value pair per line. However, let’s see if we put this same information into a defaultdict:

Note how the default formatter doesn’t give us the same easy to read notation for defaultdict as dict. It would be nice if we could have IPython represent a defaultdict in a similar way as a plain dict. But how can we do this without modifying defaultdict itself?

IPython defines a display protocol to implement a custom representation for a class. When you write your own classes, you just add new methods to these classes to define their formatting. But for existing classes, you can accomplish the same thing by writing a separate display function display function and registering it with IPython’s display classes. IPython’s own documentation on how to do this can be found at this notebook.

Let’s use this technique to register a display function for defaultdict instances. Let’s first see what types of representations IPython supports, by inspecting into IPython’s own display_formatter instance:

For now we will alter the text/plain representation, which is is available in all IPython ‘flavors’ (console, qtconsole and notebook). Let’s get the instance of the text/plain formatter:

Using this text_formatter instance we can register any function of our choice as a formatter for any class we like, even for built-in python classes or classes in the standard library. Writing text formatters is sparsely documented, but working examples can be found in the implementation of sympy. The implementation there of a text formatter looks like this:

Let’s examine the parameters that IPython passes to our formatting function:

  • arg is the instance to be printed.
  • p is an instance of IPython.lib.pretty.RepresentationPrinter. Call text() to produce your formatted output.
  • cycle is a boolean used to prevent getting stuck in an infinite loop if you are printing a structure with a cycle in it.

With this in mind, let’s define a function to format a defaultdict similar to how IPython formats a regular dict. We can build upon the way IPython serializes dictionaries by reusing the function IPython.lib.pretty.pretty, as was also done in the sympy example shown above. To have IPython use our formatter whenever it encounters a defaultdict instance, we call the function for_type on our instance of text_formatter to register our new formatter:

Note that the function for_type returns a function when called. This is the previously registered formatter function for that type. The intention is for you to keep this older formatter if you want to return the earlier behavior, but you can ignore this if you wish.

Now that we’ve registered our new formatter, let’s see how it looks on our default instance:

Excellent! We successfully managed to alter IPython’s display of a class in the standard library. You can use this technique to provide convenient and useful representations of any 3rd-party python class you might encounter. In this instance we made a relatively minor upgrade to the text display of a class.

Implementing a graphical formatter

As we saw earlier in this post, if we use the IPython notebook we have some other options available to us in addition to plain text. To illustrate this, let’s make a graphical formatter for the standard library Counter class. By default, the Counter text representation looks like this:

For small collections, this text representation is easy enough to digest. With larger collections, however, our eye may miss some outliers in this data. Using a graphical collection would be a better way to display this information. Let’s accomplish this by making an svg representation using the pygal library. pygal requires lxml to be installed. Once lxml is installed, you can install pygal with the following:

You can implement a horizontal bar chart graphical formatter for Counter instances like this:

Now as before, we’ll register this function as the display formatter for the mimetype image/svg+xml for the Counter class. Unlike a text formatter, note how svg formatters take only one argument, and return the generated svg directly from the function. Let’s see how this works for our simple example:



With only a few lines of code, we’ve managed to make a graphical format for the Counter class! Hopefully these examples will provide inspiration in making useful visualizations for other Python classes that you frequently use within your IPython sessions. While it has always been easy to update the formatting of your own classes, I hope that now you will feel just as comfortable updating the formatting of any Python class you encounter.

Look below for some great Python and IPython books from Safari Books Online.

Not a subscriber? Sign up for a free trial.

Safari Books Online has the content you need

Learning IPython for Interactive Computing and Data Visualization covers all aspects of IPython, from the highly powerful interactive Python console to the numerical and visualization features that are commonly associated with IPython.
Python for Data Analysis is packed with practical cases studies that show you how to effectively solve a broad set of data analysis problems, using several Python libraries.
Python High Performance Programming is an example-oriented guide to the techniques used to dramatically improve the performance of your Python programs. It will teach optimization techniques by using pure python tricks, high performance libraries, and the python-C integration. The book will also include a section on how to write and run parallel code.

Tags: alter, Anton I. Sipos, defaultdict, existing classes, IPython, Python,

Comments are closed.