8000 Merge pull request #16437 from anntzer/unpylabdoc · matplotlib/matplotlib@81e4720 · GitHub
[go: up one dir, main page]

Skip to content

Commit 81e4720

Browse files
authored
Merge pull request #16437 from anntzer/unpylabdoc
Rework pylab docstring.
2 parents 62d8d65 + 18d552d commit 81e4720

File tree

6 files changed

+30
-248
lines changed
  • devel/MEP
  • users
  • lib/matplotlib
  • 6 files changed

    +30
    -248
    lines changed

    doc/api/index.rst

    Lines changed: 2 additions & 9 deletions
    8000
    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
    "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-
    < 10000 span class=pl-s> 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