Repository navigation
Improve documentation for pprint module #115986
Description
Activity
Can I be assigned? I can do most of it in a day or two.
The fact
ppis not an alias forpprintsurprised me. Personally I'd prefer to use a function that better explains itself (pprintis easier to understand thanpp), without knowing the difference between them. I have some doubts about usingppas the default in all the examples, but that's just my two cents.Progress tracker
- Most users will probably only ever need to use
pprint.pp()orpprint.pprint(), but these are buried halfway down the module. It would be nice if these were the first things on the page. - All examples in the documentation use
pprint.pprint(), which has some unexpected behaviour. For example, it sorts dictionaries by default, which is somewhat unintuitive now that dictionaries maintain insertion order. I suggest we change the examples to usepprint.pp()instead, which has the more intuitive default ofsort_dicts=False. - Similarly, the docs for
pprint.pprint()could explicitly call out that it has unintuitive defaults for things such assort_dictsand link topprint.pp() - Some links in the module's documentation incorrectly point to the module itself (
pprint) instead of the functionpprint.pprint().
- Most users will probably only ever need to use
- added 5 commits that reference this issue
on Feb 28, 2024 Since
ppas a default example might be considered controversial, I will put in the second PR. To avoid merging issues, I will push second PR after the first one is accepted.The
pprintdocs could make good use of param list markup.UPDATE: PR => #116085
Reacted by Alex Waygood and Kerim Kabirov29 remaining items
@erlend-aasland let's duplicate the params list in 1 function and in the class. DRY would be violated, but readability would be improved, which is more important than blindly following the principle.
@erlend-aasland let's duplicate the params list in 1 function and in the class. DRY would be violated, but readability would be improved, which is more important than blindly following the principle.
Can you propose a PR?
Reacted by Kerim KabirovI guess it's resolved? :)
let's duplicate the params list in 1 function and in the class. DRY would be violated, but readability would be improved, which is more important than blindly following the principle.
Ah, I missed this comment before pointing it in the review, so, for posterity:
IMO, including the full list only once, and linking to it from the other locations, is better -- especially with one function we prefer (
pp), while others are backward-compatible defaults (pprint), and more special use (pformat&PrettyPrinter).
Also, this way lends itself to listing the differences in argument order and defaults, which makes them much easier to spot.Thanks for implementing that! The PR was just merged.
I guess it's resolved? :)
I think so! @erlend-aasland, is there anything else you want to improve?
Reacted by Kerim Kabirov and Erlend E. Aasland@erlend-aasland, is there anything else you want to improve?
No, I think we're good for now :)
Reacted by Petr ViktorinReacted by Kerim Kabirov
Documentation
The documentation for the
pprintmodule could be improved in many respects:pprint.pp()orpprint.pprint(), but these are buried halfway down the module. It would be nice if these were the first things on the page.pprint.pprint(), which has some unexpected behaviour. For example, it sorts dictionaries by default, which is somewhat unintuitive now that dictionaries maintain insertion order. I suggest we change the examples to usepprint.pp()instead, which has the more intuitive default ofsort_dicts=False.pprint.pprint()could explicitly call out that it has unintuitive defaults for things such assort_dictsand link topprint.pp()pprint) instead of the functionpprint.pprint().These don't all necessarily need to be tackled in the same PR
Linked PRs
pprintdocumentation #116019