PEP: 813
Title: The Pretty Print Protocol
Author: Barry Warsaw <barry@python.org>, Eric V. Smith <eric@trueblade.com>
Discussions-To: https://discuss.python.org/t/pep-813-the-pretty-print-protocol/106242
Status: Draft
Type: Standards Track
Created: 07-Nov-2025
Python-Version: 3.16
Post-History: `21-Feb-2026 <https://discuss.python.org/t/pep-813-the-pretty-print-protocol/106242>`__
              `04-Mar-2026 <https://discuss.python.org/t/pep-813-the-pretty-print-protocol/106242/79>`__


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 :mod:`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 <rich-repr-protocol_>`_.


Rationale
=========

Pretty printing is very useful for displaying complex data structures, like dictionaries read from JSON
content.  However, the existing :mod:`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:

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
:py:class:`python: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, :py:func:`python: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 :ref:`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
   <https://rich.readthedocs.io/en/latest/pretty.html#rich-repr-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 :py:func:`python: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 :py:func:`python:pprint.pformat` will be used.

Note that format specs are *not* allowed in ``str.format()`` calls, at least for the :ref:`initial
implementation <deferred>` of this PEP.


Additions to the C-API
----------------------

To support ``!p``, a new function, ``PyObject_Pretty()`` is added to the
`Limited C API <https://docs.python.org/3/c-api/stable.html#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 :func:`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:

Examples
========

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

.. code-block:: python

    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:

.. code-block:: pycon

    >>> 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:

.. code-block:: pycon
   :force:

    >>> 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:

.. code-block:: pycon
   :force:

    >>> 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:

.. code-block:: pycon
   :force:

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

.. code-block:: pycon

    >>> 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 <https://github.com/warsaw/cpython/tree/pprint>`__.


Rejected Ideas
==============

We considered an alternative :ref:`specification <specification>` of the ``__pprint__()`` return
values, where either :func:`~collections.namedtuple`\s, :mod:`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:

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 <rich-repr-protocol_>`_. 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 <https://discuss.python.org/t/pep-813-the-pretty-print-protocol/106242/79>`__

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


Copyright
=========

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


.. _rich-repr-protocol: https://rich.readthedocs.io/en/stable/pretty.html#rich-repr-protocol
