ENH updated the documentation to reflect the deprecation of the cbook method in favor of the utils module

NelleV · NelleV · commit 28af8175c9ec · 2013-02-01T10:37:15.000+01:00
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -21,7 +21,6 @@
    axes_api.rst
    axis_api.rst
    index_backend_api.rst
-   cbook_api.rst
    cm_api.rst
    collections_api.rst
    colorbar_api.rst
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
@@ -48,7 +48,7 @@ Style
     import numpy.ma as ma
     import matplotlib as mpl
     from matplotlib import pyplot as plt
-    import matplotlib.cbook as cbook
+    import matplotlib.utils as utils
     import matplotlib.collections as mcol
     import matplotlib.patches as mpatches
 
@@ -257,8 +257,8 @@ distributed with matplotlib in the
 `lib/matplotlib/mpl-data/sample_data/` directory.  Then in your
 example code you can load it into a file handle with::
 
-    import matplotlib.cbook as cbook
-    fh = cbook.get_sample_data('mydata.dat')
+    import matplotlib.utils as utils
+    fh = utils.get_sample_data('mydata.dat')
 
 .. _new-pyplot-function:
 
diff --git a/doc/mpl_toolkits/axes_grid/figures/demo_colorbar_of_inset_axes.py b/doc/mpl_toolkits/axes_grid/figures/demo_colorbar_of_inset_axes.py
@@ -4,7 +4,7 @@
 from mpl_toolkits.axes_grid.colorbar import colorbar
 
 def get_demo_image():
-    from matplotlib.cbook import get_sample_data
+    from matplotlib.utils import get_sample_data
     import numpy as np
     f = get_sample_data("axes_grid/bivariate_normal.npy", asfileobj=False)
     z = np.load(f)
diff --git a/doc/mpl_toolkits/axes_grid/figures/simple_rgb.py b/doc/mpl_toolkits/axes_grid/figures/simple_rgb.py
@@ -4,7 +4,7 @@
 
 def get_demo_image():
     import numpy as np
-    from matplotlib.cbook import get_sample_data
+    from matplotlib.utils import get_sample_data
     f = get_sample_data("axes_grid/bivariate_normal.npy", asfileobj=False)
     z = np.load(f)
     # z is a numpy array of 15x15
diff --git a/doc/users/recipes.rst b/doc/users/recipes.rst
@@ -87,7 +87,7 @@ gracefully, and here are some tricks to help you work around them.
 We'll load up some sample date data which contains datetime.date
 objects in a numpy record array::
 
-  In [63]: datafile = cbook.get_sample_data('goog.npy')
+  In [63]: datafile = utils.get_sample_data('goog.npy')
 
   In [64]: r = np.load(datafile).view(np.recarray)
 
@@ -116,8 +116,8 @@ you will see that the x tick labels are all squashed together.
 .. plot::
    :context:
 
-   import matplotlib.cbook as cbook
-   datafile = cbook.get_sample_data('goog.npy')
+   import matplotlib.utils as utils 
+   datafile = utils.get_sample_data('goog.npy')
    r = np.load(datafile).view(np.recarray)
    plt.figure()
    plt.plot(r.date, r.close)
@@ -175,10 +175,10 @@ right.
    import matplotlib.pyplot as plt
    import numpy as np
 
-   import matplotlib.cbook as cbook
+   import matplotlib.utils as utils 
 
    # load up some sample financial data
-   datafile = cbook.get_sample_data('goog.npy')
+   datafile = utils.get_sample_data('goog.npy')
    r = np.load(datafile).view(np.recarray)
 
    # create two subplots with the shared x and y axes
diff --git a/lib/matplotlib/utils/__init__.py b/lib/matplotlib/utils/__init__.py
@@ -1118,3 +1118,101 @@ def simple_linear_interpolation(a, steps):
     result[steps::steps] = a1
 
     return result
