matplotlib · anntzer · Sep 9, 2017 · Sep 9, 2017 · Sep 9, 2017 · Sep 9, 2017
diff --git a/.appveyor.yml b/.appveyor.yml
@@ -86,7 +86,7 @@ install:
     mock sphinx pandas
   - activate test-environment
   - echo %PYTHON_VERSION% %TARGET_ARCH%
-  - if %PYTHON_VERSION% == 2.7 conda install -q backports.functools_lru_cache
+  - if %PYTHON_VERSION% == 2.7 conda install -q backports.functools_lru_cache funcsigs
   # pytest-cov>=2.3.1 due to https://github.com/pytest-dev/pytest-cov/issues/124
   - pip install -q pytest "pytest-cov>=2.3.1" pytest-rerunfailures pytest-timeout
 

diff --git a/INSTALL.rst b/INSTALL.rst
@@ -187,6 +187,7 @@ Matplotlib requires a large number of dependencies:
   * `six <https://pypi.python.org/pypi/six>`_
   * `backports.functools_lru_cache <https://pypi.python.org/pypi/backports.functools_lru_cache>`_
     (for Python 2.7 only)
+  * `funcsigs <https://pypi.python.org/pypi/funcsigs>`_ (for Python 2.7 only)
   * `subprocess32 <https://pypi.python.org/pypi/subprocess32/>`_ (for Python
     2.7 only, on Linux and macOS only)
 
@@ -332,7 +333,7 @@ without fiddling with environment variables::
   # this package is only available in the conda-forge channel
   conda install -c conda-forge msinttypes
   # for Python 2.7
-  conda install -c conda-forge backports.functools_lru_cache
+  conda install -c conda-forge backports.functools_lru_cache funcsigs
 
   # copy the libs which have "wrong" names
   set LIBRARY_LIB=%CONDA_DEFAULT_ENV%\Library\lib

diff --git a/build_alllocal.cmd b/build_alllocal.cmd
@@ -7,7 +7,7 @@
 :: # this package is only available in the conda-forge channel
 :: conda install -c conda-forge msinttypes
 :: if you build on py2.7:
