Repository: cogent3/cogent3
Pull request #1379 (2023-04-23 22:17:30)

DEV: tweak discontinued_args plus docstring tidy


Patch:
diff --git a/src/cogent3/__init__.py b/src/cogent3/__init__.py
index b8fca005e..6f9dbf337 100644
--- a/src/cogent3/__init__.py
+++ b/src/cogent3/__init__.py
@@ -18,7 +18,6 @@ from cogent3.core.alignment import (
     SequenceCollection,
 )
 from cogent3.core.genetic_code import available_codes, get_code
-
 # note that moltype has to be imported last, because it sets the moltype in
 # the objects created by the other modules.
 from cogent3.core.moltype import (
diff --git a/src/cogent3/core/alignment.py b/src/cogent3/core/alignment.py
index 271aae1d2..f17f59bfd 100644
--- a/src/cogent3/core/alignment.py
+++ b/src/cogent3/core/alignment.py
@@ -56,7 +56,6 @@ from cogent3.core.genetic_code import get_code
 from cogent3.core.info import Info as InfoClass
 from cogent3.core.profile import PSSM, MotifCountsArray
 from cogent3.core.sequence import ArraySequence, Sequence, frac_same
-
 # which is a circular import otherwise.
 from cogent3.format.alignment import save_to_filename
 from cogent3.format.fasta import alignment_to_fasta
diff --git a/src/cogent3/util/warning.py b/src/cogent3/util/warning.py
index da0b95434..3954fdf7b 100644
--- a/src/cogent3/util/warning.py
+++ b/src/cogent3/util/warning.py
@@ -76,25 +76,28 @@ def deprecated_args(
     version: str,
     reason: str,
     old_new: List[Tuple[str, str]] = None,
-    discontinued: str = None,
+    discontinued: List[str] = None,
 ) -> Callable[..., Any]:
     """
     A decorator that marks specific arguments of a function as deprecated.
 
-    The decorator accepts a list of 2-tuples specifying the mapping of old argument names to new argument names.
-    When the decorated function is called with any of the old argument names, they will be replaced with their
+    The decorator accepts a list of 2-tuples specifying the mapping of old
+    argument names to new argument names. When the decorated function is
+    called with any of the old argument names, they will be replaced with their
     corresponding new names in the kwargs dictionary.
 
     Parameters
     ----------
     version : str
-        The version when the old arguments will be removed in calver format, e.g. 'YYYY.MM'
+        The version when the old arguments will be removed in calver
+        format, e.g. 'YYYY.MM'
     reason : str
         Reason for deprecation or guidance on what to do
     old-new : List[Tuple[str, str]]
         A list of deprecated old and replacement new argument names.
-    discontinued : str
-        A discontinued argument name
+    discontinued : List[str]
+        Names of single or multiple arguments to be discontinued. This should
+        only be applied to arguments that have no effect.
 
     Returns
     -------
@@ -104,22 +107,31 @@ def deprecated_args(
     Warnings
     --------
     DeprecationWarning
-        A warning will be raised when the decorated function is called for each deprecated argument
-        used in the calling function.
+        A warning will be raised when the decorated function is called for
+        each deprecated argument used in the calling function.
 
     Examples
     --------
-    Here's an example of how to use the `deprecated_args` decorator to mark the argument `old_name` as deprecated
-    and replace it with the new name `new_name`.
-
-    >>> @deprecated_args('2.0', 'Use new_name instead',old_new=[('old_arg', 'new_arg')],discontinued='discontinued_arg',)
+    To use, change the signature of the function / method by removing the
+    deprecated / discontinued arguments. Apply the decorator to the function,
+    indicating the old and new the argument names.
+
+    >>> @deprecated_args('2024.1',
+    ...                  'Use new_name instead',
+    ...                  old_new=[('old_arg', 'new_arg')],
+    ...                  discontinued='discontinued_arg',
+    ... )
     >>> def my_function(new_name):
     >>>     # do something here
 
-    When `my_function` is called with the argument `old_arg`, a warning will be raised indicating that the argument
-    is deprecated and should be replaced with `new_arg`, and `discontinued_arg` is to be discontinued.
+    When `my_function` is called with the argument `old_arg`, a warning
+    will be raised indicating that the argument is deprecated and should
+    be replaced with `new_arg`, and `discontinued_arg` is to be
+    discontinued.
     """
 
+    discontinued = [discontinued] if isinstance(discontinued, str) else discontinued
+
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
         @functools.wraps(func)
         def wrapper(*args: Any, **kwargs: Any) -> Callable[..., Any]:
@@ -128,8 +140,10 @@ def deprecated_args(
                     if old in kwargs:
                         kwargs[new] = kwargs.pop(old)
                         deprecated("argument", old, new, version, reason)
-            if discontinued and discontinued in kwargs:
-                _discontinued("argument", discontinued, version, reason)
+            if discontinued:
+                for dropped in discontinued:
+                    if dropped in kwargs:
+                        _discontinued("argument", dropped, version, reason)
 
             return func(*args, **kwargs)
 


Test patch:
diff --git a/tests/test_core/test_features.py b/tests/test_core/test_features.py
index f7a29155f..9bed39b37 100755
--- a/tests/test_core/test_features.py
+++ b/tests/test_core/test_features.py
@@ -2,7 +2,6 @@ from unittest import TestCase, main
 
 from cogent3 import ASCII, DNA, make_aligned_seqs
 from cogent3.core.annotation import Feature, Variable
-
 # Complete version of manipulating sequence annotations
 from cogent3.util.deserialise import deserialise_object
 
diff --git a/tests/test_tree_distance.py b/tests/test_tree_distance.py
index d7a4b172f..684a05c0f 100644
--- a/tests/test_tree_distance.py
+++ b/tests/test_tree_distance.py
@@ -1,4 +1,5 @@
 import pathlib
+
 import pytest
 
 from cogent3 import make_tree
diff --git a/tests/test_util/test_warning.py b/tests/test_util/test_warning.py
index 90ac8d28b..47c4da2ec 100644
--- a/tests/test_util/test_warning.py
+++ b/tests/test_util/test_warning.py
@@ -229,7 +229,7 @@ def test_deprecated_callable_resolves_type(recwarn, func, _type):
 @pytest.mark.filterwarnings("ignore::DeprecationWarning")
 def test_function_deprecated_args_deprecated_callable_chained_decorators(recwarn):
     @deprecated_args("2023.6", "x is not descriptive", old_new=[("x", "a")])
-    @deprecated_args("2023.6", "b is no longer required", discontinued="b")
+    @deprecated_args("2023.6", "b is no longer required", discontinued=["b"])
     @deprecated_callable(
         "2023.6", "Improved change function", new="changed2", is_discontinued=True
     )