set_xlim, set_ylim accept descriptive kwargs: left, right, bottom, top

efiring · efiring · commit 9ca5db03f692 · 2010-07-05T20:47:39.000Z
svn path=/trunk/matplotlib/; revision=8496
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,7 +1,11 @@
+2010-07-05 Preferred kwarg names in set_xlim are now 'left' and
+           'right'; in set_ylim, 'bottom' and 'top'; original
+           kwargs are still accepted without complaint. - EF
+
 2010-07-05 TkAgg and FltkAgg backends are now consistent with other
            interactive backends: when used in scripts from the
            command line (not from ipython -pylab), show blocks,
-           and can be called more than once.
+           and can be called more than once. - EF
 
 2010-07-02 Modified CXX/WrapPython.h to fix "swab bug" on solaris so
            mpl can compile on Solaris with CXX6 in the trunk.  Closes
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -16,7 +16,10 @@ Changes beyond 0.99.x
   pyplot functions, has been changed: when view limits are
   set explicitly with one of these methods, autoscaling is turned
   off for the matching axis. A new *auto* kwarg is available to
-  control this behavior.
+  control this behavior. The limit kwargs have been renamed to
+  *left* and *right* instead of *xmin* and *xmax*, and *bottom*
+  and *top* instead of *ymin* and *ymax*.  The old names may still
+  be used, however.
 
 * There are five new Axes methods with corresponding pyplot
   functions to facilitate autoscaling, tick location, and tick
diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py
@@ -2298,11 +2298,11 @@ def set_xbound(self, lower=None, upper=None):
 
     def get_xlim(self):
         """
-        Get the x-axis range [*xmin*, *xmax*]
+        Get the x-axis range [*left*, *right*]
         """
         return tuple(self.viewLim.intervalx)
 
-    def set_xlim(self, xmin=None, xmax=None, emit=True, auto=False):
+    def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw):
         """
         call signature::
 
@@ -2314,23 +2314,23 @@ def set_xlim(self, xmin=None, xmax=None, emit=True, auto=False):
 
           set_xlim((left, right))
           set_xlim(left, right)
-          set_xlim(xmin=1) # right unchanged
-          set_xlim(xmax=1) # left unchanged
+          set_xlim(left=1) # right unchanged
+          set_xlim(right=1) # left unchanged
 
         Keyword arguments:
 
-          *xmin*: scalar
-            the left xlim
-          *xmax*: scalar
-            the right xlim
+          *left*: scalar
+            the left xlim; *xmin*, the previous name, may still be used
+          *right*: scalar
+            the right xlim; *xmax*, the previous name, may still be used
           *emit*: [ True | False ]
             notify observers of lim change
           *auto*: [ True | False | None ]
             turn *x* autoscaling on (True), off (False; default),
             or leave unchanged (None)
 
-        Note: the kwarg terminology may be confusing.  The first value,
-        *xmin*, is the left, and the second, *xmax*, is the 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::
 
@@ -2343,26 +2343,34 @@ def set_xlim(self, xmin=None, xmax=None, emit=True, auto=False):
 
         ACCEPTS: len(2) sequence of floats
         """
-        if xmax is None and iterable(xmin):
-            xmin,xmax = xmin
-
-
-        self._process_unit_info(xdata=(xmin, xmax))
-        if xmin is not None:
-            xmin = self.convert_xunits(xmin)
-        if xmax is not None:
-            xmax = self.convert_xunits(xmax)
-
-        old_xmin,old_xmax = self.get_xlim()
-        if xmin is None: xmin = old_xmin
-        if xmax is None: xmax = old_xmax
-
-        if xmin==xmax:
-            warnings.warn('Attempting to set identical xmin==xmax results in singular transformations; automatically expanding.  xmin=%s, xmax=%s'%(xmin, xmax))
-        xmin, xmax = mtransforms.nonsingular(xmin, xmax, increasing=False)
-        xmin, xmax = self.xaxis.limit_range_for_scale(xmin, xmax)
-
-        self.viewLim.intervalx = (xmin, xmax)
+        if 'xmin' in kw:
+            left = kw.pop('xmin')
+        if 'xmax' in kw:
+            right = kw.pop('xmax')
+        if kw:
+            raise ValueError("unrecognized kwargs: %s" % kw.keys())
+
+        if right is None and iterable(left):
+            left,right = left
+
+        self._process_unit_info(xdata=(left, right))
+        if left is not None:
+            left = self.convert_xunits(left)
+        if right is not None:
+            right = self.convert_xunits(right)
+
+        old_left, old_right = self.get_xlim()
+        if left is None: left = old_left
+        if right is None: right = old_right
+
+        if left==right:
+            warnings.warn(('Attempting to set identical left==right results\n'
+                   + 'in singular transformations; automatically expanding.\n'
+                   + 'left=%s, right=%s') % (left, right))
+        left, right = mtransforms.nonsingular(left, right, increasing=False)
+        left, right = self.xaxis.limit_range_for_scale(left, right)
+
+        self.viewLim.intervalx = (left, right)
         if auto is not None:
             self._autoscaleXon = bool(auto)
 
