diff --git a/CHANGELOG.rst b/CHANGELOG.rst index df9f7e00..27fd6883 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -15,7 +15,7 @@ Added - Explicit support for Python 3.11. - Added deprecation tools for deprecating functions and arguments. - Added Pre-Commit for code formatting. - +- Added deprecation tools for deprecating functions, parameters, methods, and properties. Changed ------- diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 949ed51e..809433c4 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -140,15 +140,15 @@ with a possible alternative to be used. The decorator should be placed right above the object signature to be deprecated:: .. code-block:: python - >>> from diffsims.utils._deprecated import deprecate - >>> @deprecate(since=0.8, removal=0.9, alternative="bar") - >>> def foo(self, n): - >>> return n + 1 - - >>> @property - >>> @deprecate(since=0.9, removal=0.10, alternative="another", is_function=True) - >>> def this_property(self): - >>> return 2 + from diffsims.utils._deprecated import deprecate + @deprecate(since=0.8, removal=0.9, alternative="bar") + def foo(self, n): + return n + 1 + + @property + @deprecate(since=0.9, removal=0.10, alternative="another", is_function=True) + def this_property(self): + return 2 Build and write documentation diff --git a/diffsims/utils/_deprecated.py b/diffsims/utils/_deprecated.py index a4f1bb18..c697f052 100644 --- a/diffsims/utils/_deprecated.py +++ b/diffsims/utils/_deprecated.py @@ -18,8 +18,10 @@ """Helper functions and classes for managing diffsims. + This module and documentation is only relevant for diffsims developers, not for users. + .. warning: This module and its submodules are for internal use only. Do not use them in your own code. We may change the API at any time with no @@ -37,11 +39,10 @@ class deprecated: """Decorator to mark deprecated functions with an informative warning. + Adapted from - `scikit-image - `_ - and `matplotlib - `_. + `scikit-image`_ + and `matplotlib`_. """ def __init__( @@ -52,6 +53,7 @@ def __init__( removal: Union[str, int, float, None] = None, ): """Visible deprecation warning. + Parameters ---------- since @@ -116,6 +118,7 @@ def wrapped(*args, **kwargs): class deprecated_argument: """Decorator to remove an argument from a function or method's signature. + Adapted from `scikit-image `_. """