Merge pull request #10093 from anntzer/more-docstring-fixes

jklymak · web-flow · commit 37978a8a7015 · 2018-01-02T12:10:03.000-08:00
Some docstring fixes and change a raise type
diff --git a/doc/api/api_changes/2017-12-26-AL.rst b/doc/api/api_changes/2017-12-26-AL.rst
@@ -0,0 +1,2 @@
+`~.tight_layout.auto_adjust_subplotpars` now raises `ValueError` instead of `RuntimeError` when sizes of input lists don't match
+````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````
diff --git a/lib/matplotlib/tests/test_skew.py b/lib/matplotlib/tests/test_skew.py
@@ -188,7 +188,7 @@ def test_set_line_coll_dash_image():
 
 
 @image_comparison(baseline_images=['skew_rects'], remove_text=True)
-def test_skew_rectange():
+def test_skew_rectangle():
 
     fix, axes = plt.subplots(5, 5, sharex=True, sharey=True, figsize=(16, 12))
     axes = axes.flat
diff --git a/lib/matplotlib/tight_layout.py b/lib/matplotlib/tight_layout.py
@@ -34,77 +34,62 @@ def _get_top(tight_bbox, axes_bbox):
     return tight_bbox.ymax - axes_bbox.ymax
 
 
-def auto_adjust_subplotpars(fig, renderer,
-                            nrows_ncols,
-                            num1num2_list,
-                            subplot_list,
-                            ax_bbox_list=None,
-                            pad=1.08, h_pad=None, w_pad=None,
-                            rect=None):
+def auto_adjust_subplotpars(
+        fig, renderer, nrows_ncols, num1num2_list, subplot_list,
+        ax_bbox_list=None, pad=1.08, h_pad=None, w_pad=None, rect=None):
     """
-    Return a dictionary of subplot parameters so that spacing between
-    subplots are adjusted. Note that this function ignore geometry
-    information of subplot itself, but uses what is given by
-    *nrows_ncols* and *num1num2_list* parameteres. Also, the results could be
-    incorrect if some subplots have ``adjustable=datalim``.
-
-    Parameters:
-
-    nrows_ncols
-      number of rows and number of columns of the grid.
-
-    num1num2_list
-      list of numbers specifying the area occupied by the subplot
-
-    subplot_list
-      list of subplots that will be used to calcuate optimal subplot_params.
-
+    Return a dict of subplot parameters to adjust spacing between subplots.
+
+    Note that this function ignores geometry information of subplot
+    itself, but uses what is given by the *nrows_ncols* and *num1num2_list*
+    parameters.  Also, the results could be incorrect if some subplots have
+    ``adjustable=datalim``.
+
+    Parameters
+    ----------
+    nrows_ncols : Tuple[int, int]
+        Number of rows and number of columns of the grid.
+    num1num2_list : List[int]
+        List of numbers specifying the area occupied by the subplot
+    subplot_list : list of subplots
+        List of subplots that will be used to calculate optimal subplot_params.
     pad : float
-      padding between the figure edge and the edges of subplots, as a fraction
-      of the font-size.
+        Padding between the figure edge and the edges of subplots, as a
+        fraction of the font size.
     h_pad, w_pad : float
-      padding (height/width) between edges of adjacent subplots.
-        Defaults to `pad_inches`.
-
-    rect
-      [left, bottom, right, top] in normalized (0, 1) figure coordinates.
+        Padding (height/width) between edges of adjacent subplots, as a
+        fraction of the font size.  Defaults to *pad*.
+    rect : Tuple[float, float, float, float]
+        [left, bottom, right, top] in normalized (0, 1) figure coordinates.
     """
     rows, cols = nrows_ncols
 
-    pad_inches = pad * FontProperties(
-                    size=rcParams["font.size"]).get_size_in_points() / 72.
-
+    font_size_inches = (
+        FontProperties(size=rcParams["font.size"]).get_size_in_points() / 72)
+    pad_inches = pad * font_size_inches
     if h_pad is not None:
-        vpad_inches = h_pad * FontProperties(
-                        size=rcParams["font.size"]).get_size_in_points() / 72.
+        vpad_inches = h_pad * font_size_inches
     else:
         vpad_inches = pad_inches
 
     if w_pad is not None:
-        hpad_inches = w_pad * FontProperties(
-                        size=rcParams["font.size"]).get_size_in_points() / 72.
+        hpad_inches = w_pad * font_size_inches
     else:
         hpad_inches = pad_inches
 
-    if len(subplot_list) == 0:
-        raise RuntimeError("")
-
-    if len(num1num2_list) != len(subplot_list):
-        raise RuntimeError("")
+    if len(num1num2_list) != len(subplot_list) or len(subplot_list) == 0:
+        raise ValueError
 
     if rect is None:
-        margin_left = None
-        margin_bottom = None
-        margin_right = None
-        margin_top = None
+        margin_left = margin_bottom = margin_right = margin_top = None
     else:
         margin_left, margin_bottom, _right, _top = rect
         if _right:
