Deprecate the top-level functions in path.py

mdboom · mdboom · commit cf819b6e9838 · 2013-05-20T14:35:24.000-04:00
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -15,6 +15,22 @@ For new features that were added to matplotlib, please see
 Changes in 1.3.x
 ================
 
+* The top-level functions in `matplotlib.path` that are implemented in
+  C++ were never meant to be public.  Instead, users should use the
+  Pythonic wrappers for them in the `path.Path` and
+  `collections.Collection` classes.  Use the following mapping to update
+  your code:
+
+    - `point_in_path` -> `path.Path.contains_point`
+    - `get_path_extents` -> `path.Path.get_extents`
+    - `point_in_path_collection` -> `collection.Collection.contains`
+    - `path_in_path` -> `path.Path.contains_path`
+    - `path_intersects_path` -> `path.Path.intersects_path`
+    - `convert_path_to_polygons` -> `path.Path.to_polygons`
+    - `cleanup_path` -> `path.Path.cleaned`
+    - `points_in_path` -> `path.Path.contains_points`
+    - `clip_path_to_rect` -> `path.Path.clip_to_bbox`
+
 * `Path` objects can now be marked as `readonly` by passing
   `readonly=True` to its constructor.  The built-in path singletons,
   obtained through `Path.unit*` class methods return readonly paths.
