diff --git a/doc/api/next_api_changes/2018-01-08-AL.rst b/doc/api/next_api_changes/2018-01-08-AL.rst new file mode 100644 index 000000000000..f4cf24b8fa85 --- /dev/null +++ b/doc/api/next_api_changes/2018-01-08-AL.rst @@ -0,0 +1,6 @@ +Deprecations +```````````` + +``cbook.dedent``, ``docstring.Appender``, ``docstring.dedent``, and +``docstring.copy_dedent`` are deprecated (use the standard library's docstring +manipulation tools, such as `inspect.cleandoc` and `inspect.getdoc` instead). diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index 923bc41170dd..1d2dd4892724 100644 --- a/lib/matplotlib/__init__.py +++ b/lib/matplotlib/__init__.py @@ -1441,7 +1441,7 @@ def _add_data_doc(docstring, replace_names): ------- The augmented docstring. """ - docstring = dedent(docstring) if docstring is not None else "" + docstring = inspect.cleandoc(docstring) if docstring is not None else "" repl = ("* All positional and all keyword arguments." if replace_names is None else "" diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py index 775ad6d53e39..7c0416d2180f 100644 --- a/lib/matplotlib/cbook/__init__.py +++ b/lib/matplotlib/cbook/__init__.py @@ -559,6 +559,7 @@ def get_realpath_and_stat(path): _dedent_regex = {} +@deprecated("3.1", alternative="inspect.cleandoc") def dedent(s): """ Remove excess indentation from docstring *s*. diff --git a/lib/matplotlib/docstring.py b/lib/matplotlib/docstring.py index a97d10391eb2..79ea63a964c2 100644 --- a/lib/matplotlib/docstring.py +++ b/lib/matplotlib/docstring.py @@ -1,45 +1,49 @@ +import inspect + from matplotlib import cbook class Substitution(object): """ - A decorator to take a function's docstring and perform string - substitution on it. + A decorator that performs %-substitution on an object's docstring. - This decorator should be robust even if func.__doc__ is None - (for example, if -OO was passed to the interpreter) + This decorator should be robust even if ``obj.__doc__`` is None (for + example, if -OO was passed to the interpreter). - Usage: construct a docstring.Substitution with a sequence or - dictionary suitable for performing substitution; then - decorate a suitable function with the constructed object. e.g. + Usage: construct a docstring.Substitution with a sequence or dictionary + suitable for performing substitution; then decorate a suitable function + with the constructed object, e.g.:: - sub_author_name = Substitution(author='Jason') + sub_author_name = Substitution(author='Jason') - @sub_author_name - def some_function(x): - "%(author)s wrote this function" + @sub_author_name + def some_function(x): + "%(author)s wrote this function" - # note that some_function.__doc__ is now "Jason wrote this function" + # note that some_function.__doc__ is now "Jason wrote this function" - One can also use positional arguments. + One can also use positional arguments:: - sub_first_last_names = Substitution('Edgar Allen', 'Poe') + sub_first_last_names = Substitution('Edgar Allen', 'Poe') - @sub_first_last_names - def some_function(x): - "%s %s wrote the Raven" + @sub_first_last_names + def some_function(x): + "%s %s wrote the Raven" """ def __init__(self, *args, **kwargs): - assert not (len(args) and len(kwargs)), \ - "Only positional or keyword args are allowed" + if args and kwargs: + raise TypeError("Only positional or keyword args are allowed") self.params = args or kwargs def __call__(self, func): - func.__doc__ = func.__doc__ and func.__doc__ % self.params + if func.__doc__: + func.__doc__ %= self.params return func def update(self, *args, **kwargs): - "Assume self.params is a dict and update it with supplied args" + """ + Update ``self.params`` (which must be a dict) with the supplied args. + """ self.params.update(*args, **kwargs) @classmethod @@ -55,6 +59,7 @@ def from_params(cls, params): return result +@cbook.deprecated("3.1") class Appender(object): """ A function decorator that will append an addendum to the docstring @@ -84,6 +89,7 @@ def __call__(self, func): return func +@cbook.deprecated("3.1", alternative="inspect.getdoc()") def dedent(func): "Dedent a docstring (if present)" func.__doc__ = func.__doc__ and cbook.dedent(func.__doc__) @@ -98,17 +104,19 @@ def do_copy(target): return target return do_copy -# create a decorator that will house the various documentation that -# is reused throughout matplotlib + +# Create a decorator that will house the various docstring snippets reused +# throughout Matplotlib. interpd = Substitution() def dedent_interpd(func): - """A special case of the interpd that first performs a dedent on - the incoming docstring""" - return interpd(dedent(func)) + """Dedent *func*'s docstring, then interpolate it with ``interpd``.""" + func.__doc__ = inspect.getdoc(func.__doc__) + return interpd(func) +@cbook.deprecated("3.1", alternative="docstring.copy() and cbook.dedent()") def copy_dedent(source): """A decorator that will copy the docstring from the source and then dedent it""" diff --git a/lib/matplotlib/mlab.py b/lib/matplotlib/mlab.py index e2a9173cfa9b..072cd8ce0d2e 100644 --- a/lib/matplotlib/mlab.py +++ b/lib/matplotlib/mlab.py @@ -54,6 +54,7 @@ """ import csv +import inspect import numpy as np @@ -618,7 +619,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None, # Split out these keyword docs so that they can be used elsewhere -docstring.interpd.update(Spectral=cbook.dedent(""" +docstring.interpd.update(Spectral=inspect.cleandoc(""" Fs : scalar The sampling frequency (samples per time unit). It is used to calculate the Fourier frequencies, freqs, in cycles per time @@ -640,7 +641,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None, """)) -docstring.interpd.update(Single_Spectrum=cbook.dedent(""" +docstring.interpd.update(Single_Spectrum=inspect.cleandoc(""" pad_to : int The number of points to which the data segment is padded when performing the FFT. While not increasing the actual resolution of @@ -652,7 +653,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None, """)) -docstring.interpd.update(PSD=cbook.dedent(""" +docstring.interpd.update(PSD=inspect.cleandoc(""" pad_to : int The number of points to which the data segment is padded when performing the FFT. This can be different from *NFFT*, which diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index 0a025ed2f96a..565e7baae2c6 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -1,5 +1,6 @@ import contextlib import functools +import inspect import math from numbers import Number import textwrap @@ -2435,8 +2436,8 @@ def transmute(self, x0, y0, width, height, mutation_size): return Path(saw_vertices, codes) if __doc__: # __doc__ could be None if -OO optimization is enabled - __doc__ = cbook.dedent(__doc__) % \ - {"AvailableBoxstyles": _pprint_styles(_style_list)} + __doc__ = inspect.cleandoc(__doc__) % { + "AvailableBoxstyles": _pprint_styles(_style_list)} docstring.interpd.update( AvailableBoxstyles=_pprint_styles(BoxStyle._style_list), @@ -3104,8 +3105,8 @@ def connect(self, posA, posB): return Path(vertices, codes) if __doc__: - __doc__ = cbook.dedent(__doc__) % \ - {"AvailableConnectorstyles": _pprint_styles(_style_list)} + __doc__ = inspect.cleandoc(__doc__) % { + "AvailableConnectorstyles": _pprint_styles(_style_list)} def _point_along_a_line(x0, y0, x1, y1, d): @@ -3895,8 +3896,8 @@ def transmute(self, path, mutation_size, linewidth): return path, True if __doc__: - __doc__ = cbook.dedent(__doc__) % \ - {"AvailableArrowstyles": _pprint_styles(_style_list)} + __doc__ = inspect.cleandoc(__doc__) % { + "AvailableArrowstyles": _pprint_styles(_style_list)} docstring.interpd.update( diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index c61cf1f3e775..62500aedba86 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -167,7 +167,7 @@ def uninstall_repl_displayhook(): draw_all = _pylab_helpers.Gcf.draw_all -@docstring.copy_dedent(Artist.findobj) +@docstring.copy(Artist.findobj) def findobj(o=None, match=None, include_self=True): if o is None: o = gcf() @@ -300,17 +300,17 @@ def pause(interval): time.sleep(interval) -@docstring.copy_dedent(matplotlib.rc) +@docstring.copy(matplotlib.rc) def rc(group, **kwargs): matplotlib.rc(group, **kwargs) -@docstring.copy_dedent(matplotlib.rc_context) +@docstring.copy(matplotlib.rc_context) def rc_context(rc=None, fname=None): return matplotlib.rc_context(rc, fname) -@docstring.copy_dedent(matplotlib.rcdefaults) +@docstring.copy(matplotlib.rcdefaults) def rcdefaults(): matplotlib.rcdefaults() if matplotlib.is_interactive(): @@ -612,12 +612,12 @@ def get_current_fig_manager(): return figManager -@docstring.copy_dedent(FigureCanvasBase.mpl_connect) +@docstring.copy(FigureCanvasBase.mpl_connect) def connect(s, func): return get_current_fig_manager().canvas.mpl_connect(s, func) -@docstring.copy_dedent(FigureCanvasBase.mpl_disconnect) +@docstring.copy(FigureCanvasBase.mpl_disconnect) def disconnect(cid): return get_current_fig_manager().canvas.mpl_disconnect(cid) @@ -687,7 +687,7 @@ def draw(): get_current_fig_manager().canvas.draw_idle() -@docstring.copy_dedent(Figure.savefig) +@docstring.copy(Figure.savefig) def savefig(*args, **kwargs): fig = gcf() res = fig.savefig(*args, **kwargs) @@ -695,7 +695,7 @@ def savefig(*args, **kwargs): return res -@docstring.copy_dedent(Figure.ginput) +@docstring.copy(Figure.ginput) def ginput(*args, **kwargs): """ Blocking call to interact with the figure. @@ -708,7 +708,7 @@ def ginput(*args, **kwargs): return gcf().ginput(*args, **kwargs) -@docstring.copy_dedent(Figure.waitforbuttonpress) +@docstring.copy(Figure.waitforbuttonpress) def waitforbuttonpress(*args, **kwargs): """ Blocking call to interact with the figure. @@ -725,17 +725,17 @@ def waitforbuttonpress(*args, **kwargs): ## Putting things in figures ## -@docstring.copy_dedent(Figure.text) +@docstring.copy(Figure.text) def figtext(x, y, s, *args, **kwargs): return gcf().text(x, y, s, *args, **kwargs) -@docstring.copy_dedent(Figure.suptitle) +@docstring.copy(Figure.suptitle) def suptitle(t, **kwargs): return gcf().suptitle(t, **kwargs) -@docstring.copy_dedent(Figure.figimage) +@docstring.copy(Figure.figimage) def figimage(*args, **kwargs): return gcf().figimage(*args, **kwargs) @@ -2104,12 +2104,12 @@ def set_cmap(cmap): im.set_cmap(cmap) -@docstring.copy_dedent(matplotlib.image.imread) +@docstring.copy(matplotlib.image.imread) def imread(fname, format=None): return matplotlib.image.imread(fname, format) -@docstring.copy_dedent(matplotlib.image.imsave) +@docstring.copy(matplotlib.image.imsave) def imsave(fname, arr, **kwargs): return matplotlib.image.imsave(fname, arr, **kwargs) @@ -2320,14 +2320,6 @@ def getname_val(identifier): fig.autofmt_xdate() -def _autogen_docstring(base): - """Autogenerated wrappers will get their docstring from a base function - with an addendum.""" - msg = '' - addendum = docstring.Appender(msg, '\n\n') - return lambda func: addendum(docstring.copy_dedent(base)(func)) - - # If rcParams['backend_fallback'] is true, and an interactive backend is # requested, ignore rcParams['backend'] and force selection of a backend that # is compatible with the current running interactive framework. @@ -2350,14 +2342,14 @@ def _autogen_docstring(base): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.acorr) +@docstring.copy(Axes.acorr) def acorr(x, *, data=None, **kwargs): return gca().acorr( x, **({"data": data} if data is not None else {}), **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.angle_spectrum) +@docstring.copy(Axes.angle_spectrum) def angle_spectrum( x, Fs=None, Fc=None, window=None, pad_to=None, sides=None, *, data=None, **kwargs): @@ -2367,55 +2359,55 @@ def angle_spectrum( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.annotate) +@docstring.copy(Axes.annotate) def annotate(s, xy, *args, **kwargs): return gca().annotate(s, xy, *args, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.arrow) +@docstring.copy(Axes.arrow) def arrow(x, y, dx, dy, **kwargs): return gca().arrow(x, y, dx, dy, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.autoscale) +@docstring.copy(Axes.autoscale) def autoscale(enable=True, axis='both', tight=None): return gca().autoscale(enable=enable, axis=axis, tight=tight) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.axhline) +@docstring.copy(Axes.axhline) def axhline(y=0, xmin=0, xmax=1, **kwargs): return gca().axhline(y=y, xmin=xmin, xmax=xmax, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.axhspan) +@docstring.copy(Axes.axhspan) def axhspan(ymin, ymax, xmin=0, xmax=1, **kwargs): return gca().axhspan(ymin, ymax, xmin=xmin, xmax=xmax, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.axis) +@docstring.copy(Axes.axis) def axis(*v, **kwargs): return gca().axis(*v, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.axvline) +@docstring.copy(Axes.axvline) def axvline(x=0, ymin=0, ymax=1, **kwargs): return gca().axvline(x=x, ymin=ymin, ymax=ymax, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.axvspan) +@docstring.copy(Axes.axvspan) def axvspan(xmin, xmax, ymin=0, ymax=1, **kwargs): return gca().axvspan(xmin, xmax, ymin=ymin, ymax=ymax, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.bar) +@docstring.copy(Axes.bar) def bar( x, height, width=0.8, bottom=None, *, align='center', data=None, **kwargs): @@ -2425,21 +2417,21 @@ def bar( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.barbs) +@docstring.copy(Axes.barbs) def barbs(*args, data=None, **kw): return gca().barbs( *args, **({"data": data} if data is not None else {}), **kw) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.barh) +@docstring.copy(Axes.barh) def barh(y, width, height=0.8, left=None, *, align='center', **kwargs): return gca().barh( y, width, height=height, left=left, align=align, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.boxplot) +@docstring.copy(Axes.boxplot) def boxplot( x, notch=None, sym=None, vert=None, whis=None, positions=None, widths=None, patch_artist=None, @@ -2464,7 +2456,7 @@ def boxplot( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.broken_barh) +@docstring.copy(Axes.broken_barh) def broken_barh(xranges, yrange, *, data=None, **kwargs): return gca().broken_barh( xranges, yrange, **({"data": data} if data is not None else @@ -2472,19 +2464,19 @@ def broken_barh(xranges, yrange, *, data=None, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.cla) +@docstring.copy(Axes.cla) def cla(): return gca().cla() # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.clabel) +@docstring.copy(Axes.clabel) def clabel(CS, *args, **kwargs): return gca().clabel(CS, *args, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.cohere) +@docstring.copy(Axes.cohere) def cohere( x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=0, pad_to=None, @@ -2497,7 +2489,7 @@ def cohere( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.contour) +@docstring.copy(Axes.contour) def contour(*args, data=None, **kwargs): __ret = gca().contour( *args, **({"data": data} if data is not None else {}), @@ -2507,7 +2499,7 @@ def contour(*args, data=None, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.contourf) +@docstring.copy(Axes.contourf) def contourf(*args, data=None, **kwargs): __ret = gca().contourf( *args, **({"data": data} if data is not None else {}), @@ -2517,7 +2509,7 @@ def contourf(*args, data=None, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.csd) +@docstring.copy(Axes.csd) def csd( x, y, NFFT=None, Fs=None, Fc=None, detrend=None, window=None, noverlap=None, pad_to=None, sides=None, scale_by_freq=None, @@ -2530,7 +2522,7 @@ def csd( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.errorbar) +@docstring.copy(Axes.errorbar) def errorbar( x, y, yerr=None, xerr=None, fmt='', ecolor=None, elinewidth=None, capsize=None, barsabove=False, lolims=False, @@ -2545,7 +2537,7 @@ def errorbar( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.eventplot) +@docstring.copy(Axes.eventplot) def eventplot( positions, orientation='horizontal', lineoffsets=1, linelengths=1, linewidths=None, colors=None, @@ -2558,7 +2550,7 @@ def eventplot( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.fill) +@docstring.copy(Axes.fill) def fill(*args, data=None, **kwargs): return gca().fill( *args, **({"data": data} if data is not None else {}), @@ -2566,7 +2558,7 @@ def fill(*args, data=None, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.fill_between) +@docstring.copy(Axes.fill_between) def fill_between( x, y1, y2=0, where=None, interpolate=False, step=None, *, data=None, **kwargs): @@ -2576,7 +2568,7 @@ def fill_between( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.fill_betweenx) +@docstring.copy(Axes.fill_betweenx) def fill_betweenx( y, x1, x2=0, where=None, step=None, interpolate=False, *, data=None, **kwargs): @@ -2586,13 +2578,13 @@ def fill_betweenx( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.grid) +@docstring.copy(Axes.grid) def grid(b=None, which='major', axis='both', **kwargs): return gca().grid(b=b, which=which, axis=axis, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.hexbin) +@docstring.copy(Axes.hexbin) def hexbin( x, y, C=None, gridsize=100, bins=None, xscale='linear', yscale='linear', extent=None, cmap=None, norm=None, vmin=None, @@ -2611,7 +2603,7 @@ def hexbin( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.hist) +@docstring.copy(Axes.hist) def hist( x, bins=None, range=None, density=None, weights=None, cumulative=False, bottom=None, histtype='bar', align='mid', @@ -2627,7 +2619,7 @@ def hist( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.hist2d) +@docstring.copy(Axes.hist2d) def hist2d( x, y, bins=10, range=None, density=False, weights=None, cmin=None, cmax=None, *, data=None, **kwargs): @@ -2640,7 +2632,7 @@ def hist2d( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.hlines) +@docstring.copy(Axes.hlines) def hlines( y, xmin, xmax, colors='k', linestyles='solid', label='', *, data=None, **kwargs): @@ -2651,7 +2643,7 @@ def hlines( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.imshow) +@docstring.copy(Axes.imshow) def imshow( X, cmap=None, norm=None, aspect=None, interpolation=None, alpha=None, vmin=None, vmax=None, origin=None, extent=None, @@ -2669,25 +2661,25 @@ def imshow( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.legend) +@docstring.copy(Axes.legend) def legend(*args, **kwargs): return gca().legend(*args, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.locator_params) +@docstring.copy(Axes.locator_params) def locator_params(axis='both', tight=None, **kwargs): return gca().locator_params(axis=axis, tight=tight, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.loglog) +@docstring.copy(Axes.loglog) def loglog(*args, **kwargs): return gca().loglog(*args, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.magnitude_spectrum) +@docstring.copy(Axes.magnitude_spectrum) def magnitude_spectrum( x, Fs=None, Fc=None, window=None, pad_to=None, sides=None, scale=None, *, data=None, **kwargs): @@ -2698,25 +2690,25 @@ def magnitude_spectrum( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.margins) +@docstring.copy(Axes.margins) def margins(*margins, x=None, y=None, tight=True): return gca().margins(*margins, x=x, y=y, tight=tight) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.minorticks_off) +@docstring.copy(Axes.minorticks_off) def minorticks_off(): return gca().minorticks_off() # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.minorticks_on) +@docstring.copy(Axes.minorticks_on) def minorticks_on(): return gca().minorticks_on() # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.pcolor) +@docstring.copy(Axes.pcolor) def pcolor( *args, alpha=None, norm=None, cmap=None, vmin=None, vmax=None, data=None, **kwargs): @@ -2729,7 +2721,7 @@ def pcolor( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.pcolormesh) +@docstring.copy(Axes.pcolormesh) def pcolormesh( *args, alpha=None, norm=None, cmap=None, vmin=None, vmax=None, shading='flat', antialiased=False, data=None, @@ -2743,7 +2735,7 @@ def pcolormesh( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.phase_spectrum) +@docstring.copy(Axes.phase_spectrum) def phase_spectrum( x, Fs=None, Fc=None, window=None, pad_to=None, sides=None, *, data=None, **kwargs): @@ -2753,7 +2745,7 @@ def phase_spectrum( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.pie) +@docstring.copy(Axes.pie) def pie( x, explode=None, labels=None, colors=None, autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1, @@ -2771,7 +2763,7 @@ def pie( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.plot) +@docstring.copy(Axes.plot) def plot(*args, scalex=True, scaley=True, data=None, **kwargs): return gca().plot( *args, scalex=scalex, scaley=scaley, **({"data": data} if data @@ -2779,7 +2771,7 @@ def plot(*args, scalex=True, scaley=True, data=None, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.plot_date) +@docstring.copy(Axes.plot_date) def plot_date( x, y, fmt='o', tz=None, xdate=True, ydate=False, *, data=None, **kwargs): @@ -2789,7 +2781,7 @@ def plot_date( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.psd) +@docstring.copy(Axes.psd) def psd( x, NFFT=None, Fs=None, Fc=None, detrend=None, window=None, noverlap=None, pad_to=None, sides=None, scale_by_freq=None, @@ -2802,7 +2794,7 @@ def psd( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.quiver) +@docstring.copy(Axes.quiver) def quiver(*args, data=None, **kw): __ret = gca().quiver( *args, **({"data": data} if data is not None else {}), **kw) @@ -2811,13 +2803,13 @@ def quiver(*args, data=None, **kw): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.quiverkey) +@docstring.copy(Axes.quiverkey) def quiverkey(Q, X, Y, U, label, **kw): return gca().quiverkey(Q, X, Y, U, label, **kw) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.scatter) +@docstring.copy(Axes.scatter) def scatter( x, y, s=None, c=None, marker=None, cmap=None, norm=None, vmin=None, vmax=None, alpha=None, linewidths=None, verts=None, @@ -2833,19 +2825,19 @@ def scatter( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.semilogx) +@docstring.copy(Axes.semilogx) def semilogx(*args, **kwargs): return gca().semilogx(*args, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.semilogy) +@docstring.copy(Axes.semilogy) def semilogy(*args, **kwargs): return gca().semilogy(*args, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.specgram) +@docstring.copy(Axes.specgram) def specgram( x, NFFT=None, Fs=None, Fc=None, detrend=None, window=None, noverlap=None, cmap=None, xextent=None, pad_to=None, @@ -2862,7 +2854,7 @@ def specgram( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.spy) +@docstring.copy(Axes.spy) def spy( Z, precision=0, marker=None, markersize=None, aspect='equal', origin='upper', **kwargs): @@ -2874,7 +2866,7 @@ def spy( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.stackplot) +@docstring.copy(Axes.stackplot) def stackplot(x, *args, data=None, **kwargs): return gca().stackplot( x, *args, **({"data": data} if data is not None else {}), @@ -2882,7 +2874,7 @@ def stackplot(x, *args, data=None, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.stem) +@docstring.copy(Axes.stem) def stem( *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0, label=None, data=None): @@ -2893,7 +2885,7 @@ def stem( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.step) +@docstring.copy(Axes.step) def step(x, y, *args, where='pre', data=None, **kwargs): return gca().step( x, y, *args, where=where, **({"data": data} if data is not @@ -2901,7 +2893,7 @@ def step(x, y, *args, where='pre', data=None, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.streamplot) +@docstring.copy(Axes.streamplot) def streamplot( x, y, u, v, density=1, linewidth=None, color=None, cmap=None, norm=None, arrowsize=1, arrowstyle='-|>', minlength=0.1, @@ -2920,7 +2912,7 @@ def streamplot( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.table) +@docstring.copy(Axes.table) def table( cellText=None, cellColours=None, cellLoc='right', colWidths=None, rowLabels=None, rowColours=None, @@ -2936,19 +2928,19 @@ def table( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.text) +@docstring.copy(Axes.text) def text(x, y, s, fontdict=None, withdash=False, **kwargs): return gca().text(x, y, s, fontdict=fontdict, withdash=withdash, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.tick_params) +@docstring.copy(Axes.tick_params) def tick_params(axis='both', **kwargs): return gca().tick_params(axis=axis, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.ticklabel_format) +@docstring.copy(Axes.ticklabel_format) def ticklabel_format( *, axis='both', style='', scilimits=None, useOffset=None, useLocale=None, useMathText=None): @@ -2959,7 +2951,7 @@ def ticklabel_format( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.tricontour) +@docstring.copy(Axes.tricontour) def tricontour(*args, **kwargs): __ret = gca().tricontour(*args, **kwargs) if __ret._A is not None: sci(__ret) # noqa @@ -2967,7 +2959,7 @@ def tricontour(*args, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.tricontourf) +@docstring.copy(Axes.tricontourf) def tricontourf(*args, **kwargs): __ret = gca().tricontourf(*args, **kwargs) if __ret._A is not None: sci(__ret) # noqa @@ -2975,7 +2967,7 @@ def tricontourf(*args, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@_autogen_docstring(Axes.tripcolor) +@docstring.copy(Axes.tripcolor) def tripcolor(*args, **kwargs): __ret = gca().tripcolor(*args, **kwargs) sci(__ret) @@ -2983,13 +2975,13 @@ def tripcolor(*args, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.triplot) +@docstring.copy(Axes.triplot) def triplot(*args, **kwargs): return gca().triplot(*args, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.violinplot) +@docstring.copy(Axes.violinplot) def violinplot( dataset, positions=None, vert=True, widths=0.5, showmeans=False, showextrema=True, showmedians=False, @@ -3002,7 +2994,7 @@ def violinplot( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.vlines) +@docstring.copy(Axes.vlines) def vlines( x, ymin, ymax, colors='k', linestyles='solid', label='', *, data=None, **kwargs): @@ -3013,7 +3005,7 @@ def vlines( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.xcorr) +@docstring.copy(Axes.xcorr) def xcorr( x, y, normed=True, detrend=mlab.detrend_none, usevlines=True, maxlags=10, *, data=None, **kwargs): @@ -3024,40 +3016,40 @@ def xcorr( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes._sci) +@docstring.copy(Axes._sci) def sci(im): return gca()._sci(im) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.set_title) +@docstring.copy(Axes.set_title) def title(label, fontdict=None, loc='center', pad=None, **kwargs): return gca().set_title( label, fontdict=fontdict, loc=loc, pad=pad, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.set_xlabel) +@docstring.copy(Axes.set_xlabel) def xlabel(xlabel, fontdict=None, labelpad=None, **kwargs): return gca().set_xlabel( xlabel, fontdict=fontdict, labelpad=labelpad, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.set_ylabel) +@docstring.copy(Axes.set_ylabel) def ylabel(ylabel, fontdict=None, labelpad=None, **kwargs): return gca().set_ylabel( ylabel, fontdict=fontdict, labelpad=labelpad, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.set_xscale) +@docstring.copy(Axes.set_xscale) def xscale(value, **kwargs): return gca().set_xscale(value, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. -@docstring.copy_dedent(Axes.set_yscale) +@docstring.copy(Axes.set_yscale) def yscale(value, **kwargs): return gca().set_yscale(value, **kwargs) diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py index 157c2d50b2b6..ddd1bcbcd3d2 100644 --- a/lib/matplotlib/scale.py +++ b/lib/matplotlib/scale.py @@ -1,3 +1,6 @@ +import inspect +import textwrap + import numpy as np from numpy import ma @@ -668,18 +671,17 @@ def scale_factory(scale, axis, **kwargs): """ Return a scale class by name. - ACCEPTS: [ %(names)s ] + Parameters + ---------- + scale : {%(names)s} + axis : Axis """ scale = scale.lower() - if scale is None: - scale = 'linear' - if scale not in _scale_mapping: raise ValueError("Unknown scale type '%s'" % scale) - return _scale_mapping[scale](axis, **kwargs) -scale_factory.__doc__ = cbook.dedent(scale_factory.__doc__) % \ - {'names': " | ".join(get_scale_names())} +scale_factory.__doc__ = scale_factory.__doc__ % { + "names": ", ".join(get_scale_names())} def register_scale(scale_class): @@ -706,15 +708,13 @@ def _get_scale_docs(): Helper function for generating docstrings related to scales. """ docs = [] - for name in get_scale_names(): - scale_class = _scale_mapping[name] - docs.append(" '%s'" % name) - docs.append("") - class_docs = cbook.dedent(scale_class.__init__.__doc__) - class_docs = "".join([" %s\n" % - x for x in class_docs.split("\n")]) - docs.append(class_docs) - docs.append("") + for name, scale_class in _scale_mapping.items(): + docs.extend([ + f" {name!r}", + "", + textwrap.indent(inspect.getdoc(scale_class.__init__), " " * 8), + "" + ]) return "\n".join(docs) diff --git a/lib/mpl_toolkits/axes_grid1/anchored_artists.py b/lib/mpl_toolkits/axes_grid1/anchored_artists.py index 949faacb1beb..fef40db2dcb5 100644 --- a/lib/mpl_toolkits/axes_grid1/anchored_artists.py +++ b/lib/mpl_toolkits/axes_grid1/anchored_artists.py @@ -10,7 +10,6 @@ class AnchoredDrawingArea(AnchoredOffsetbox): - @docstring.dedent def __init__(self, width, height, xdescent, ydescent, loc, pad=0.4, borderpad=0.5, prop=None, frameon=True, **kwargs): @@ -87,7 +86,6 @@ def __init__(self, width, height, xdescent, ydescent, class AnchoredAuxTransformBox(AnchoredOffsetbox): - @docstring.dedent def __init__(self, transform, loc, pad=0.4, borderpad=0.5, prop=None, frameon=True, **kwargs): """ @@ -160,7 +158,6 @@ def __init__(self, transform, loc, class AnchoredEllipse(AnchoredOffsetbox): - @docstring.dedent def __init__(self, transform, width, height, angle, loc, pad=0.1, borderpad=0.1, prop=None, frameon=True, **kwargs): """ @@ -226,7 +223,6 @@ def __init__(self, transform, width, height, angle, loc, class AnchoredSizeBar(AnchoredOffsetbox): - @docstring.dedent def __init__(self, transform, size, label, loc, pad=0.1, borderpad=0.1, sep=2, frameon=True, size_vertical=0, color='black', @@ -375,7 +371,6 @@ def __init__(self, transform, size, label, loc, class AnchoredDirectionArrows(AnchoredOffsetbox): - @docstring.dedent def __init__(self, transform, label_x, label_y, length=0.15, fontsize=0.08, loc=2, angle=0, aspect_ratio=1, pad=0.4, borderpad=0.4, frameon=False, color='w', alpha=1, diff --git a/tools/boilerplate.py b/tools/boilerplate.py index d7ad65ffb16b..74a3a4d065b8 100644 --- a/tools/boilerplate.py +++ b/tools/boilerplate.py @@ -35,7 +35,7 @@ # Autogenerated by boilerplate.py. Do not edit as changes will be lost.""" CMAPPABLE_TEMPLATE = AUTOGEN_MSG + """ -@_autogen_docstring(Axes.%(real_name)s) +@docstring.copy(Axes.%(real_name)s) def %(func)s%(sig)s: __ret = gca().%(real_name)s%(call)s %(mappable)s @@ -43,7 +43,7 @@ def %(func)s%(sig)s: """ NON_CMAPPABLE_TEMPLATE = AUTOGEN_MSG + """ -@docstring.copy_dedent(Axes.%(real_name)s) +@docstring.copy(Axes.%(real_name)s) def %(func)s%(sig)s: return gca().%(real_name)s%(call)s """