From 52a5ae4da9f815828e5b72ee94337962e3a9c372 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Thu, 27 Jul 2023 00:57:28 +0200 Subject: [PATCH] Move pylab documentation to its own module page Previously, pylab was not listed under modules, but the module docstring (and thus also the target of pylab links) wa on the API Reference top page. While pylab is discouraged, it's still a regular module and should be handled as such. Even more importantly, by removing the pylab section from the API reference top page, we de-emphasize it. Note, that pylab is still mentioned in the more in-depth backend discussion at https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html Co-authored-by: hannah Co-authored-by: Jody Klymak --- doc/api/index.rst | 7 +------ doc/api/pylab.rst | 6 ++++++ lib/matplotlib/pylab.py | 28 +++++++++++++++++++--------- 3 files changed, 26 insertions(+), 15 deletions(-) create mode 100644 doc/api/pylab.rst diff --git a/doc/api/index.rst b/doc/api/index.rst index 8ad4e2e9ea1a..644842ee70ae 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -80,12 +80,6 @@ Further reading: .. _api-index: -The pylab API (discouraged) -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: pylab - :no-members: - Modules ------- @@ -162,3 +156,4 @@ Alphabetical list of modules: toolkits/mplot3d.rst toolkits/axes_grid1.rst toolkits/axisartist.rst + pylab.rst diff --git a/doc/api/pylab.rst b/doc/api/pylab.rst new file mode 100644 index 000000000000..184d0b578c71 --- /dev/null +++ b/doc/api/pylab.rst @@ -0,0 +1,6 @@ +********* +``pylab`` +********* + +.. automodule:: pylab + :no-members: diff --git a/lib/matplotlib/pylab.py b/lib/matplotlib/pylab.py index ebd65655bbed..a5b9abebffe9 100644 --- a/lib/matplotlib/pylab.py +++ b/lib/matplotlib/pylab.py @@ -1,14 +1,24 @@ """ +`pylab` is a historic interface and its use is strongly discouraged. The equivalent +replacement is `matplotlib.pyplot`. See :ref:` api_interfaces` for a full overview +of Matplotlib interfaces. + +`pylab` was designed to support a MATLAB-like way of working with all plotting related +functions directly available in the global namespace. This was achieved through a +wildcard import (``from pylab import *``). + .. warning:: - Since heavily importing into the global namespace may result in unexpected - behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot` - instead. - -`pylab` is a module that includes `matplotlib.pyplot`, `numpy`, `numpy.fft`, -`numpy.linalg`, `numpy.random`, and some additional functions, all within -a single namespace. Its original purpose was to mimic a MATLAB-like way -of working by importing all functions into the global namespace. This is -considered bad style nowadays. + The use of `pylab` is discouraged for the following reasons: + + ``from pylab import *`` imports all the functions from `matplotlib.pyplot`, `numpy`, + `numpy.fft`, `numpy.linalg`, and `numpy.random`, and some additional functions into + the global namespace. + + Such a pattern is nowadays considered bad practice, as it clutters the global + namespace. Even more severely, in the case of `pylab`, this will overwrite some + builtin functions (e.g. the builtin `sum` will be replaced by `numpy.sum`), which + can lead to unexpected behavior. + """ from matplotlib.cbook import flatten, silent_list