Abstract

This PEP describes the “pretty print protocol”, a collection of changes proposed to make pretty printing more customizable and convenient.

Motivation

“Pretty printing” is a feature which provides a capability to format object representations for better readability. The core functionality is implemented by the standard library pprint module. pprint includes a class and APIs which users can invoke to format and print more readable representations of objects, versus the standard repr() built-in function. Important use cases include pretty printing large dictionaries and other complicated objects for debugging purposes.

This PEP builds on the features of the module to provide more customization and user convenience. It is also inspired by the Rich library’s pretty printing protocol.

Rationale

Pretty printing is very useful for displaying complex data structures, like dictionaries read from JSON content. However, the existing pprint module can only format builtin objects that it knows about. By providing a way for classes to customize how their instances participate in pretty printing, users have more options for visually improving the display of their complex data, especially for debugging.

By extending the built-in print() function to automatically pretty print its output, debugging with user-friendly display is made even more convenient. Since no extra imports are required, users can easily just piggyback on well-worn “print debugging” patterns, at least for the most common use cases.

These extensions work both independently and complimentary, to provide powerful new use cases.

Specification

There are several parts to this proposal.

Examples

A custom __pprint__() method can be used to customize the representation of the object, such as with this class:

class Bass:
    def __init__(self, strings: int, pickups: str, active: bool=False):
        self._strings = strings
        self._pickups = pickups
        self._active = active

    def __pprint__(self):
        yield self._strings
        yield 'pickups', self._pickups
        yield 'active', self._active, False

Now let’s create a couple of instances, and pretty print them:

>>> precision = Bass(4, 'split coil P', active=False)
>>> stingray = Bass(5, 'humbucker', active=True)

>>> pprint.pprint(precision)
Bass(4, pickups='split coil P')
>>> pprint.pprint(stingray)
Bass(5, pickups='humbucker', active=True)

Here’s an example of using the pretty argument to built-in print():

>>> import os
>>> print(os.pathconf_names)
{'PC_ASYNC_IO': 17, 'PC_CHOWN_RESTRICTED': 7, 'PC_FILESIZEBITS': 18, 'PC_LINK_MAX': 1, 'PC_MAX_CANON': 2, 'PC_MAX_INPUT': 3, 'PC_NAME_MAX': 4, 'PC_NO_TRUNC': 8, 'PC_PATH_MAX': 5, 'PC_PIPE_BUF': 6, 'PC_PRIO_IO': 19, 'PC_SYNC_IO': 25, 'PC_VDISABLE': 9, 'PC_MIN_HOLE_SIZE': 27, 'PC_ALLOC_SIZE_MIN': 16, 'PC_REC_INCR_XFER_SIZE': 20, 'PC_REC_MAX_XFER_SIZE': 21, 'PC_REC_MIN_XFER_SIZE': 22, 'PC_REC_XFER_ALIGN': 23, 'PC_SYMLINK_MAX': 24}

>>> print(os.pathconf_names, pretty=True)
{'PC_ALLOC_SIZE_MIN': 16,
 'PC_ASYNC_IO': 17,
 'PC_CHOWN_RESTRICTED': 7,
 'PC_FILESIZEBITS': 18,
 'PC_LINK_MAX': 1,
 'PC_MAX_CANON': 2,
 'PC_MAX_INPUT': 3,
 'PC_MIN_HOLE_SIZE': 27,
 'PC_NAME_MAX': 4,
 'PC_NO_TRUNC': 8,
 'PC_PATH_MAX': 5,
 'PC_PIPE_BUF': 6,
 'PC_PRIO_IO': 19,
 'PC_REC_INCR_XFER_SIZE': 20,
 'PC_REC_MAX_XFER_SIZE': 21,
 'PC_REC_MIN_XFER_SIZE': 22,
 'PC_REC_XFER_ALIGN': 23,
 'PC_SYMLINK_MAX': 24,
 'PC_SYNC_IO': 25,
 'PC_VDISABLE': 9}

Backwards Compatibility

When none of the new features are used, this PEP is fully backward compatible, both for built-in print() and the pprint module.

Security Implications

There are no known security implications for this proposal.

How to Teach This

Documentation and examples are added to the pprint module and the print() function. Beginners don’t need to be taught these new features until they want prettier representations of their objects.

Reference Implementation

The reference implementation is currently available as a PEP author branch of the CPython main branch.

Rejected Ideas

None at this time.

Open Issues

The output format and APIs are heavily inspired by Rich. The idea is that Rich could implement an API compatible with print(..., pretty=RichPrinter) fairly easily. Rich’s API is designed to print constructor-like representations of instances, which means that it’s not possible to control much of the “class chrome” around the arguments. Rich does support using angle brackets (i.e. <...>) instead of parentheses by setting the attribute .angular=True on the rich repr method. This PEP does not support that feature, although it likely could in the future.

This also means that there’s no way to control the pretty printed format of built-in types like strings, dicts, lists, etc. This seems fine as pprint is not intended to be as feature-rich (pun intended!) as Rich. This PEP purposefully deems such fancy features as out-of-scope.

One consequence of print(..., pretty=True) is that it can be more less obvious if you wanted to print multiple objects with, say a newline between the object representations. Compare these two outputs:

>>> print(precision, '\n', stingray, pretty=True)
Bass(4, pickups='split coil P') '\n' Bass(5, pickups='humbucker', active=True)

>>> print(precision, stingray, sep='\n', pretty=True)
Bass(4, pickups='split coil P')
Bass(5, pickups='humbucker', active=True)

It’s likely you’ll want the second output, but more complicated multi-object displays could get even less convenient and/or more verbose.

Acknowledgments

TBD

Footnotes

TBD

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.