[Scipy-svn] r6477 - in trunk: doc/release scipy/constants scipy/constants/tests

[scipy-svn at scipy.org]

Author: warren.weckesser
Date: 2010-06-02 18:50:28 -0500 (Wed, 02 Jun 2010)
New Revision: 6477

Modified:
   trunk/doc/release/0.8.0-notes.rst
   trunk/scipy/constants/codata.py
   trunk/scipy/constants/tests/test_codata.py
Log:
Add a keyword argument to constants.codata.find, so the change in behavior can go through a proper deprecation cycle.

Modified: trunk/doc/release/0.8.0-notes.rst
===================================================================
--- trunk/doc/release/0.8.0-notes.rst	2010-06-01 23:27:33 UTC (rev 6476)
+++ trunk/doc/release/0.8.0-notes.rst	2010-06-02 23:50:28 UTC (rev 6477)
@@ -66,6 +66,10 @@
 * linalg: The function `solveh_banded` currently returns a tuple containing
   the Cholesky factorization and the solution to the linear system.  In
   SciPy 0.9, the return value will be just the solution.
+* The function `constants.codata.find` will generate a DeprecationWarning.
+  In Scipy version 0.8.0, the keyword argument 'disp' was added to the
+  function, with the default value 'True'.  In 0.9.0, the default will be
+  'False'.
 
 New features
 ============
@@ -133,10 +137,13 @@
 scipy.sparse.linalg.eigen.arpack. It is based on using an symmetric solver on
 <A, A>, and as such may not be very precise.
 
-Better behavior for `scipy.constants.find` (scipy.constants)
-------------------------------------------------------------
-The function `scipy.constants.find` was modified to return the list of keys
-that it finds, instead of printing them and returning None.
+Alternative behavior available for `scipy.constants.find`
+---------------------------------------------------------
+The keyword argument `disp` was added to the function `scipy.constants.find`,
+with the default value `True`.  When `disp` is `True`, the behavior is the
+same as in Scipy version 0.7.  When `False`, the function returns the list of
+keys instead of printing them.  (In SciPy version 0.9, the default will be
+reversed.)
 
 Incomplete sparse LU decompositions
 -----------------------------------

Modified: trunk/scipy/constants/codata.py
===================================================================
--- trunk/scipy/constants/codata.py	2010-06-01 23:27:33 UTC (rev 6476)
+++ trunk/scipy/constants/codata.py	2010-06-02 23:50:28 UTC (rev 6477)
@@ -20,6 +20,7 @@
     find(sub) prints out a list of keys containing the string sub.
 """
 
+import warnings
 import string
 from math import pi, sqrt
 __all__ = ['physical_constants', 'value', 'unit', 'precision', 'find']
@@ -442,19 +443,24 @@
     """
     return physical_constants[key][2] / physical_constants[key][0]
 
-def find(sub) :
+
+def find(sub, disp=True) :
     """
-    Return list of codata.physical_constant keys containing a given string
+    Find the codata.physical_constant keys containing a given string.
 
     Parameters
     ----------
     sub : str or unicode
         Sub-string to search keys for
+    disp : bool
+        If True, print the keys that are found, and return None.
+        Otherwise, return the list of keys without printing anything.
 
     Returns
     -------
-    keys : list
-        List of keys containing `sub`
+    keys : None or list
+        If `disp` is False, the list of keys is returned. Otherwise, None
+        is returned.
 
     See Also
     --------
@@ -462,6 +468,9 @@
         dictionary literal object, does not itself possess a docstring.
 
     """
+    warnings.warn("In Scipy version 0.8.0, the keyword argument 'disp' was added to "
+                  "find(), with the default value True.  In 0.9.0, the default will be False.",
+                  DeprecationWarning)
     l_sub = string.lower(sub)
     result = []
     for key in physical_constants :
@@ -469,8 +478,14 @@
         if l_sub in l_key:
             result.append(key)
     result.sort()
-    return result
+    if disp:
+        for key in result:
+            print key
+        return
+    else:
+        return result
 
+
 #table is lacking some digits for exact values: calculate from definition
 
 c = value('speed of light in vacuum')

Modified: trunk/scipy/constants/tests/test_codata.py
===================================================================
--- trunk/scipy/constants/tests/test_codata.py	2010-06-01 23:27:33 UTC (rev 6476)
+++ trunk/scipy/constants/tests/test_codata.py	2010-06-02 23:50:28 UTC (rev 6477)
@@ -1,16 +1,20 @@
 
+import warnings
+
 from scipy.constants import find
 from numpy.testing import assert_equal
 
 def test_find():
 
-    keys = find('weak mixing')
+    warnings.simplefilter('ignore', DeprecationWarning)
+
+    keys = find('weak mixing', disp=False)
     assert_equal(keys, ['weak mixing angle'])
 
-    keys = find('qwertyuiop')
+    keys = find('qwertyuiop', disp=False)
     assert_equal(keys, [])
 
-    keys = find('natural unit')
+    keys = find('natural unit', disp=False)
     assert_equal(keys, sorted(['natural unit of velocity',
                                 'natural unit of action',
                                 'natural unit of action in eV s',