Thank you for trying to fix this. I fully agree that if we could get this working, we should merge it.

CodSpeed Performance Report

Merging #910 will not alter performance

Comparing LennartGevers:clean-decorator-behavior (e98f882) with main (355584e)

Summary

✅ 6 untouched

✅ PR Title Formatted Correctly

The title of this PR has been updated to match the correct format. Thank you!

Hey @basnijholt,

this branch is ~90% there, but I think that the current solution is inferior to an alternative but more intricate design that’s worth discussing.

The main issue is that once you start using renames, defaults, or bound, the function’s signature changes at runtime and Python’s ParamSpec can’t express that. So we can’t properly expose the updated signature to type checkers or IDEs.

Example:

@pipefunc("f", update_defaults={"b": 0.5})
def f(a: int, b: float = 2) -> int:
    return a**b

f(4)      # 16
f.run(4)  # 2

This works, but it feels weird that f and f.run behave differently. The concept of having a Pipeline context behavior and "normal" behavior does not feel intuitive to me. But..., as soon as signature-modifying args are involved, we lose the ability to type things statically, meaning that this initially look like the only option.

I think the key insight is that there are really two kinds of attributes:
• ones that don’t change the signature (output_name, mapspec, etc.), and
• ones that do (renames, defaults, bound, maybe scope).

Right now they’re all handled in the same class, which complicates typing and behavior.

So my idea is to split them:
• Func: lightweight, immutable, only stores pipeline metadata (like a frozen dataclass) with no signature magic.
• PipeFunc: wraps a Func and adds the dynamic behavior (renames, defaults, etc.).

@func would be the minimal decorator that keeps IDE hovers and types perfect, while @pipefunc(...) or PipeFunc(...) gives you the full power and mutability. As soon as a Func is passed to a Pipeline it is promoted to a PipeFunc so that it can respond to Pipeline.add_mapspec_axis and so on.

We could alternatively overload pipefunc so it returns a Func when no signature-modifying args are given, and a PipeFunc otherwise.

@overload
def pipefunc(..., renames=None, defaults=None, bound=None) -> Func: ...
@overload
def pipefunc(..., renames=..., defaults=..., bound=...) -> PipeFunc: ...

But to be really honest, I think that a function which effectively has stateful behaviour is an anti-pattern. This should be reserved exclusively for OOP. So maybe we should only advocate instantiating PipeFuncs with its constructor. I think the sum of all of these behaviours (side effects, mutability, no signature and docs, ...) is why people often prefer to instantiate a PipeFunc with its constructor anyways.

Differentiating the Func and PipeFunc layer would separate concerns nicely, simplify the internals, and avoid weird side effects from mutating a live PipeFunc, like

@pipefunc("f",)
def f(a: int, b: float = 2) -> int:
    return a**b

h = f
h.update_defaults({"b": 0.5})
f(4) #2

Would do you think about that? @basnijholt

@LennartGevers with #960 merged, the typing part of your #910 is now in main (you're credited as co-author). Thanks for the groundwork, what landed is basically your ParamSpec approach:

• PipeFunc is now Generic[P, R], so IDEs show the original parameters and return type, calls are type checked, and methods like update_renames stay available and typed.
• The original docstring now shows up in help(f) and Jupyter's f? instead of the huge PipeFunc class docstring.
• Added __wrapped__ following the functools.wraps convention. inspect.signature still reflects renames.
• The renames limitation you described is documented here, with # type: ignore[call-arg] as the workaround.

Good news on the tradeoff you described in the PR text: with current pyright, hovering the name shows the docstring even when the decorator returns PipeFunc[P, R], so we get docs and working methods. Might be worth re-checking your demo.py, this seems to have improved on their side since October.

About the Func/PipeFunc split: I see the appeal but I'd rather not maintain and explain two public concepts when the problem only affects directly calling a renamed PipeFunc. Your other point about __call__ semantics and mutability is a real one, but it's a breaking change, so I'd park it with the 1.0 ideas in #513.

Closing #910 in favor of this. Thanks again!

Drafted with the help of Claude (Fable 5).