PEP 813: The Pretty Print Protocol

[warsaw]

Basic requirements (all PEP Types)

• Read and followed PEP 1 & PEP 12
• File created from the latest PEP template
• PEP has next available number, & set in filename (pep-NNNN.rst), PR title (PEP 123: <Title of PEP>) and PEP header
• Title clearly, accurately and concisely describes the content in 79 characters or less
• Core dev/PEP editor listed as Author or Sponsor, and formally confirmed their approval
• Author, Status (Draft), Type and Created headers filled out correctly
• PEP-Delegate, Topic, Requires and Replaces headers completed if appropriate
• Required sections included
  • Abstract (first section)
  • Copyright (last section; exact wording from template required)
• Code is well-formatted (PEP 7/PEP 8) and is in code blocks, with the right lexer names if non-Python
• PEP builds with no warnings, pre-commit checks pass and content displays as intended in the rendered HTML
• Authors/sponsor added to .github/CODEOWNERS for the PEP

Standards Track requirements

• PEP topic discussed in a suitable venue with general agreement that a PEP is appropriate
• Suggested sections included (unless not applicable)
  • Motivation
  • Rationale
  • Specification
  • Backwards Compatibility
  • Security Implications
  • How to Teach This
  • Reference Implementation
  • Rejected Ideas
  • Open Issues
• Python-Version set to valid (pre-beta) future Python version, if relevant
• Any project stated in the PEP as supporting/endorsing/benefiting from the PEP formally confirmed such
• Right before or after initial merging, PEP discussion thread created and linked to in Discussions-To and Post-History

---

📚 Documentation preview 📚: https://pep-previews--4690.org.readthedocs.build/pep-0813/

[hugovk]

Looks useful!

[AA-Turner]

Sorry for the slight delay in initial review!

Mostly editorial comments in line, a couple of questions where I didn't follow the text too.

A slightly more substantive point I think it'd be useful to address is what style/form of prettiness will be chosen -- I'm thinking here of the proposed(?) change to pprint to add block-style formatting, similar to how code is often formatted in source form, rather than the more traditional pprint approach (as illustrated in the examples here). Personally, I'd always want to use the block-style if possible, but my understanding of the current proposal is that options like that wouldn't be possible.

A

[willingc]

Nice. A few clarifications in addition to Adam's.

[willingc]

Suggested change

	The ``pprint`` module is great as far as it goes. This PEP builds on the features of this module to provide
	The ``pprint`` module provides fundamentals for user-readable information display. This PEP builds on the features of this module to provide

[willingc]

Suggested change

	more customization and convenience.
	more customization, display structure, and user convenience.

[willingc]

Suggested change

	Pretty printing is very useful for displaying complex data structures, like dictionaries read from JSON
	content. By providing a way for classes to customize how their instances participate in pretty printing,
	users have more options for visually improving the display and debugging of their complex data.
	Pretty printing is very useful for displaying complex data structures, like dictionaries read from JSON
	content. Through class customization options for pretty printing,
	users have more options for visually improving the display and debugging of their complex data.

[willingc]

Suggested change

	By extending the built-in :func:`print` function to automatically pretty print its output, this feature is
	made even more convenient, since no extra imports are required, and users can easily just piggyback on
	well-worn "print debugging" patterns, at least for the most common use cases.
	By extending the built-in :func:`print` function to automatically pretty print its output, user-readable display is
	made even more convenient. Since no extra imports are required, users can easily piggyback on
	well-worn "print debugging" patterns for most common use cases.

[willingc]

Suggested change

	These two extensions work independently, but hand-in-hand can provide a powerful and convenient new feature.
	These two extensions, class customization for pretty printing and default print behavior, work independently but can be used in conjunction to provide a powerful and convenient user display of information.

[willingc]

Suggested change

	distinct from pretty printing, some classes may want more control over their pretty display.
	structured representation distinct from pretty printing, some classes may benefit from more control over pretty visual display of their instances.

[warsaw]

Sorry for the slight delay in initial review!

No worries! I was on vacation so I'm just getting back to this now.

Mostly editorial comments in line, a couple of questions where I didn't follow the text too.

Very much appreciated!

A slightly more substantive point I think it'd be useful to address is what style/form of prettiness will be chosen -- I'm thinking here of the proposed(?) change to pprint to add block-style formatting, similar to how code is often formatted in source form, rather than the more traditional pprint approach (as illustrated in the examples here). Personally, I'd always want to use the block-style if possible, but my understanding of the current proposal is that options like that wouldn't be possible.

While I prefer to defer substantive discussions to the inevitable mega-DPO thread, I think a possible way to handle this would be to use a different PrettyPrinter.pformat() method. Given that print(..., pretty=True) just instantiates pprint.PrettyPrinter and then calls its pformat() function, we could use a new or different default which had something like the block-style formatting you propose.

I'll have to discuss with @ericvsmith as we move forward with the proposal.

[willmcgugan]

Hi foks,

Can I be bold (and possibly also italic and underline) and suggest that this should become something like Rich's rich repr protocol. If not adopt it entirely.

In its current form, it looks like most of the work in formatting something as "pretty" is left to the object implementing __pprint__. This may give the most freedom but it would require effort from the author of the object. Pretty output often requires extensive string processing, and has a potentially large footprint for errors.

Because Rich's __rich_repr__ is declarative it moves the work of generating the pretty output to the library, where there is less chance of breaking anything. It also allows the library to make the decision how and when to break the object output on to multiple lines.

The rich repr approach does place some limitations on the output. The author couldn't generate absolutely anything in pretty output, but I consider this to be a plus. The pretty output will always look like formatted code in your editor, as you couldn't generate anything too crazy with this approach. Other features like color and indent guides are optional, but would remain possible.

Example Rich output for context:

Will (Rich guy)

[warsaw]

If not adopt it entirely.

That's really interesting and powerful @willmcgugan, thanks for the reference. @ericvsmith and I have been thinking about how to improve the proposal to make things more flexible, and this is a really good real-world example of what it might look like.

Have you had any problems or suggestions for improving rich's pretty printing?

I wonder about adopting it directly. I'm not sure how well that will play with the stdlib pprint module, or how complicated rich's pretty printer implementation is (something I will TAL at when I get some time).

Even if it isn't feasible to adopt directly, I'd want to think about ways to make them interoperate seamlessly.

[willmcgugan]

The implementation is a little gnarly.

Much of the complexity came from introspection. __repr__ methods that crashed, which is common in objects from ORMs, where it was assumed the database layer would exist. Also objects with __getattr__ implemented that claim they support all attributes. Haven't had any for a while, but there will be plenty of such edge cases in the Rich issues.

I'd also like to echo @AA-Turner 's comments about the formatting. I don't consider pprint's output to be pretty any more. It was pre-Python3 and pre-black. I think most people will have an expectation that "pretty" is how your editor would auto-format a data-structure.

Feel free to mention me any time. I'm interested in following along on this one.