-:: conda install -c conda-forge backports.functools_lru_cache
+:: conda install -c conda-forge backports.functools_lru_cache funcsigs
 
 set TARGET=bdist_wheel
 IF [%1]==[] (

diff --git a/ci/conda_recipe/meta.yaml b/ci/conda_recipe/meta.yaml
@@ -40,6 +40,7 @@ requirements:
     - pyqt  # [not osx]
     - tk 8.5* # [linux]
     - backports.functools_lru_cache  # [py2k]
+    - funcsigs  # [py2k]
 
   run:
     - python
@@ -55,6 +56,7 @@ requirements:
     - pyqt  # [not osx]
     - tk 8.5*  # [linux and win]
     - backports.functools_lru_cache  # [py2k]
+    - funcsigs  # [py2k]
 
 test:
     imports:

diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -230,7 +230,7 @@ def get_ylabel(self):
 
     def set_ylabel(self, ylabel, fontdict=None, labelpad=None, **kwargs):
         """
-        Set the label for the yaxis
+        Set the label for the yaxis.
 
         Parameters
         ----------

diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1488,45 +1488,40 @@ 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 axis properties.
 
         Valid signatures::
 
-          xmin, xmax, ymin, ymax = axis()
-          xmin, xmax, ymin, ymax = axis(list_arg)
-          xmin, xmax, ymin, ymax = axis(string_arg)
-          xmin, xmax, ymin, ymax = axis(**kwargs)
+          xmin, xmax, ymin, ymax = axis(*, emit=True)
+          xmin, xmax, ymin, ymax = axis(_string_arg_, *, emit=True)
+          xmin, xmax, ymin, ymax = axis([xmin, ymin, xmax, ymax], *, emit=True)
 
         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
-                ========== ================================================
-
-        emit : bool, optional
-            Passed to set_{x,y}lim functions, if observers
-            are notified of axis limit change
+        _string_arg_ : str, optional
+
+            The following values are allowed:
+
+            ========== =======================================================
+            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
+            'image'    'scaled' with axis limits equal to data limits
+            'square'   Square plot; similar to 'scaled', but initially forcing
+                       ``xmax-xmin = ymax-ymin``
+            ========== =======================================================
 
         xmin, ymin, xmax, ymax : float, optional
             The axis limits to be set
 
+        emit : bool, optional
+            Whether observers are notified of axes limit changes.
+
         Returns
         -------
         xmin, xmax, ymin, ymax : float
@@ -1547,17 +1542,15 @@ def axis(self, *v, **kwargs):
                 self.set_axis_on()
             elif s == 'off':
                 self.set_axis_off()
-            elif s in ('equal', 'tight', 'scaled', 'normal',
-                       'auto', 'image', 'square'):
+            elif s in ['equal', 'tight', 'scaled', 'auto', 'image', 'square']:
                 self.set_autoscale_on(True)
                 self.set_aspect('auto')
                 self.autoscale_view(tight=False)
-                # self.apply_aspect()
                 if s == 'equal':
                     self.set_aspect('equal', adjustable='datalim')
                 elif s == 'scaled':
                     self.set_aspect('equal', adjustable='box', anchor='C')
-                    self.set_autoscale_on(False)  # Req. by Mark Bakker
+                    self.set_autoscale_on(False)
                 elif s == 'tight':
                     self.autoscale_view(tight=True)
                     self.set_autoscale_on(False)
@@ -2950,7 +2943,7 @@ def get_xscale(self):
 
     def set_xscale(self, value, **kwargs):
         """
-        Set the x-axis scale
+        Set the x-axis scale.
 
         Parameters
         ----------
@@ -3257,7 +3250,7 @@ def get_yscale(self):
 
     def set_yscale(self, value, **kwargs):
         """
-        Set the y-axis scale
+        Set the y-axis scale.
 
         Parameters
         ----------

diff --git a/lib/matplotlib/docstring.py b/lib/matplotlib/docstring.py
@@ -4,52 +4,53 @@
 import six
 
 from matplotlib import cbook
-import sys
-import types
 
 
 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 ValueError("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__:
+            if six.PY2:
+                getattr(func, "im_func", func).__doc__ %= self.params
+            else:
+                func.__doc__ %= self.params
         return func
 
     def update(self, *args, **kwargs):
-        "Assume self.params is a dict and update it with supplied args"
+        """Assume self.params is a dict and update it with supplied args."""
         self.params.update(*args, **kwargs)
 
     @classmethod
+    @cbook.deprecated("2.2")
     def from_params(cls, params):
         """
         In the case where the params is a mutable sequence (list or
@@ -62,6 +63,7 @@ def from_params(cls, params):
         return result
 
 
+@cbook.deprecated("2.2")
 class Appender(object):
     """
     A function decorator that will append an addendum to the docstring
@@ -86,43 +88,52 @@ def __init__(self, addendum, join=''):
         self.join = join
 
     def __call__(self, func):
-        docitems = [func.__doc__, self.addendum]
-        func.__doc__ = func.__doc__ and self.join.join(docitems)
+        if func.__doc__:
+            func.__doc__ = self.join.join([func.__doc__, self.addendum])
         return func
 
 
+@cbook.deprecated("2.2")
 def dedent(func):
-    "Dedent a docstring (if present)"
-    func.__doc__ = func.__doc__ and cbook.dedent(func.__doc__)
+    """Dedent a docstring (if present)."""
+    if func.__doc__:
+        if six.PY2:
+            getattr(func, "im_func", func).__doc__ = cbook.dedent(func.__doc__)
+        else:
+            func.__doc__ = cbook.dedent(func.__doc__)
     return func
 
 
+@cbook.deprecated("2.2")
 def copy(source):
-    "Copy a docstring from another source function (if present)"
-    def do_copy(target):
+    """A decorator that copies the docstring from the source (if present)."""
+    def decorator(target):
         if source.__doc__:
             target.__doc__ = source.__doc__
         return target
-    return do_copy
+    return decorator
 
-# create a decorator that will house the various documentation that
-#  is reused throughout matplotlib
+# Create a decorator that will house the various documentation that is reused
+# throughout Matplotlib.
 interpd = Substitution()
 
 
 def dedent_interpd(func):
-    """A special case of the interpd that first performs a dedent on
-    the incoming docstring"""
-    if isinstance(func, types.MethodType) and not six.PY3:
-        func = func.im_func
-    return interpd(dedent(func))
+    """Decorator that dedents and interpolates an object's docstring.
+    """
+    if func.__doc__:
+        if six.PY2:
+            getattr(func, "im_func", func).__doc__ = cbook.dedent(func.__doc__)
+        else:
+            func.__doc__ = cbook.dedent(func.__doc__)
+    return interpd(func)
 
 
+@cbook.deprecated("2.2")
 def copy_dedent(source):
-    """A decorator that will copy the docstring from the source and
-    then dedent it"""
-    # note the following is ugly because "Python is not a functional
-    # language" - GVR. Perhaps one day, functools.compose will exist.
-    #  or perhaps not.
-    #  http://mail.python.org/pipermail/patches/2007-February/021687.html
-    return lambda target: dedent(copy(source)(target))
+    """A decorator that copies the dedented docstring from the source."""
+    def decorator(func):
+        if source.__doc__:
+            dedent(source)
+        return func
+    return decorator