8000 Rework pylab docstring. · matplotlib/matplotlib@18d552d · GitHub
[go: up one dir, main page]
Skip to content

Commit 18d552d

Browse files
anntzeranntzer
committed
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.
1 parent b66fecd commit 18d552d

File tree

6 files changed

+30
-248
lines changed

6 files changed

+30
-248
lines changed

‎doc/api/index.rst

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -55,15 +55,8 @@ Further reading:
5555
The pylab API (disapproved)
5656
^^^^^^^^^^^^^^^^^^^^^^^^^^^
5757

58-
.. warning::
59-
Since heavily importing into the global namespace may result in unexpected
60-
behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot`
61-
instead.
62-
63-
`pylab` is a module that includes `matplotlib.pyplot`, `numpy`
64-
and some additional functions within a single namespace. Its original purpose
65-
was to mimic a MATLAB-like way of working by importing all functions into the
66-
global namespace. This is considered bad style nowadays.
58+
.. automodule:: pylab
59+
:no-members:
6760

6861
Modules
6962
-------

‎doc/api/prev_api_changes/api_changes_3.1.0.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -613,11 +613,11 @@ in Matplotlib 2.2 has been removed. See below for a list:
613613
``mlab.FormatFormatStr``, ``mlab.FormatString``, ``mlab.FormatObj``
614614
- ``mlab.donothing_callback``
615615

616-
:mod:`matplotlib.pylab` removals
617-
--------------------------------
616+
`pylab` removals
617+
----------------
618618
Lots of code inside the :mod:`matplotlib.mlab` module which was deprecated
619619
in Matplotlib 2.2 has been removed. This means the following functions are
620-
no longer available in the `matplotlib.pylab` module:
620+
no longer available in the `pylab` module:
621621

622622
- ``amap``
623623
- ``base_repr``

‎doc/devel/MEP/MEP12.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ sections described above. "Clean-up" should involve:
108108
<https://pypi.python.org/pypi/flake8>`_, or a similar checker, is
109109
highly recommended)
110110
* Commented-out code should be removed.
111-
* Replace uses of ``pylab`` interface with ``pyplot`` (+ ``numpy``,
111+
* Replace uses of `pylab` interface with `.pyplot` (+ `numpy`,
112112
etc.). See `c25ef1e
113113
<https://github.com/tonysyu/matplotlib/commit/c25ef1e02b3a0ecb279492409dac0de9b3d2c0e2>`_
114114
* Remove shebang line, e.g.:
@@ -134,7 +134,7 @@ sections described above. "Clean-up" should involve:
134134
and `1458aa8
135135
<https://github.com/tonysyu/matplotlib/commit/1458aa87c5eae9dd99e141956a6adf7a0f3c6707>`_
136136

137-
Use of ``pylab`` should be demonstrated/discussed on a dedicated help
137+
Use of `pylab` should be demonstrated/discussed on a dedicated help
138138
page instead of the gallery examples.
139139

140140
**Note:** When moving an existing example, you should search for

‎doc/missing-references.json

Lines changed: 12 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -485,7 +485,7 @@
485485
},
486486
" F438 py:func": {
487487
"log.debug": [
488-
"doc/devel/contributing.rst:429"
488+
"doc/devel/contributing.rst:434"
489489
],
490490
"matplotlib.Axis.set_ticks_position": [
491491
"doc/users/prev_whats_new/whats_new_1.4.rst:141"
@@ -576,8 +576,8 @@
576576
"doc/users/event_handling.rst:164"
577577
],
578578
"matplotlib.text.Text.__init__": [
579-
"doc/devel/contributing.rst:379",
580-
"doc/devel/contributing.rst:387"
579+
"doc/devel/contributing.rst:384",
580+
"doc/devel/contributing.rst:392"
581581
],
582582
"option_scale_image": [
583583
"lib/matplotlib/backends/backend_cairo.py:docstring of matplotlib.backends.backend_cairo.RendererCairo.draw_image:22",
@@ -623,17 +623,13 @@
623623
"matplotlib.ft2font": [
624624
"doc/api/prev_api_changes/api_changes_0.91.0.rst:34"
625625
],
626-
"matplotlib.pylab": [
627-
"doc/api/prev_api_changes/api_changes_3.1.0.rst:616",
628-
"doc/users/history.rst:63"
629-
],
630626
"matplotlib.tests.test_basic": [
631627
"doc/devel/testing.rst:98"
632628
]
633629
},
634630
"py:obj": {
635631
"./gallery/index.html": [
636-
"doc/devel/contributing.rst:541"
632+
"doc/devel/contributing.rst:546"
637633
],
638634
"Artist.sticky_edges": [
639635
"doc/api/axes_api.rst:357:<autosummary>:1",
@@ -961,10 +957,10 @@
961957
"doc/devel/MEP/MEP23.rst:40"
962958
],
963959
"cbook._warn_external": [
964-
"doc/devel/contributing.rst:472",
965-
"doc/devel/contributing.rst:487",
966-
"doc/devel/contributing.rst:496",
967-
"doc/devel/contributing.rst:521"
960+
"doc/devel/contributing.rst:477",
961+
"doc/devel/contributing.rst:492",
962+
"doc/devel/contributing.rst:501",
963+
"doc/devel/contributing.rst:526"
968964
],
969965
"cbook.deprecated": [
970966
"doc/api/prev_api_changes/api_changes_3.1.0.rst:1073",
@@ -974,7 +970,7 @@
974970
"doc/api/prev_api_changes/api_changes_3.1.0.rst:766"
975971
],
976972
"cbook.warn_deprecated()": [
977-
"doc/devel/contributing.rst:309"
973+
"doc/devel/contributing.rst:314"
978974
],
979975
"cleanup": [
980976
"lib/matplotlib/animation.py:docstring of matplotlib.animation.HTMLWriter.setup:19"
@@ -1101,8 +1097,8 @@
11011097
"doc/gallery/misc/ftface_props.rst:14"
11021098
],
11031099
"logging.WARNING": [
1104-
"doc/devel/contributing.rst:447",
1105-
"doc/devel/contributing.rst:484"
1100+
"doc/devel/contributing.rst:452",
1101+
"doc/devel/contributing.rst:489"
11061102
],
11071103
"ls_mapper": [
11081104
"doc/api/prev_api_changes/api_changes_1.5.0.rst:11"
@@ -1474,9 +1470,6 @@
14741470
"matplotlib.patches.Patch.__init__": [
14751471
"doc/devel/documenting_mpl.rst:671"
14761472
],
1477-
"matplotlib.pylab": [
1478-
"doc/api/prev_api_changes/api_changes_3.1.0.rst:618"
1479-
],
14801473
"matplotlib.pyplot.get_scale_docs()": [
14811474
"doc/api/prev_api_changes/api_changes_3.1.0.rst:853"
14821475
],
@@ -1556,10 +1549,6 @@
15561549
"print_xyz": [
15571550
"lib/matplotlib/backends/backend_template.py:docstring of matplotlib.backends.backend_template:22"
15581551
],
1559-
"pylab": [
1560-
"doc/api/index.rst:63",
1561-
"doc/devel/MEP/MEP12.rst:13"
1562-
],
15631552
"pyplot.set_loglevel": [
15641553
"doc/users/prev_whats_new/whats_new_3.1.0.rst:377"
15651554
],
@@ -1681,7 +1670,7 @@
16811670
"lib/matplotlib/figure.py:docstring of matplotlib.figure.Figure.set_constrained_layout:5"
16821671
],
16831672
"warn": [
1684-
"doc/devel/contributing.rst:496"
1673+
"doc/devel/contributing.rst:501"
16851674
],
16861675
"whats_new.rst": [
16871676
"doc/users/next_whats_new/README.rst:6"

‎doc/users/history.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ without affecting user code.
6262

6363
The Matplotlib code is conceptually divided into three parts: the
6464
*pylab interface* is the set of functions provided by
65-
:mod:`matplotlib.pylab` which allow the user to create plots with code
65+
:mod:`pylab` which allow the user to create plots with code
6666
quite similar to MATLAB figure generating code
6767
(:doc:`/tutorials/introductory/pyplot`). The *Matplotlib frontend* or *Matplotlib
6868
API* is the set of classes that do the heavy lifting, creating and

‎lib/matplotlib/pylab.py

Lines changed: 10 additions & 210 deletions
Original file line numberDiff line numberDiff line change
@@ -1,214 +1,14 @@
11
"""
2-
This is a procedural interface to the matplotlib object-oriented
3-
plotting library.
4-
5-
The following plotting commands are provided; the majority have
6-
MATLAB |reg| [*]_ analogs and similar arguments.
7-
8-
.. |reg| unicode:: 0xAE
9-
10-
_Plotting commands
11-
acorr - plot the autocorrelation function
12-
annotate - annotate something in the figure
13-
arrow - add an arrow to the axes
14-
axes - Create a new axes
15-
axhline - draw a horizontal line across axes
16-
axvline - draw a vertical line across axes
17-
axhspan - draw a horizontal bar across axes
18-
axvspan - draw a vertical bar across axes
19-
axis - Set or return the current axis limits
20-
autoscale - turn axis autoscaling on or off, and apply it
21-
bar - make a bar chart
22-
barh - a horizontal bar chart
23-
broken_barh - a set of horizontal bars with gaps
24-
box - set the axes frame on/off state
25-
boxplot - make a box and whisker plot
26-
violinplot - make a violin plot
27-
cla - clear current axes
28-
clabel - label a contour plot
29-
clf - clear a figure window
30-
clim - adjust the color limits of the current image
31-
close - close a figure window
32-
colorbar - add a colorbar to the current figure
33-
cohere - make a plot of coherence
34-
contour - make a contour plot
35-
contourf - make a filled contour plot
36-
csd - make a plot of cross spectral density
37-
delaxes - delete an axes from the current figure
38-
draw - Force a redraw of the current figure
39-
errorbar - make an errorbar graph
40-
figlegend - make legend on the figure rather than the axes
41-
figimage - make a figure image
42-
figtext - add text in figure coords
43-
figure - create or change active figure
44-
fill - make filled polygons
45-
findobj - recursively find all objects matching some criteria
46-
gca - return the current axes
47-
gcf - return the current figure
48-
gci - get the current image, or None
49-
getp - get a graphics property
50-
grid - set whether gridding is on
51-
hist - make a histogram
52-
ioff - turn interaction mode off
53-
ion - turn interaction mode on
54-
isinteractive - return True if interaction mode is on
55-
imread - load image file into array
56-
imsave - save array as an image file
57-
imshow - plot image data
58-
legend - make an axes legend
59-
locator_params - adjust parameters used in locating axis ticks
60-
loglog - a log log plot
61-
matshow - display a matrix in a new figure preserving aspect
62-
margins - set margins used in autoscaling
63-
pause - pause for a specified interval
64-
pcolor - make a pseudocolor plot
65-
pcolormesh - make a pseudocolor plot using a quadrilateral mesh
66-
pie - make a pie chart
67-
plot - make a line plot
68-
plot_date - plot dates
69-
plotfile - plot column data from an ASCII tab/space/comma delimited file
70-
pie - pie charts
71-
polar - make a polar plot on a PolarAxes
72-
psd - make a plot of power spectral density
73-
quiver - make a direction field (arrows) plot
74-
rc - control the default params
75-
rgrids - customize the radial grids and labels for polar
76-
savefig - save the current figure
77-
scatter - make a scatter plot
78-
setp - set a graphics property
79-
semilogx - log x axis
80-
semilogy - log y axis
81-
show - show the figures
82-
specgram - a spectrogram plot
83-
spy - plot sparsity pattern using markers or image
84-
stem - make a stem plot
85-
subplot - make one subplot (numrows, numcols, axesnum)
86-
subplots - make a figure with a set of (numrows, numcols) subplots
87-
subplots_adjust - control the subplot positions of current figure
88-
subplot_tool - launch the subplot configuration tool
89-
suptitle - add a figure title
90-
table - add a table to the plot
91-
text - add some text at location (x, y) to the current axes
92-
thetagrids - customize the radial theta grids and labels for polar
93-
tick_params - control the appearance of ticks and tick labels
94-
ticklabel_format - control the format of tick labels
95-
title - add a title to the current axes
96-
tricontour - make a contour plot on a triangular grid
97-
tricontourf - make a filled contour plot on a triangular grid
98-
tripcolor - make a pseudocolor plot on a triangular grid
99-
triplot - plot a triangular grid
100-
xcorr - plot the autocorrelation function of x and y
101-
xlim - set/get the xlimits
102-
ylim - set/get the ylimits
103-
xticks - set/get the xticks
104-
yticks - set/get the yticks
105-
xlabel - add an xlabel to the current axes
106-
ylabel - add a ylabel to the current axes
107-
108-
autumn - set the default colormap to autumn
109-
bone - set the default colormap to bone
110-
cool - set the default colormap to cool
111-
copper - set the default colormap to copper
112-
flag - set the default colormap to flag
113-
gray - set the default colormap to gray
114-
hot - set the default colormap to hot
115-
hsv - set the default colormap to hsv
116-
jet - set the default colormap to jet
117-
pink - set the default colormap to pink
118-
prism - set the default colormap to prism
119-
spring - set the default colormap to spring
120-
summer - set the default colormap to summer
121-
winter - set the default colormap to winter
122-
123-
_Event handling
124-
125-
connect - register an event handler
126-
disconnect - remove a connected event handler
127-
128-
_Matrix commands
129-
130-
cumprod - the cumulative product along a dimension
131-
cumsum - the cumulative sum along a dimension
132-
detrend - remove the mean or besdt fit line from an array
133-
diag - the k-th diagonal of matrix
134-
diff - the n-th difference of an array
135-
eig - the eigenvalues and eigen vectors of v
136-
eye - a matrix where the k-th diagonal is ones, else zero
137-
find - return the indices where a condition is nonzero
138-
fliplr - flip the rows of a matrix up/down
139-
flipud - flip the columns of a matrix left/right
140-
linspace - a linear spaced vector of N values from min to max inclusive
141-
logspace - a log spaced vector of N values from min to max inclusive
142-
meshgrid - repeat x and y to make regular matrices
143-
ones - an array of ones
144-
rand - an array from the uniform distribution [0, 1]
145-
randn - an array from the normal distribution
146-
rot90 - rotate matrix k*90 degrees counterclockwise
147-
squeeze - squeeze an array removing any dimensions of length 1
148-
tri - a triangular matrix
149-
tril - a lower triangular matrix
150-
triu - an upper triangular matrix
151-
vander - the Vandermonde matrix of vector x
152-
svd - singular value decomposition
153-
zeros - a matrix of zeros
154-
155-
_Probability
156-
157-
rand - random numbers from the uniform distribution
158-
randn - random numbers from the normal distribution
159-
160-
_Statistics
161-
162-
amax - the maximum along dimension m
163-
amin - the minimum along dimension m
164-
corrcoef - correlation coefficient
165-
cov - covariance matrix
166-
mean - the mean along dimension m
167-
median - the median along dimension m
168-
norm - the norm of vector x
169-
prod - the product along dimension m
170-
ptp - the max-min along dimension m
171-
std - the standard deviation along dimension m
172-
asum - the sum along dimension m
173-
ksdensity - the kernel density estimate
174-
175-
_Time series analysis
176-
177-
bartlett - M-point Bartlett window
178-
blackman - M-point Blackman window
179-
cohere - the coherence using average periodogram
180-
csd - the cross spectral density using average periodogram
181-
fft - the fast Fourier transform of vector x
182-
hamming - M-point Hamming window
183-
hanning - M-point Hanning window
184-
hist - compute the histogram of x
185-
kaiser - M length Kaiser window
186-
psd - the power spectral density using average periodogram
187-
sinc - the sinc function of array x
188-
189-
_Dates
190-
191-
date2num - convert python datetimes to numeric representation
192-
drange - create an array of numbers for date plots
193-
num2date - convert numeric type (float days since 0001) to datetime
194-
195-
_Other
196-
197-
angle - the angle of a complex array
198-
load - Deprecated--please use loadtxt.
199-
loadtxt - load ASCII data into array.
200-
polyfit - fit x, y to an n-th order polynomial
201-
polyval - evaluate an n-th order polynomial
202-
roots - the roots of the polynomial coefficients in p
203-
save - Deprecated--please use savetxt.
204-
savetxt - save an array to an ASCII file.
205-
trapz - trapezoidal integration
206-
207-
__end
208-
209-
.. [*] MATLAB is a registered trademark of The MathWorks, Inc.
210-
211-
2+
.. warning::
3+
Since heavily importing into the global namespace may result in unexpected
4+
behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot`
5+
instead.
6+
7+
`pylab` is a module that includes `matplotlib.pyplot`, `numpy`, `numpy.fft`,
8+
`numpy.linalg`, `numpy.random`, and some additional functions, all within
9+
a single namespace. Its original purpose was to mimic a MATLAB-like way
10+
of working by importing all functions into the global namespace. This is
11+
considered bad style nowadays.
21212
"""
21313

21414
from matplotlib.cbook import flatten, silent_list, iterable, dedent

0 commit comments

Comments
 (0)
0