@@ -2377,7 +2385,7 @@ def set_xlim(self, xmin=None, xmax=None, emit=True, auto=False):
                         other.figure.canvas is not None):
                         other.figure.canvas.draw_idle()
 
-        return xmin, xmax
+        return left, right
 
     def get_xscale(self):
         'return the xaxis scale string: %s' % (
@@ -2492,11 +2500,11 @@ def set_ybound(self, lower=None, upper=None):
 
     def get_ylim(self):
         """
-        Get the y-axis range [*ymin*, *ymax*]
+        Get the y-axis range [*bottom*, *top*]
         """
         return tuple(self.viewLim.intervaly)
 
-    def set_ylim(self, ymin=None, ymax=None, emit=True, auto=False):
+    def set_ylim(self, bottom=None, top=None, emit=True, auto=False, **kw):
         """
         call signature::
 
@@ -2508,23 +2516,23 @@ def set_ylim(self, ymin=None, ymax=None, emit=True, auto=False):
 
           set_ylim((bottom, top))
           set_ylim(bottom, top)
-          set_ylim(ymin=1) # top unchanged
-          set_ylim(ymax=1) # bottom unchanged
+          set_ylim(bottom=1) # top unchanged
+          set_ylim(top=1) # bottom unchanged
 
         Keyword arguments:
 
-          *ymin*: scalar
-            the bottom ylim
-          *ymax*: scalar
-            the top ylim
+          *bottom*: scalar
+            the bottom ylim; the previous name, *ymin*, may still be used
+          *top*: scalar
+            the top ylim; the previous name, *ymax*, may still be used
           *emit*: [ True | False ]
             notify observers of lim change
           *auto*: [ True | False | None ]
             turn *y* autoscaling on (True), off (False; default),
             or leave unchanged (None)
 
-        Note: the kwarg terminology may be confusing.  The first value,
-        *ymin*, is the bottom, and the second, *ymax*, is the 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::
 
@@ -2537,26 +2545,35 @@ def set_ylim(self, ymin=None, ymax=None, emit=True, auto=False):
 
         ACCEPTS: len(2) sequence of floats
         """
-        if ymax is None and iterable(ymin):
-            ymin,ymax = ymin
+        if 'ymin' in kw:
+            bottom = kw.pop('ymin')
+        if 'ymax' in kw:
+            top = kw.pop('ymax')
+        if kw:
+            raise ValueError("unrecognized kwargs: %s" % kw.keys())
+
+        if top is None and iterable(bottom):
+            bottom,top = bottom
 
-        if ymin is not None:
-            ymin = self.convert_yunits(ymin)
-        if ymax is not None:
-            ymax = self.convert_yunits(ymax)
+        if bottom is not None:
+            bottom = self.convert_yunits(bottom)
+        if top is not None:
+            top = self.convert_yunits(top)
 
-        old_ymin,old_ymax = self.get_ylim()
+        old_bottom, old_top = self.get_ylim()
 
-        if ymin is None: ymin = old_ymin
-        if ymax is None: ymax = old_ymax
+        if bottom is None: bottom = old_bottom
+        if top is None: top = old_top
 
-        if ymin==ymax:
-            warnings.warn('Attempting to set identical ymin==ymax results in singular transformations; automatically expanding.  ymin=%s, ymax=%s'%(ymin, ymax))
+        if bottom==top:
+            warnings.warn(('Attempting to set identical bottom==top results\n'
+                   + 'in singular transformations; automatically expanding.\n'
+                   + 'bottom=%s, top=%s') % (bottom, top))
 
-        ymin, ymax = mtransforms.nonsingular(ymin, ymax, increasing=False)
-        ymin, ymax = self.yaxis.limit_range_for_scale(ymin, ymax)
+        bottom, top = mtransforms.nonsingular(bottom, top, increasing=False)
+        bottom, top = self.yaxis.limit_range_for_scale(bottom, top)
 
-        self.viewLim.intervaly = (ymin, ymax)
+        self.viewLim.intervaly = (bottom, top)
         if auto is not None:
             self._autoscaleYon = bool(auto)
 
@@ -2571,7 +2588,7 @@ def set_ylim(self, ymin=None, ymax=None, emit=True, auto=False):
                         other.figure.canvas is not None):
                         other.figure.canvas.draw_idle()
 
-        return ymin, ymax
+        return bottom, top
 
     def get_yscale(self):
         'return the xaxis scale string: %s' % (
