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