matplotlib · tacaswell · Jun 10, 2019 · Jun 9, 2019
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -603,7 +603,7 @@ def get_cachedir():
 
 
 def _get_data_path():
-    'get the path to matplotlib data'
+    """Return the path to matplotlib data."""
 
     if 'MATPLOTLIBDATA' in os.environ:
         path = os.environ['MATPLOTLIBDATA']

diff --git a/lib/matplotlib/_constrained_layout.py b/lib/matplotlib/_constrained_layout.py
@@ -66,10 +66,7 @@ def _in_same_row(rownum0min, rownum0max, rownumCmin, rownumCmax):
 
 
 def _axes_all_finite_sized(fig):
-    """
-    helper function to make sure all axes in the
-    figure have a finite width and height.  If not, return False
-    """
+    """Return whether all axes in the figure have a finite width and height."""
     for ax in fig.axes:
         if ax._layoutbox is not None:
             newpos = ax._poslayoutbox.get_rect()
@@ -471,10 +468,7 @@ def _align_spines(fig, gs):
 
 
 def _arrange_subplotspecs(gs, hspace=0, wspace=0):
-    """
-    arrange the subplotspec children of this gridspec, and then recursively
-    do the same of any gridspec children of those gridspecs...
-    """
+    """Recursively arrange the subplotspec children of the given gridspec."""
     sschildren = []
     for child in gs.children:
         if child._is_subplotspec_layoutbox():

diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -326,7 +326,9 @@ def _set_artist_props(self, a):
         a.set_figure(self.figure)
 
     def get_view_interval(self):
-        'return the view Interval instance for the axis this tick is ticking'
+        """
+        Return the view limits ``(min, max)`` of the axis the tick belongs to.
+        """
         raise NotImplementedError('Derived must override')
 
     def _apply_params(self, **kw):
@@ -624,7 +626,7 @@ def update_position(self, loc):
         self.stale = True
 
     def get_view_interval(self):
-        """Return the Interval instance for this axis view limits."""
+        # docstring inherited
         return self.axes.viewLim.intervaly
 
 
@@ -839,7 +841,7 @@ def get_children(self):
                 *self.get_major_ticks(), *self.get_minor_ticks()]
 
     def cla(self):
-        'clear the current axis'
+        """Clear this axis."""
 
         self.label.set_text('')  # self.set_label_text would change isDefault_
 
@@ -971,7 +973,7 @@ def set_clip_path(self, clippath, transform=None):
         self.stale = True
 
     def get_view_interval(self):
-        """Return the Interval instance for this axis view limits."""
+        """Return the view limits ``(min, max)`` of this axis."""
         raise NotImplementedError('Derived must override')
 
     def set_view_interval(self, vmin, vmax, ignore=False):
@@ -1391,11 +1393,11 @@ def get_ticks_direction(self, minor=False):
                 [tick._tickdir for tick in self.get_major_ticks()])
 
     def _get_tick(self, major):
-        'return the default tick instance'
+        """Return the default tick instance."""
         raise NotImplementedError('derived must override')
 
     def _copy_tick_props(self, src, dest):
-        'Copy the props from src tick to dest tick'
+        """Copy the properties from *src* tick to *dest* tick."""
         if src is None or dest is None:
             return
         dest.label1.update_from(src.label1)
@@ -1502,11 +1504,10 @@ def grid(self, b=None, which='major', **kwargs):
 
     def update_units(self, data):
         """
-        introspect *data* for units converter and update the
+        Introspect *data* for units converter and update the
         axis.converter instance if necessary. Return *True*
         if *data* is registered for unit conversion.
         """
-
         converter = munits.registry.get_converter(data)
         if converter is None:
             return False
@@ -1524,8 +1525,8 @@ def update_units(self, data):
 
     def _update_axisinfo(self):
         """
-        check the axis converter for the stored units to see if the
-        axis info needs to be updated
+        Check the axis converter for the stored units to see if the
+        axis info needs to be updated.
         """
         if self.converter is None:
             return

diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
@@ -340,16 +340,12 @@ def set_clim(self, vmin=None, vmax=None):
 
     @cbook.deprecated("3.1", alternative="ScalarMappable.get_cmap")
     def get_cmap(self):
