From a2b990dda73b314ab62f2e573b62fe79f45b88e9 Mon Sep 17 00:00:00 2001 From: Cameron Fackler Date: Mon, 31 Oct 2016 20:23:40 -0400 Subject: [PATCH 1/4] Convert docstring for set_xlim(), per issue #7205 Convert set_xlim() docstring to numpydoc format. --- lib/matplotlib/axes/_base.py | 65 ++++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 25 deletions(-) diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index ba2db57a3e9f..fde425ef6a7b 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2789,43 +2789,58 @@ def get_xlim(self): def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw): """ - Set the data limits for the xaxis + Set the data limits for the x-axis - Examples:: + Parameters + ---------- + left : scalar, optional + The left xlim (default: None, which leaves the left limit + unchanged). The previous name `xmin` may be used instead. - set_xlim((left, right)) - set_xlim(left, right) - set_xlim(left=1) # right unchanged - set_xlim(right=1) # left unchanged + right : scalar, optional + The right xlim (default: None, which leaves the right limit + unchanged). The previous name `xmax` may be used instead. - Keyword arguments: + emit : bool, optional + Whether to notify observers of limit change (default: True). - *left*: scalar - The left xlim; *xmin*, the previous name, may still be used + auto : {True, False, None}, optional + Whether to turn on autoscaling of the x-axis. True turns on, + False turns off (default action), None leaves unchanged. - *right*: scalar - The right xlim; *xmax*, the previous name, may still be used + xlimits : tuple, optional + The left and right xlims may be passed as the tuple + (`left`, `right`) as the first positional argument (or as + the `left` keyword argument). - *emit*: [ *True* | *False* ] - Notify observers of limit change + Returns + ------- + xlimits : tuple + Returns the current x-axis limits, reflecting any changes + made by this call, as (`left`, `right`). - *auto*: [ *True* | *False* | *None* ] - Turn *x* autoscaling on (*True*), off (*False*; default), - or leave unchanged (*None*) + Notes + ----- + The `left` value may be greater than the `right` value, in which + case the x-axis values will decrease from left to right. - Note, the *left* (formerly *xmin*) value may be greater than - the *right* (formerly *xmax*). - For example, suppose *x* is years before present. - Then one might use:: + Examples + -------- + >>> set_xlim(left, right) + >>> set_xlim((left, right)) + >>> left, right = set_xlim(left, right) - set_xlim(5000, 0) + One limit may be left unchanged. - so 5000 years ago is on the left of the plot and the - present is on the right. + >>> set_xlim(right=right_lim) - Returns the current xlimits as a length 2 tuple + Limits may be passed in reverse order. For example, suppose `x` + represents the number of years before present. The x-axis limits + might be set like the following so 5000 years ago is on the left + of the plot and the present is on the right. + + >>> set_xlim(5000, 0) - ACCEPTS: length 2 sequence of floats """ if 'xmin' in kw: left = kw.pop('xmin') From 49a8d835f6c7ce4eab6e0e85f7c0ac31c3fd90a9 Mon Sep 17 00:00:00 2001 From: Cameron Fackler Date: Mon, 31 Oct 2016 23:25:13 -0400 Subject: [PATCH 2/4] Convert set_xlim and set_ylim docstrings; #7205 Docstrings converted to numpydoc format. --- lib/matplotlib/axes/_base.py | 78 ++++++++++++++++++++++-------------- 1 file changed, 48 insertions(+), 30 deletions(-) diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index fde425ef6a7b..cc0106951a18 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2804,7 +2804,7 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw): emit : bool, optional Whether to notify observers of limit change (default: True). - auto : {True, False, None}, optional + auto : bool or None, optional Whether to turn on autoscaling of the x-axis. True turns on, False turns off (default action), None leaves unchanged. @@ -2834,10 +2834,11 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw): >>> set_xlim(right=right_lim) - Limits may be passed in reverse order. For example, suppose `x` - represents the number of years before present. The x-axis limits - might be set like the following so 5000 years ago is on the left - of the plot and the present is on the right. + Limits may be passed in reverse order to flip the direction of + the x-axis. For example, suppose `x` represents the number of + years before present. The x-axis limits might be set like the + following so 5000 years ago is on the left of the plot and the + present is on the right. >>> set_xlim(5000, 0) @@ -3058,43 +3059,60 @@ def get_ylim(self): def set_ylim(self, bottom=None, top=None, emit=True, auto=False, **kw): """ - Set the data limits for the yaxis + Set the data limits for the y-axis - Examples:: + Parameters + ---------- + bottom : scalar, optional + The bottom ylim (default: None, which leaves the bottom + limit unchanged). The previous name `ymin` may be used + instead. - set_ylim((bottom, top)) - set_ylim(bottom, top) - set_ylim(bottom=1) # top unchanged - set_ylim(top=1) # bottom unchanged + top : scalar, optional + The top ylim (default: None, which leaves the top limit + unchanged). The previous name `ymax` may be used instead. - Keyword arguments: + emit : bool, optional + Whether to notify observers of limit change (default: True). - *bottom*: scalar - The bottom ylim; the previous name, *ymin*, may still be used + auto : bool or None, optional + Whether to turn on autoscaling of the y-axis. True turns on, + False turns off (default action), None leaves unchanged. - *top*: scalar - The top ylim; the previous name, *ymax*, may still be used + ylimits : tuple, optional + The bottom and top yxlims may be passed as the tuple + (`bottom`, `top`) as the first positional argument (or as + the `bottom` keyword argument). - *emit*: [ *True* | *False* ] - Notify observers of limit change + Returns + ------- + ylimits : tuple + Returns the current y-axis limits, reflecting any changes + made by this call, as (`bottom`, `top`). - *auto*: [ *True* | *False* | *None* ] - Turn *y* autoscaling on (*True*), off (*False*; default), - or leave unchanged (*None*) + Notes + ----- + The `bottom` value may be greater than the `top` value, in which + case the y-axis values will decrease from bottom to top. - Note, the *bottom* (formerly *ymin*) value may be greater than - the *top* (formerly *ymax*). - For example, suppose *y* is depth in the ocean. - Then one might use:: + Examples + -------- + >>> set_ylim(bottom, top) + >>> set_ylim((bottom, top)) + >>> bottom, top = set_ylim(bottom, top) + + One limit may be left unchanged. - set_ylim(5000, 0) + >>> set_ylim(top=top_lim) - so 5000 m depth is at the bottom of the plot and the - surface, 0 m, is at the top. + Limits may be passed in reverse order to flip the direction of + the y-axis. For example, suppose `y` represents depth of the + ocean in m. The y-axis limits might be set like the following + so 5000 m depth is at the bottom of the plot and the surface, + 0 m, is at the top. - Returns the current ylimits as a length 2 tuple + >>> set_ylim(5000, 0) - ACCEPTS: length 2 sequence of floats """ if 'ymin' in kw: bottom = kw.pop('ymin') From 349909eb8cd0220b8dce46adff089180f2b4d51f Mon Sep 17 00:00:00 2001 From: Cameron Fackler Date: Wed, 2 Nov 2016 23:26:44 -0400 Subject: [PATCH 3/4] Convert get_xlim and get_ylim docstrings --- lib/matplotlib/axes/_base.py | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index cc0106951a18..3c0d5775264d 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2783,7 +2783,19 @@ def set_xbound(self, lower=None, upper=None): def get_xlim(self): """ - Get the x-axis range [*left*, *right*] + Get the x-axis range + + Returns + ------- + xlimits : tuple + Returns the current x-axis limits as the tuple + (`left`, `right`). + + Notes + ----- + The x-axis may be inverted, in which case the `left` value will + be greater than the `right` value. + """ return tuple(self.viewLim.intervalx) @@ -3053,7 +3065,19 @@ def set_ybound(self, lower=None, upper=None): def get_ylim(self): """ - Get the y-axis range [*bottom*, *top*] + Get the y-axis range + + Returns + ------- + ylimits : tuple + Returns the current y-axis limits as the tuple + (`bottom`, `top`). + + Notes + ----- + The y-axis may be inverted, in which case the `bottom` value + will be greater than the `top` value. + """ return tuple(self.viewLim.intervaly) From 803a05fa52d6d09c21b3ddd8064e77f3b6e81eb6 Mon Sep 17 00:00:00 2001 From: Cameron Fackler Date: Sun, 6 Nov 2016 18:06:32 -0500 Subject: [PATCH 4/4] DOC Remove old API notes from updated docstrings --- lib/matplotlib/axes/_base.py | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index 3c0d5775264d..e179498e30ab 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2807,11 +2807,11 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw): ---------- left : scalar, optional The left xlim (default: None, which leaves the left limit - unchanged). The previous name `xmin` may be used instead. + unchanged). right : scalar, optional The right xlim (default: None, which leaves the right limit - unchanged). The previous name `xmax` may be used instead. + unchanged). emit : bool, optional Whether to notify observers of limit change (default: True). @@ -2828,8 +2828,7 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw): Returns ------- xlimits : tuple - Returns the current x-axis limits, reflecting any changes - made by this call, as (`left`, `right`). + Returns the new x-axis limits as (`left`, `right`). Notes ----- @@ -3089,12 +3088,11 @@ def set_ylim(self, bottom=None, top=None, emit=True, auto=False, **kw): ---------- bottom : scalar, optional The bottom ylim (default: None, which leaves the bottom - limit unchanged). The previous name `ymin` may be used - instead. + limit unchanged). top : scalar, optional The top ylim (default: None, which leaves the top limit - unchanged). The previous name `ymax` may be used instead. + unchanged). emit : bool, optional Whether to notify observers of limit change (default: True). @@ -3111,8 +3109,7 @@ def set_ylim(self, bottom=None, top=None, emit=True, auto=False, **kw): Returns ------- ylimits : tuple - Returns the current y-axis limits, reflecting any changes - made by this call, as (`bottom`, `top`). + Returns the new y-axis limits as (`bottom`, `top`). Notes -----