Simplify deferred annotation handling code

- Remove redundant _snapshot_annotation_locals function (was just a copy)
- Use _caller_locals directly instead of double-copying
- Fix priority order in _build_evaluation_locals: snapshot locals now
  have highest priority over default arguments
- Use public API inspect.Parameter.empty instead of inspect._empty
- Clean up duplicate docstring entries for id, kwargs, produces
- Remove unnecessary C901 noqa (function simplified)

Author: tobiasraabe

src/_pytask/_inspect.py

@@ -73,11 +73,14 @@ def get_annotations(
 def _build_evaluation_locals(
     obj: Callable[..., Any], provided_locals: dict[str, Any] | None
 ) -> dict[str, Any]:
+    # Order matters: later updates override earlier ones.
+    # Default arguments are lowest priority (fallbacks), then provided_locals,
+    # then snapshot_locals (captured loop variables) have highest priority.
     evaluation_locals: dict[str, Any] = {}
+    evaluation_locals.update(_get_default_argument_locals(obj))
     if provided_locals:
         evaluation_locals.update(provided_locals)
     evaluation_locals.update(_get_snapshot_locals(obj))
-    evaluation_locals.update(_get_default_argument_locals(obj))
     return evaluation_locals
 
 
@@ -95,7 +98,7 @@ def _get_default_argument_locals(obj: Callable[..., Any]) -> dict[str, Any]:
 
     defaults = {}
     for parameter in parameters:
-        if parameter.default is not inspect._empty:
+        if parameter.default is not inspect.Parameter.empty:
             defaults[parameter.name] = parameter.default
     return defaults
 

src/_pytask/task_utils.py

@@ -44,7 +44,7 @@
 """
 
 
-def task(  # noqa: PLR0913, C901
+def task(  # noqa: PLR0913
     name: str | None = None,
     *,
     after: str | Callable[..., Any] | list[Callable[..., Any]] | None = None,
@@ -72,30 +72,18 @@ def task(  # noqa: PLR0913, C901
         information.
     is_generator
         An indicator whether this task is a task generator.
-    id
-        An id for the task if it is part of a parametrization. Otherwise, an automatic
-        id will be generated. See
-        :doc:`this tutorial <../tutorials/repeating_tasks_with_different_inputs>` for
-        more information.
-    kwargs
-        A dictionary containing keyword arguments which are passed to the task when it
-        is executed.
-    produces
-        Definition of products to parse the function returns and store them. See
-        :doc:`this how-to guide <../how_to_guides/using_task_returns>` for more
     id
         An id for the task if it is part of a repetition. Otherwise, an automatic id
         will be generated. See :ref:`how-to-repeat-a-task-with-different-inputs-the-id`
         for more information.
     kwargs
-        Use a dictionary to pass any keyword arguments to the task function which can be
-        dependencies or products of the task. Read :ref:`task-kwargs` for more
-        information.
-    produces
-        Use this argument if you want to parse the return of the task function as a
-        product, but you cannot annotate the return of the function. See :doc:`this
-        how-to guide <../how_to_guides/using_task_returns>` or :ref:`task-produces` for
+        A dictionary containing keyword arguments which are passed to the task function.
+        These can be dependencies or products of the task. Read :ref:`task-kwargs` for
         more information.
+    produces
+        Use this argument to parse the return of the task function as a product. See
+        :doc:`this how-to guide <../how_to_guides/using_task_returns>` or
+        :ref:`task-produces` for more information.
 
     Examples
     --------
@@ -150,8 +138,6 @@ def wrapper(func: Callable[..., Any]) -> Callable[..., Any]:
         parsed_name = _parse_name(unwrapped, name)
         parsed_after = _parse_after(after)
 
-        annotation_locals = _snapshot_annotation_locals(_caller_locals)
-
         if hasattr(unwrapped, "pytask_meta"):
             unwrapped.pytask_meta.after = parsed_after
             unwrapped.pytask_meta.is_generator = is_generator
@@ -160,11 +146,11 @@ def wrapper(func: Callable[..., Any]) -> Callable[..., Any]:
             unwrapped.pytask_meta.markers.append(Mark("task", (), {}))
             unwrapped.pytask_meta.name = parsed_name
             unwrapped.pytask_meta.produces = produces
-            unwrapped.pytask_meta.after = parsed_after
+            unwrapped.pytask_meta.annotation_locals = _caller_locals
         else:
             unwrapped.pytask_meta = CollectionMetadata(  # type: ignore[attr-defined]
                 after=parsed_after,
-                annotation_locals=annotation_locals,
+                annotation_locals=_caller_locals,
                 is_generator=is_generator,
                 id_=id,
                 kwargs=parsed_kwargs,
@@ -173,9 +159,6 @@ def wrapper(func: Callable[..., Any]) -> Callable[..., Any]:
                 produces=produces,
             )
 
-        if annotation_locals is not None and hasattr(unwrapped, "pytask_meta"):
-            unwrapped.pytask_meta.annotation_locals = annotation_locals
-
         if coiled_kwargs and hasattr(unwrapped, "pytask_meta"):
             unwrapped.pytask_meta.attributes["coiled_kwargs"] = coiled_kwargs
 
@@ -314,22 +297,6 @@ def parse_keyword_arguments_from_signature_defaults(
     return kwargs
 
 
-def _snapshot_annotation_locals(
-    caller_locals: dict[str, Any] | None,
-) -> dict[str, Any] | None:
-    """Capture caller's frame locals at decoration time for deferred annotation eval.
-
-    This function captures variables that may be referenced in type annotations but
-    won't be available when annotations are evaluated later (e.g., loop variables in
-    task generators under Python 3.14's PEP 649 deferred annotations).
-
-    We capture the caller's frame locals - variables in the scope where @task is
-    applied (e.g., loop variables like `path` that are only referenced in annotations).
-
-    """
-    return caller_locals.copy() if caller_locals else None
-
-
 def _generate_ids_for_tasks(
     tasks: list[tuple[str, Callable[..., Any]]],
 ) -> dict[str, Callable[..., Any]]: