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