Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python Enhancement Proposals

PEP 813 – The Pretty Print Protocol

Author:
Barry Warsaw <barry at python.org>, Eric V. Smith <eric at trueblade.com>
Discussions-To:
Discourse thread
Status:
Draft
Type:
Standards Track
Created:
07-Nov-2025
Python-Version:
3.15
Post-History:
21-Feb-2026 04-Mar-2026
Table of Contents

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 adding a !p conversion specifier to f-strings and str.format(), 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.

__pprint__() methods

Classes can implement a new dunder method, __pprint__() which if present, generates parts of their instance’s pretty printed representation. This augments __repr__() which, prior to this proposal, was the only method used to generate a custom representation of the object. Since object reprs provide functionality distinct from pretty printing, some classes may want more control over their pretty display. The pprint.PrettyPrinter class is modified to respect an object’s __pprint__() method if present.

__pprint__() is optional; if missing, the standard pretty printers fall back to __repr__() for full backward compatibility (technically speaking, pprint.saferepr() is used). However, if defined on a class, __pprint__() takes a single argument, the object to be pretty printed (i.e. self).

The method is expected to return or yield a sequence of values, which are used to construct a pretty representation of the object. These values are wrapped in standard class “chrome”, such as the class name. The printed representation will usually look like a class constructor, with positional, keyword, and default arguments. The values can be any of the following formats:

  • A single value, representing a positional argument. The value itself is used.
  • A 2-tuple of (name, value) representing a keyword argument. A representation of name=value is used. If name is “false-y”, then value is treated as a positional argument. This is how you would print a positional argument with a tuple value. See Examples. Otherwise, name MUST exactly be a str.
  • A 3-tuple of (name, value, default_value) representing a keyword argument with a default value. If value equals default_value, then this tuple is skipped, otherwise name=value is used. name MUST exactly be a str.

Note

This protocol is compatible with the Rich library’s pretty printing protocol.

Additions to f-strings and str.format()

In addition to the existing !s, !r, and !a conversion specifiers, a new !p conversion specifier will be added. The effect of this specifier with an expression value will be to call pprint.pformat() (importing the pprint module as needed), passing value as the only argument.

For f-strings only, the !p conversion specifier accepts an optional “format spec” expression, after the normal separating :, for example: f'{obj!p:expression}'. Formally, the expression can be anything that evaluates to a callable accepting a single argument (the object to format), and returns a string which is used as the f-string substitution value. Also for f-strings, the !p specifier is fully compatible with the obj= form, e.g. f'{obj=!p:expression}'. If no format spec is given, as above pprint.pformat() will be used.

Note that format specs are not allowed in str.format() calls, at least for the initial implementation of this PEP.

Additions to the C-API

To support !p, a new function, PyObject_Pretty() is added to the Limited C API. This function takes two arguments: a PyObject * for the object to pretty print, and an optional PyObject * for the formatter callable (which may be NULL). When the formatter is NULL, this function imports the pprint module and calls pprint.pformat() with the object as its argument, returning the results. When the formatter is not NULL, it must be a callable that accepts the object as its single argument and returns a string; this is used to support the already-evaluated :expression in f'{obj!p:expression}'.

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)

The !p conversion specifier can be used in f-strings and str.format() to pretty print values:

 >>> print(f'{precision=!p}')
 precision=Bass(4, pickups='split coil P')

 >>> print('{!p}'.format(precision))
 Bass(4, pickups='split coil P')

For more complex objects, !p can help make debugging output more readable:

 >>> 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(f'{os.pathconf_names = !p}')
 os.pathconf_names = {'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}

For f-strings only, the !p conversion specifier also accepts a format spec expression, which must evaluate to a callable taking a single argument and returning a string:

 >>> def slappa(da: Bass) -> str:
 ...     return 'All about that bass'

 >>> print(f'{precision=!p:slappa}')
 precision=All about that bass

Here’s an example where a positional argument has a tuple value. In this case, you use the 2-tuple format, with the name being “false-y”.

>>> class Things:
...     def __pprint__(self):
...         yield (None, (1, 2))
...         yield ('', (3, 4))
...         yield ('arg', (5, 6))
...
>>> from rich.pretty import pprint
>>> pprint(Things())
Things((1, 2), (3, 4), arg=(5, 6))

Backwards Compatibility

When none of the new features are used, this PEP is fully backward compatible.

Security Implications

There are no known security implications for this proposal.

How to Teach This

Documentation and examples are added to the pprint module, f-strings, and str.format(). 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

We considered an alternative specification of the __pprint__() return values, where either namedtuple()s, dataclasses, or a duck-typed instance were used as the return types. Ultimately we rejected this because we don’t want to force folks to define a new class or add any imports just to return values from this function.

Deferred Ideas

In the future, we could add support for !p conversions to t-strings. Addition of the :expression format for !p conversions on str.format() is also deferred.

Open Issues

Rich compatibility

The output format and APIs are heavily inspired by Rich. The idea is that Rich could implement a callable compatible with !p:callable 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.

Acknowledgments

Pablo Galindo Salgado for helping the PEP authors prototype the use of and prove the feasibility of !p:callable for f-strings.

Footnotes

None at this time.

Change History

  • 04-Mar-2026
    • For f-strings only (not str.format()) the !p conversion specifier takes an optional “format spec”.
    • The PEP no longer proposes a pretty argument to the print() built-in function. With the addition of !p:callable syntax for f-strings, the new argument is unnecessary.
    • Specify that to pretty print tuples as positional arguments, use the 2-tuple value format, passing a “false-y” value as the argument name.
    • Clarify that a truth-y name must be a str.
    • Specify that the !p conversion in f-strings and str.format() implicitly perform an import of the pprint module.
    • Describe the new Limited C API function PyObject_Pretty(), and add the optional argument.

Source: https://github.com/python/peps/blob/main/peps/pep-0813.rst

Last modified: 2026-03-04 19:18:31 GMT