Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Restructure interface section of API Reference index page #26402

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

Merged
merged 1 commit into from
Aug 8, 2023
Merged

Restructure interface section of API Reference index page #26402

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
88 changes: 25 additions & 63 deletions doc/api/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,82 +1,44 @@
API Reference
=============

When using the library you will typically create
:doc:`Figure <figure_api>` and :doc:`Axes <axes_api>` 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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
API:

looking in the rendered docs, it totally doesn't need it.


- `~.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 <examples-index>` 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 <pyplots_examples>`

.. _api-index:

Expand Down
4 changes: 2 additions & 2 deletions lib/matplotlib/pylab.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
Expand Down