diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index 400063b05fab..9b0be0aca05a 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -1598,9 +1598,10 @@ def apply_aspect(self, position=None): self.set_xbound((x0, x1)) def axis(self, *v, **kwargs): - """Set axis properties. + """ + Convenience method to get or set some axis properties. - Valid signatures:: + Call signatures:: xmin, xmax, ymin, ymax = axis() xmin, xmax, ymin, ymax = axis(list_arg) @@ -1609,39 +1610,44 @@ def axis(self, *v, **kwargs): Parameters ---------- - v : list of float or {'on', 'off', 'equal', 'tight', 'scaled',\ - 'normal', 'auto', 'image', 'square'} - Optional positional argument - - Axis data limits set from a list; or a command relating to axes: - - ========== ================================================ - Value Description - ========== ================================================ - 'on' Toggle axis lines and labels on - 'off' Toggle axis lines and labels off - 'equal' Equal scaling by changing limits - 'scaled' Equal scaling by changing box dimensions - 'tight' Limits set such that all data is shown - 'auto' Automatic scaling, fill rectangle with data - 'normal' Same as 'auto'; deprecated - 'image' 'scaled' with axis limits equal to data limits - 'square' Square plot; similar to 'scaled', but initially\ - forcing xmax-xmin = ymax-ymin - ========== ================================================ + v : List[float] or one of the strings listed below. + Optional positional-only argument + + If a list, set the axis data limits. If a string: + + ======== ========================================================== + Value Description + ======== ========================================================== + 'on' Turn on axis lines and labels. + 'off' Turn off axis lines and labels. + 'equal' Set equal scaling (i.e., make circles circular) by + changing axis limits. + 'scaled' Set equal scaling (i.e., make circles circular) by + changing dimensions of the plot box. + 'tight' Set limits just large enough to show all data. + 'auto' Automatic scaling (fill plot box with data). + 'normal' Same as 'auto'; deprecated. + 'image' 'scaled' with axis limits equal to data limits. + 'square' Square plot; similar to 'scaled', but initially forcing + ``xmax-xmin = ymax-ymin``. + ======== ========================================================== emit : bool, optional - Passed to set_{x,y}lim functions, if observers - are notified of axis limit change + Passed to set_{x,y}lim functions, if observers are notified of axis + limit change. xmin, ymin, xmax, ymax : float, optional - The axis limits to be set + The axis limits to be set. Returns ------- xmin, xmax, ymin, ymax : float - The axis limits + The axis limits. + See also + -------- + matplotlib.axes.Axes.set_xlim + matplotlib.axes.Axes.set_ylim """ if len(v) == 0 and len(kwargs) == 0: @@ -1762,18 +1768,18 @@ def get_yticklines(self): # Adding and tracking artists def _sci(self, im): - """ - helper for :func:`~matplotlib.pyplot.sci`; - do not use elsewhere. + """Set the current image. + + This image will be the target of colormap functions like + `~.pyplot.viridis`, and other functions such as `~.pyplot.clim`. The + current image is an attribute of the current axes. """ if isinstance(im, matplotlib.contour.ContourSet): if im.collections[0] not in self.collections: - raise ValueError( - "ContourSet must be in current Axes") + raise ValueError("ContourSet must be in current Axes") elif im not in self.images and im not in self.collections: - raise ValueError( - "Argument must be an image, collection, or ContourSet in " - "this Axes") + raise ValueError("Argument must be an image, collection, or " + "ContourSet in this Axes") self._current_image = im def _gci(self): @@ -3674,7 +3680,12 @@ def format_coord(self, x, y): return 'x=%s y=%s' % (xs, ys) def minorticks_on(self): - 'Add autoscaling minor ticks to the axes.' + """ + Display minor ticks on the axes. + + Displaying minor ticks may reduce performance; you may turn them off + using `minorticks_off()` if drawing speed is a problem. + """ for ax in (self.xaxis, self.yaxis): scale = ax.get_scale() if scale == 'log': diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index fc99fb6085db..2725094fe077 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -67,7 +67,10 @@ MaxNLocator from matplotlib.backends import pylab_setup + ## Backend detection ## + + def _backend_selection(): """ If rcParams['backend_fallback'] is true, check to see if the @@ -103,8 +106,10 @@ def _backend_selection(): _backend_selection() + ## Global ## + _backend_mod, new_figure_manager, draw_if_interactive, _show = pylab_setup() _IP_REGISTERED = None @@ -306,9 +311,9 @@ def rcdefaults(): draw_all() -# The current "image" (ScalarMappable) is retrieved or set -# only via the pyplot interface using the following two -# functions: +## Current image ## + + def gci(): """ Get the current colorable artist. Specifically, returns the @@ -326,18 +331,9 @@ def gci(): return gcf()._gci() -def sci(im): - """ - Set the current image. This image will be the target of colormap - commands like :func:`~matplotlib.pyplot.jet`, - :func:`~matplotlib.pyplot.hot` or - :func:`~matplotlib.pyplot.clim`). The current image is an - attribute of the current axes. - """ - gca()._sci(im) +## Any Artist ## -## Any Artist ## # (getp is simply imported) @docstring.copy(_setp) def setp(obj, *args, **kwargs): @@ -649,7 +645,8 @@ def close(*args): elif isinstance(arg, Figure): _pylab_helpers.Gcf.destroy_fig(arg) else: - raise TypeError('Unrecognized argument type %s to close' % type(arg)) + raise TypeError('Unrecognized argument type %s to close' + % type(arg)) else: raise TypeError('close takes 0 or 1 arguments') @@ -712,7 +709,8 @@ def waitforbuttonpress(*args, **kwargs): return gcf().waitforbuttonpress(*args, **kwargs) -# Putting things in figures +## Putting things in figures ## + @docstring.copy_dedent(Figure.text) def figtext(x, y, s, *args, **kwargs): @@ -768,6 +766,8 @@ def figlegend(*args, **kwargs): ## Axes ## + + def axes(arg=None, **kwargs): """ Add an axes to the current figure and make it the current axes. @@ -845,7 +845,8 @@ def axes(arg=None, **kwargs): def delaxes(ax=None): """ Remove the given `Axes` *ax* from the current figure. If *ax* is *None*, - the current axes is removed. A KeyError is raised if the axes doesn't exist. + the current axes is removed. A KeyError is raised if the axes doesn't + exist. """ if ax is None: ax = gca() @@ -887,7 +888,8 @@ def gca(**kwargs): """ return gcf().gca(**kwargs) -# More ways of creating axes: + +## More ways of creating axes ## def subplot(*args, **kwargs): @@ -1183,7 +1185,7 @@ def twinx(ax=None): For an example """ if ax is None: - ax=gca() + ax = gca() ax1 = ax.twinx() return ax1 @@ -1196,7 +1198,7 @@ def twiny(ax=None): returned. """ if ax is None: - ax=gca() + ax = gca() ax1 = ax.twiny() return ax1 @@ -1287,150 +1289,9 @@ def box(on=None): ax.set_frame_on(on) -def title(s, *args, **kwargs): - """ - Set a title of the current axes. - - Set one of the three available axes titles. The available titles are - positioned above the axes in the center, flush with the left edge, - and flush with the right edge. - - .. seealso:: - See :func:`~matplotlib.pyplot.text` for adding text - to the current axes - - Parameters - ---------- - label : str - Text to use for the title - - fontdict : dict - A dictionary controlling the appearance of the title text, - the default `fontdict` is: - - {'fontsize': rcParams['axes.titlesize'], - 'fontweight' : rcParams['axes.titleweight'], - 'verticalalignment': 'baseline', - 'horizontalalignment': loc} - - loc : {'center', 'left', 'right'}, str, optional - Which title to set, defaults to 'center' - - Returns - ------- - text : :class:`~matplotlib.text.Text` - The matplotlib text instance representing the title - - Other parameters - ---------------- - kwargs : text properties - Other keyword arguments are text properties, see - :class:`~matplotlib.text.Text` for a list of valid text - properties. - - """ - return gca().set_title(s, *args, **kwargs) - ## Axis ## -def axis(*v, **kwargs): - """ - Convenience method to get or set axis properties. - - Calling with no arguments:: - - >>> axis() - - returns the current axes limits ``[xmin, xmax, ymin, ymax]``.:: - - >>> axis(v) - - sets the min and max of the x and y axes, with - ``v = [xmin, xmax, ymin, ymax]``.:: - - >>> axis('off') - - turns off the axis lines and labels.:: - - >>> axis('equal') - - changes limits of *x* or *y* axis so that equal increments of *x* - and *y* have the same length; a circle is circular.:: - - >>> axis('scaled') - - achieves the same result by changing the dimensions of the plot box instead - of the axis data limits.:: - - >>> axis('tight') - - changes *x* and *y* axis limits such that all data is shown. If - all data is already shown, it will move it to the center of the - figure without modifying (*xmax* - *xmin*) or (*ymax* - - *ymin*). Note this is slightly different than in MATLAB.:: - - >>> axis('image') - - is 'scaled' with the axis limits equal to the data limits.:: - - >>> axis('auto') - - and:: - - >>> axis('normal') - - are deprecated. They restore default behavior; axis limits are automatically - scaled to make the data fit comfortably within the plot box. - - if ``len(*v)==0``, you can pass in *xmin*, *xmax*, *ymin*, *ymax* - as kwargs selectively to alter just those limits without changing - the others. - - >>> axis('square') - - changes the limit ranges (*xmax*-*xmin*) and (*ymax*-*ymin*) of - the *x* and *y* axes to be the same, and have the same scaling, - resulting in a square plot. - - The xmin, xmax, ymin, ymax tuple is returned - - .. seealso:: - - :func:`xlim`, :func:`ylim` - For setting the x- and y-limits individually. - """ - return gca().axis(*v, **kwargs) - - -def xlabel(s, *args, **kwargs): - """ - Set the x-axis label of the current axes. - - Call signature:: - - xlabel(label, fontdict=None, labelpad=None, **kwargs) - - This is the pyplot equivalent of calling `.set_xlabel` on the current axes. - See there for a full parameter description. - """ - return gca().set_xlabel(s, *args, **kwargs) - - -def ylabel(s, *args, **kwargs): - """ - Set the y-axis label of the current axes. - - Call signature:: - - ylabel(label, fontdict=None, labelpad=None, **kwargs) - - This is the pyplot equivalent of calling `.set_ylabel` on the current axes. - See there for a full parameter description. - """ - return gca().set_ylabel(s, *args, **kwargs) - - def xlim(*args, **kwargs): """ Get or set the x limits of the current axes. @@ -1504,54 +1365,6 @@ def ylim(*args, **kwargs): return ret -@docstring.dedent_interpd -def xscale(scale, **kwargs): - """ - Set the scaling of the x-axis. - - Parameters - ---------- - scale : [%(scale)s] - The scaling type. - **kwargs - Additional parameters depend on *scale*. See Notes. - - Notes - ----- - This is the pyplot equivalent of calling `~.Axes.set_xscale` on the - current axes. - - Different keywords may be accepted, depending on the scale: - - %(scale_docs)s - """ - gca().set_xscale(scale, **kwargs) - - -@docstring.dedent_interpd -def yscale(scale, **kwargs): - """ - Set the scaling of the y-axis. - - Parameters - ---------- - scale : [%(scale)s] - The scaling type. - **kwargs - Additional parameters depend on *scale*. See Notes. - - Notes - ----- - This is the pyplot equivalent of calling `~.Axes.set_yscale` on the - current axes. - - Different keywords may be accepted, depending on the scale: - - %(scale_docs)s - """ - gca().set_yscale(scale, **kwargs) - - def xticks(*args, **kwargs): """ Get or set the current tick locations and labels of the x-axis. @@ -1614,19 +1427,19 @@ def xticks(*args, **kwargs): """ ax = gca() - if len(args)==0: + if len(args) == 0: locs = ax.get_xticks() labels = ax.get_xticklabels() - elif len(args)==1: + elif len(args) == 1: locs = ax.set_xticks(args[0]) labels = ax.get_xticklabels() - elif len(args)==2: + elif len(args) == 2: locs = ax.set_xticks(args[0]) labels = ax.set_xticklabels(args[1], **kwargs) - else: raise TypeError('Illegal number of arguments to xticks') - if len(kwargs): - for l in labels: - l.update(kwargs) + else: + raise TypeError('Illegal number of arguments to xticks') + for l in labels: + l.update(kwargs) return locs, silent_list('Text xticklabel', labels) @@ -1693,41 +1506,21 @@ def yticks(*args, **kwargs): """ ax = gca() - if len(args)==0: + if len(args) == 0: locs = ax.get_yticks() labels = ax.get_yticklabels() - elif len(args)==1: + elif len(args) == 1: locs = ax.set_yticks(args[0]) labels = ax.get_yticklabels() - elif len(args)==2: + elif len(args) == 2: locs = ax.set_yticks(args[0]) labels = ax.set_yticklabels(args[1], **kwargs) - else: raise TypeError('Illegal number of arguments to yticks') - if len(kwargs): - for l in labels: - l.update(kwargs) - - - return ( locs, - silent_list('Text yticklabel', labels) - ) - - -def minorticks_on(): - """ - Display minor ticks on the current plot. - - Displaying minor ticks reduces performance; turn them off using - minorticks_off() if drawing speed is a problem. - """ - gca().minorticks_on() - + else: + raise TypeError('Illegal number of arguments to yticks') + for l in labels: + l.update(kwargs) -def minorticks_off(): - """ - Remove minor ticks from the current plot. - """ - gca().minorticks_off() + return locs, silent_list('Text yticklabel', labels) def rgrids(*args, **kwargs): @@ -1837,6 +1630,7 @@ def thetagrids(*args, **kwargs): ## Plotting Info ## + def plotting(): pass @@ -2144,8 +1938,10 @@ def pad(s, l): plotting.__doc__ = '\n'.join(lines) + ## Plotting part 1: manually generated functions and wrappers ## + def colorbar(mappable=None, cax=None, ax=None, **kw): if mappable is None: mappable = gci() @@ -2460,6 +2256,11 @@ def axhline(y=0, xmin=0, xmax=1, **kwargs): def axhspan(ymin, ymax, xmin=0, xmax=1, **kwargs): return gca().axhspan(ymin=ymin, ymax=ymax, xmin=xmin, xmax=xmax, **kwargs) +# Autogenerated by boilerplate.py. Do not edit as changes will be lost. +@docstring.copy_dedent(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) def axvline(x=0, ymin=0, ymax=1, **kwargs): @@ -2712,6 +2513,16 @@ def magnitude_spectrum( def margins(*args, **kw): return gca().margins(*args, **kw) +# Autogenerated by boilerplate.py. Do not edit as changes will be lost. +@docstring.copy_dedent(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) +def minorticks_on(): + return gca().minorticks_on() + # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @_autogen_docstring(Axes.pcolor) def pcolor(*args, data=None, **kwargs): @@ -2947,6 +2758,39 @@ def xcorr( x=x, y=y, normed=normed, detrend=detrend, usevlines=usevlines, maxlags=maxlags, data=data, **kwargs) +# Autogenerated by boilerplate.py. Do not edit as changes will be lost. +@docstring.copy_dedent(Axes._sci) +def sci(im): + return gca()._sci(im=im) + +# Autogenerated by boilerplate.py. Do not edit as changes will be lost. +@docstring.copy_dedent(Axes.set_title) +def title(label, fontdict=None, loc='center', pad=None, **kwargs): + return gca().set_title( + label=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) +def xlabel(xlabel, fontdict=None, labelpad=None, **kwargs): + return gca().set_xlabel( + 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) +def ylabel(ylabel, fontdict=None, labelpad=None, **kwargs): + return gca().set_ylabel( + 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) +def xscale(value, **kwargs): + return gca().set_xscale(value=value, **kwargs) + +# Autogenerated by boilerplate.py. Do not edit as changes will be lost. +@docstring.copy_dedent(Axes.set_yscale) +def yscale(value, **kwargs): + return gca().set_yscale(value=value, **kwargs) + # Autogenerated by boilerplate.py. Do not edit as changes will be lost. def autumn(): """ diff --git a/tools/boilerplate.py b/tools/boilerplate.py index 25bae7c7814b..682fe3b2cef4 100644 --- a/tools/boilerplate.py +++ b/tools/boilerplate.py @@ -40,18 +40,18 @@ CMAPPABLE_TEMPLATE = AUTOGEN_MSG + """ -@_autogen_docstring(Axes.%(func)s) +@_autogen_docstring(Axes.%(real_name)s) def %(func)s%(sig)s: - __ret = gca().%(func)s%(call)s + __ret = gca().%(real_name)s%(call)s %(mappable)s return __ret """ NON_CMAPPABLE_TEMPLATE = AUTOGEN_MSG + """ -@docstring.copy_dedent(Axes.%(func)s) +@docstring.copy_dedent(Axes.%(real_name)s) def %(func)s%(sig)s: - return gca().%(func)s%(call)s + return gca().%(real_name)s%(call)s """ # Used for colormap functions @@ -80,6 +80,7 @@ def boilerplate_gen(): 'autoscale', 'axhline', 'axhspan', + 'axis', 'axvline', 'axvspan', 'bar', @@ -109,6 +110,8 @@ def boilerplate_gen(): 'loglog', 'magnitude_spectrum', 'margins', + 'minorticks_off', + 'minorticks_on', 'pcolor', 'pcolormesh', 'phase_spectrum', @@ -138,6 +141,13 @@ def boilerplate_gen(): 'violinplot', 'vlines', 'xcorr', + # pyplot name : real name + 'sci:_sci', + 'title:set_title', + 'xlabel:set_xlabel', + 'ylabel:set_ylabel', + 'xscale:set_xscale', + 'yscale:set_yscale', ) cmappable = { @@ -182,7 +192,12 @@ def __repr__(self): break_long_words=False, width=70, initial_indent=' ' * 8, subsequent_indent=' ' * 8) - for func in _commands: + for spec in _commands: + if ':' in spec: + func, real_name = spec.split(':') + else: + func = real_name = spec + # For some commands, an additional line is needed to set the color map. if func in cmappable: fmt = CMAPPABLE_TEMPLATE @@ -191,7 +206,7 @@ def __repr__(self): fmt = NON_CMAPPABLE_TEMPLATE # Get signature of wrapped function. - sig = inspect.signature(getattr(Axes, func)) + sig = inspect.signature(getattr(Axes, real_name)) # Replace self argument. params = list(sig.parameters.values())[1:]