-            margin_right = 1. - _right
+            margin_right = 1 - _right
         else:
             margin_right = None
         if _top:
-            margin_top = 1. - _top
+            margin_top = 1 - _top
         else:
             margin_top = None
 
@@ -262,42 +247,34 @@ def get_subplotspec_list(axes_list, grid_spec=None):
 def get_tight_layout_figure(fig, axes_list, subplotspec_list, renderer,
                             pad=1.08, h_pad=None, w_pad=None, rect=None):
     """
-    Return subplot parameters for tight-layouted-figure with specified
-    padding.
-
-    Parameters:
-
-      *fig* : figure instance
-
-      *axes_list* : a list of axes
-
-      *subplotspec_list* : a list of subplotspec associated with each
-        axes in axes_list
-
-      *renderer* : renderer instance
-
-      *pad* : float
-        padding between the figure edge and the edges of subplots,
-        as a fraction of the font-size.
-
-      *h_pad*, *w_pad* : float
-        padding (height/width) between edges of adjacent subplots.
-        Defaults to `pad_inches`.
-
-      *rect* : if rect is given, it is interpreted as a rectangle
-        (left, bottom, right, top) in the normalized figure
-        coordinate that the whole subplots area (including
-        labels) will fit into. Default is (0, 0, 1, 1).
+    Return subplot parameters for tight-layouted-figure with specified padding.
+
+    Parameters
+    ----------
+    fig : Figure
+    axes_list : list of Axes
+    subplotspec_list : list of `~.SubplotSpec`
+        The subplotspecs of each axes.
+    renderer : renderer
+    pad : float
+        Padding between the figure edge and the edges of subplots, as a
+        fraction of the font size.
+    h_pad, w_pad : float
+        Padding (height/width) between edges of adjacent subplots.  Defaults to
+        *pad_inches*.
+    rect : Tuple[float, float, float, float], optional
+        (left, bottom, right, top) rectangle in normalized figure coordinates
+        that the whole subplots area (including labels) will fit into.
+        Defaults to using the entire figure.
     """
 
     subplot_list = []
     nrows_list = []
     ncols_list = []
     ax_bbox_list = []
 
-    subplot_dict = {}  # multiple axes can share
-                       # same subplot_interface (e.g., axes_grid1). Thus
-                       # we need to join them together.
+    subplot_dict = {}  # Multiple axes can share same subplot_interface (e.g.,
+                       # axes_grid1); thus we need to join them together.
 
     subplotspec_list2 = []
 
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -2450,16 +2450,14 @@ class LassoSelector(_SelectorWidget):
     """
     Selection curve of an arbitrary shape.
 
-    For the selector to remain responsive you must keep a reference to
-    it.
+    For the selector to remain responsive you must keep a reference to it.
 
-    The selected path can be used in conjunction with
-    :func:`~matplotlib.path.Path.contains_point` to select
-    data points from an image.
+    The selected path can be used in conjunction with `~.Path.contains_point`
+    to select data points from an image.
 
-    In contrast to :class:`Lasso`, `LassoSelector` is written with an interface
-    similar to :class:`RectangleSelector` and :class:`SpanSelector` and will
-    continue to interact with the axes until disconnected.
+    In contrast to `Lasso`, `LassoSelector` is written with an interface
+    similar to `RectangleSelector` and `SpanSelector`, and will continue to
+    interact with the axes until disconnected.
 
     Example usage::
 
@@ -2477,17 +2475,17 @@ def onselect(verts):
     onselect : function
         Whenever the lasso is released, the *onselect* function is called and
         passed the vertices of the selected path.
-    button : list[Int], optional
+    button : List[Int], optional
         A list of integers indicating which mouse buttons should be used for
         rectangle selection. You can also specify a single integer if only a
         single button is desired.  Default is ``None``, which does not limit
         which button can be used.
 
         Note, typically:
 
-            - 1 = left mouse button
-            - 2 = center mouse button (scroll wheel)
-            - 3 = right mouse button
+        - 1 = left mouse button
+        - 2 = center mouse button (scroll wheel)
+        - 3 = right mouse button
 
     """
 
@@ -2758,16 +2756,15 @@ class Lasso(AxesWidget):
     Unlike :class:`LassoSelector`, this must be initialized with a starting
     point `xy`, and the `Lasso` events are destroyed upon release.
 
-    Parameters:
-
-    *ax* : :class:`~matplotlib.axes.Axes`
+    Parameters
+    ----------
+    ax : `~matplotlib.axes.Axes`
         The parent axes for the widget.
-    *xy* : array
+    xy : array
         Coordinates of the start of the lasso.
-    *callback* : function
+    callback : callable
         Whenever the lasso is released, the `callback` function is called and
         passed the vertices of the selected path.
-
     """
 
     def __init__(self, ax, xy, callback=None, useblit=True):

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+`~.tight_layout.auto_adjust_subplotpars` now raises `ValueError` instead of `RuntimeError` when sizes of input lists don't match
	`2`	+````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````````