Merge pull request matplotlib#27105 from timhoffm/doc-axes-core

Use Axes instead of axes core library code

Author: dstansby

lib/matplotlib/_constrained_layout.py

@@ -1,11 +1,11 @@
 """
-Adjust subplot layouts so that there are no overlapping axes or axes
-decorations.  All axes decorations are dealt with (labels, ticks, titles,
+Adjust subplot layouts so that there are no overlapping Axes or Axes
+decorations.  All Axes decorations are dealt with (labels, ticks, titles,
 ticklabels) and some dependent artists are also dealt with (colorbar,
 suptitle).
 
 Layout is done via `~matplotlib.gridspec`, with one constraint per gridspec,
-so it is possible to have overlapping axes if the gridspecs overlap (i.e.
+so it is possible to have overlapping Axes if the gridspecs overlap (i.e.
 using `~matplotlib.gridspec.GridSpecFromSubplotSpec`).  Axes placed using
 ``figure.subplots()`` or ``figure.add_subplots()`` will participate in the
 layout.  Axes manually placed via ``figure.add_axes()`` will not.
@@ -33,8 +33,8 @@
 is the width or height of each column/row minus the size of the margins.
 
 Then the size of the margins for each row and column are determined as the
-max width of the decorators on each axes that has decorators in that margin.
-For instance, a normal axes would have a left margin that includes the
+max width of the decorators on each Axes that has decorators in that margin.
+For instance, a normal Axes would have a left margin that includes the
 left ticklabels, and the ylabel if it exists.  The right margin may include a
 colorbar, the bottom margin the xaxis decorations, and the top margin the
 title.
@@ -73,11 +73,11 @@ def do_constrained_layout(fig, h_pad, w_pad,
         `.Figure` instance to do the layout in.
 
     h_pad, w_pad : float
-      Padding around the axes elements in figure-normalized units.
+      Padding around the Axes elements in figure-normalized units.
 
     hspace, wspace : float
        Fraction of the figure to dedicate to space between the
-       axes.  These are evenly spread between the gaps between the axes.
+       Axes.  These are evenly spread between the gaps between the Axes.
        A value of 0.2 for a three-column layout would have a space
        of 0.1 of the figure width between each column.
        If h/wspace < h/w_pad, then the pads are used instead.
@@ -111,7 +111,7 @@ def do_constrained_layout(fig, h_pad, w_pad,
         # larger/smaller).  This second reposition tends to be much milder,
         # so doing twice makes things work OK.
 
-        # make margins for all the axes and subfigures in the
+        # make margins for all the Axes and subfigures in the
         # figure.  Add margins for colorbars...
         make_layout_margins(layoutgrids, fig, renderer, h_pad=h_pad,
                             w_pad=w_pad, hspace=hspace, wspace=wspace)
@@ -128,7 +128,7 @@ def do_constrained_layout(fig, h_pad, w_pad,
 
         warn_collapsed = ('constrained_layout not applied because '
                           'axes sizes collapsed to zero.  Try making '
-                          'figure larger or axes decorations smaller.')
+                          'figure larger or Axes decorations smaller.')
         if check_no_collapsed_axes(layoutgrids, fig):
             reposition_axes(layoutgrids, fig, renderer, h_pad=h_pad,
                             w_pad=w_pad, hspace=hspace, wspace=wspace)
@@ -152,7 +152,7 @@ def make_layoutgrids(fig, layoutgrids, rect=(0, 0, 1, 1)):
 
     (Sub)Figures get a layoutgrid so we can have figure margins.
 
-    Gridspecs that are attached to axes get a layoutgrid so axes
+    Gridspecs that are attached to Axes get a layoutgrid so Axes
     can have margins.
     """
 
@@ -182,7 +182,7 @@ def make_layoutgrids(fig, layoutgrids, rect=(0, 0, 1, 1)):
     for sfig in fig.subfigs:
         layoutgrids = make_layoutgrids(sfig, layoutgrids)
 
-    # for each axes at the local level add its gridspec:
+    # for each Axes at the local level add its gridspec:
     for ax in fig._localaxes:
         gs = ax.get_gridspec()
         if gs is not None:
@@ -239,7 +239,7 @@ def make_layoutgrids_gs(layoutgrids, gs):
 
 def check_no_collapsed_axes(layoutgrids, fig):
     """
-    Check that no axes have collapsed to zero size.
+    Check that no Axes have collapsed to zero size.
     """
     for sfig in fig.subfigs:
         ok = check_no_collapsed_axes(layoutgrids, sfig)
