From 50fc4c83a99d1e306cbb99dd3101991bfdb99b2d Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Sun, 23 Sep 2018 15:38:53 +0200 Subject: [PATCH] Less ACCEPTS, more numpydoc. --- doc/api/next_api_changes/2018-09-22-AL.rst | 4 ++ lib/matplotlib/artist.py | 4 +- lib/matplotlib/axes/_axes.py | 2 +- lib/matplotlib/axes/_base.py | 2 +- lib/matplotlib/axis.py | 62 ++++++++++++++------- lib/matplotlib/figure.py | 10 +++- lib/matplotlib/lines.py | 4 +- lib/matplotlib/patches.py | 7 ++- lib/matplotlib/tests/test_artist.py | 1 + lib/mpl_toolkits/axes_grid1/axes_divider.py | 2 +- 10 files changed, 67 insertions(+), 31 deletions(-) create mode 100644 doc/api/next_api_changes/2018-09-22-AL.rst diff --git a/doc/api/next_api_changes/2018-09-22-AL.rst b/doc/api/next_api_changes/2018-09-22-AL.rst new file mode 100644 index 000000000000..95850a294ed2 --- /dev/null +++ b/doc/api/next_api_changes/2018-09-22-AL.rst @@ -0,0 +1,4 @@ +Additional positional arguments to `Axis.set_ticklabels` +```````````````````````````````````````````````````````` +Passing positional arguments to `Axis.set_ticklabels` beyond `ticklabels` +itself has no effect, and support for them is deprecated. diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py index 49af30d2478c..5d1945a1111f 100644 --- a/lib/matplotlib/artist.py +++ b/lib/matplotlib/artist.py @@ -1227,7 +1227,9 @@ def get_valid_values(self, attr): # Much faster than list(inspect.signature(func).parameters)[1], # although barely relevant wrt. matplotlib's total import time. param_name = func.__code__.co_varnames[1] - match = re.search("(?m)^ *{} : (.+)".format(param_name), docstring) + # We could set the presence * based on whether the parameter is a + # varargs (it can't be a varkwargs) but it's not really worth the it. + match = re.search("(?m)^ *\*?{} : (.+)".format(param_name), docstring) if match: return match.group(1) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index ea1c53aa39c4..158b34ac1034 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -4881,7 +4881,7 @@ def fill(self, *args, **kwargs): Parameters ---------- - args : sequence of x, y, [color] + *args : sequence of x, y, [color] Each polygon is defined by the lists of *x* and *y* positions of its nodes, optionally followed by a *color* specifier. See :mod:`matplotlib.colors` for supported color specifiers. The diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index ef2b8966bb51..712c9f097371 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2248,7 +2248,7 @@ def margins(self, *margins, x=None, y=None, tight=True): Parameters ---------- - args : float, optional + *margins : float, optional If a single positional argument is provided, it specifies both margins of the x-axis and y-axis limits. If two positional arguments are provided, they will be interpreted diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py index 5164567ae1c7..9bc1cfa642fe 100644 --- a/lib/matplotlib/axis.py +++ b/lib/matplotlib/axis.py @@ -1539,9 +1539,11 @@ def convert_units(self, x): def set_units(self, u): """ - set the units for axis + Set the units for axis. - ACCEPTS: a units tag + Parameters + ---------- + u : units tag """ pchanged = False if u is None: @@ -1558,14 +1560,21 @@ def set_units(self, u): self.stale = True def get_units(self): - 'return the units for axis' + """Return the units for axis.""" return self.units def set_label_text(self, label, fontdict=None, **kwargs): """ Set the text value of the axis label. - ACCEPTS: A string value for the label + Parameters + ---------- + label : str + Text string. + fontdict : dict + Text properties. + **kwargs : + Merged into fontdict. """ self.isDefault_label = False self.label.set_text(label) @@ -1601,7 +1610,7 @@ def set_minor_formatter(self, formatter): """ if not isinstance(formatter, mticker.Formatter): raise TypeError("formatter argument should be instance of " - "matplotlib.ticker.Formatter") + "matplotlib.ticker.Formatter") self.isDefault_minfmt = False self.minor.formatter = formatter formatter.set_axis(self) @@ -1617,7 +1626,7 @@ def set_major_locator(self, locator): """ if not isinstance(locator, mticker.Locator): raise TypeError("formatter argument should be instance of " - "matplotlib.ticker.Locator") + "matplotlib.ticker.Locator") self.isDefault_majloc = False self.major.locator = locator locator.set_axis(self) @@ -1633,7 +1642,7 @@ def set_minor_locator(self, locator): """ if not isinstance(locator, mticker.Locator): raise TypeError("formatter argument should be instance of " - "matplotlib.ticker.Locator") + "matplotlib.ticker.Locator") self.isDefault_minloc = False self.minor.locator = locator locator.set_axis(self) @@ -1651,21 +1660,29 @@ def set_pickradius(self, pickradius): def set_ticklabels(self, ticklabels, *args, minor=False, **kwargs): """ - Set the text values of the tick labels. Return a list of Text - instances. Use *kwarg* *minor=True* to select minor ticks. - All other kwargs are used to update the text object properties. - As for get_ticklabels, label1 (left or bottom) is - affected for a given tick only if its label1On attribute - is True, and similarly for label2. The list of returned - label text objects consists of all such label1 objects followed - by all such label2 objects. + Set the text values of the tick labels. - The input *ticklabels* is assumed to match the set of - tick locations, regardless of the state of label1On and - label2On. + Parameters + ---------- + ticklabels : sequence of str or of `Text`\s + List of texts for tick labels; must include values for non-visible + labels. + minor : bool + If True, set minor ticks instead of major ticks. + **kwargs + Text properties. - ACCEPTS: sequence of strings or Text objects - """ + Returns + ------- + labels : list of `Text`\s + For each tick, includes ``tick.label1`` if it is visible, then + ``tick.label2`` if it is visible, in that order. + """ + if args: + cbook.warn_deprecated( + "3.1", "Additional positional arguments to set_ticklabels are " + "ignored, and deprecated since Matplotlib 3.1; passing them " + "will raise a TypeError in Matplotlib 3.3.") get_labels = [] for t in ticklabels: # try calling get_text() to check whether it is Text object @@ -1705,7 +1722,10 @@ def set_ticks(self, ticks, minor=False): """ Set the locations of the tick marks from sequence ticks - ACCEPTS: sequence of floats + Parameters + ---------- + ticks : sequence of floats + minor : bool """ # XXX if the user changes units, the information will be lost here ticks = self.convert_units(ticks) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 7798a3b34d71..8ce130148a68 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -979,7 +979,10 @@ def set_figwidth(self, val, forward=True): """ Set the width of the figure in inches. - .. ACCEPTS: float + Parameters + ---------- + val : float + forward : bool """ self.set_size_inches(val, self.get_figheight(), forward=forward) @@ -987,7 +990,10 @@ def set_figheight(self, val, forward=True): """ Set the height of the figure in inches. - .. ACCEPTS: float + Parameters + ---------- + val : float + forward : bool """ self.set_size_inches(self.get_figwidth(), val, forward=forward) diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py index 879c7de90600..a8ec5151c2d4 100644 --- a/lib/matplotlib/lines.py +++ b/lib/matplotlib/lines.py @@ -650,7 +650,9 @@ def set_data(self, *args): """ Set the x and y data. - ACCEPTS: 2D array (rows are x, y) or two 1D arrays + Parameters + ---------- + *args : (N, 2) array or two 1D arrays """ if len(args) == 1: x, y = args[0] diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index 5832687476fc..3bf448a5d545 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -337,9 +337,11 @@ def set_alpha(self, alpha): def set_linewidth(self, w): """ - Set the patch linewidth in points + Set the patch linewidth in points. - ACCEPTS: float or None for default + Parameters + ---------- + w : float or None """ if w is None: w = mpl.rcParams['patch.linewidth'] @@ -2516,7 +2518,6 @@ def set_boxstyle(self, boxstyle=None, **kw): %(AvailableBoxstyles)s ACCEPTS: %(ListBoxstyles)s - """ if boxstyle is None: return BoxStyle.pprint_styles() diff --git a/lib/matplotlib/tests/test_artist.py b/lib/matplotlib/tests/test_artist.py index 3c8f11404aad..fd1db5ce2fd8 100644 --- a/lib/matplotlib/tests/test_artist.py +++ b/lib/matplotlib/tests/test_artist.py @@ -262,6 +262,7 @@ def test_None_zorder(): ('ACCEPTS: Some description.', 'Some description. '), ('.. ACCEPTS: Some description.', 'Some description. '), ('arg : int', 'int'), + ('*arg : int', 'int'), ('arg : int\nACCEPTS: Something else.', 'Something else. '), ]) def test_artist_inspector_get_valid_values(accept_clause, expected): diff --git a/lib/mpl_toolkits/axes_grid1/axes_divider.py b/lib/mpl_toolkits/axes_grid1/axes_divider.py index 0d804da132b3..a8616d7472b9 100644 --- a/lib/mpl_toolkits/axes_grid1/axes_divider.py +++ b/lib/mpl_toolkits/axes_grid1/axes_divider.py @@ -361,7 +361,7 @@ def __init__(self, fig, *args, horizontal=None, vertical=None, Parameters ---------- fig : :class:`matplotlib.figure.Figure` - args : tuple (*numRows*, *numCols*, *plotNum*) + *args : tuple (*numRows*, *numCols*, *plotNum*) The array of subplots in the figure has dimensions *numRows*, *numCols*, and *plotNum* is the number of the subplot being created. *plotNum* starts at 1 in the upper left