Deprecate @pytask.mark.task in favor of @pytask.task. (#417)

Author: tobiasraabe

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
 

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",

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, (), {}))

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",
 ]

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