From cabc0534be24ffa3c3e2433014e2b4a06a85e4df Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Fri, 12 Apr 2019 14:45:53 +0200 Subject: [PATCH 1/3] numpydocify quiverkey. --- doc/api/index.rst | 1 + doc/api/next_api_changes/2019-04-14-AL.rst | 5 + doc/api/quiver_api.rst | 20 ++++ lib/matplotlib/axes/_axes.py | 2 +- lib/matplotlib/quiver.py | 123 +++++++++------------ 5 files changed, 80 insertions(+), 71 deletions(-) create mode 100644 doc/api/next_api_changes/2019-04-14-AL.rst create mode 100644 doc/api/quiver_api.rst diff --git a/doc/api/index.rst b/doc/api/index.rst index 270678d51c91..60cbc279dad5 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -55,6 +55,7 @@ Modules patheffects_api.rst pyplot_summary.rst projections_api.rst + quiver_api.rst rcsetup_api.rst sankey_api.rst scale_api.rst diff --git a/doc/api/next_api_changes/2019-04-14-AL.rst b/doc/api/next_api_changes/2019-04-14-AL.rst new file mode 100644 index 000000000000..e5a8b3732729 --- /dev/null +++ b/doc/api/next_api_changes/2019-04-14-AL.rst @@ -0,0 +1,5 @@ +Deprecations +```````````` + +``quiver.QuiverKey.quiverkey_doc`` is deprecated; use +``quiver.QuiverKey.__init__.__doc__`` instead. diff --git a/doc/api/quiver_api.rst b/doc/api/quiver_api.rst new file mode 100644 index 000000000000..8dbcce61beb5 --- /dev/null +++ b/doc/api/quiver_api.rst @@ -0,0 +1,20 @@ +********************* +``matplotlib.quiver`` +********************* + +.. currentmodule:: matplotlib.quiver + +.. automodule:: matplotlib.quiver + :no-members: + :no-inherited-members: + +Classes +------- + +.. autosummary:: + :toctree: _as_gen/ + :template: autosummary.rst + + Quiver + QuiverKey + Barbs diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 60a2cce43d40..9330061c2c17 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -4991,11 +4991,11 @@ def arrow(self, x, y, dx, dy, **kwargs): self.add_artist(a) return a + @docstring.copy(mquiver.QuiverKey.__init__) def quiverkey(self, Q, X, Y, U, label, **kw): qk = mquiver.QuiverKey(Q, X, Y, U, label, **kw) self.add_artist(qk) return qk - quiverkey.__doc__ = mquiver.QuiverKey.quiverkey_doc # Handle units for x and y, if they've been passed def _quiver_units(self, args, kw): diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py index 1fc3c63dab3c..60a1f137101f 100644 --- a/lib/matplotlib/quiver.py +++ b/lib/matplotlib/quiver.py @@ -163,74 +163,9 @@ quiverkey : Add a key to a quiver plot """ % docstring.interpd.params -_quiverkey_doc = """ -Add a key to a quiver plot. - -Call signature:: - - quiverkey(Q, X, Y, U, label, **kw) - -Arguments: - - *Q*: - The Quiver instance returned by a call to quiver. - - *X*, *Y*: - The location of the key; additional explanation follows. - - *U*: - The length of the key - - *label*: - A string with the length and units of the key - -Keyword arguments: - - *angle* = 0 - The angle of the key arrow. Measured in degrees anti-clockwise from the - x-axis. - - *coordinates* = [ 'axes' | 'figure' | 'data' | 'inches' ] - Coordinate system and units for *X*, *Y*: 'axes' and 'figure' are - normalized coordinate systems with 0,0 in the lower left and 1,1 - in the upper right; 'data' are the axes data coordinates (used for - the locations of the vectors in the quiver plot itself); 'inches' - is position in the figure in inches, with 0,0 at the lower left - corner. - - *color*: - overrides face and edge colors from *Q*. - - *labelpos* = [ 'N' | 'S' | 'E' | 'W' ] - Position the label above, below, to the right, to the left of the - arrow, respectively. - - *labelsep*: - Distance in inches between the arrow and the label. Default is - 0.1 - - *labelcolor*: - defaults to default :class:`~matplotlib.text.Text` color. - - *fontproperties*: - A dictionary with keyword arguments accepted by the - :class:`~matplotlib.font_manager.FontProperties` initializer: - *family*, *style*, *variant*, *size*, *weight* - -Any additional keyword arguments are used to override vector -properties taken from *Q*. - -The positioning of the key depends on *X*, *Y*, *coordinates*, and -*labelpos*. If *labelpos* is 'N' or 'S', *X*, *Y* give the position -of the middle of the key arrow. If *labelpos* is 'E', *X*, *Y* -positions the head, and if *labelpos* is 'W', *X*, *Y* positions the -tail; in either of these two cases, *X*, *Y* is somewhere in the -middle of the arrow+label key object. -""" - class QuiverKey(martist.Artist): - """ Labelled arrow for use as a quiver plot scale key.""" + """Labelled arrow for use as a quiver plot scale key.""" halign = {'N': 'center', 'S': 'center', 'E': 'left', 'W': 'right'} valign = {'N': 'bottom', 'S': 'top', 'E': 'center', 'W': 'center'} pivot = {'N': 'middle', 'S': 'middle', 'E': 'tip', 'W': 'tail'} @@ -239,6 +174,53 @@ def __init__(self, Q, X, Y, U, label, *, angle=0, coordinates='axes', color=None, labelsep=0.1, labelpos='N', labelcolor=None, fontproperties=None, **kw): + """ + Add a key to a quiver plot. + + The positioning of the key depends on *X*, *Y*, *coordinates*, and + *labelpos*. If *labelpos* is 'N' or 'S', *X*, *Y* give the position of + the middle of the key arrow. If *labelpos* is 'E', *X*, *Y* positions + the head, and if *labelpos* is 'W', *X*, *Y* positions the tail; in + either of these two cases, *X*, *Y* is somewhere in the middle of the + arrow+label key object. + + Parameters + ---------- + Q : `Quiver` + A `Quiver` object as returned by a call to `~Axes.quiver()`. + X, Y: float + The location of the key. + U : float + The length of the key + label : str + The key label (e.g., length and units of the key). + angle : float, default: 0 + The angle of the key arrow, in degrees anti-clockwise from the + x-axis. + coordinates : {'axes', 'figure', 'data', 'inches'}, default: 'axes' + Coordinate system and units for *X*, *Y*: 'axes' and 'figure' are + normalized coordinate systems with 0,0 in the lower left and 1,1 + in the upper right; 'data' are the axes data coordinates (used for + the locations of the vectors in the quiver plot itself); 'inches' + is position in the figure in inches, with 0,0 at the lower left + corner. + color : color + Overrides face and edge colors from *Q*. + labelpos : {'N', 'S', 'E', 'W'} + Position the label above, below, to the right, to the left of the + arrow, respectively. + labelsep : float, default: 0.1 + Distance in inches between the arrow and the label. + labelcolor : color, default: :rc:`text.color` + Label color. + fontproperties : dict, optional + A dictionary with keyword arguments accepted by the + `~matplotlib.font_manager.FontProperties` initializer: + *family*, *style*, *variant*, *size*, *weight* + **kwargs + Any additional keyword arguments are used to override vector + properties taken from *Q*. + """ martist.Artist.__init__(self) self.Q = Q self.X = X @@ -292,8 +274,6 @@ def remove(self): # pass the remove call up the stack martist.Artist.remove(self) - __init__.__doc__ = _quiverkey_doc - def _init(self): if True: # not self._initialized: if not self.Q._initialized: @@ -374,7 +354,10 @@ def contains(self, mouseevent): return True, {} return False, {} - quiverkey_doc = _quiverkey_doc + @cbook.deprecated("3.2") + @property + def quiverkey_doc(self): + return self.__init__.__doc__ # This is a helper function that parses out the various combination of @@ -690,7 +673,7 @@ def _make_verts(self, U, V, angles): return XY def _h_arrows(self, length): - """ length is in arrow width units """ + """Length is in arrow width units.""" # It might be possible to streamline the code # and speed it up a bit by using complex (x,y) # instead of separate arrays; but any gain would be slight. From 51f5c91b275dff80dc85e4a0af87c1f68edb3232 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sun, 14 Apr 2019 21:33:27 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-Authored-By: anntzer --- lib/matplotlib/quiver.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py index 60a1f137101f..44d0c2fa5b29 100644 --- a/lib/matplotlib/quiver.py +++ b/lib/matplotlib/quiver.py @@ -186,8 +186,8 @@ def __init__(self, Q, X, Y, U, label, Parameters ---------- - Q : `Quiver` - A `Quiver` object as returned by a call to `~Axes.quiver()`. + Q : `matplotlib.quiver.Quiver` + A `.Quiver` object as returned by a call to `~.Axes.quiver()`. X, Y: float The location of the key. U : float From 32211b8fd7992a6252f28c9f2aef30aee86d1aa7 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Mon, 15 Apr 2019 00:25:01 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-Authored-By: anntzer --- lib/matplotlib/quiver.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py index 44d0c2fa5b29..6bb3226c9bf3 100644 --- a/lib/matplotlib/quiver.py +++ b/lib/matplotlib/quiver.py @@ -188,10 +188,10 @@ def __init__(self, Q, X, Y, U, label, ---------- Q : `matplotlib.quiver.Quiver` A `.Quiver` object as returned by a call to `~.Axes.quiver()`. - X, Y: float + X, Y : float The location of the key. U : float - The length of the key + The length of the key. label : str The key label (e.g., length and units of the key). angle : float, default: 0 @@ -216,7 +216,7 @@ def __init__(self, Q, X, Y, U, label, fontproperties : dict, optional A dictionary with keyword arguments accepted by the `~matplotlib.font_manager.FontProperties` initializer: - *family*, *style*, *variant*, *size*, *weight* + *family*, *style*, *variant*, *size*, *weight*. **kwargs Any additional keyword arguments are used to override vector properties taken from *Q*.