-        """
-        return the colormap
-        """
+        """Return the colormap."""
         return self.cmap
 
     @cbook.deprecated("3.1", alternative="ScalarMappable.get_clim")
     def get_clim(self):
-        """
-        return the min, max of the color limits for image scaling
-        """
+        """Return the min, max of the color limits for image scaling."""
         return self.norm.vmin, self.norm.vmax
 
 

diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -1352,7 +1352,7 @@ def set_axis(self, axis):
         self._locator.set_axis(axis)
 
     def refresh(self):
-        'Refresh internal information based on current limits.'
+        # docstring inherited
         dmin, dmax = self.viewlim_to_dt()
         self._locator = self.get_locator(dmin, dmax)
 

diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -537,10 +537,9 @@ def make_image(self, renderer, magnification=1.0, unsampled=False):
 
     def _draw_unsampled_image(self, renderer, gc):
         """
-        draw unsampled image. The renderer should support a draw_image method
+        Draw unsampled image. The renderer should support a draw_image method
         with scale parameter.
         """
-
         im, l, b, trans = self.make_image(renderer, unsampled=True)
 
         if im is None:
@@ -552,7 +551,8 @@ def _draw_unsampled_image(self, renderer, gc):
 
     def _check_unsampled_image(self, renderer):
         """
-        return True if the image is better to be drawn unsampled.
+        Return whether the image is better to be drawn unsampled.
+
         The derived class needs to override it.
         """
         return False
@@ -852,12 +852,20 @@ def _check_unsampled_image(self, renderer):
 
     def set_extent(self, extent):
         """
-        extent is data axes (left, right, bottom, top) for making image plots
+        Set the image extent.
 
-        This updates ax.dataLim, and, if autoscaling, sets viewLim
-        to tightly fit the image, regardless of dataLim.  Autoscaling
+        Parameters
+        ----------
+        extent : 4-tuple of float
+            The position and size of the image as tuple
+            ``(left, right, bottom, top)`` in data coordinates.
+
+        Notes
+        -----
+        This updates ``ax.dataLim`, and, if autoscaling, sets ``ax.viewLim``
+        to tightly fit the image, regardless of ``dataLim``.  Autoscaling
         state is not changed, so following this with ax.autoscale_view
-        will redo the autoscaling in accord with dataLim.
+        will redo the autoscaling in accord with ``dataLim``.
         """
         self._extent = xmin, xmax, ymin, ymax = extent
         corners = (xmin, ymin), (xmax, ymax)
@@ -871,7 +879,7 @@ def set_extent(self, extent):
         self.stale = True
 
     def get_extent(self):
-        """Get the image extent: left, right, bottom, top"""
+        """Return the image extent as tuple (left, right, bottom, top)."""
         if self._extent is not None:
             return self._extent
         else:
@@ -923,17 +931,18 @@ def format_cursor_data(self, data):
 class NonUniformImage(AxesImage):
     def __init__(self, ax, *, interpolation='nearest', **kwargs):
         """
-        kwargs are identical to those for AxesImage, except
-        that 'nearest' and 'bilinear' are the only supported 'interpolation'
-        options.
+        Parameters
+        ----------
+        interpolation : {'nearest', 'bilinear'}
+
+        **kwargs
+            All other keyword arguments are identical to those of `.AxesImage`.
         """
         super().__init__(ax, **kwargs)
         self.set_interpolation(interpolation)
 
     def _check_unsampled_image(self, renderer):
-        """
-        return False. Do not use unsampled image.
-        """
+        """Return False. Do not use unsampled image."""
         return False
 
     def make_image(self, renderer, magnification=1.0, unsampled=False):
