added @deprecated and @experimental

Author: jlwalke2

src/sasctl/utils/decorators.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python
+# encoding: utf-8
+#
+# Copyright © 2019, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import functools
+import textwrap
+import warnings
+
+import six
+
+
+class ExperimentalWarning(UserWarning):
+    """Warning raised by @experimental decorator."""
+    pass
+
+
+def _insert_docstring_text(func, text):
+    docstring = func.__doc__ or ''
+
+    # Dedent the existing docstring.  Multi-line docstrings are only indented
+    # after the first line, so split before dedenting.
+    if '\n' in docstring:
+        first_line, remainder = docstring.split('\n', 1)
+        docstring = first_line + '\n' + textwrap.dedent(remainder)
+    else:
+        docstring = textwrap.dedent(docstring)
+
+    docstring = docstring.strip()
+
+    text = ('',
+            text,
+            '')
+
+    return docstring + '\n'.join(text)
+
+
+def deprecated(reason=None, version=None, removed_in=None):
+    """Decorate a function or class to designated it as deprecated.
+
+    Will raise a `DeprecationWarning` when used and automatically adds a
+    Sphinx '.. deprecated::' directive to the docstring.
+
+    Parameters
+    ----------
+    reason : str, optional
+        User-friendly reason for deprecating.
+    version : str
+        Version in which initially marked as deprecated.
+    removed_in : str, optional
+        Version in which the class or function will be removed.
+
+    Returns
+    -------
+    decorator
+
+    """
+    if version is None:
+        raise ValueError('version must be specified.')
+
+    def decorator(func):
+
+        @functools.wraps(func)
+        def _wrapper(*args, **kwargs):
+            warning = '%s is deprecated since version %s' % (func.__name__, version)
+
+            if removed_in is not None:
+                warning += ' and will be removed in version %s.' % removed_in
+            else:
+                warning += ' and may be removed in a future version.'
+
+            if reason is not None:
+                warning = warning + '  ' + reason
+
+            warnings.warn(warning,
+                          category=DeprecationWarning, stacklevel=2)
+            return func(*args, **kwargs)
+
+        # Generate Sphinx deprecated directive
+        directive = '.. deprecated:: %s' % version
+
+        if reason is not None:
+            directive += '\n  %s' % reason
+
+        # Insert directive into original docstring
+        _wrapper.__doc__ = _insert_docstring_text(func, directive)
+
+        return _wrapper
+
+    return decorator
+
+
+def experimental(func):
+    """Decorate a function or class to designated it as experimental.
+
+    Will raise an `ExperimentalWarning` when used and automatically adds a
+    Sphinx '.. warning::' directive to the docstring.
+
+    Parameters
+    ----------
+    func
+
+    Returns
+    -------
+    func
+
+    """
+    @functools.wraps(func)
+    def _wrapper(*args, **kwargs):
+        warning = '%s is experimental and may be modified or removed without warning.' % func.__name__
+        warnings.warn(warning,
+                      category=ExperimentalWarning, stacklevel=2)
+        return func(*args, **kwargs)
+
+    type_ = 'class' if isinstance(func, six.class_types) else 'method'
+    directive = '.. warning:: This %s is experimental and may be modified or removed without warning.' % type_
+
+    # Insert directive into original docstring
+    _wrapper.__doc__ = _insert_docstring_text(func, directive)
+
+    return _wrapper
+

tests/unit/test_decorators.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python
+# encoding: utf-8
+#
+# Copyright © 2019, SAS Institute Inc., Cary, NC, USA.  All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import pytest
+
+from sasctl.utils.decorators import deprecated, experimental, ExperimentalWarning
+
+
+def test_deprecated():
+    """Function can be deprecated with @deprecated(version=XX)."""
+    @deprecated(version=1.2)
+    def old_function(a):
+        """Do old stuff.
+
+        Parameters
+        ----------
+        a : any
+
+        Returns
+        -------
+        stuff
+
+        """
+        return a
+
+    # Calling the function should raise a warning
+    with pytest.warns(DeprecationWarning) as warnings:
+        result = old_function('spam')
+
+    msg = warnings[0].message
+    assert 'old_function is deprecated since version 1.2 and may be removed in a future version.' == str(msg)
+    assert '.. deprecated:: 1.2' in old_function.__doc__
+
+    # Return value from function should be unchanged.
+    assert result == 'spam'
+
+
+def test_deprecated_with_reason():
+    """Function can be deprecated with @deprecated(reason, version=XX)."""
+    @deprecated('Use new_function instead.', version=1.3)
+    def old_function(a):
+        """Do old stuff.
+
+        Parameters
+        ----------
+        a : any
+
+        Returns
+        -------
+        stuff
+
+        """
+        return a
+
+    # Calling the function should raise a warning
+    with pytest.warns(DeprecationWarning) as warnings:
+        result = old_function('spam')
+
+    msg = warnings[0].message
+    assert 'old_function is deprecated since version 1.3 and may be removed in a future version.  Use new_function instead.' == str(msg)
+    assert '.. deprecated:: 1.3\n  Use new_function instead.' in old_function.__doc__
+
+    # Return value from function should be unchanged.
+    assert result == 'spam'
+
+
+def test_experimental_function():
+    @experimental
+    def new_function(p):
+        """Revive a dead parrot.
+
+        Parameters
+        ----------
+        p : parrot
+
+        Returns
+        -------
+        parrot
+
+        """
+        return p
+
+    # Calling the function should raise a warning
+    with pytest.warns(ExperimentalWarning) as warnings:
+        result = new_function('norwegian blue')
+
+    assert '.. warning:: ' in new_function.__doc__
+
+    # Return value from function should be unchanged.
+    assert result == 'norwegian blue'
+
+
+def test_experimental_class():
+    @experimental
+    class NewClass:
+        pass
+
+    # Calling the function should raise a warning
+    with pytest.warns(ExperimentalWarning) as warnings:
+        result = NewClass()
+
+    assert '.. warning:: ' in NewClass.__doc__