Skip to content

Rework pylab docstring. #16441

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Rework pylab docstring. #16441

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 2 additions & 9 deletions doc/api/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------
Expand Down
6 changes: 3 additions & 3 deletions doc/api/prev_api_changes/api_changes_3.1.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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``
Expand Down
4 changes: 2 additions & 2 deletions doc/devel/MEP/MEP12.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ sections described above. "Clean-up" should involve:
<https://pypi.python.org/pypi/flake8>`_, 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
<https://github.com/tonysyu/matplotlib/commit/c25ef1e02b3a0ecb279492409dac0de9b3d2c0e2>`_
* Remove shebang line, e.g.:
Expand All @@ -134,7 +134,7 @@ sections described above. "Clean-up" should involve:
and `1458aa8
<https://github.com/tonysyu/matplotlib/commit/1458aa87c5eae9dd99e141956a6adf7a0f3c6707>`_

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
Expand Down
35 changes: 12 additions & 23 deletions doc/missing-references.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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:<autosummary>:1",
Expand Down Expand Up @@ -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",
Expand All @@ -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"
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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"
],
Expand Down Expand Up @@ -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"
],
Expand Down Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion doc/users/history.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
220 changes: 10 additions & 210 deletions lib/matplotlib/pylab.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down