8000 Merge pull request #22613 from tacaswell/doc_oo_to_explicit · matplotlib/matplotlib@a436253 · GitHub
[go: up one dir, main page]
Skip to content

Commit a436253

Browse files
greglucasgreglucas
authored
Merge pull request #22613 from tacaswell/doc_oo_to_explicit
DOC: Add links to explicit vs implicit API everywhere "OO" is used
2 parents 0e46ff2 + 7083aba commit a436253

File tree

11 files changed

+128
-104
lines changed
  • lib/matplotlib
  • tutorials

    • 11 files changed

    +128
    -104
    lines changed

    ‎doc/api/index.rst‎

    Lines changed: 56 additions & 51 deletions
    Original file line numberDiff line numberDiff line change
    @@ -30,6 +30,62 @@ methods on them to plot data, add axis labels and a figure title.
    3030
    fig.set_facecolor('lightsteelblue')
    3131

    3232

    33+
    34+
    .. _usage_patterns:
    35+
    36+
    Usage patterns
    37+
    --------------
    38+
    39+
    Below we describe several common approaches to plotting with Matplotlib. See
    40+
    :ref:`api_interfaces` for an explanation of the trade-offs between the supported user
    41+
    APIs.
    42+
    43+
    44+
    The explicit API
    45+
    ^^^^^^^^^^^^^^^^
    46+
    47+
    At its core, Matplotlib is an object-oriented library. We recommend directly
    48+
    working with the objects if you need more control and customization of your
    49+
    plots.
    50+
    51+
    In many cases you will create a `.Figure` and one or more
    52+
    `~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
    53+
    on these objects. However, it's also possible to create `.Figure`\ s
    54+
    explicitly (e.g. when including them in GUI applications).
    55+
    56+
    Further reading:
    57+
    58+
    - `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
    59+
    plotting functions.
    60+
    - Most of the :ref:`examples <examples-index>` use the object-oriented approach
    61+
    (except for the pyplot section)
    62+
    63+
    64+
    The implicit API
    65+
    ^^^^^^^^^^^^^^^^
    66+
    67+
    `matplotlib.pyplot` is a collection of functions that make
    68+
    Matplotlib work like MATLAB. Each pyplot function makes some change to a
    69+
    figure: e.g., creates a figure, creates a plotting area in a figure, plots
    70+
    some lines in a plotting area, decorates the plot with labels, etc.
    71+
    72+
    `.pyplot` is mainly intended for interactive plots and simple cases of
    73+
    programmatic plot generation.
    74+
    75+
    Further reading:
    76+
    77+
    - The `matplotlib.pyplot` function reference
    78+
    - :doc:`/tutorials/introductory/pyplot`
    79+
    - :ref:`Pyplot examples <pyplots_examples>`
    80+
    81+
    .. _api-index:
    82+
    83+
    The pylab API (discouraged)
    84+
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
    85+
    86+
    .. automodule:: pylab
    87+
    :no-members:
    88+
    3389
    Modules
    3490
    -------
    3591

    @@ -107,54 +163,3 @@ Alphabetical list of modules:
    107163
    toolkits/axes_grid1.rst
    108164
    toolkits/axisartist.rst
    109165
    toolkits/axes_grid.rst
    110-
    111-
    112-
    .. _usage_patterns:
    113-
    114-
    Usage patterns
    115-
    --------------
    116-
    117-
    Below we describe several common approaches to plotting with Matplotlib.
    118-
    119-
    The pyplot API
    120-
    ^^^^^^^^^^^^^^
    121-
    122-
    `matplotlib.pyplot` is a collection of functions that make
    123-
    Matplotlib work like MATLAB. Each pyplot function makes some change to a
    124-
    figure: e.g., creates a figure, creates a plotting area in a figure, plots
    125-
    some lines in a plotting area, decorates the plot with labels, etc.
    126-
    127-
    `.pyplot` is mainly intended for interactive plots and simple cases of
    128-
    programmatic plot generation.
    129-
    130-
    Further reading:
    131-
    132-
    - The `matplotlib.pyplot` function reference
    133-
    - :doc:`/tutorials/introductory/pyplot`
    134-
    - :ref:`Pyplot examples <pyplots_examples>`
    135-
    136-
    .. _api-index:
    137-
    138-
    The object-oriented API
    139-
    ^^^^^^^^^^^^^^^^^^^^^^^
    140-
    141-
    At its core, Matplotlib is object-oriented. We recommend directly working
    142-
    with the objects, if you need more control and customization of your plots.
    143-
    144-
    In many cases you will create a `.Figure` and one or more
    145-
    `~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
    146-
    on these objects. However, it's also possible to create `.Figure`\ s
    147-
    explicitly (e.g. when including them in GUI applications).
    148-
    149-
    Further reading:
    150-
    151-
    - `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
    152-
    plotting functions.
    153-
    - Most of the :ref:`examples <examples-index>` use the object-oriented approach
    154-
    (except for the pyplot section)
    155-
    156-
    The pylab API (discouraged)
    157-
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^
    158-
    159-
    .. automodule:: pylab
    160-
    :no-members:

    ‎doc/users/project/history.rst‎

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -11,7 +11,7 @@ History
    1111
    Matplotlib is a library for making 2D plots of arrays in `Python
    1212
    <https://www.python.org>`_. Although it has its origins in emulating
    1313
    the MATLAB graphics commands, it is
    14-
    independent of MATLAB, and can be used in a Pythonic, object oriented
    14+
    independent of MATLAB, and can be used in a Pythonic, object-oriented
    1515
    way. Although Matplotlib is written primarily in pure Python, it
    1616
    makes heavy use of `NumPy <https://numpy.org>`_ and other extension
    1717
    code to provide good performance even for large arrays.

    ‎examples/misc/pythonic_matplotlib.py‎

    Lines changed: 6 additions & 5 deletions
    Original file line numberDiff line numberDiff line change
    @@ -3,9 +3,9 @@
    33
    Pythonic Matplotlib
    44
    ===================
    55
    6-
    Some people prefer to write more pythonic, object-oriented code
    7-
    rather than use the pyplot interface to matplotlib. This example shows
    8-
    you how.
    6+
    Some people prefer to write more "Pythonic", explicit object-oriented code,
    7+
    rather than use the implicit pyplot interface to Matplotlib. This example
    8+
    shows you how to take advantage of the explicit Matplotlib interface.
    99
    1010
    Unless you are an application developer, I recommend using part of the
    1111
    pyplot interface, particularly the figure, close, subplot, axes, and
    @@ -14,7 +14,7 @@
    1414
    instances, managing the bounding boxes of the figure elements,
    1515
    creating and realizing GUI windows and embedding figures in them.
    1616
    17-
    If you are an application developer and want to embed matplotlib in
    17+
    If you are an application developer and want to embed Matplotlib in
    1818
    your application, follow the lead of examples/embedding_in_wx.py,
    1919
    examples/embedding_in_gtk.py or examples/embedding_in_tk.py. In this
    2020
    case you will want to control the creation of all your figures,
    @@ -28,7 +28,7 @@
    2828
    application developers, however.
    2929
    3030
    If you see an example in the examples dir written in pyplot interface,
    31-
    and you want to emulate that using the true python method calls, there
    31+
    and you want to emulate that using the true Python method calls, there
    3232
    is an easy mapping. Many of those examples use 'set' to control
    3333
    figure properties. Here's how to map those commands onto instance
    3434
    methods
    @@ -52,6 +52,7 @@
    5252
    a.set_yticklabels([])
    5353
    a.set_xticks([])
    5454
    a.set_yticks([])
    55+
    5556
    """
    5657

    5758
    import matplotlib.pyplot as plt

    ‎examples/subplots_axes_and_figures/multiple_figs_demo.py‎

    Lines changed: 5 additions & 4 deletions
    Original file line numberDiff line numberDiff line change
    @@ -10,10 +10,11 @@
    1010
    1111
    .. note::
    1212
    13-
    We discourage working with multiple figures in pyplot because managing
    14-
    the *current figure* is cumbersome and error-prone. Instead, we recommend
    15-
    to use the object-oriented approach and call methods on Figure and Axes
    16-
    instances.
    13+
    We discourage working with multiple figures through the implicit pyplot
    14+
    interface because managing the *current figure* is cumbersome and
    15+
    error-prone. Instead, we recommend using the explicit approach and call
    16+
    methods on Figure and Axes instances. See :ref:`api_interfaces` for an
    17+
    explanation of the trade-offs between the implicit and explicit interfaces.
    1718
    1819
    """
    1920
    import matplotlib.pyplot as plt

    ‎lib/matplotlib/__init__.py‎

    Lines changed: 8 additions & 4 deletions
    Original file line numberDiff line numberDiff line change
    @@ -17,10 +17,13 @@
    1717
    1818
    at the ipython shell prompt.
    1919
    20-
    For the most part, direct use of the object-oriented library is encouraged when
    21-
    programming; pyplot is primarily for working interactively. The exceptions are
    22-
    the pyplot functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`,
    23-
    and `.pyplot.savefig`, which can greatly simplify scripting.
    20+
    For the most part, direct use of the explicit object-oriented library is
    21+
    encouraged when programming; the implicit pyplot interface is primarily for
    22+
    working interactively. The exceptions to this suggestion are the pyplot
    23+
    functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`, and
    24+
    `.pyplot.savefig`, which can greatly simplify scripting. See
    25+
    :ref:`api_interfaces` for an explanation of the tradeoffs between the implicit
    26+
    and explicit interfaces.
    2427
    2528
    Modules include:
    2629
    @@ -79,6 +82,7 @@
    7982
    8083
    Occasionally the internal documentation (python docstrings) will refer
    8184
    to MATLAB&reg;, a registered trademark of The MathWorks, Inc.
    85+
    8286
    """
    8387

    8488
    import atexit

    ‎lib/matplotlib/pyplot.py‎

    Lines changed: 5 additions & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -16,7 +16,7 @@
    1616
    y = np.sin(x)
    1717
    plt.plot(x, y)
    1818
    19-
    The explicit (object-oriented) API is recommended for complex plots, though
    19+
    The explicit object-oriented API is recommended for complex plots, though
    2020
    pyplot is still usually used to create the figure and often the axes in the
    2121
    figure. See `.pyplot.figure`, `.pyplot.subplots`, and
    2222
    `.pyplot.subplot_mosaic` to create figures, and
    @@ -29,6 +29,10 @@
    2929
    y = np.sin(x)
    3030
    fig, ax = plt.subplots()
    3131
    ax.plot(x, y)
    32+
    33+
    34+
    See :ref:`api_interfaces` for an explanation of the tradeoffs between the
    35+
    implicit and explicit interfaces.
    3236
    """
    3337

    3438
    import functools

    ‎tutorials/introductory/images.py‎

    Lines changed: 9 additions & 9 deletions
    Original file line numberDiff line numberDiff line change
    @@ -37,15 +37,15 @@
    3737
    cells below those that create the plot will change the plot - it is a
    3838
    live object in memory.
    3939
    40-
    This tutorial will use Matplotlib's imperative-style plotting
    41-
    interface, pyplot. This interface maintains global state, and is very
    42-
    useful for quickly and easily experimenting with various plot
    43-
    settings. The alternative is the object-oriented interface, which is also
    44-
    very powerful, and generally more suitable for large application
    45-
    development. If you'd like to learn about the object-oriented
    46-
    interface, a great place to start is our :doc:`Quick start guide
    47-
    </tutorials/introductory/quick_start>`. For now, let's get on
    48-
    with the imperative-style approach:
    40+
    This tutorial will use Matplotlib's implicit plotting interface, pyplot. This
    41+
    interface maintains global state, and is very useful for quickly and easily
    42+
    experimenting with various plot settings. The alternative is the explicit,
    43+
    which is more suitable for large application development. For an explanation
    44+
    of the tradeoffs between the implicit and explicit interfaces See
    45+
    :ref:`api_interfaces` and the :doc:`Quick start guide
    46+
    </tutorials/introductory/quick_start>` to start using the explicit interface.
    47+
    For now, let's get on with the implicit approach:
    48+
    4949
    """
    5050

    5151
    import matplotlib.pyplot as plt

    ‎tutorials/introductory/lifecycle.py‎

    Lines changed: 14 additions & 11 deletions
    Original file line numberDiff line numberDiff line change
    @@ -17,17 +17,19 @@
    1717
    <https://pbpython.com/effective-matplotlib.html>`_
    1818
    by Chris Moffitt. It was transformed into this tutorial by Chris Holdgraf.
    1919
    20-
    A note on the Object-Oriented API vs. Pyplot
    21-
    ============================================
    20+
    A note on the explicit vs. implicit interfaces
    21+
    ==============================================
    2222
    23-
    Matplotlib has two interfaces. The first is an object-oriented (OO)
    24-
    interface. In this case, we utilize an instance of :class:`axes.Axes`
    25-
    in order to render visualizations on an instance of :class:`figure.Figure`.
    23+
    Matplotlib has two interfaces. For an explanation of the trade-offs between the
    24+
    explicit and implicit interfaces see :ref:`api_interfaces`.
    2625
    27-
    The second is based on MATLAB and uses a state-based interface. This is
    28-
    encapsulated in the :mod:`.pyplot` module. See the :doc:`pyplot tutorials
    29-
    </tutorials/introductory/pyplot>` for a more in-depth look at the pyplot
    30-
    interface.
    26+
    In the explicit object-oriented (OO) interface we directly utilize instances of
    27+
    :class:`axes.Axes` to build up the visualization in an instance of
    28+
    :class:`figure.Figure`. In the implicit interface, inspired by and modeled on
    29+
    MATLAB, uses an global state-based interface which is is encapsulated in the
    30+
    :mod:`.pyplot` module to plot to the "current Axes". See the :doc:`pyplot
    31+
    tutorials </tutorials/introductory/pyplot>` for a more in-depth look at the
    32+
    pyplot interface.
    3133
    3234
    Most of the terms are straightforward but the main thing to remember
    3335
    is that:
    @@ -41,14 +43,15 @@
    4143
    4244
    .. note::
    4345
    44-
    In general, try to use the object-oriented interface over C7BC the pyplot
    45-
    interface.
    46+
    In general prefer the explicit interface over the implicit pyplot interface
    47+
    for plotting.
    4648
    4749
    Our data
    4850
    ========
    4951
    5052
    We'll use the data from the post from which this tutorial was derived.
    5153
    It contains sales information for a number of companies.
    54+
    5255
    """
    5356

    5457
    # sphinx_gallery_thumbnail_number = 10

    ‎tutorials/introductory/pyplot.py‎

    Lines changed: 14 additions & 12 deletions
    Original file line numberDiff line numberDiff line change
    @@ -4,19 +4,20 @@
    44
    ===============
    55
    66
    An introduction to the pyplot interface. Please also see
    7-
    :doc:`/tutorials/introductory/quick_start` for an overview of how Matplotlib works.
    7+
    :doc:`/tutorials/introductory/quick_start` for an overview of how Matplotlib
    8+
    works and :ref:`api_interfaces` for an explanation of the trade-offs between the
    9+
    supported user APIs.
    10+
    811
    """
    912

    1013
    ###############################################################################
    1114
    # Intro to pyplot
    1215
    # ===============
    1316
    #
    14-
    # :mod:`matplotlib.pyplot` is a collection of functions
    15-
    # that make matplotlib work like MATLAB.
    16-
    # Each ``pyplot`` function makes
    17-
    # some change to a figure: e.g., creates a figure, creates a plotting area
    18-
    # in a figure, plots some lines in a plotting area, decorates the plot
    19-
    # with labels, etc.
    17+
    # :mod:`matplotlib.pyplot` is a collection of functions that make matplotlib
    18+
    # work like MATLAB. Each ``pyplot`` function makes some change to a figure:
    19+
    # e.g., creates a figure, creates a plotting area in a figure, plots some lines
    20+
    # in a plotting area, decorates the plot with labels, etc.
    2021
    #
    2122
    # In :mod:`matplotlib.pyplot` various states are preserved
    2223
    # across function calls, so that it keeps track of things like
    @@ -28,10 +29,11 @@
    2829
    #
    2930
    # .. note::
    3031
    #
    31-
    # the pyplot API is generally less-flexible than the object-oriented API.
    32-
    # Most of the function calls you see here can also be called as methods
    33-
    # from an ``Axes`` object. We recommend browsing the tutorials and
    34-
    # examples to see how this works.
    32+
    # the implicit pyplot API is generally less verbose but also not as flexible as the
    33+
    # explicit API. Most of the function calls you see here can also be called
    34+
    # as methods from an ``Axes`` object. We recommend browsing the tutorials
    35+
    # and examples to see how this works. See :ref:`api_interfaces` for an
    36+
    # explanation of the trade off of the supported user APIs.
    3537
    #
    3638
    # Generating visualizations with pyplot is very quick:
    3739

    @@ -301,7 +303,7 @@ def f(t):
    301303
    # and the current axes with `~.pyplot.cla`. If you find
    302304
    # it annoying that states (specifically the current image, figure and axes)
    303305
    # are being maintained for you behind the scenes, don't despair: this is just a thin
    304-
    # stateful wrapper around an object oriented API, which you can use
    306+
    # stateful wrapper around an object-oriented API, which you can use
    305307
    # instead (see :doc:`/tutorials/intermediate/artists`)
    306308
    #
    307309
    # If you are making lots of figures, you need to be aware of one

    ‎tutorials/introductory/quick_start.py‎

    Lines changed: 6 additions & 3 deletions
    Original file line numberDiff line numberDiff line change
    @@ -134,16 +134,19 @@
    134134
    # Coding styles
    135135
    # =============
    136136
    #
    137-
    # The object-oriented and the pyplot interfaces
    138-
    # ---------------------------------------------
    137+
    # The explicit and the implicit interfaces
    138+
    # ----------------------------------------
    139139
    #
    140140
    # As noted above, there are essentially two ways to use Matplotlib:
    141141
    #
    142142
    # - Explicitly create Figures and Axes, and call methods on them (the
    143143
    # "object-oriented (OO) style").
    144-
    # - Rely on pyplot to automatically create and manage the Figures and Axes, and
    144+
    # - Rely on pyplot to implicitly create and manage the Figures and Axes, and
    145145
    # use pyplot functions for plotting.
    146146
    #
    147+
    # See :ref:`api_interfaces` for an explanation of the tradeoffs between the
    148+
    # implicit and explicit interfaces.
    149+
    #
    147150
    # So one can use the OO-style
    148151

    149152
    x = np.linspace(0, 2, 100) # Sample data.

    0 commit comments

    Comments
     (0)
    0