At the recently concluded Python core team sprint, @ericvsmith and I worked on some major updates to PEP 813 - The Pretty Print Protocol. We think it’s in pretty[1] good shape and essentially ready to be proposed for Python 3.16. It was a lot of fun clanking away at a collaboration between the two of us, with Eric driving the updated reference implementation and me on the PEP.
Here thusly is the round 2 discussion. Please continue the discussions here; I will ask the moderators to lock the round 1 discussion thread.
The main difference is that we won’t be touching the existing pprint API[2]. Instead we’ll be adding new functionality.
Here’s a summary of the extensive differences from the previous version of the PEP:
- Add a new default printer,
pprint.Printer, and leavepprint.PrettyPrinterunchanged. __pprint__()describes an object’s structure, and the printer makes all layout decisions.- Section markers
pprint.VALUES,pprint.KWARGSandpprint.ITEMSsay how tuples are read, replacing the reading of tuples by their shape and the “false-y” name for positional tuple values. - Add
pprint.Layoutfor an object’s chrome, thepprint.DELEGATEmarker, and thepprint.Keywordandpprint.Entrytypes. The markers are PEP 661 sentinels. - Specify that the default printer reads the stream permissively, and that other printers may define their own vocabulary.
- Add
pprint.decompose(), and thepprint.LEAFsentinel that it returns for a leaf. - Defer a table of markers in the default printer, and a way to change the default printer.
- Add
pprint.DescriptionTypefor type annotating__pprint__()methods. - Add an optional
hintsattribute topprint.Layout, which can be used by third-party printers. - Add a
hugattribute topprint.Layout, so thatdefaultdictand similar types keepPrettyPrinter’s layout. - A printer returns an iterable of lines, and
!pjoins them with'\n'. - Specify how the default printer lays out, sorts, and limits the depth of nested objects, including keys that wrap.
- The default printer’s
expandoption takes apprint.Expandmember:NEVER,FITorALWAYS. Its defaults arewidth=78,indent=4andexpand=Expand.FIT. - The default printer’s
compactoption works with everyexpandmode. - The built-in and standard library types implement
__pprint__().strandbytesdescribe themselves with the newpprint.BreakableStringandpprint.BreakableBytes, andintandfloatwith the newpprint.FormattableNumber, so the printer handles no type natively. - The default printer’s
number_formatoption replacesunderscore_numbers. - Specify when an inherited
__pprint__()is used, and explain why. dataclassesandcollections.namedtuplegenerate__pprint__()methods.- The
!pformat spec can be a single replacement field,f'{obj!p:{printer}}', whose value is called without first being converted to a string. Any other spec is aSyntaxError. - A printer of
Nonemeans the default printer, in f-strings, t-strings andPyObject_Pretty(). - In
str.format(), a format spec after!ppads the pretty printed string. - T-strings support
!p.string.templatelib.Interpolationgets aprinterattribute, andstring.templatelib.converthandles'p'. - Describe compatibility with Rich, IPython and other pretty printing protocols.
- Move the Rationale section after the Specification, as PEP 12 now recommends.