+
+
+def report_memory(i=0):  # argument may go away
+    'return the memory consumed by process'
+    from subprocess import Popen, PIPE
+    pid = os.getpid()
+    if sys.platform == 'sunos5':
+        a2 = Popen('ps -p %d -o osz' % pid, shell=True,
+                   stdout=PIPE).stdout.readlines()
+        mem = int(a2[-1].strip())
+    elif sys.platform.startswith('linux'):
+        a2 = Popen('ps -p %d -o rss,sz' % pid, shell=True,
+                   stdout=PIPE).stdout.readlines()
+        mem = int(a2[1].split()[1])
+    elif sys.platform.startswith('darwin'):
+        a2 = Popen('ps -p %d -o rss,vsz' % pid, shell=True,
+                   stdout=PIPE).stdout.readlines()
+        mem = int(a2[1].split()[0])
+    elif sys.platform.startswith('win'):
+        try:
+            a2 = Popen(["tasklist", "/nh", "/fi", "pid eq %d" % pid],
+                       stdout=PIPE).stdout.read()
+        except OSError:
+            raise NotImplementedError(
+                "report_memory works on Windows only if "
+                "the 'tasklist' program is found")
+        mem = int(a2.strip().split()[-2].replace(',', ''))
+    else:
+        raise NotImplementedError(
+            "We don't have a memory monitor for %s" % sys.platform)
+    return mem
+
+
+def print_cycles(objects, outstream=sys.stdout, show_progress=False):
+    """
+    *objects*
+        A list of objects to find cycles in.  It is often useful to
+        pass in gc.garbage to find the cycles that are preventing some
+        objects from being garbage collected.
+
+    *outstream*
+        The stream for output.
+
+    *show_progress*
+        If True, print the number of objects reached as they are found.
+    """
+    import gc
+    from types import FrameType
+
+    def print_path(path):
+        for i, step in enumerate(path):
+            # next "wraps around"
+            next = path[(i + 1) % len(path)]
+
+            outstream.write("   %s -- " % str(type(step)))
+            if isinstance(step, dict):
+                for key, val in step.iteritems():
+                    if val is next:
+                        outstream.write("[%s]" % repr(key))
+                        break
+                    if key is next:
+                        outstream.write("[key] = %s" % repr(val))
+                        break
+            elif isinstance(step, list):
+                outstream.write("[%d]" % step.index(next))
+            elif isinstance(step, tuple):
+                outstream.write("( tuple )")
+            else:
+                outstream.write(repr(step))
+            outstream.write(" ->\n")
+        outstream.write("\n")
+
+    def recurse(obj, start, all, current_path):
+        if show_progress:
+            outstream.write("%d\r" % len(all))
+
+        all[id(obj)] = None
+
+        referents = gc.get_referents(obj)
+        for referent in referents:
+            # If we've found our way back to the start, this is
+            # a cycle, so print it out
+            if referent is start:
+                print_path(current_path)
+
+            # Don't go back through the original list of objects, or
+            # through temporary references to the object, since those
+            # are just an artifact of the cycle detector itself.
+            elif referent is objects or isinstance(referent, FrameType):
+                continue
+
+            # We haven't seen this object before, so recurse
+            elif id(referent) not in all:
+                recurse(referent, start, all, current_path + [obj])
+
+    for obj in objects:
+        outstream.write("Examining: %r\n" % (obj,))
+        recurse(obj, obj, {}, [])
diff --git a/lib/matplotlib/utils/_cbook.py b/lib/matplotlib/utils/_cbook.py
@@ -499,36 +499,6 @@ def finddir(o, match, case=False):
     return [orig for name, orig in names if name.find(match) >= 0]
 
 
-def report_memory(i=0):  # argument may go away
-    'return the memory consumed by process'
-    from subprocess import Popen, PIPE
-    pid = os.getpid()
-    if sys.platform == 'sunos5':
-        a2 = Popen('ps -p %d -o osz' % pid, shell=True,
-                   stdout=PIPE).stdout.readlines()
-        mem = int(a2[-1].strip())
-    elif sys.platform.startswith('linux'):
-        a2 = Popen('ps -p %d -o rss,sz' % pid, shell=True,
-                   stdout=PIPE).stdout.readlines()
-        mem = int(a2[1].split()[1])
-    elif sys.platform.startswith('darwin'):
-        a2 = Popen('ps -p %d -o rss,vsz' % pid, shell=True,
-                   stdout=PIPE).stdout.readlines()
-        mem = int(a2[1].split()[0])
-    elif sys.platform.startswith('win'):
-        try:
-            a2 = Popen(["tasklist", "/nh", "/fi", "pid eq %d" % pid],
-                       stdout=PIPE).stdout.read()
-        except OSError:
-            raise NotImplementedError(
-                "report_memory works on Windows only if "
-                "the 'tasklist' program is found")
-        mem = int(a2.strip().split()[-2].replace(',', ''))
-    else:
-        raise NotImplementedError(
-            "We don't have a memory monitor for %s" % sys.platform)
-    return mem
-
 
 class MemoryMonitor:
     def __init__(self, nmax=20000):
@@ -582,72 +552,6 @@ def plot(self, i0=0, isub=1, fig=None):
         fig.canvas.draw()
 
 
