equationFromString deprecation

Author: cadenmyers13

src/diffpy/srfit/fitbase/fitcontribution.py

@@ -28,7 +28,7 @@
 from diffpy.srfit.fitbase.parameter import ParameterProxy
 from diffpy.srfit.fitbase.parameterset import ParameterSet
 from diffpy.srfit.fitbase.profile import Profile
-from diffpy.srfit.fitbase.recipeorganizer import equationFromString
+from diffpy.srfit.fitbase.recipeorganizer import get_equation_from_string
 from diffpy.utils._deprecator import build_deprecation_message, deprecated
 
 base = "diffpy.srfit.fitbase.FitContribution"
@@ -296,7 +296,9 @@ def set_equation(self, eqstr, ns={}):
         variable.
         """
         # Build the equation instance.
-        eq = equationFromString(eqstr, self._eqfactory, buildargs=True, ns=ns)
+        eq = get_equation_from_string(
+            eqstr, self._eqfactory, buildargs=True, ns=ns
+        )
         eq.name = "eq"
 
         # Register any new Parameters.
@@ -386,7 +388,7 @@ def set_residual_equation(self, eqstr):
         elif eqstr == "resv":
             eqstr = resvstr
 
-        reseq = equationFromString(eqstr, self._eqfactory)
+        reseq = get_equation_from_string(eqstr, self._eqfactory)
         self._eqfactory.wipeout(self._reseq)
         self._reseq = reseq
 

src/diffpy/srfit/fitbase/recipeorganizer.py

@@ -17,10 +17,10 @@
 RecipeContainer is the base class for organizing Parameters, and other
 RecipeContainers.  RecipeOrganizer is an extended RecipeContainer that
 incorporates equation building, constraints and Restraints.
-equationFromString creates an Equation instance from a string.
+get_equation_from_string creates an Equation instance from a string.
 """
 
-__all__ = ["RecipeContainer", "RecipeOrganizer", "equationFromString"]
+__all__ = ["RecipeContainer", "RecipeOrganizer", "get_equation_from_string"]
 
 import re
 from collections import OrderedDict
@@ -160,6 +160,13 @@
     removal_version,
 )
 
+equationFromString_deprecation_msg = build_deprecation_message(
+    recipeorganizer_base,
+    "equationFromString",
+    "get_equation_from_string",
+    removal_version,
+)
+
 
 class RecipeContainer(Observable, Configurable, Validatable):
     """Base class for organizing pieces of a FitRecipe.
@@ -851,7 +858,7 @@ def register_string_function(self, function_str, name, func_params={}):
         """
 
         # Build the equation instance.
