From 2cb8b93dc4cc5fdc7c1b014e6ffa21cfc410e901 Mon Sep 17 00:00:00 2001
From: Tobias Raabe <raabe@posteo.de>
Date: Sun, 10 Sep 2023 19:49:58 +0200
Subject: [PATCH] Deprecate using @task as a mark decorator.

---
 docs/source/changes.md         |  1 +
 src/_pytask/mark/__init__.pyi  | 14 ++++++++++++++
 src/_pytask/mark/structures.py |  7 +++++++
 src/pytask/__init__.py         |  2 ++
 tests/test_mark.py             | 18 ++++++++++++++++++
 5 files changed, 42 insertions(+)

diff --git a/docs/source/changes.md b/docs/source/changes.md
index fcdc005c..7e85b0e6 100644
--- a/docs/source/changes.md
+++ b/docs/source/changes.md
@@ -34,6 +34,7 @@ releases are available on [PyPI](https://pypi.org/project/pytask) and
 - {pull}`413` removes scripts to generate `.svg`s.
 - {pull}`414` allow more ruff rules.
 - {pull}`416` removes `.from_annot` again.
+- {pull}`417` deprecates {func}`pytask.mark.task` in favor of {func}`pytask.task`.
 
 ## 0.3.2 - 2023-06-07
 
diff --git a/src/_pytask/mark/__init__.pyi b/src/_pytask/mark/__init__.pyi
index 3dac4a4e..2894e6bf 100644
--- a/src/_pytask/mark/__init__.pyi
+++ b/src/_pytask/mark/__init__.pyi
@@ -1,4 +1,5 @@
 from pathlib import Path
+from typing import Any
 from typing_extensions import deprecated
 from _pytask.mark.expression import Expression
 from _pytask.mark.expression import ParseError
@@ -28,6 +29,19 @@ class MARK_GEN:  # noqa: N801
     )
     @staticmethod
     def depends_on(objects: PyTree[str | Path]) -> None: ...
+    @deprecated(
+        "'@pytask.mark.task' is deprecated starting pytask v0.4.0 and will be removed in v0.5.0. Use '@pytask.task' instead.",  # noqa: E501, PYI053
+        category=DeprecationWarning,
+        stacklevel=1,
+    )
+    @staticmethod
+    def task(
+        name: str | None = None,
+        *,
+        id: str | None = None,  # noqa: A002
+        kwargs: dict[Any, Any] | None = None,
+        produces: PyTree[Any] = None,
+    ) -> None: ...
 
 __all__ = [
     "Expression",
diff --git a/src/_pytask/mark/structures.py b/src/_pytask/mark/structures.py
index 242fd1e9..1531e3ea 100644
--- a/src/_pytask/mark/structures.py
+++ b/src/_pytask/mark/structures.py
@@ -230,6 +230,13 @@ def __getattr__(self, name: str) -> MarkDecorator | Any:
         if name == "task":
             from _pytask.task_utils import task
 
+            warnings.warn(
+                "'@pytask.mark.task' is deprecated starting pytask v0.4.0 and will be "
+                "removed in v0.5.0. Use '@pytask.task' instead.",
+                category=DeprecationWarning,
+                stacklevel=1,
+            )
+
             return task
 
         return MarkDecorator(Mark(name, (), {}))
diff --git a/src/pytask/__init__.py b/src/pytask/__init__.py
index 4c4f255a..2a88d423 100644
--- a/src/pytask/__init__.py
+++ b/src/pytask/__init__.py
@@ -58,6 +58,7 @@
 from _pytask.report import DagReport
 from _pytask.report import ExecutionReport
 from _pytask.session import Session
+from _pytask.task_utils import task
 from _pytask.traceback import format_exception_without_traceback
 from _pytask.traceback import remove_internal_traceback_frames_from_exc_info
 from _pytask.traceback import remove_traceback_from_exc_info
@@ -139,5 +140,6 @@
     "remove_traceback_from_exc_info",
     "render_exc_info",
     "set_marks",
+    "task",
     "warning_record_to_str",
 ]
diff --git a/tests/test_mark.py b/tests/test_mark.py
index f9ccf93a..cd2355ed 100644
--- a/tests/test_mark.py
+++ b/tests/test_mark.py
@@ -377,3 +377,21 @@ def task_write_text(depends_on, produces):
     )
     assert b"DeprecationWarning: '@pytask.mark.depends_on'" in result.stdout
     assert b"DeprecationWarning: '@pytask.mark.produces'" in result.stdout
+
+
+@pytest.mark.end_to_end()
+def test_deprecation_warnings_for_task_decorator(tmp_path):
+    source = """
+    import pytask
+
+    @pytask.mark.task
+    def task_write_text(): ...
+    """
+    tmp_path.joinpath("task_module.py").write_text(textwrap.dedent(source))
+
+    result = subprocess.run(
+        ("pytest", tmp_path.joinpath("task_module.py").as_posix()),
+        capture_output=True,
+        check=False,
+    )
+    assert b"DeprecationWarning: '@pytask.mark.task'" in result.stdout