diff --git a/lib/matplotlib/cbook.py b/lib/matplotlib/cbook.py
@@ -1,5 +1,5 @@
 """
-A collection of utility functions and classes.  Originally, many 
+A collection of utility functions and classes.  Originally, many
 (but not all) were from the Python Cookbook -- hence the name cbook.
 
 This module is safe to import from anywhere within matplotlib;
@@ -44,6 +44,125 @@ class MatplotlibDeprecationWarning(UserWarning):
 
 mplDeprecation = MatplotlibDeprecationWarning
 
+
+def deprecated(since, message='', name='', alternative='', pending=False,
+               obj_type='function'):
+    """
+    Used to mark a function as deprecated.
+
+    Parameters
+    ------------
+    since : str
+        The release at which this API became deprecated.  This is
+        required.
+
+    message : str, optional
+        Override the default deprecation message.  The format
+        specifier `%(func)s` may be used for the name of the function,
+        and `%(alternative)s` may be used in the deprecation message
+        to insert the name of an alternative to the deprecated
+        function.  `%(obj_type)` may be used to insert a friendly name
+        for the type of object being deprecated.
+
+    name : str, optional
+        The name of the deprecated function; if not provided the name
+        is automatically determined from the passed in function,
+        though this is useful in the case of renamed functions, where
+        the new function is just assigned to the name of the
+        deprecated function.  For example::
+
+            def new_function():
+                ...
+            oldFunction = new_function
+
+    alternative : str, optional
+        An alternative function that the user may use in place of the
+        deprecated function.  The deprecation warning will tell the user about
+        this alternative if provided.
+
+    pending : bool, optional
+        If True, uses a PendingDeprecationWarning instead of a
+        DeprecationWarning.
+    """
+
+    def deprecate(func, message=message, name=name, alternative=alternative,
+                  pending=pending):
+        import functools
+        import textwrap
+
+        if isinstance(func, classmethod):
+            try:
+                func = func.__func__
+            except AttributeError:
+                # classmethods in Python2.6 and below lack the __func__
+                # attribute so we need to hack around to get it
+                method = func.__get__(None, object)
+                if hasattr(method, '__func__'):
+                    func = method.__func__
+                elif hasattr(method, 'im_func'):
+                    func = method.im_func
+                else:
+                    # Nothing we can do really...  just return the original
+                    # classmethod
+                    return func
+            is_classmethod = True
+        else:
+            is_classmethod = False
+
+        if not name:
+            name = func.__name__
+
+        altmessage = ''
+        if not message or type(message) == type(deprecate):
+            if pending:
+                message = ('The %(func)s %(obj_type)s will be deprecated in a '
+                           'future version.')
+            else:
+                message = ('The %(func)s %(obj_type)s is deprecated and may '
+                           'be removed in a future version.')
+            if alternative:
+                altmessage = '\n        Use %s instead.' % alternative
+
+        message = ((message % {
+            'func': name,
+            'name': name,
+            'alternative': alternative,
+            'obj_type': obj_type}) +
+            altmessage)
+
+        @functools.wraps(func)
+        def deprecated_func(*args, **kwargs):
+            warnings.warn(message, mplDeprecation, stacklevel=2)
+
+            return func(*args, **kwargs)
+
+        old_doc = deprecated_func.__doc__
+        if not old_doc:
+            old_doc = ''
+        old_doc = textwrap.dedent(old_doc).strip('\n')
+        altmessage = altmessage.strip()
+        if not altmessage:
+            altmessage = message.strip()
+        new_doc = (('\n.. deprecated:: %(since)s'
+                    '\n    %(message)s\n\n' %
+                    {'since': since, 'message': altmessage.strip()}) + old_doc)
+        if not old_doc:
+            # This is to prevent a spurious 'unexected unindent' warning from
+            # docutils when the original docstring was blank.
+            new_doc += r'\ '
+
+        deprecated_func.__doc__ = new_doc
+
+        if is_classmethod:
+            deprecated_func = classmethod(deprecated_func)
+        return deprecated_func
+
+    if type(message) == type(deprecate):
+        return deprecate(message)
+
+    return deprecate
+
+
 # On some systems, locale.getpreferredencoding returns None,
 # which can break unicode; and the sage project reports that
 # some systems have incorrect locale specifications, e.g.,
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -22,6 +22,7 @@
 from matplotlib.artist import allow_rasterization
 import matplotlib.backend_bases as backend_bases
 import matplotlib.path as mpath
+from matplotlib import _path
 import matplotlib.mlab as mlab
 
 
@@ -315,7 +316,7 @@ def contains(self, mouseevent):
 
         transform, transOffset, offsets, paths = self._prepare_points()
 
-        ind = mpath.point_in_path_collection(
+        ind = _path.point_in_path_collection(
             mouseevent.x, mouseevent.y, pickradius,
             transform.frozen(), paths, self.get_transforms(),
             offsets, transOffset, pickradius <= 0,
diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py
@@ -9,13 +9,16 @@
 import numpy as np
 from numpy import ma
 
-from matplotlib._path import point_in_path, get_path_extents, \
-    point_in_path_collection, get_path_collection_extents, \
-    path_in_path, path_intersects_path, convert_path_to_polygons, \
-    cleanup_path, points_in_path, clip_path_to_rect
+from matplotlib import _path
+
+# ._path import point_in_path, get_path_extents, \
+#     point_in_path_collection, get_path_collection_extents, \
+#     path_in_path, path_intersects_path, convert_path_to_polygons, \
+#     cleanup_path, points_in_path, clip_path_to_rect
 from matplotlib.cbook import simple_linear_interpolation, maxdict
 from matplotlib import rcParams
 
+
 class Path(object):
     """
     :class:`Path` represents a series of possibly disconnected,
