feat: add @deprecated decorator

[cadenmyers13]

No description provided.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (30407bf) to head (4ec1cf2).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #363   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            9         9           
  Lines          520       520           
=========================================
  Hits           520       520           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cadenmyers13]

Directions for deprecating functions

This is step-by-step directions for deprecating an old function name in a different package to a new function name in the new package. The example I will be showing here follows the deprecation of diffpy.srfit.pdf.basepdfgenerator.BasePDFGenerator._setCalculator. This is being moved to diffpy.cmipdf.basepdfgenerator.PDFGenerator._set_calculator. Note the difference is the function name and the package where it is being imported from.

1) copy the deprecated function and class to its new location with the new function name:

Make sure any imports used in this function are copied over as well.

# in diffpy.cmipdf/src/diffpy/cmipdf/basepdfgenerator.py

class BasePDFGenerator(ProfileGenerator):
    ...
    def _set_calculator(self, calc):
       # function stuff here
       return something

2) Add new import statement that points to the function in the new location

Additionally, we will import our custom deprecator from diffpy.utils for any python version. Python 3.13 has its own custom deprecating decorator. The custom one and the one implemented in Python 3.13 have identical API so they should work the same no matter what Python version you are using in your env.

# in diffpy.srfit/src/diffpy/srfit/pdf/basepdfgenerator.py

from diffpy.utils._deprecator import deprecated
from diffpy.cmipdf.basepdfgenerator import BasePDFGenerator as _NewBasePDFGenerator

3) deprecate the old function within this file

This step points the old function to the new function and allows for backwards compatibility. This code will be removed in the future when we decide its time to remove deprecated functions. The decorator @deprecated() is where you house your deprecation message. Make sure your message as the old import location, new import location, and what version it will be removed in.

class BasePDFGenerator(ProfileGenerator):
   ...
    @deprecated(
        "`diffpy.srfit.pdf.basepdfgenerator.BasePDFGenerator._setCalculator` is deprecated and will be 
           removed in version 2.0.0. "
          "Use `diffpy.cmipdf.basepdfgenerator.BasePDFGenerator._set_calculator` instead."
    )
    def _setCalculator(self, calc):
        """Deprecated alias for `diffpy.cmipdf.basepdfgenerator.BasePDFGenerator._set_calculator`."""
        return _NewBasePDFGenerator._set_calculator(self, calc)

4) Create an issue "deprecated: remove functions on release of "

In this issue, write down every function you deprecated so we know what to remove in the future.