Deprecate @pytask.mark.parametrize. (#381)

docs/source/changes.md

@@ -20,6 +20,7 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
   documentation.
 - {pull}`368` fixes an error in `update_plugin_list.py` introduced by {pull}`364`.
 - {pull}`369` reverts the changes that turn `Node.state()` into a hook.
+- {pull}`381` deprecates `@pytask.mark.parametrize`. (Closes {issue}`233`.)
 
 ## 0.3.1 - 2023-12-25
 

src/_pytask/collect.py

@@ -6,6 +6,7 @@
 import os
 import sys
 import time
+import warnings
 from importlib import util as importlib_util
 from pathlib import Path
 from typing import Any
@@ -105,6 +106,15 @@ def pytask_collect_file_protocol(
     return flat_reports
 
 
+_PARAMETRIZE_DEPRECATION_WARNING = """\
+The @pytask.mark.parametrize decorator is deprecated and will be removed in pytask \
+v0.4. Either upgrade your code to the new syntax explained in \
+https://tinyurl.com/pytask-loops or silence the warning by setting \
+`silence_parametrize_deprecation = true` in your pyproject.toml under \
+[tool.pytask.ini_options] and pin pytask to <0.4.
+"""
+
+
 @hookimpl
 def pytask_collect_file(
     session: Session, path: Path, reports: list[CollectionReport]
@@ -126,6 +136,13 @@ def pytask_collect_file(
                 continue
 
             if has_mark(obj, "parametrize"):
+                if not session.config.get("silence_parametrize_deprecation", False):
+                    warnings.warn(
+                        message=_PARAMETRIZE_DEPRECATION_WARNING,
+                        category=FutureWarning,
+                        stacklevel=1,
+                    )
+
                 names_and_objects = session.hook.pytask_parametrize_task(
                     session=session, name=name, obj=obj
                 )

src/_pytask/warnings_utils.py

@@ -155,8 +155,7 @@ def catch_warnings_for_item(
 ) -> Generator[None, None, None]:
     """Context manager that catches warnings generated in the contained execution block.
 
-    ``item`` can be None if we are not in the context of an item execution. Each warning
-    captured triggers the ``pytest_warning_recorded`` hook.
+    ``item`` can be None if we are not in the context of an item execution.
 
     """
     with warnings.catch_warnings(record=True) as log:

tests/test_parametrize.py

@@ -492,3 +492,40 @@ def task_write_numbers_to_file(i):
     session = main({"paths": tmp_path})
 
     assert session.exit_code == ExitCode.OK
+
+
+@pytest.mark.end_to_end()
+def test_deprecation_warning_for_parametrizing_tasks(runner, tmp_path):
+    source = """
+    import pytask
+
+    @pytask.mark.parametrize('i, produces', [(1, "1.txt"), (2, "2.txt")])
+    def task_write_numbers_to_file(produces, i):
+        produces.write_text(str(i))
+    """
+    tmp_path.joinpath("task_module.py").write_text(textwrap.dedent(source))
+
+    result = runner.invoke(cli, [tmp_path.as_posix()])
+
+    assert result.exit_code == ExitCode.OK
+    assert "FutureWarning" in result.output
+
+
+@pytest.mark.end_to_end()
+def test_silence_deprecation_warning_for_parametrizing_tasks(runner, tmp_path):
+    source = """
+    import pytask
+
+    @pytask.mark.parametrize('i, produces', [(1, "1.txt"), (2, "2.txt")])
+    def task_write_numbers_to_file(produces, i):
+        produces.write_text(str(i))
+    """
+    tmp_path.joinpath("task_module.py").write_text(textwrap.dedent(source))
+    tmp_path.joinpath("pyproject.toml").write_text(
+        "[tool.pytask.ini_options]\nsilence_parametrize_deprecation = true"
+    )
+
+    result = runner.invoke(cli, [tmp_path.as_posix()])
+
+    assert result.exit_code == ExitCode.OK
+    assert "FutureWarning" not in result.output