@@ -270,7 +270,7 @@ def compress_fixed_aspect(layoutgrids, fig):
             extraw = np.zeros(gs.ncols)
             extrah = np.zeros(gs.nrows)
         elif _gs != gs:
-            raise ValueError('Cannot do compressed layout if axes are not'
+            raise ValueError('Cannot do compressed layout if Axes are not'
                              'all from the same gridspec')
         orig = ax.get_position(original=True)
         actual = ax.get_position(original=False)
@@ -282,7 +282,7 @@ def compress_fixed_aspect(layoutgrids, fig):
             extrah[sub.rowspan] = np.maximum(extrah[sub.rowspan], dh)
 
     if gs is None:
-        raise ValueError('Cannot do compressed layout if no axes '
+        raise ValueError('Cannot do compressed layout if no Axes '
                          'are part of a gridspec.')
     w = np.sum(extraw) / 2
     layoutgrids[fig].edit_margin_min('left', w)
@@ -313,7 +313,7 @@ def get_margin_from_padding(obj, *, w_pad=0, h_pad=0,
     nrows, ncols = gs.get_geometry()
     # there are two margins for each direction.  The "cb"
     # margins are for pads and colorbars, the non-"cb" are
-    # for the axes decorations (labels etc).
+    # for the Axes decorations (labels etc).
     margin = {'leftcb': w_pad, 'rightcb': w_pad,
               'bottomcb': h_pad, 'topcb': h_pad,
               'left': 0, 'right': 0,
@@ -335,7 +335,7 @@ def get_margin_from_padding(obj, *, w_pad=0, h_pad=0,
 def make_layout_margins(layoutgrids, fig, renderer, *, w_pad=0, h_pad=0,
                         hspace=0, wspace=0):
     """
-    For each axes, make a margin between the *pos* layoutbox and the
+    For each Axes, make a margin between the *pos* layoutbox and the
     *axes* layoutbox be a minimum size that can accommodate the
     decorations on the axis.
 
@@ -379,7 +379,7 @@ def make_layout_margins(layoutgrids, fig, renderer, *, w_pad=0, h_pad=0,
         margin = get_margin_from_padding(ax, w_pad=w_pad, h_pad=h_pad,
                                          hspace=hspace, wspace=wspace)
         pos, bbox = get_pos_and_bbox(ax, renderer)
-        # the margin is the distance between the bounding box of the axes
+        # the margin is the distance between the bounding box of the Axes
         # and its position (plus the padding from above)
         margin['left'] += pos.x0 - bbox.x0
         margin['right'] += bbox.x1 - pos.x1
@@ -388,7 +388,7 @@ def make_layout_margins(layoutgrids, fig, renderer, *, w_pad=0, h_pad=0,
         margin['top'] += bbox.y1 - pos.y1
 
         # make margin for colorbars.  These margins go in the
-        # padding margin, versus the margin for axes decorators.
+        # padding margin, versus the margin for Axes decorators.
         for cbax in ax._colorbars:
             # note pad is a fraction of the parent width...
             pad = colorbar_get_pad(layoutgrids, cbax)
@@ -493,14 +493,14 @@ def match_submerged_margins(layoutgrids, fig):
     """
     Make the margins that are submerged inside an Axes the same size.
 
-    This allows axes that span two columns (or rows) that are offset
+    This allows Axes that span two columns (or rows) that are offset
     from one another to have the same size.
 
     This gives the proper layout for something like::
         fig = plt.figure(constrained_layout=True)
         axs = fig.subplot_mosaic("AAAB\nCCDD")
 
-    Without this routine, the axes D will be wider than C, because the
+    Without this routine, the Axes D will be wider than C, because the
     margin width between the two columns in C has no width by default,
     whereas the margins between the two columns of D are set by the
     width of the margin between A and B. However, obviously the user would
@@ -613,7 +613,7 @@ def get_cb_parent_spans(cbax):
 
 def get_pos_and_bbox(ax, renderer):
     """
-    Get the position and the bbox for the axes.
+    Get the position and the bbox for the Axes.
 
     Parameters
     ----------
@@ -642,7 +642,7 @@ def get_pos_and_bbox(ax, renderer):
 def reposition_axes(layoutgrids, fig, renderer, *,
                     w_pad=0, h_pad=0, hspace=0, wspace=0):
     """
-    Reposition all the axes based on the new inner bounding box.
+    Reposition all the Axes based on the new inner bounding box.
     """
     trans_fig_to_subfig = fig.transFigure - fig.transSubfigure
     for sfig in fig.subfigs:

lib/matplotlib/_layoutgrid.py

@@ -5,8 +5,8 @@
 
 Each box is defined by left[ncols], right[ncols], bottom[nrows] and top[nrows],
 and by two editable margins for each side.  The main margin gets its value
-set by the size of ticklabels, titles, etc on each axes that is in the figure.
-The outer margin is the padding around the axes, and space for any
+set by the size of ticklabels, titles, etc on each Axes that is in the figure.
+The outer margin is the padding around the Axes, and space for any
 colorbars.
 
 The "inner" widths and heights of these boxes are then constrained to be the

lib/matplotlib/_tight_layout.py

@@ -1,7 +1,7 @@
 """
 Routines to adjust subplot params so that subplots are
-nicely fit in the figure. In doing so, only axis labels, tick labels, axes
-titles and offsetboxes that are anchored to axes are currently considered.
+nicely fit in the figure. In doing so, only axis labels, tick labels, Axes
+titles and offsetboxes that are anchored to Axes are currently considered.
 
 Internally, this module assumes that the margins (left margin, etc.) which are
 differences between ``Axes.get_tightbbox`` and ``Axes.bbox`` are independent of
@@ -22,7 +22,7 @@ def _auto_adjust_subplotpars(
         ax_bbox_list=None, pad=1.08, h_pad=None, w_pad=None, rect=None):
     """
     Return a dict of subplot parameters to adjust spacing between subplots
-    or ``None`` if resulting axes would have zero height or width.
+    or ``None`` if resulting Axes would have zero height or width.
 
     Note that this function ignores geometry information of subplot itself, but
     uses what is given by the *shape* and *subplot_list* parameters.  Also, the
@@ -91,7 +91,7 @@ def _auto_adjust_subplotpars(
 
     fig_width_inch, fig_height_inch = fig.get_size_inches()
 
-    # margins can be negative for axes with aspect applied, so use max(, 0) to
+    # margins can be negative for Axes with aspect applied, so use max(, 0) to
     # make them nonnegative.
     if not margin_left:
         margin_left = max(hspaces[:, 0].max(), 0) + pad_inch/fig_width_inch
@@ -119,12 +119,12 @@ def _auto_adjust_subplotpars(
     if margin_left + margin_right >= 1:
         _api.warn_external('Tight layout not applied. The left and right '
                            'margins cannot be made large enough to '
-                           'accommodate all axes decorations.')
+                           'accommodate all Axes decorations.')
         return None
     if margin_bottom + margin_top >= 1:
         _api.warn_external('Tight layout not applied. The bottom and top '
                            'margins cannot be made large enough to '
-                           'accommodate all axes decorations.')
+                           'accommodate all Axes decorations.')
         return None
 
     kwargs = dict(left=margin_left,
@@ -138,8 +138,8 @@ def _auto_adjust_subplotpars(
         h_axes = (1 - margin_right - margin_left - hspace * (cols - 1)) / cols
         if h_axes < 0:
             _api.warn_external('Tight layout not applied. tight_layout '
-                               'cannot make axes width small enough to '
-                               'accommodate all axes decorations')
+                               'cannot make Axes width small enough to '
+                               'accommodate all Axes decorations')
             return None
         else:
             kwargs["wspace"] = hspace / h_axes
@@ -148,8 +148,8 @@ def _auto_adjust_subplotpars(
         v_axes = (1 - margin_top - margin_bottom - vspace * (rows - 1)) / rows
         if v_axes < 0:
             _api.warn_external('Tight layout not applied. tight_layout '
-                               'cannot make axes height small enough to '
-                               'accommodate all axes decorations.')
+                               'cannot make Axes height small enough to '
+                               'accommodate all Axes decorations.')
             return None
         else:
             kwargs["hspace"] = vspace / v_axes
@@ -159,9 +159,9 @@ def _auto_adjust_subplotpars(
 
 def get_subplotspec_list(axes_list, grid_spec=None):
     """
-    Return a list of subplotspec from the given list of axes.
+    Return a list of subplotspec from the given list of Axes.
 
-    For an instance of axes that does not support subplotspec, None is inserted
+    For an instance of Axes that does not support subplotspec, None is inserted
     in the list.
 
     If grid_spec is given, None is inserted for those not from the given
@@ -201,7 +201,7 @@ def get_tight_layout_figure(fig, axes_list, subplotspec_list, renderer,
     fig : Figure
     axes_list : list of Axes
     subplotspec_list : list of `.SubplotSpec`
-        The subplotspecs of each axes.
+        The subplotspecs of each Axes.
     renderer : renderer
     pad : float
         Padding between the figure edge and the edges of subplots, as a
@@ -221,7 +221,7 @@ def get_tight_layout_figure(fig, axes_list, subplotspec_list, renderer,
         None if tight_layout could not be accomplished.
     """
 
-    # Multiple axes can share same subplotspec (e.g., if using axes_grid1);
+    # Multiple Axes can share same subplotspec (e.g., if using axes_grid1);
     # we need to group them together.
     ss_to_subplots = {ss: [] for ss in subplotspec_list}
     for ax, ss in zip(axes_list, subplotspec_list):
@@ -240,7 +240,7 @@ def get_tight_layout_figure(fig, axes_list, subplotspec_list, renderer,
 
     span_pairs = []
     for ss in ss_to_subplots:
-        # The intent here is to support axes from different gridspecs where
+        # The intent here is to support Axes from different gridspecs where
         # one's nrows (or ncols) is a multiple of the other (e.g. 2 and 4),
         # but this doesn't actually work because the computed wspace, in
         # relative-axes-height, corresponds to different physical spacings for

lib/matplotlib/animation.py

@@ -1171,7 +1171,7 @@ def _blit_draw(self, artists):
         # of the entire figure.
         updated_ax = {a.axes for a in artists}
         # Enumerate artists to cache Axes backgrounds. We do not draw
-        # artists yet to not cache foreground from plots with shared axes
+        # artists yet to not cache foreground from plots with shared Axes
         for ax in updated_ax:
             # If we haven't cached the background for the current view of this
             # Axes object, do so now. This might not always be reliable, but

lib/matplotlib/artist.py

@@ -224,10 +224,10 @@ def remove(self):
 
         The effect will not be visible until the figure is redrawn, e.g.,
         with `.FigureCanvasBase.draw_idle`.  Call `~.axes.Axes.relim` to
-        update the axes limits if desired.
+        update the Axes limits if desired.
 
         Note: `~.axes.Axes.relim` will not see collections even if the
-        collection was added to the axes with *autolim* = True.
+        collection was added to the Axes with *autolim* = True.
 
         Note: there is no support for removing the artist's legend entry.
         """
@@ -299,7 +299,7 @@ def axes(self):
     def axes(self, new_axes):
         if (new_axes is not None and self._axes is not None
                 and new_axes != self._axes):
-            raise ValueError("Can not reset the axes.  You are probably "
+            raise ValueError("Can not reset the Axes.  You are probably "
                              "trying to re-use an artist in more than one "
                              "Axes which is not supported")
         self._axes = new_axes
@@ -340,7 +340,7 @@ def get_window_extent(self, renderer=None):
         Be careful when using this function, the results will not update
         if the artist window extent of the artist changes.  The extent
         can change due to any changes in the transform stack, such as
-        changing the axes limits, the figure size, or the canvas used
+        changing the Axes limits, the figure size, or the canvas used
         (as is done when saving a figure).  This can lead to unexpected
         behavior where interactive figures will look fine on the screen,
         but will save incorrectly.

lib/matplotlib/axes/_axes.py

@@ -460,8 +460,8 @@ def indicate_inset(self, bounds, inset_ax=None, *, transform=None,
             visibility to True if the automatic choice is not deemed correct.
 
         """
-        # to make the axes connectors work, we need to apply the aspect to
-        # the parent axes.
+        # to make the Axes connectors work, we need to apply the aspect to
+        # the parent Axes.
         self.apply_aspect()
 
         if transform is None:
@@ -5782,7 +5782,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
         im.set_data(X)
         im.set_alpha(alpha)
         if im.get_clip_path() is None:
-            # image does not already have clipping set, clip to axes patch
+            # image does not already have clipping set, clip to Axes patch
             im.set_clip_path(self.patch)
         im._scale_norm(norm, vmin, vmax)
         im.set_url(url)
@@ -6519,7 +6519,7 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
             ret._scale_norm(norm, vmin, vmax)
 
         if ret.get_clip_path() is None:
-            # image does not already have clipping set, clip to axes patch
+            # image does not already have clipping set, clip to Axes patch
             ret.set_clip_path(self.patch)
 
         ret.sticky_edges.x[:] = [xl, xr]
@@ -8471,7 +8471,7 @@ def violin(self, vpstats, positions=None, vert=True, widths=0.5,
 
     def _get_aspect_ratio(self):
         """
-        Convenience method to calculate the aspect ratio of the axes in
+        Convenience method to calculate the aspect ratio of the Axes in
         the display coordinate system.
         """
         figure_size = self.get_figure().get_size_inches()