-def print_cycles(objects, outstream=sys.stdout, show_progress=False):
-    """
-    *objects*
-        A list of objects to find cycles in.  It is often useful to
-        pass in gc.garbage to find the cycles that are preventing some
-        objects from being garbage collected.
-
-    *outstream*
-        The stream for output.
-
-    *show_progress*
-        If True, print the number of objects reached as they are found.
-    """
-    import gc
-    from types import FrameType
-
-    def print_path(path):
-        for i, step in enumerate(path):
-            # next "wraps around"
-            next = path[(i + 1) % len(path)]
-
-            outstream.write("   %s -- " % str(type(step)))
-            if isinstance(step, dict):
-                for key, val in step.iteritems():
-                    if val is next:
-                        outstream.write("[%s]" % repr(key))
-                        break
-                    if key is next:
-                        outstream.write("[key] = %s" % repr(val))
-                        break
-            elif isinstance(step, list):
-                outstream.write("[%d]" % step.index(next))
-            elif isinstance(step, tuple):
-                outstream.write("( tuple )")
-            else:
-                outstream.write(repr(step))
-            outstream.write(" ->\n")
-        outstream.write("\n")
-
-    def recurse(obj, start, all, current_path):
-        if show_progress:
-            outstream.write("%d\r" % len(all))
-
-        all[id(obj)] = None
-
-        referents = gc.get_referents(obj)
-        for referent in referents:
-            # If we've found our way back to the start, this is
-            # a cycle, so print it out
-            if referent is start:
-                print_path(current_path)
-
-            # Don't go back through the original list of objects, or
-            # through temporary references to the object, since those
-            # are just an artifact of the cycle detector itself.
-            elif referent is objects or isinstance(referent, FrameType):
-                continue
-
-            # We haven't seen this object before, so recurse
-            elif id(referent) not in all:
-                recurse(referent, start, all, current_path + [obj])
-
-    for obj in objects:
-        outstream.write("Examining: %r\n" % (obj,))
-        recurse(obj, obj, {}, [])
-
 
 def recursive_remove(path):
     if os.path.isdir(path):
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -568,7 +568,7 @@ def set_xlim3d(self, left=None, right=None, emit=True, auto=False, **kw):
         if kw:
             raise ValueError("unrecognized kwargs: %s" % kw.keys())
 
-        if right is None and cbook.iterable(left):
+        if right is None and utils.iterable(left):
             left, right = left
 
         self._process_unit_info(xdata=(left, right))
@@ -623,7 +623,7 @@ def set_ylim3d(self, bottom=None, top=None, emit=True, auto=False, **kw):
         if kw:
             raise ValueError("unrecognized kwargs: %s" % kw.keys())
 
-        if top is None and cbook.iterable(bottom):
+        if top is None and utils.iterable(bottom):
             bottom, top = bottom
 
         self._process_unit_info(ydata=(bottom, top))
@@ -677,7 +677,7 @@ def set_zlim3d(self, bottom=None, top=None, emit=True, auto=False, **kw):
         if kw:
             raise ValueError("unrecognized kwargs: %s" % kw.keys())
 
-        if top is None and cbook.iterable(bottom):
+        if top is None and utils.iterable(bottom):
             bottom, top = bottom
 
         self._process_unit_info(zdata=(bottom, top))
@@ -1425,7 +1425,7 @@ def set_zbound(self, lower=None, upper=None):
         .. versionadded :: 1.1.0
             This function was added, but not tested. Please report any bugs.
         """
-        if upper is None and cbook.iterable(lower):
+        if upper is None and utis.iterable(lower):
             lower,upper = lower
 
         old_lower,old_upper = self.get_zbound()
diff --git a/unit/memleak_gui.py b/unit/memleak_gui.py
@@ -11,7 +11,7 @@
 The default number of loops typically will not yield a stable
 estimate--for that you may need many hundreds of loops and some patience.
 
-You may need to edit cbook.report_memory to support your platform
+You may need to edit utils.report_memory to support your platform
 
 '''
 from __future__ import print_function
@@ -48,7 +48,7 @@
 if options.backend:
     matplotlib.use(options.backend)
 import pylab
-import matplotlib.cbook as cbook
+import matplotlib.utils as utils
 
 print('# columns are: iteration, OS memory (k), number of python objects')
 print('#')
@@ -59,7 +59,7 @@
     fig.clf()
     pylab.close(fig)
     gc.collect()
-    val = cbook.report_memory(i)
+    val = utils.report_memory(i)
     if options.verbose:
         if i % 10 == 0:
             #print ("iter: %4d OS memory: %8d Python objects: %8d" %
@@ -106,4 +106,4 @@
     print('# Average memory consumed per loop: %1.4fk bytes\n' % ((end-start)/float(indEnd-indStart)))
 
 if options.cycles:
-    cbook.print_cycles(gc.garbage)
+    utils.print_cycles(gc.garbage)
diff --git a/unit/memleak_hawaii3.py b/unit/memleak_hawaii3.py
@@ -6,7 +6,7 @@
 import matplotlib
 matplotlib.use('PDF')
 
-from matplotlib.cbook import report_memory
+from matplotlib.utils import report_memory
 import numpy as np
 from pylab import figure, show, close
 
diff --git a/unit/memleak_nongui.py b/unit/memleak_nongui.py
@@ -2,7 +2,7 @@
 import os,matplotlib
 matplotlib.use('Agg')
 from matplotlib.figure import Figure
-from matplotlib.cbook import report_memory
+from matplotlib.utils import report_memory
 
 def plot():
     fig = Figure()
