Merge pull request #26396 from timhoffm/pylab

story645 · web-flow · commit 72578a7a053d · 2023-07-27T12:15:22.000-04:00
Move pylab documentation to its own module page
diff --git 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
@@ -0,0 +1,6 @@
+*********
+``pylab``
+*********
+
+.. automodule:: pylab
+   :no-members:
diff --git 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
