feat: deprecate diffpy.srfit.sas and SASCF in favor of diffpy.cmisas

docs/source/api/diffpy.srfit.sas.rst

@@ -3,6 +3,10 @@
 diffpy.srfit.sas package
 ========================
 
+.. deprecated:: 3.5.0
+    ``diffpy.srfit.sas`` has moved to ``diffpy.cmisas`` and will be removed
+    in version 4.0.0. Please use ``diffpy.cmisas`` instead.
+
 .. automodule:: diffpy.srfit.sas
     :members:
     :undoc-members:

news/sas-dep.rst

@@ -0,0 +1,24 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* ``diffpy.srfit.sas``, which moved to ``diffpy.cmisas``. Importing it now raises a ``DeprecationWarning``.
+* ``diffpy.srfit.pdf.characteristicfunctions.SASCF``. Please use ``diffpy.cmisas.characteristicfunctions.SASCF`` instead.
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/srfit/pdf/characteristicfunctions.py

@@ -121,6 +121,14 @@ def _build_dep_msg(old_name, new_name, signature_note=None):
     "radius = a - delta / 2 and thickness = delta.",
 )
 
+SASCF_dep_msg = build_deprecation_message(
+    cf_base,
+    "SASCF",
+    "SASCF",
+    removal_version,
+    new_base="diffpy.cmisas.characteristicfunctions",
+)
+
 
 # The record of non-physical input warnings already issued in this process,
 # keyed by (function name, requirement). See _warn_non_physical.
@@ -621,6 +629,11 @@ def shellCF2(r, a, delta):
 class SASCF(Calculator):
     """Calculator class for characteristic functions from sas-models.
 
+    .. deprecated:: 3.5.0
+        ``SASCF`` has moved to ``diffpy.cmisas.characteristicfunctions``
+        and will be removed in version 4.0.0. Please use
+        ``diffpy.cmisas.characteristicfunctions.SASCF`` instead.
+
     This class wraps a sas.models.BaseModel to calculate I(Q) related to
     nanoparticle shape. This I(Q) is inverted to f(r) according to:
     f(r) = 1 / (4 pi r) * SINFT(I(Q)),
@@ -648,6 +661,7 @@ def __init__(self, name, model):
         model : BaseModel
             The sas.models.BaseModel object this adapts.
         """
+        warnings.warn(SASCF_dep_msg, DeprecationWarning, stacklevel=2)
         Calculator.__init__(self, name)
 
         self._model = model

src/diffpy/srfit/sas/__init__.py

@@ -22,9 +22,27 @@
     "CFCalculator",
 ]
 
+import warnings
+
+from diffpy.utils._deprecator import build_deprecation_message
+
 from .prcalculator import CFCalculator, PrCalculator
 from .sasgenerator import SASGenerator
 from .sasparser import SASParser
 from .sasprofile import SASProfile
 
+removal_version = "4.0.0"
+
+warnings.warn(
+    build_deprecation_message(
+        "diffpy.srfit",
+        "sas",
+        "cmisas",
+        removal_version,
+        new_base="diffpy",
+    ),
+    DeprecationWarning,
+    stacklevel=2,
+)
+
 # End of file

tests/deprecated/test_sas_deprecations.py

@@ -0,0 +1,46 @@
+"""Tests for the deprecation of diffpy.srfit.sas, which moved to
+diffpy.cmisas.
+
+Remove this file in version 4.0.0, together with diffpy.srfit.sas.
+"""
+
+import importlib
+from types import SimpleNamespace
+
+import pytest
+
+import diffpy.srfit.sas
+from diffpy.srfit.pdf.characteristicfunctions import SASCF
+
+
+def test_sas_package_import_warns():
+    # Case: diffpy.srfit.sas is imported.
+    # Expected: A DeprecationWarning points to diffpy.cmisas.
+    expected_msg = (
+        "'diffpy.srfit.sas' is deprecated and will be removed in version "
+        "4.0.0. Please use 'diffpy.cmisas' instead."
+    )
+    with pytest.warns(DeprecationWarning) as record:
+        importlib.reload(diffpy.srfit.sas)
+    actual_msg = str(record[0].message)
+    assert actual_msg == expected_msg
+
+
+def test_SASCF():
+    # Case: SASCF is created from a sas model with no parameters.
+    # Expected: A DeprecationWarning points to
+    # diffpy.cmisas.characteristicfunctions.SASCF, and a SASCF is still
+    # returned.
+    expected_msg = (
+        "'diffpy.srfit.pdf.characteristicfunctions.SASCF' is deprecated and "
+        "will be removed in version 4.0.0. Please use "
+        "'diffpy.cmisas.characteristicfunctions.SASCF' instead."
+    )
+    model = SimpleNamespace(params={}, dispersion={})
+    with pytest.warns(DeprecationWarning) as record:
+        characteristic_function = SASCF("sphere", model)
+    actual_msg = str(record[0].message)
+    assert actual_msg == expected_msg
+    actual_type = type(characteristic_function)
+    expected_type = SASCF
+    assert actual_type == expected_type