Merge pull request #78 from zmx27/deprecate-setscattering

chore: deprecate setScatteringFactorTableByType

Author: sbillinge

news/deprecate-setscattering.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Deprecated setScatteringFactorTableByType.
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/extensions/wrap_ScatteringFactorTable.cpp

@@ -158,8 +158,11 @@ const char* doc_ScatteringFactorTableOwner_setScatteringFactorTableByType = "\
 Set internal ScatteringFactorTable according to specified string type.\n\
 \n\
 tp   -- string identifier of a registered ScatteringFactorTable type.\n\
-        Use ScatteringFactorTable.getRegisteredTypes for the allowed values.\n\
+    Use ScatteringFactorTable.getRegisteredTypes for the allowed values.\n\
 \n\
+Deprecated: This method is deprecated and will be removed in the 2.0.0 release.\n\
+Use direct assignment to the `scatteringfactortable` property instead, for example:\n\
+    obj.scatteringfactortable = SFTNeutron()\n\
 No return value.\n\
 ";
 
@@ -399,10 +402,28 @@ void wrap_ScatteringFactorTable()
                 getsftable,
                 setsftable<ScatteringFactorTableOwner,ScatteringFactorTable>,
                 doc_ScatteringFactorTableOwner_scatteringfactortable)
+        // deprecated: prefer assigning the `scatteringfactortable` property
         .def("setScatteringFactorTableByType",
-                &SFTOwner::setScatteringFactorTableByType,
-                bp::arg("tp"),
-                doc_ScatteringFactorTableOwner_setScatteringFactorTableByType)
+            +[](SFTOwner& obj, const std::string& tp)
+            {
+                namespace bp = boost::python;
+                try
+                {
+                bp::object warnings = bp::import("warnings");
+                bp::object builtins = bp::import("builtins");
+                bp::object DeprecationWarning = builtins.attr("DeprecationWarning");
+                warnings.attr("warn")(
+                    std::string("setScatteringFactorTableByType is deprecated; "
+                            "assign the 'scatteringfactortable' property directly, for example:\n"
+                            "obj.scatteringfactortable = SFTNeutron()"),
+                    DeprecationWarning,
+                    2);
+                }
+                catch (...) { /* don't let warnings break the binding */ }
+                obj.setScatteringFactorTableByType(tp);
+            },
+            bp::arg("tp"),
+            doc_ScatteringFactorTableOwner_setScatteringFactorTableByType)
         .def("getRadiationType",
                 &SFTOwner::getRadiationType,
                 return_value_policy<copy_const_reference>(),

tests/test_debyepdfcalculator.py

@@ -5,11 +5,13 @@
 
 import pickle
 import unittest
+import warnings
 
 import numpy
 from testutils import _maxNormDiff, loadDiffPyStructure, pickle_with_attr
 
 from diffpy.srreal.pdfcalculator import DebyePDFCalculator, PDFCalculator
+from diffpy.srreal.scatteringfactortable import SFTNeutron
 
 
 ##############################################################################
@@ -141,8 +143,28 @@ def test_partial_pdfs(self):
 
     def test_pickling(self):
         """Check pickling and unpickling of PDFCalculator."""
+        # New syntax: assign an SFT instance to the property (should not warn)
         dpdfc = self.dpdfc
-        dpdfc.setScatteringFactorTableByType("N")
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            dpdfc.scatteringfactortable = SFTNeutron()
+        self.assertFalse(
+            any(isinstance(x.message, DeprecationWarning) for x in w)
+        )
+
+        dpdfc.scatteringfactortable.setCustomAs("Na", "Na", 7)
+        spkl = pickle.dumps(dpdfc)
+        dpdfc1_new = pickle.loads(spkl)
+        self.assertEqual(
+            dpdfc.scatteringfactortable.type(),
+            dpdfc1_new.scatteringfactortable.type(),
+        )
+        self.assertEqual(7.0, dpdfc1_new.scatteringfactortable.lookup("Na"))
+
+        # Old syntax: call the deprecated method (should warn)
+        dpdfc = self.dpdfc
+        with self.assertWarns(DeprecationWarning):
+            dpdfc.setScatteringFactorTableByType("N")
         dpdfc.scatteringfactortable.setCustomAs("Na", "Na", 7)
         dpdfc.addEnvelope("sphericalshape")
         dpdfc.debyeprecision = 0.001