Review actions #3

matplotlib · pelson · Jan 31, 2012 · Jan 31, 2012 · Feb 6, 2012 · Feb 6, 2012
commit 270f2919e287c29de42daf5d697eb28d2667aabe
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -13,6 +13,16 @@ For new features that were added to matplotlib, please see
 
 Changes in 1.1.x
 ================
+* Use of :func:`matplotlib.projections.projection_factory` is now deprecated
+  in favour of axes class identification using 
+  :func:`matplotlib.projections.process_projection_requirements` followed by 
+  direct axes class invocation (at the time of writing, this is done by 
+  :meth:`matplotlib.figure.Figure.add_axes`, 
+  :meth:`matplotlib.figure.Figure.add_subplot` and 
+  :meth:`matplotlib.figure.Figure.gca`. 
+  This change means that third party objects can expose themselves as 
+  matplotlib axes by providing a ``_as_mpl_axes`` method (see 
+  :ref:`adding-new-scales` for more detail).
 
 * Added new :class:`matplotlib.sankey.Sankey` for generating Sankey diagrams.
 

diff --git a/lib/matplotlib/projections/__init__.py b/lib/matplotlib/projections/__init__.py
@@ -63,40 +63,67 @@ def get_projection_class(projection=None):
         raise ValueError("Unknown projection '%s'" % projection)
 
 
+def projection_factory(projection, figure, rect, **kwargs):
+    """
+    Get a new projection instance.
+
+    *projection* is a projection name.
+
+    *figure* is a figure to add the axes to.
+
+    *rect* is a :class:`~matplotlib.transforms.Bbox` object specifying
+    the location of the axes within the figure.
+
+    Any other kwargs are passed along to the specific projection
+    constructor being used.
+
+    .. deprecated:: 
+
+        This routine is deprecated in favour of getting the projection
+        class directly with :func:`get_projection_class` and initialising it
+        directly. Will be removed in version 1.3.  
+
+    """
+
+    return get_projection_class(projection)(figure, rect, **kwargs)
+
+
 def process_projection_requirements(figure, *args, **kwargs):
-        """
-        Handle the args/kwargs to for add_axes/add_subplot/gca,
-        returning::
-
-            (axes_proj_class, proj_class_kwargs, proj_stack_key)
-
-        Which can be used for new axes initialization/identification.        
-
-        """
-        ispolar = kwargs.pop('polar', False)
-        projection = kwargs.pop('projection', None)
-        if ispolar:
-            if projection is not None and projection != 'polar':
-                raise ValueError(
-                    "polar=True, yet projection=%r. " 
-                    "Only one of these arguments should be supplied." %
-                    projection)
-            projection = 'polar'
-
-        if isinstance(projection, basestring) or projection is None:
-            projection_class = get_projection_class(projection)
-        elif hasattr(projection, '_as_mpl_axes'):
-            projection_class, extra_kwargs = projection._as_mpl_axes()
-            kwargs.update(**extra_kwargs)
-        else:
-            raise TypeError('projection must be a string, None or implement a ' 
-                                '_as_mpl_axes method. Got %r' % projection)
-
-        # Make the key without projection kwargs, this is used as a unique
-        # lookup for axes instances
-        key = figure._make_key(*args, **kwargs)
+    """
+    Handle the args/kwargs to for add_axes/add_subplot/gca,
+    returning::
+
+        (axes_proj_class, proj_class_kwargs, proj_stack_key)
 
-        return projection_class, kwargs, key
+    Which can be used for new axes initialization/identification.
+
+    .. note:: **kwargs** is modified in place.        
+
+    """
+    ispolar = kwargs.pop('polar', False)
+    projection = kwargs.pop('projection', None)
+    if ispolar:
+        if projection is not None and projection != 'polar':
+            raise ValueError(
+                "polar=True, yet projection=%r. " 
+                "Only one of these arguments should be supplied." %
+                projection)
+        projection = 'polar'
+
+    if isinstance(projection, basestring) or projection is None:
+        projection_class = get_projection_class(projection)
+    elif hasattr(projection, '_as_mpl_axes'):
+        projection_class, extra_kwargs = projection._as_mpl_axes()
+        kwargs.update(**extra_kwargs)
+    else:
+        raise TypeError('projection must be a string, None or implement a ' 
+                            '_as_mpl_axes method. Got %r' % projection)
+
+    # Make the key without projection kwargs, this is used as a unique
+    # lookup for axes instances
+    key = figure._make_key(*args, **kwargs)
+
+    return projection_class, kwargs, key
 
 
 def get_projection_names():