@@ -1204,7 +1213,7 @@ def __init__(self, fig,
         self.magnification = 1.0
 
     def get_extent(self):
-        """Get the image extent: left, right, bottom, top"""
+        """Return the image extent as tuple (left, right, bottom, top)."""
         numrows, numcols = self.get_size()
         return (-0.5 + self.ox, numcols-0.5 + self.ox,
                 -0.5 + self.oy, numrows-0.5 + self.oy)

diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py
@@ -405,7 +405,7 @@ def set_fill(self, b):
         self.stale = True
 
     def get_fill(self):
-        'return whether fill is set'
+        """Return whether the patch is filled."""
         return self._fill
 
     # Make fill a property so as to preserve the long-standing
@@ -1797,9 +1797,7 @@ class _Style:
     provides some helper functions.
     """
     def __new__(cls, stylename, **kw):
-        """
-        return the instance of the subclass with the given style name.
-        """
+        """Return the instance of the subclass with the given style name."""
 
         # The "class" should have the _style_list attribute, which is a mapping
         # of style names to style classes.
@@ -3025,8 +3023,8 @@ def connect(self, posA, posB):
 
 def _point_along_a_line(x0, y0, x1, y1, d):
     """
-    find a point along a line connecting (x0, y0) -- (x1, y1) whose
-    distance from (x0, y0) is d.
+    Return the point on the line connecting (*x0*, *y0*) -- (*x1*, *y1*) whose
+    distance from (*x0*, *y0*) is *d*.
     """
     dx, dy = x0 - x1, y0 - y1
     ff = d / (dx * dx + dy * dy) ** .5
@@ -4321,10 +4319,7 @@ def __init__(self, xyA, xyB, coordsA, coordsB=None,
         self._annotation_clip = None
 
     def _get_xy(self, x, y, s, axes=None):
-        """
-        calculate the pixel position of given point
-        """
-
+        """Calculate the pixel position of given point."""
         if axes is None:
             axes = self.axes
 
@@ -4418,7 +4413,7 @@ def _get_xy(self, x, y, s, axes=None):
                 y = b + y
             return x, y
         elif s == 'axes fraction':
-            #(0,0) is lower left, (1,1) is upper right of axes
+            # (0,0) is lower left, (1,1) is upper right of axes
             trans = axes.transAxes
             return trans.transform_point((x, y))
         elif isinstance(s, transforms.Transform):
@@ -4429,28 +4424,32 @@ def _get_xy(self, x, y, s, axes=None):
 
     def set_annotation_clip(self, b):
         """
-        set *annotation_clip* attribute.
+        Set the clipping behavior.
+
+        Parameters
+        ----------
+        b : bool or None
 
-          * True: the annotation will only be drawn when self.xy is inside the
-                   axes.
-          * False: the annotation will always be drawn regardless of its
-                    position.
-          * None: the self.xy will be checked only if *xycoords* is "data"
+            - *False*: The annotation will always be drawn regardless of its
+              position.
+            - *True*: The annotation will only be drawn if ``self.xy`` is
+              inside the axes.
+            - *None*: The annotation will only be drawn if ``self.xy`` is
+              inside the axes and  ``self.xycoords == "data"``.
         """
         self._annotation_clip = b
         self.stale = True
 
     def get_annotation_clip(self):
         """
-        Return *annotation_clip* attribute.
-        See :meth:`set_annotation_clip` for the meaning of return values.
+        Return the clipping behavior.
+
+        See `.set_annotation_clip` for the meaning of the return value.
         """
         return self._annotation_clip
 
     def get_path_in_displaycoord(self):
-        """
-        Return the mutated path of the arrow in the display coord
-        """
+        """Return the mutated path of the arrow in display coordinates."""
 
         dpi_cor = self.get_dpi_cor()
 

diff --git a/lib/matplotlib/patheffects.py b/lib/matplotlib/patheffects.py
@@ -185,7 +185,7 @@ def __init__(self, offset=(0, 0), **kwargs):
 
     def draw_path(self, renderer, gc, tpath, affine, rgbFace):
         """
-        draw the path with updated gc.
+        Draw the path with updated gc.
         """
         # Do not modify the input! Use copy instead.
 

diff --git a/lib/matplotlib/projections/polar.py b/lib/matplotlib/projections/polar.py
@@ -236,6 +236,7 @@ def pan(self, numsteps):
         return self.base.pan(numsteps)
 
     def refresh(self):
+        # docstring inherited
         return self.base.refresh()
 
     def view_limits(self, vmin, vmax):
@@ -427,6 +428,7 @@ def zoom(self, direction):
         return self.base.zoom(direction)
 
     def refresh(self):
+        # docstring inherited
         return self.base.refresh()
 
     def view_limits(self, vmin, vmax):