Repository: nilearn/nilearn

Issue:
[Quality] Improving the replace_parameters decorator
The decorator [`nilearn._utils.helpers.replace_parameters`](https://github.com/nilearn/nilearn/blob/7fd55bad75a087ac591edf4c00c85a5806a1c461/nilearn/_utils/helpers.py#L5) would be better renamed to `rename_parameters`, affording clarity to its purpose. This is not a user facing change.

Currently this decorator raises a Python `DeprecationWarning`. It should raise a Python `FutureWarning` instead. The former is intended to only be for developers and is ignored by default, while the latter  is for users (including developers) and is shown by default. 
This change tracks with Python guidelines about how to use these warnings and also removes the extra code written to always show the `DeprecationWarning`.


Discussion:
I will also update the tests for the decorator and the decorated functions to use pytests. Some of the tests need to be corrected as well.

Resolving patch:
diff --git a/nilearn/_utils/__init__.py b/nilearn/_utils/__init__.py
--- a/nilearn/_utils/__init__.py
+++ b/nilearn/_utils/__init__.py
@@ -8,9 +8,9 @@
 from .cache_mixin import CacheMixin
 
 from .logger import _compose_err_msg
-from nilearn._utils.helpers import replace_parameters
+from nilearn._utils.helpers import rename_parameters
 
 __all__ = ['check_niimg', 'check_niimg_3d', 'concat_niimgs', 'check_niimg_4d',
            '_repr_niimgs', 'copy_img', 'load_niimg',
-           'as_ndarray', 'CacheMixin', '_compose_err_msg', 'replace_parameters',
+           'as_ndarray', 'CacheMixin', '_compose_err_msg', 'rename_parameters',
            ]
diff --git a/nilearn/_utils/helpers.py b/nilearn/_utils/helpers.py
--- a/nilearn/_utils/helpers.py
+++ b/nilearn/_utils/helpers.py
@@ -2,10 +2,10 @@
 import warnings
 
 
-def replace_parameters(replacement_params,
-                       end_version='future',
-                       lib_name='Nilearn',
-                       ):
+def rename_parameters(replacement_params,
+                      end_version='future',
+                      lib_name='Nilearn',
+                      ):
     """
     Decorator to deprecate & replace specificied parameters
     in the decorated functions and methods
@@ -74,8 +74,7 @@ def _warn_deprecated_params(replacement_params, end_version, lib_name, kwargs):
                                                             replacement_param,
                                                             )
         )
-        warnings.filterwarnings('always', message=param_deprecation_msg)
-        warnings.warn(category=DeprecationWarning,
+        warnings.warn(category=FutureWarning,
                       message=param_deprecation_msg,
                       stacklevel=3)
 
diff --git a/nilearn/plotting/html_connectome.py b/nilearn/plotting/html_connectome.py
--- a/nilearn/plotting/html_connectome.py
+++ b/nilearn/plotting/html_connectome.py
@@ -3,7 +3,7 @@
 import numpy as np
 from scipy import sparse
 
-from nilearn._utils import replace_parameters
+from nilearn._utils import rename_parameters
 from .. import datasets
 from . import cm
 
@@ -99,10 +99,10 @@ def _replacement_params_view_connectome():
     }
 
 
-@replace_parameters(replacement_params=_replacement_params_view_connectome(),
-                    end_version='0.6.0',
-                    lib_name='Nilearn'
-                    )
+@rename_parameters(replacement_params=_replacement_params_view_connectome(),
+                   end_version='0.6.0',
+                   lib_name='Nilearn'
+                   )
 def view_connectome(adjacency_matrix, node_coords, edge_threshold=None,
                     edge_cmap=cm.bwr, symmetric_cmap=True,
                     linewidth=6., node_size=3., colorbar=True,
@@ -199,10 +199,10 @@ def _replacement_params_view_markers():
             }
 
 
-@replace_parameters(replacement_params=_replacement_params_view_markers(),
-                    end_version='0.6.0',
-                    lib_name='Nilearn',
-                    )
+@rename_parameters(replacement_params=_replacement_params_view_markers(),
+                   end_version='0.6.0',
+                   lib_name='Nilearn',
+                   )
 def view_markers(marker_coords, marker_color=None, marker_size=5.,
                  title=None, title_fontsize=25):
     """


Test patch:
diff --git a/nilearn/plotting/tests/test_html_connectome.py b/nilearn/plotting/tests/test_html_connectome.py
--- a/nilearn/plotting/tests/test_html_connectome.py
+++ b/nilearn/plotting/tests/test_html_connectome.py
@@ -135,7 +135,7 @@ def test_params_deprecation_view_connectome():
     old_params = ['coords', 'threshold', 'cmap', 'marker_size']
     for old_param_, raised_warning_ in zip(old_params, raised_warnings):
         assert warning_msgs[old_param_] == str(raised_warning_.message)
-        assert raised_warning_.category is DeprecationWarning
+        assert raised_warning_.category is FutureWarning
 
 
 def test_get_markers():
@@ -199,4 +199,4 @@ def test_params_deprecation_view_markers():
     assert len(raised_warnings) == 2
     for old_param_, raised_warning_ in zip(old_params, raised_warnings):
         assert warning_msgs[old_param_] == str(raised_warning_.message)
-        assert raised_warning_.category is DeprecationWarning
+        assert raised_warning_.category is FutureWarning
diff --git a/nilearn/tests/test_helpers.py b/nilearn/tests/test_helpers.py
--- a/nilearn/tests/test_helpers.py
+++ b/nilearn/tests/test_helpers.py
@@ -21,7 +21,7 @@ def _mock_args_for_testing_replace_parameter():
     return mock_kwargs_with_deprecated_params_used, replacement_params
 
 
-def test_replace_parameters():
+def test_rename_parameters():
     """ Integration tests that deprecates mock parameters in a mock function
     and checks that the deprecated parameters transfer their values correctly
     to replacement parameters and all deprecation warning are raised as
@@ -40,7 +40,7 @@ def test_replace_parameters():
          ),
         ]
     
-    @helpers.replace_parameters(replacement_params, '0.6.1rc', 'other_lib', )
+    @helpers.rename_parameters(replacement_params, '0.6.1rc', 'other_lib', )
     def mock_function(replacement_param_0, replacement_param_1,
                       unchanged_param_0, unchanged_param_1):
         return (replacement_param_0, replacement_param_1, unchanged_param_0,
@@ -60,7 +60,7 @@ def mock_function(replacement_param_0, replacement_param_1,
     raised_warnings.sort(key=lambda mem: str(mem.message))
     for raised_warning_, expected_warning_ in zip(raised_warnings,
                                                   expected_warnings):
-        assert raised_warning_.category is DeprecationWarning
+        assert raised_warning_.category is FutureWarning
         assert str(raised_warning_.message) == expected_warning_
 
 
@@ -108,5 +108,5 @@ def test_future_warn_deprecated_params():
     for raised_warning_, expected_warning_ in zip(raised_warnings,
                                                   expected_warnings
                                                   ):
-        assert raised_warning_.category is DeprecationWarning
+        assert raised_warning_.category is FutureWarning
         assert str(raised_warning_.message) == expected_warning_