-        eq = equationFromString(
+        eq = get_equation_from_string(
             function_str, self._eqfactory, ns=func_params, buildargs=True
         )
         eq.name = name
@@ -907,7 +914,9 @@ def evaluate_equation(self, equation_str, func_params={}):
             If `func_params` uses a name that is already used for a
             variable.
         """
-        eq = equationFromString(equation_str, self._eqfactory, func_params)
+        eq = get_equation_from_string(
+            equation_str, self._eqfactory, func_params
+        )
         try:
             returned_value = eq()
         finally:
@@ -969,7 +978,9 @@ def constrain_parameter(self, parameter, constraint_eq, params={}):
 
         if isinstance(constraint_eq, str):
             eqstr = constraint_eq
-            eq = equationFromString(constraint_eq, self._eqfactory, params)
+            eq = get_equation_from_string(
+                constraint_eq, self._eqfactory, params
+            )
         else:
             eq = Equation(root=constraint_eq)
             eqstr = constraint_eq.name
@@ -1194,7 +1205,7 @@ def add_restraint(
         """
         if isinstance(param_or_eq, str):
             eqstr = param_or_eq
-            eq = equationFromString(param_or_eq, self._eqfactory, params)
+            eq = get_equation_from_string(param_or_eq, self._eqfactory, params)
         else:
             eq = Equation(root=param_or_eq)
             eqstr = param_or_eq.name
@@ -1489,38 +1500,45 @@ def show(self, pattern="", textwidth=78):
 # End RecipeOrganizer
 
 
-def equationFromString(
+def get_equation_from_string(
     eqstr, factory, ns={}, buildargs=False, argclass=Parameter, argkw={}
 ):
-    """Make an equation from a string.
+    """Make an Equation object from a string.
 
     Attributes
     ----------
-    eqstr
+    eqstr : str
         A string representation of the equation. The equation must
         consist of numpy operators and "known" Parameters. Parameters
         are known if they are in ns, or already defined in the factory.
-    factory
+    factory : EquationFactory
         An EquationFactory instance.
-    ns
-        A dictionary of Parameters indexed by name that are used
+    ns : dict, optional
+        The dictionary of Parameters indexed by name that are used
         in the eqstr but not already defined in the factory
         (default {}).
-    buildargs
+    buildargs : bool, optional
         A flag indicating whether missing Parameters can be created
         by the Factory (default False). If False, then the a ValueError
         will be raised if there are undefined arguments in the eqstr.
-    argclass
+    argclass : Parameter class, optional
         Class to use when creating new Arguments (default
         Parameter). The class constructor must accept the 'name' key
         word.
-    argkw
+    argkw : dict, optional
         Key word dictionary to pass to the argclass constructor
         (default {}).
 
+    Returns
+    -------
+    eq : Equation
+        An Equation instance representing the equation in eqstr.
 
-    Raises ValueError if ns uses a name that is already defined in the factory.
-    Raises ValueError if the equation has undefined parameters.
+    Raises
+    ------
+    ValueError
+        If buildargs is False and there are undefined parameters in eqstr
+        or if ns uses a name that is already defined in the factory.
     """
 
     defined = set(factory.builders.keys())
@@ -1542,6 +1560,27 @@ def equationFromString(
     return eq
 
 
+@deprecated(equationFromString_deprecation_msg)
+def equationFromString(
+    eqstr, factory, ns={}, buildargs=False, argclass=Parameter, argkw={}
+):
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use
+    diffpy.srfit.fitbase.recipeorganizer.get_equation_from_string
+    instead.
+    """
+    return get_equation_from_string(
+        eqstr,
+        factory,
+        ns=ns,
+        buildargs=buildargs,
+        argclass=argclass,
+        argkw=argkw,
+    )
+
+
 def _has_clear_constraints(msg):
     return hasattr(msg, "clear_all_constraints")
 

tests/test_constraint.py

@@ -19,7 +19,7 @@
 from diffpy.srfit.equation.builder import EquationFactory
 from diffpy.srfit.fitbase.constraint import Constraint
 from diffpy.srfit.fitbase.parameter import Parameter
-from diffpy.srfit.fitbase.recipeorganizer import equationFromString
+from diffpy.srfit.fitbase.recipeorganizer import get_equation_from_string
 
 
 class TestConstraint(unittest.TestCase):
@@ -37,17 +37,17 @@ def test_constrain_parameter(self):
 
         c = Constraint()
         # Constrain p1 = 2*p2
-        eq = equationFromString("2*p2", factory)
+        eq = get_equation_from_string("2*p2", factory)
         c.constrain_parameter(p1, eq)
 
         self.assertTrue(p1.constrained)
         self.assertFalse(p2.constrained)
 
-        eq2 = equationFromString("2*p2+1", factory)
+        eq2 = get_equation_from_string("2*p2+1", factory)
         c2 = Constraint()
         self.assertRaises(ValueError, c2.constrain, p1, eq2)
         p2.setConst()
-        eq3 = equationFromString("p1", factory)
+        eq3 = get_equation_from_string("p1", factory)
         self.assertRaises(ValueError, c2.constrain, p2, eq3)
 
         p2.set_value(2.5)
@@ -76,17 +76,17 @@ def testConstraint(self):
 
         c = Constraint()
         # Constrain p1 = 2*p2
-        eq = equationFromString("2*p2", factory)
+        eq = get_equation_from_string("2*p2", factory)
         c.constrain(p1, eq)
 
         self.assertTrue(p1.constrained)
         self.assertFalse(p2.constrained)
 
-        eq2 = equationFromString("2*p2+1", factory)
+        eq2 = get_equation_from_string("2*p2+1", factory)
         c2 = Constraint()
         self.assertRaises(ValueError, c2.constrain, p1, eq2)
         p2.setConst()
-        eq3 = equationFromString("p1", factory)
+        eq3 = get_equation_from_string("p1", factory)
         self.assertRaises(ValueError, c2.constrain, p2, eq3)
 
         p2.set_value(2.5)

tests/test_recipeorganizer.py

@@ -25,15 +25,16 @@
     RecipeContainer,
     RecipeOrganizer,
     equationFromString,
+    get_equation_from_string,
 )
 
 # ----------------------------------------------------------------------------
 
 
 class TestEquationFromString(unittest.TestCase):
 
-    def testEquationFromString(self):
-        """Test the equationFromString method."""
+    def test_get_equation_from_string(self):
+        """Test the get_equation_from_string method."""
 
         p1 = Parameter("p1", 1)
         p2 = Parameter("p2", 2)
@@ -46,15 +47,17 @@ def testEquationFromString(self):
         factory.registerArgument("p2", p2)
 
         # Check usage where all parameters are registered with the factory
-        eq = equationFromString("p1+p2", factory)
+        eq = get_equation_from_string("p1+p2", factory)
 
         self.assertEqual(2, len(eq.args))
         self.assertTrue(p1 in eq.args)
         self.assertTrue(p2 in eq.args)
         self.assertEqual(3, eq())
 
         # Try to use a parameter that is not registered
-        self.assertRaises(ValueError, equationFromString, "p1+p2+p3", factory)
+        self.assertRaises(
+            ValueError, get_equation_from_string, "p1+p2+p3", factory
+        )
 
         # Pass that argument in the ns dictionary
         eq = equationFromString("p1+p2+p3", factory, {"p3": p3})
@@ -69,12 +72,16 @@ def testEquationFromString(self):
 
         # Pass and use an unregistered parameter
         self.assertRaises(
-            ValueError, equationFromString, "p1+p2+p3+p4", factory, {"p3": p3}
+            ValueError,
+            get_equation_from_string,
+            "p1+p2+p3+p4",
+            factory,
+            {"p3": p3},
         )
 
         # Try to overload a registered parameter
         self.assertRaises(
-            ValueError, equationFromString, "p1+p2", factory, {"p2": p4}
+            ValueError, get_equation_from_string, "p1+p2", factory, {"p2": p4}
         )
 
         return

tests/test_restraint.py

@@ -18,7 +18,7 @@
 
 from diffpy.srfit.equation.builder import EquationFactory
 from diffpy.srfit.fitbase.parameter import Parameter
-from diffpy.srfit.fitbase.recipeorganizer import equationFromString
+from diffpy.srfit.fitbase.recipeorganizer import get_equation_from_string
 from diffpy.srfit.fitbase.restraint import Restraint
 
 
@@ -36,7 +36,7 @@ def testRestraint(self):
         factory.registerArgument("p2", p2)
 
         # Restrain 1 <  p1 + p2 < 5
-        eq = equationFromString("p1 + p2", factory)
+        eq = get_equation_from_string("p1 + p2", factory)
         r = Restraint(eq, 1, 5)
 
         # This should have no penalty