Summary

Addresses the IDE/introspection pain point from #902 and picks up the non-breaking part of #910 by @LennartGevers (credited as co-author). Unlike #910, this keeps PipeFunc.__call__'s pipeline semantics (renames, defaults, bound, hooks, profiling) fully intact — no behavior changes.

• PipeFunc is now Generic[P, R] using ParamSpec, and @pipefunc returns PipeFunc[P, R]. Type checkers and IDEs now see the wrapped function's parameter names, types, and return type when calling it, while PipeFunc methods (update_renames, update_scope, ...) stay available and typed:

  @pipefunc(output_name="c")
  def add(a: int, b: float) -> float:
      """Add two numbers."""
      return a + b
  
  reveal_type(add)         # PipeFunc[[a: int, b: float], float]
  reveal_type(add(1, 2.0)) # float
  add("x", "y")            # error: incompatible argument types

• __doc__ propagation: the wrapped function's docstring is exposed on the instance, so help(f) and Jupyter's f? show the original docs. Class docstrings of callable instances are deliberately not copied.

• __wrapped__ property following the functools.wraps convention. inspect.signature is unaffected since the existing __signature__ (which reflects renames/defaults) takes precedence.

• __test__ = False on PipeFunc: pytest follows __wrapped__ during collection, so without this it would collect PipeFunc objects wrapping functions named test* (this bit our own tests/integration/map/test_error_handling.py).

Trade-off

The static signature is the original one, so calls using renamed/scoped parameters (f(a1=3) after renames={"a": "a1"}) are now flagged by type checkers even though they work at runtime — ParamSpec cannot express runtime signature rewrites (see the discussion in #910). Runtime behavior is unchanged; tests covering that dynamic behavior gained targeted # type: ignore[call-arg] comments. Unannotated functions are unaffected (gradual typing).

The remaining #910 question — whether __call__ should bypass pipeline semantics entirely — is left open; this PR is forward-compatible with either answer.

Verification

• New tests: docstring propagation, fallback to class docstring, __wrapped__, pickle round-trip, inspect.signature precedence, callable-instance docstring exclusion.
• Full suite: 1400 passed, 11 skipped, 2 xfailed.
• pre-commit run --all-files (ruff, mypy, etc.) passes.
• mypy probe confirms P/R bind correctly (revealed types above).

Part of #902; continues #910.

Breaking change (typing only)

PipeFunc was previously Generic[T] with a single type parameter (T bound to Callable). Code that explicitly subscripted it — e.g. x: PipeFunc[Callable[[int], int]] — must update to the new two-parameter form, e.g. PipeFunc[[int], int] or PipeFunc[..., int]. Unsubscripted PipeFunc annotations (the common case, used everywhere internally) are unaffected, and there is no runtime behavior change.