From 49b272878ade945b58f0ddea369f0ab96f5f9bc3 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Thu, 27 Jul 2023 23:27:31 +0200 Subject: [PATCH] Restructure interface section of API Reference index page - switch to Axes interface / pyplot interface terminology (#26388) - Reduce the interface description to very compact two-sentence descriptions and refer to the interface page for everything else. The focus here is to point the users to relevant API resources for the respective interfaces, not to discuss these interfaces in detail. The latter is the task of https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html and I will add some missing pieces there in a follow-up PR. Co-authored-by: hannah --- doc/api/index.rst | 88 ++++++++++++----------------------------- lib/matplotlib/pylab.py | 4 +- 2 files changed, 27 insertions(+), 65 deletions(-) diff --git a/doc/api/index.rst b/doc/api/index.rst index 644842ee70ae..1b098009faed 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -1,82 +1,44 @@ API Reference ============= -When using the library you will typically create -:doc:`Figure ` and :doc:`Axes ` objects and -call their methods to add content and modify the appearance. +Matplotlib interfaces +--------------------- -- :mod:`matplotlib.figure`: axes creation, figure-level content -- :mod:`matplotlib.axes`: most plotting methods, Axes labels, access to axis - styling, etc. +Matplotlib provides two different interfaces: -Example: We create a Figure ``fig`` and Axes ``ax``. Then we call -methods on them to plot data, add axis labels and a figure title. +- **Axes interface**: create a `.Figure` and one or more `~.axes.Axes` objects + (typically using `.pyplot.subplots`), then *explicitly* use methods on these objects + to add data, configure limits, set labels etc. +- **pyplot interface**: consists of functions in the `.pyplot` module. Figure and Axes + are manipulated through these functions and are only *implicitly* present in the + background. -.. plot:: - :include-source: - :align: center +See :ref:`api_interfaces` for a more detailed description of both and their recommended +use cases. - import matplotlib.pyplot as plt - import numpy as np +.. grid:: 1 1 2 2 + :padding: 0 0 1 1 - x = np.arange(0, 4, 0.05) - y = np.sin(x*np.pi) + .. grid-item-card:: - fig, ax = plt.subplots(figsize=(3,2), constrained_layout=True) - ax.plot(x, y) - ax.set_xlabel('t [s]') - ax.set_ylabel('S [V]') - ax.set_title('Sine wave') - fig.set_facecolor('lightsteelblue') + **Axes interface** (object-based, explicit) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + API: + - `~.pyplot.subplots`: create Figure and Axes + - :mod:`~matplotlib.axes`: add data, limits, labels etc. + - `.Figure`: for figure-level methods -.. _usage_patterns: + .. grid-item-card:: -Usage patterns --------------- + **pyplot interface** (function-based, implicit) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Below we describe several common approaches to plotting with Matplotlib. See -:ref:`api_interfaces` for an explanation of the trade-offs between the supported user -APIs. + API: + - `matplotlib.pyplot` -The explicit API -^^^^^^^^^^^^^^^^ - -At its core, Matplotlib is an object-oriented library. We recommend directly -working with the objects if you need more control and customization of your -plots. - -In many cases you will create a `.Figure` and one or more -`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work -on these objects. However, it's also possible to create `.Figure`\ s -explicitly (e.g. when including them in GUI applications). - -Further reading: - -- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of - plotting functions. -- Most of the :ref:`examples ` use the object-oriented approach - (except for the pyplot section) - - -The implicit API -^^^^^^^^^^^^^^^^ - -`matplotlib.pyplot` is a collection of functions that make -Matplotlib work like MATLAB. Each pyplot function makes some change to a -figure: e.g., creates a figure, creates a plotting area in a figure, plots -some lines in a plotting area, decorates the plot with labels, etc. - -`.pyplot` is mainly intended for interactive plots and simple cases of -programmatic plot generation. - -Further reading: - -- The `matplotlib.pyplot` function reference -- :ref:`pyplot_tutorial` -- :ref:`Pyplot examples ` .. _api-index: diff --git a/lib/matplotlib/pylab.py b/lib/matplotlib/pylab.py index a5b9abebffe9..684021b2e977 100644 --- a/lib/matplotlib/pylab.py +++ b/lib/matplotlib/pylab.py @@ -1,6 +1,6 @@ """ `pylab` is a historic interface and its use is strongly discouraged. The equivalent -replacement is `matplotlib.pyplot`. See :ref:` api_interfaces` for a full overview +replacement is `matplotlib.pyplot`. See :ref:`api_interfaces` for a full overview of Matplotlib interfaces. `pylab` was designed to support a MATLAB-like way of working with all plotting related @@ -14,7 +14,7 @@ `numpy.fft`, `numpy.linalg`, and `numpy.random`, and some additional functions into the global namespace. - Such a pattern is nowadays considered bad practice, as it clutters the global + Such a pattern is considered bad practice in modern python, as it clutters the global namespace. Even more severely, in the case of `pylab`, this will overwrite some builtin functions (e.g. the builtin `sum` will be replaced by `numpy.sum`), which can lead to unexpected behavior.