GeezerVison is showing github.com — Improve documentation for `pprint` module · Issue #115986 · python/cpython
Improve documentation for pprint module #115986DescriptionDocumentation
The documentation for the pprint module could be improved in many respects:
- Most users will probably only ever need to use
pprint.pp() or pprint.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 use pprint.pp() instead, which has the more intuitive default of sort_dicts=False.
- Similarly, the docs for
pprint.pprint() could explicitly call out that it has unintuitive defaults for things such as sort_dicts and link to pprint.pp()
- Some links in the module's documentation incorrectly point to the module itself (
pprint) instead of the function pprint.pprint().
These don't all necessarily need to be tackled in the same PR
Linked PRs
Reacted by Hugo van Kemenade, Kerim Kabirov, Mattia, Erlend E. Aasland and Álvaro Mondéjar Rubio Reacted by Beni Cherniavsky-Paskin ActivityPrivat33r-dev commented on Feb 27, 2024 Can I be assigned? I can do most of it in a day or two. gaogaotiantian commented on Feb 27, 2024 The fact pp is not an alias for pprint surprised me. Personally I'd prefer to use a function that better explains itself (pprint is easier to understand than pp), without knowing the difference between them. I have some doubts about using pp as the default in all the examples, but that's just my two cents. Privat33r-dev commented on Feb 28, 2024 Progress tracker
- Most users will probably only ever need to use
pprint.pp() or pprint.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 use pprint.pp() instead, which has the more intuitive default of sort_dicts=False.
- Similarly, the docs for
pprint.pprint() could explicitly call out that it has unintuitive defaults for things such as sort_dicts and link to pprint.pp()
- Some links in the module's documentation incorrectly point to the module itself (
pprint) instead of the function pprint.pprint().
Privat33r-dev commented on Feb 28, 2024 Since pp as 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. erlend-aasland commented on Feb 28, 2024 Reacted by Alex Waygood and Kerim Kabirov Privat33r-dev commented on Apr 26, 2024 @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 commented on Apr 29, 2024
@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? Privat33r-dev commented on Jun 27, 2024 I guess it's resolved? :) encukou commented on Jun 27, 2024
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 commented on Jun 27, 2024
@erlend-aasland, is there anything else you want to improve?
No, I think we're good for now :) Reacted by Petr Viktorin Reacted by Kerim Kabirov
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|