From 18d552d8b6172d3869b4d4791db6495b715f46cc Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Fri, 7 Feb 2020 16:51:51 +0100 Subject: [PATCH] Rework pylab docstring. The old pylab module docstring was not rendered anywhere in the html docs (it was only visible with pydoc or with IPython's `pylab?`), and is outdated (e.g. it doesn't even list viridis as colormap). Instead of trying to list the functions provided, replace the docstring by the warning discouraging the use of pylab, and use that as entry in the html docs. --- doc/api/index.rst | 11 +- .../prev_api_changes/api_changes_3.1.0.rst | 6 +- doc/devel/MEP/MEP12.rst | 4 +- doc/missing-references.json | 35 +-- doc/users/history.rst | 2 +- lib/matplotlib/pylab.py | 220 +----------------- 6 files changed, 30 insertions(+), 248 deletions(-) diff --git a/doc/api/index.rst b/doc/api/index.rst index b45d005be134..d96c22de75c8 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -55,15 +55,8 @@ Further reading: The pylab API (disapproved) ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. 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` -and some additional functions 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. +.. automodule:: pylab + :no-members: Modules ------- diff --git a/doc/api/prev_api_changes/api_changes_3.1.0.rst b/doc/api/prev_api_changes/api_changes_3.1.0.rst index 9206495ed683..4afb048d0391 100644 --- a/doc/api/prev_api_changes/api_changes_3.1.0.rst +++ b/doc/api/prev_api_changes/api_changes_3.1.0.rst @@ -613,11 +613,11 @@ in Matplotlib 2.2 has been removed. See below for a list: ``mlab.FormatFormatStr``, ``mlab.FormatString``, ``mlab.FormatObj`` - ``mlab.donothing_callback`` -:mod:`matplotlib.pylab` removals --------------------------------- +`pylab` removals +---------------- Lots of code inside the :mod:`matplotlib.mlab` module which was deprecated in Matplotlib 2.2 has been removed. This means the following functions are -no longer available in the `matplotlib.pylab` module: +no longer available in the `pylab` module: - ``amap`` - ``base_repr`` diff --git a/doc/devel/MEP/MEP12.rst b/doc/devel/MEP/MEP12.rst index 2a7c69852b17..1b10ccf446ee 100644 --- a/doc/devel/MEP/MEP12.rst +++ b/doc/devel/MEP/MEP12.rst @@ -108,7 +108,7 @@ sections described above. "Clean-up" should involve: `_, or a similar checker, is highly recommended) * Commented-out code should be removed. -* Replace uses of ``pylab`` interface with ``pyplot`` (+ ``numpy``, +* Replace uses of `pylab` interface with `.pyplot` (+ `numpy`, etc.). See `c25ef1e `_ * Remove shebang line, e.g.: @@ -134,7 +134,7 @@ sections described above. "Clean-up" should involve: and `1458aa8 `_ -Use of ``pylab`` should be demonstrated/discussed on a dedicated help +Use of `pylab` should be demonstrated/discussed on a dedicated help page instead of the gallery examples. **Note:** When moving an existing example, you should search for diff --git a/doc/missing-references.json b/doc/missing-references.json index a2f3e2738f5e..3ee0e23bda78 100644 --- a/doc/missing-references.json +++ b/doc/missing-references.json @@ -485,7 +485,7 @@ }, "py:func": { "log.debug": [ - "doc/devel/contributing.rst:429" + "doc/devel/contributing.rst:434" ], "matplotlib.Axis.set_ticks_position": [ "doc/users/prev_whats_new/whats_new_1.4.rst:141" @@ -576,8 +576,8 @@ "doc/users/event_handling.rst:164" ], "matplotlib.text.Text.__init__": [ - "doc/devel/contributing.rst:379", - "doc/devel/contributing.rst:387" + "doc/devel/contributing.rst:384", + "doc/devel/contributing.rst:392" ], "option_scale_image": [ "lib/matplotlib/backends/backend_cairo.py:docstring of matplotlib.backends.backend_cairo.RendererCairo.draw_image:22", @@ -623,17 +623,13 @@ "matplotlib.ft2font": [ "doc/api/prev_api_changes/api_changes_0.91.0.rst:34" ], - "matplotlib.pylab": [ - "doc/api/prev_api_changes/api_changes_3.1.0.rst:616", - "doc/users/history.rst:63" - ], "matplotlib.tests.test_basic": [ "doc/devel/testing.rst:98" ] }, "py:obj": { "./gallery/index.html": [ - "doc/devel/contributing.rst:541" + "doc/devel/contributing.rst:546" ], "Artist.sticky_edges": [ "doc/api/axes_api.rst:357::1", @@ -961,10 +957,10 @@ "doc/devel/MEP/MEP23.rst:40" ], "cbook._warn_external": [ - "doc/devel/contributing.rst:472", - "doc/devel/contributing.rst:487", - "doc/devel/contributing.rst:496", - "doc/devel/contributing.rst:521" + "doc/devel/contributing.rst:477", + "doc/devel/contributing.rst:492", + "doc/devel/contributing.rst:501", + "doc/devel/contributing.rst:526" ], "cbook.deprecated": [ "doc/api/prev_api_changes/api_changes_3.1.0.rst:1073", @@ -974,7 +970,7 @@ "doc/api/prev_api_changes/api_changes_3.1.0.rst:766" ], "cbook.warn_deprecated()": [ - "doc/devel/contributing.rst:309" + "doc/devel/contributing.rst:314" ], "cleanup": [ "lib/matplotlib/animation.py:docstring of matplotlib.animation.HTMLWriter.setup:19" @@ -1101,8 +1097,8 @@ "doc/gallery/misc/ftface_props.rst:14" ], "logging.WARNING": [ - "doc/devel/contributing.rst:447", - "doc/devel/contributing.rst:484" + "doc/devel/contributing.rst:452", + "doc/devel/contributing.rst:489" ], "ls_mapper": [ "doc/api/prev_api_changes/api_changes_1.5.0.rst:11" @@ -1474,9 +1470,6 @@ "matplotlib.patches.Patch.__init__": [ "doc/devel/documenting_mpl.rst:671" ], - "matplotlib.pylab": [ - "doc/api/prev_api_changes/api_changes_3.1.0.rst:618" - ], "matplotlib.pyplot.get_scale_docs()": [ "doc/api/prev_api_changes/api_changes_3.1.0.rst:853" ], @@ -1556,10 +1549,6 @@ "print_xyz": [ "lib/matplotlib/backends/backend_template.py:docstring of matplotlib.backends.backend_template:22" ], - "pylab": [ - "doc/api/index.rst:63", - "doc/devel/MEP/MEP12.rst:13" - ], "pyplot.set_loglevel": [ "doc/users/prev_whats_new/whats_new_3.1.0.rst:377" ], @@ -1681,7 +1670,7 @@ "lib/matplotlib/figure.py:docstring of matplotlib.figure.Figure.set_constrained_layout:5" ], "warn": [ - "doc/devel/contributing.rst:496" + "doc/devel/contributing.rst:501" ], "whats_new.rst": [ "doc/users/next_whats_new/README.rst:6" diff --git a/doc/users/history.rst b/doc/users/history.rst index e5d7cf0d637e..77c78ed07565 100644 --- a/doc/users/history.rst +++ b/doc/users/history.rst @@ -62,7 +62,7 @@ without affecting user code. The Matplotlib code is conceptually divided into three parts: the *pylab interface* is the set of functions provided by -:mod:`matplotlib.pylab` which allow the user to create plots with code +:mod:`pylab` which allow the user to create plots with code quite similar to MATLAB figure generating code (:doc:`/tutorials/introductory/pyplot`). The *Matplotlib frontend* or *Matplotlib API* is the set of classes that do the heavy lifting, creating and diff --git a/lib/matplotlib/pylab.py b/lib/matplotlib/pylab.py index 63ffa3e71603..187cb5ef0bb7 100644 --- a/lib/matplotlib/pylab.py +++ b/lib/matplotlib/pylab.py @@ -1,214 +1,14 @@ """ -This is a procedural interface to the matplotlib object-oriented -plotting library. - -The following plotting commands are provided; the majority have -MATLAB |reg| [*]_ analogs and similar arguments. - -.. |reg| unicode:: 0xAE - -_Plotting commands - acorr - plot the autocorrelation function - annotate - annotate something in the figure - arrow - add an arrow to the axes - axes - Create a new axes - axhline - draw a horizontal line across axes - axvline - draw a vertical line across axes - axhspan - draw a horizontal bar across axes - axvspan - draw a vertical bar across axes - axis - Set or return the current axis limits - autoscale - turn axis autoscaling on or off, and apply it - bar - make a bar chart - barh - a horizontal bar chart - broken_barh - a set of horizontal bars with gaps - box - set the axes frame on/off state - boxplot - make a box and whisker plot - violinplot - make a violin plot - cla - clear current axes - clabel - label a contour plot - clf - clear a figure window - clim - adjust the color limits of the current image - close - close a figure window - colorbar - add a colorbar to the current figure - cohere - make a plot of coherence - contour - make a contour plot - contourf - make a filled contour plot - csd - make a plot of cross spectral density - delaxes - delete an axes from the current figure - draw - Force a redraw of the current figure - errorbar - make an errorbar graph - figlegend - make legend on the figure rather than the axes - figimage - make a figure image - figtext - add text in figure coords - figure - create or change active figure - fill - make filled polygons - findobj - recursively find all objects matching some criteria - gca - return the current axes - gcf - return the current figure - gci - get the current image, or None - getp - get a graphics property - grid - set whether gridding is on - hist - make a histogram - ioff - turn interaction mode off - ion - turn interaction mode on - isinteractive - return True if interaction mode is on - imread - load image file into array - imsave - save array as an image file - imshow - plot image data - legend - make an axes legend - locator_params - adjust parameters used in locating axis ticks - loglog - a log log plot - matshow - display a matrix in a new figure preserving aspect - margins - set margins used in autoscaling - pause - pause for a specified interval - pcolor - make a pseudocolor plot - pcolormesh - make a pseudocolor plot using a quadrilateral mesh - pie - make a pie chart - plot - make a line plot - plot_date - plot dates - plotfile - plot column data from an ASCII tab/space/comma delimited file - pie - pie charts - polar - make a polar plot on a PolarAxes - psd - make a plot of power spectral density - quiver - make a direction field (arrows) plot - rc - control the default params - rgrids - customize the radial grids and labels for polar - savefig - save the current figure - scatter - make a scatter plot - setp - set a graphics property - semilogx - log x axis - semilogy - log y axis - show - show the figures - specgram - a spectrogram plot - spy - plot sparsity pattern using markers or image - stem - make a stem plot - subplot - make one subplot (numrows, numcols, axesnum) - subplots - make a figure with a set of (numrows, numcols) subplots - subplots_adjust - control the subplot positions of current figure - subplot_tool - launch the subplot configuration tool - suptitle - add a figure title - table - add a table to the plot - text - add some text at location (x, y) to the current axes - thetagrids - customize the radial theta grids and labels for polar - tick_params - control the appearance of ticks and tick labels - ticklabel_format - control the format of tick labels - title - add a title to the current axes - tricontour - make a contour plot on a triangular grid - tricontourf - make a filled contour plot on a triangular grid - tripcolor - make a pseudocolor plot on a triangular grid - triplot - plot a triangular grid - xcorr - plot the autocorrelation function of x and y - xlim - set/get the xlimits - ylim - set/get the ylimits - xticks - set/get the xticks - yticks - set/get the yticks - xlabel - add an xlabel to the current axes - ylabel - add a ylabel to the current axes - - autumn - set the default colormap to autumn - bone - set the default colormap to bone - cool - set the default colormap to cool - copper - set the default colormap to copper - flag - set the default colormap to flag - gray - set the default colormap to gray - hot - set the default colormap to hot - hsv - set the default colormap to hsv - jet - set the default colormap to jet - pink - set the default colormap to pink - prism - set the default colormap to prism - spring - set the default colormap to spring - summer - set the default colormap to summer - winter - set the default colormap to winter - -_Event handling - - connect - register an event handler - disconnect - remove a connected event handler - -_Matrix commands - - cumprod - the cumulative product along a dimension - cumsum - the cumulative sum along a dimension - detrend - remove the mean or besdt fit line from an array - diag - the k-th diagonal of matrix - diff - the n-th difference of an array - eig - the eigenvalues and eigen vectors of v - eye - a matrix where the k-th diagonal is ones, else zero - find - return the indices where a condition is nonzero - fliplr - flip the rows of a matrix up/down - flipud - flip the columns of a matrix left/right - linspace - a linear spaced vector of N values from min to max inclusive - logspace - a log spaced vector of N values from min to max inclusive - meshgrid - repeat x and y to make regular matrices - ones - an array of ones - rand - an array from the uniform distribution [0, 1] - randn - an array from the normal distribution - rot90 - rotate matrix k*90 degrees counterclockwise - squeeze - squeeze an array removing any dimensions of length 1 - tri - a triangular matrix - tril - a lower triangular matrix - triu - an upper triangular matrix - vander - the Vandermonde matrix of vector x - svd - singular value decomposition - zeros - a matrix of zeros - -_Probability - - rand - random numbers from the uniform distribution - randn - random numbers from the normal distribution - -_Statistics - - amax - the maximum along dimension m - amin - the minimum along dimension m - corrcoef - correlation coefficient - cov - covariance matrix - mean - the mean along dimension m - median - the median along dimension m - norm - the norm of vector x - prod - the product along dimension m - ptp - the max-min along dimension m - std - the standard deviation along dimension m - asum - the sum along dimension m - ksdensity - the kernel density estimate - -_Time series analysis - - bartlett - M-point Bartlett window - blackman - M-point Blackman window - cohere - the coherence using average periodogram - csd - the cross spectral density using average periodogram - fft - the fast Fourier transform of vector x - hamming - M-point Hamming window - hanning - M-point Hanning window - hist - compute the histogram of x - kaiser - M length Kaiser window - psd - the power spectral density using average periodogram - sinc - the sinc function of array x - -_Dates - - date2num - convert python datetimes to numeric representation - drange - create an array of numbers for date plots - num2date - convert numeric type (float days since 0001) to datetime - -_Other - - angle - the angle of a complex array - load - Deprecated--please use loadtxt. - loadtxt - load ASCII data into array. - polyfit - fit x, y to an n-th order polynomial - polyval - evaluate an n-th order polynomial - roots - the roots of the polynomial coefficients in p - save - Deprecated--please use savetxt. - savetxt - save an array to an ASCII file. - trapz - trapezoidal integration - -__end - -.. [*] MATLAB is a registered trademark of The MathWorks, Inc. - - +.. 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. """ from matplotlib.cbook import flatten, silent_list, iterable, dedent