From ff430eab4a2c5bef833bedfa16816d1b9934f610 Mon Sep 17 00:00:00 2001 From: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com> Date: Wed, 28 Feb 2024 01:50:42 +0100 Subject: [PATCH 01/10] GH-115986 Doc: change 'pprint' module documentation's structure Ensure `pp` and `pprint` are positioned prominently at the top of the page. --- Doc/library/pprint.rst | 173 +++++++++++++++++++++-------------------- 1 file changed, 89 insertions(+), 84 deletions(-) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index e883acd67d6c72..a74f233373bcd9 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -31,7 +31,95 @@ Dictionaries are sorted by key before the display is computed. .. versionchanged:: 3.10 Added support for pretty-printing :class:`dataclasses.dataclass`. -The :mod:`pprint` module defines one class: +.. _pprint-functions: + +Functions +--------- + +.. function:: pp(object, *args, sort_dicts=False, **kwargs) + + Prints the formatted representation of *object* followed by a newline. + If *sort_dicts* is false (the default), dictionaries will be displayed with + their keys in insertion order, otherwise the dict keys will be sorted. + *args* and *kwargs* will be passed to :func:`pprint` as formatting + parameters. + + .. versionadded:: 3.8 + + +.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \ + compact=False, sort_dicts=True, underscore_numbers=False) + + Prints the formatted representation of *object* on *stream*, followed by a + newline. If *stream* is ``None``, ``sys.stdout`` is used. This may be used + in the interactive interpreter instead of the :func:`print` function for + inspecting values (you can even reassign ``print = pprint.pprint`` for use + within a scope). + + The configuration parameters *stream*, *indent*, *width*, *depth*, + *compact*, *sort_dicts* and *underscore_numbers* are passed to the + :class:`PrettyPrinter` constructor and their meanings are as + described in its documentation above. + + >>> import pprint + >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni'] + >>> stuff.insert(0, stuff) + >>> pprint.pprint(stuff) + [, + 'spam', + 'eggs', + 'lumberjack', + 'knights', + 'ni'] + +.. function:: pformat(object, indent=1, width=80, depth=None, *, \ + compact=False, sort_dicts=True, underscore_numbers=False) + + Return the formatted representation of *object* as a string. *indent*, + *width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are + passed to the :class:`PrettyPrinter` constructor as formatting parameters + and their meanings are as described in its documentation above. + + +.. function:: isreadable(object) + + .. index:: pair: built-in function; eval + + Determine if the formatted representation of *object* is "readable", or can be + used to reconstruct the value using :func:`eval`. This always returns ``False`` + for recursive objects. + + >>> pprint.isreadable(stuff) + False + + +.. function:: isrecursive(object) + + Determine if *object* requires a recursive representation. This function is + subject to the same limitations as noted in :func:`saferepr` below and may raise an + :exc:`RecursionError` if it fails to detect a recursive object. + + +One more support function is also defined: + +.. function:: saferepr(object) + + Return a string representation of *object*, protected against recursion in + some common data structures, namely instances of :class:`dict`, :class:`list` + and :class:`tuple` or subclasses whose ``__repr__`` has not been overridden. If the + representation of object exposes a recursive entry, the recursive reference + will be represented as ````. The + representation is not otherwise formatted. + + >>> pprint.saferepr(stuff) + "[, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']" + +.. _prettyprinter-objects: + +PrettyPrinter Objects +--------------------- + +This module defines one class: .. First the implementation class: @@ -112,89 +200,6 @@ The :mod:`pprint` module defines one class: >>> pp.pprint(tup) ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...))))))) -.. function:: pformat(object, indent=1, width=80, depth=None, *, \ - compact=False, sort_dicts=True, underscore_numbers=False) - - Return the formatted representation of *object* as a string. *indent*, - *width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are - passed to the :class:`PrettyPrinter` constructor as formatting parameters - and their meanings are as described in its documentation above. - - -.. function:: pp(object, *args, sort_dicts=False, **kwargs) - - Prints the formatted representation of *object* followed by a newline. - If *sort_dicts* is false (the default), dictionaries will be displayed with - their keys in insertion order, otherwise the dict keys will be sorted. - *args* and *kwargs* will be passed to :func:`pprint` as formatting - parameters. - - .. versionadded:: 3.8 - - -.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \ - compact=False, sort_dicts=True, underscore_numbers=False) - - Prints the formatted representation of *object* on *stream*, followed by a - newline. If *stream* is ``None``, ``sys.stdout`` is used. This may be used - in the interactive interpreter instead of the :func:`print` function for - inspecting values (you can even reassign ``print = pprint.pprint`` for use - within a scope). - - The configuration parameters *stream*, *indent*, *width*, *depth*, - *compact*, *sort_dicts* and *underscore_numbers* are passed to the - :class:`PrettyPrinter` constructor and their meanings are as - described in its documentation above. - - >>> import pprint - >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni'] - >>> stuff.insert(0, stuff) - >>> pprint.pprint(stuff) - [, - 'spam', - 'eggs', - 'lumberjack', - 'knights', - 'ni'] - -.. function:: isreadable(object) - - .. index:: pair: built-in function; eval - - Determine if the formatted representation of *object* is "readable", or can be - used to reconstruct the value using :func:`eval`. This always returns ``False`` - for recursive objects. - - >>> pprint.isreadable(stuff) - False - - -.. function:: isrecursive(object) - - Determine if *object* requires a recursive representation. This function is - subject to the same limitations as noted in :func:`saferepr` below and may raise an - :exc:`RecursionError` if it fails to detect a recursive object. - - -One more support function is also defined: - -.. function:: saferepr(object) - - Return a string representation of *object*, protected against recursion in - some common data structures, namely instances of :class:`dict`, :class:`list` - and :class:`tuple` or subclasses whose ``__repr__`` has not been overridden. If the - representation of object exposes a recursive entry, the recursive reference - will be represented as ````. The - representation is not otherwise formatted. - - >>> pprint.saferepr(stuff) - "[, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']" - - -.. _prettyprinter-objects: - -PrettyPrinter Objects ---------------------- :class:`PrettyPrinter` instances have the following methods: From 7f5be79bb9b7eea52c1f71b7358d346101a1db5b Mon Sep 17 00:00:00 2001 From: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com> Date: Wed, 28 Feb 2024 02:25:09 +0100 Subject: [PATCH 02/10] Doc: fix links in 'pprint' documentation Before links pointed out to the module `pprint` instead of the `pprint.pprint` function. --- Doc/library/pprint.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index a74f233373bcd9..639ec2c5440705 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -41,7 +41,7 @@ Functions Prints the formatted representation of *object* followed by a newline. If *sort_dicts* is false (the default), dictionaries will be displayed with their keys in insertion order, otherwise the dict keys will be sorted. - *args* and *kwargs* will be passed to :func:`pprint` as formatting + *args* and *kwargs* will be passed to :func:`pprint.pprint` as formatting parameters. .. versionadded:: 3.8 @@ -263,7 +263,7 @@ are converted to strings. The default implementation uses the internals of the Example ------- -To demonstrate several uses of the :func:`pprint` function and its parameters, +To demonstrate several uses of the :func:`pprint.pprint` function and its parameters, let's fetch information about a project from `PyPI `_:: >>> import json @@ -272,7 +272,7 @@ let's fetch information about a project from `PyPI `_:: >>> with urlopen('https://pypi.org/pypi/sampleproject/json') as resp: ... project_info = json.load(resp)['info'] -In its basic form, :func:`pprint` shows the whole object:: +In its basic form, :func:`pprint.pprint` shows the whole object:: >>> pprint.pprint(project_info) {'author': 'The Python Packaging Authority', From 7001ac5fbf4e1fc2813f2f526c45849203265ee4 Mon Sep 17 00:00:00 2001 From: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com> Date: Wed, 28 Feb 2024 12:04:49 +0100 Subject: [PATCH 03/10] Add warning to use 'pp' instead of 'pprint' As `pprint` might have unintended consequences with dict sorting. --- Doc/library/pprint.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 639ec2c5440705..70e33f17c1c6c8 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -61,6 +61,10 @@ Functions :class:`PrettyPrinter` constructor and their meanings are as described in its documentation above. + Note that *sort_dicts* default value is true, which might be an unintuitive + behavior; you will most likely want to use the :func:`print.pp` function + or set this parameter to ``False``. + >>> import pprint >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni'] >>> stuff.insert(0, stuff) From 9f7e07738aae0f76a33f548ba368cc682573447d Mon Sep 17 00:00:00 2001 From: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com> Date: Wed, 28 Feb 2024 12:05:33 +0100 Subject: [PATCH 04/10] Fix typo --- Doc/library/pprint.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 70e33f17c1c6c8..8a570b52588b8c 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -62,7 +62,7 @@ Functions described in its documentation above. Note that *sort_dicts* default value is true, which might be an unintuitive - behavior; you will most likely want to use the :func:`print.pp` function + behavior; you will most likely want to use the :func:`pprint.pp` function or set this parameter to ``False``. >>> import pprint From a9298cd0fabf0e041bc3ca9f4e027ac6aec78ae4 Mon Sep 17 00:00:00 2001 From: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com> Date: Wed, 28 Feb 2024 18:13:27 +0100 Subject: [PATCH 05/10] Add prefix to 'pprint.pprint' references --- Doc/library/pprint.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 8a570b52588b8c..f5cb1569391e44 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -41,7 +41,7 @@ Functions Prints the formatted representation of *object* followed by a newline. If *sort_dicts* is false (the default), dictionaries will be displayed with their keys in insertion order, otherwise the dict keys will be sorted. - *args* and *kwargs* will be passed to :func:`pprint.pprint` as formatting + *args* and *kwargs* will be passed to :func:`~pprint.pprint` as formatting parameters. .. versionadded:: 3.8 @@ -267,7 +267,7 @@ are converted to strings. The default implementation uses the internals of the Example ------- -To demonstrate several uses of the :func:`pprint.pprint` function and its parameters, +To demonstrate several uses of the :func:`~pprint.pprint` function and its parameters, let's fetch information about a project from `PyPI `_:: >>> import json @@ -276,7 +276,7 @@ let's fetch information about a project from `PyPI `_:: >>> with urlopen('https://pypi.org/pypi/sampleproject/json') as resp: ... project_info = json.load(resp)['info'] -In its basic form, :func:`pprint.pprint` shows the whole object:: +In its basic form, :func:`~pprint.pprint` shows the whole object:: >>> pprint.pprint(project_info) {'author': 'The Python Packaging Authority', From 6f4cf9327aa6868f91a5be2a06b38dd20fe38310 Mon Sep 17 00:00:00 2001 From: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com> Date: Wed, 28 Feb 2024 18:15:30 +0100 Subject: [PATCH 06/10] Improve formatting for sys.stdout Suggested-by: @erlend-aasland --- Doc/library/pprint.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index f5cb1569391e44..750de9f15cc34e 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -51,7 +51,7 @@ Functions compact=False, sort_dicts=True, underscore_numbers=False) Prints the formatted representation of *object* on *stream*, followed by a - newline. If *stream* is ``None``, ``sys.stdout`` is used. This may be used + newline. If *stream* is ``None``, :data:`sys.stdout` is used. This may be used in the interactive interpreter instead of the :func:`print` function for inspecting values (you can even reassign ``print = pprint.pprint`` for use within a scope). @@ -136,9 +136,9 @@ This module defines one class: Construct a :class:`PrettyPrinter` instance. This constructor understands several keyword parameters. - *stream* (default ``sys.stdout``) is a :term:`file-like object` to + *stream* (default :data:`sys.stdout`) is a :term:`file-like object` to which the output will be written by calling its :meth:`!write` method. - If both *stream* and ``sys.stdout`` are ``None``, then + If both *stream* and :data:`sys.stdout` are ``None``, then :meth:`~PrettyPrinter.pprint` silently returns. Other values configure the manner in which nesting of complex data @@ -179,7 +179,7 @@ This module defines one class: Added the *underscore_numbers* parameter. .. versionchanged:: 3.11 - No longer attempts to write to ``sys.stdout`` if it is ``None``. + No longer attempts to write to :data:`sys.stdout` if it is ``None``. >>> import pprint >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni'] From 65d20b5b4f6d82798594b4578a917d9f1a817b7d Mon Sep 17 00:00:00 2001 From: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com> Date: Wed, 28 Feb 2024 18:16:33 +0100 Subject: [PATCH 07/10] Improve 'pprint.pp' formatting --- Doc/library/pprint.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 750de9f15cc34e..977626965713a5 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -62,7 +62,7 @@ Functions described in its documentation above. Note that *sort_dicts* default value is true, which might be an unintuitive - behavior; you will most likely want to use the :func:`pprint.pp` function + behavior; you will most likely want to use the :func:`~pprint.pp` function or set this parameter to ``False``. >>> import pprint From f126b368c55c5c4e8273f66c7b72e88d4b9c1295 Mon Sep 17 00:00:00 2001 From: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com> Date: Wed, 28 Feb 2024 18:26:58 +0100 Subject: [PATCH 08/10] Remove references from other than first occurences of sys.stdout --- Doc/library/pprint.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 977626965713a5..51644e75186fa8 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -136,9 +136,9 @@ This module defines one class: Construct a :class:`PrettyPrinter` instance. This constructor understands several keyword parameters. - *stream* (default :data:`sys.stdout`) is a :term:`file-like object` to + *stream* (default :data:`!sys.stdout`) is a :term:`file-like object` to which the output will be written by calling its :meth:`!write` method. - If both *stream* and :data:`sys.stdout` are ``None``, then + If both *stream* and :data:`!sys.stdout` are ``None``, then :meth:`~PrettyPrinter.pprint` silently returns. Other values configure the manner in which nesting of complex data @@ -179,7 +179,7 @@ This module defines one class: Added the *underscore_numbers* parameter. .. versionchanged:: 3.11 - No longer attempts to write to :data:`sys.stdout` if it is ``None``. + No longer attempts to write to :data:`!sys.stdout` if it is ``None``. >>> import pprint >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni'] From b7f656e60ebd746bc2ebc26a62909098bb5718a5 Mon Sep 17 00:00:00 2001 From: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com> Date: Wed, 28 Feb 2024 19:05:20 +0100 Subject: [PATCH 09/10] Remove mention that pprint.pprint is unintuitive Co-authored-by: Erlend E. Aasland --- Doc/library/pprint.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 51644e75186fa8..0f3a97770486dd 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -61,10 +61,6 @@ Functions :class:`PrettyPrinter` constructor and their meanings are as described in its documentation above. - Note that *sort_dicts* default value is true, which might be an unintuitive - behavior; you will most likely want to use the :func:`~pprint.pp` function - or set this parameter to ``False``. - >>> import pprint >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni'] >>> stuff.insert(0, stuff) From e9aa1d2767c46f8b95dedc70e9172ed7672c2a42 Mon Sep 17 00:00:00 2001 From: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com> Date: Wed, 28 Feb 2024 19:05:45 +0100 Subject: [PATCH 10/10] Minor clean up Co-authored-by: Erlend E. Aasland --- Doc/library/pprint.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 0f3a97770486dd..2a2eb098646364 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -100,8 +100,6 @@ Functions :exc:`RecursionError` if it fails to detect a recursive object. -One more support function is also defined: - .. function:: saferepr(object) Return a string representation of *object*, protected against recursion in