@@ -356,9 +359,10 @@ def iter_segments(self, transform=None, remove_nans=True, clip=None,
         CLOSEPOLY    = self.CLOSEPOLY
         STOP         = self.STOP
 
-        vertices, codes = cleanup_path(self, transform, remove_nans, clip,
-                                       snap, stroke_width, simplify, curves,
-                                       sketch)
+        vertices, codes = _path.cleanup_path(
+            self, transform, remove_nans, clip,
+            snap, stroke_width, simplify, curves,
+            sketch)
         len_vertices = len(vertices)
 
         i = 0
@@ -398,7 +402,7 @@ def contains_point(self, point, transform=None, radius=0.0):
         """
         if transform is not None:
             transform = transform.frozen()
-        result = point_in_path(point[0], point[1], radius, self, transform)
+        result = _path.point_in_path(point[0], point[1], radius, self, transform)
         return result
 
     def contains_points(self, points, transform=None, radius=0.0):
@@ -414,7 +418,7 @@ def contains_points(self, points, transform=None, radius=0.0):
         """
         if transform is not None:
             transform = transform.frozen()
-        result = points_in_path(points, radius, self, transform)
+        result = _path.points_in_path(points, radius, self, transform)
         return result
 
     def contains_path(self, path, transform=None):
@@ -426,7 +430,7 @@ def contains_path(self, path, transform=None):
         """
         if transform is not None:
             transform = transform.frozen()
-        return path_in_path(self, None, path, transform)
+        return _path.path_in_path(self, None, path, transform)
 
     def get_extents(self, transform=None):
         """
@@ -444,7 +448,7 @@ def get_extents(self, transform=None):
             if not transform.is_affine:
                 path = self.transformed(transform)
                 transform = None
-        return Bbox(get_path_extents(path, transform))
+        return Bbox(_path.get_path_extents(path, transform))
 
     def intersects_path(self, other, filled=True):
         """
@@ -454,7 +458,7 @@ def intersects_path(self, other, filled=True):
         That is, if one path completely encloses the other,
         :meth:`intersects_path` will return True.
         """
-        return path_intersects_path(self, other, filled)
+        return _path.path_intersects_path(self, other, filled)
 
     def intersects_bbox(self, bbox, filled=True):
         """
@@ -514,7 +518,7 @@ def to_polygons(self, transform=None, width=0, height=0):
 
         # Deal with the case where there are curves and/or multiple
         # subpaths (using extension code)
-        return convert_path_to_polygons(self, transform, width, height)
+        return _path.convert_path_to_polygons(self, transform, width, height)
 
     _unit_rectangle = None
     @classmethod
@@ -833,12 +837,11 @@ def clip_to_bbox(self, bbox, inside=True):
         to the outside of the box.
         """
         # Use make_compound_path_from_polys
-        verts = clip_path_to_rect(self, bbox, inside)
+        verts = _path.clip_path_to_rect(self, bbox, inside)
         paths = [Path(poly) for poly in verts]
         return self.make_compound_path(*paths)
 
 
-_get_path_collection_extents = get_path_collection_extents
 def get_path_collection_extents(
         master_transform, paths, transforms, offsets, offset_transform):
     """
@@ -869,9 +872,10 @@ def get_path_collection_extents(
     from transforms import Bbox
     if len(paths) == 0:
         raise ValueError("No paths provided")
-    return Bbox.from_extents(*_get_path_collection_extents(
+    return Bbox.from_extents(*_path.get_path_collection_extents(
         master_transform, paths, transforms, offsets, offset_transform))
 
+
 def get_paths_extents(paths, transforms=[]):
     """
     Given a sequence of :class:`Path` objects and optional
@@ -887,5 +891,28 @@ def get_paths_extents(paths, transforms=[]):
     from transforms import Bbox, Affine2D
     if len(paths) == 0:
         raise ValueError("No paths provided")
-    return Bbox.from_extents(*_get_path_collection_extents(
+    return Bbox.from_extents(*_path.get_path_collection_extents(
         Affine2D(), paths, transforms, [], Affine2D()))
+
+
+def _define_deprecated_functions(ns):
+    from cbook import deprecated
+
+    # The C++ functions are not meant to be used directly.
+    # Users should use the more pythonic wrappers in the Path
+    # class instead.
+    for func, alternative in [
+            ('point_in_path', 'path.Path.contains_point'),
+            ('get_path_extents', 'path.Path.get_extents'),
+            ('point_in_path_collection', 'collection.Collection.contains'),
+            ('path_in_path', 'path.Path.contains_path'),
+            ('path_intersects_path', 'path.Path.intersects_path'),
+            ('convert_path_to_polygons', 'path.Path.to_polygons'),
+            ('cleanup_path', 'path.Path.cleaned'),
+            ('points_in_path', 'path.Path.contains_points'),
+            ('clip_path_to_rect', 'path.Path.clip_to_bbox')]:
+        ns[func] = deprecated(
+            since='1.3', alternative=alternative)(getattr(_path, func))
+
+
+_define_deprecated_functions(locals())
