Ensure all remap decorators are AST-friendly

[Borda]

Motivation

Decorators handling remapping, redirection, and deprecation currently obscure the original callable from static analysis. Tools relying on AST parsing (e.g., IDEs, Mypy, Sphinx) lose source mapping, signature visibility, and type hints of the decorated functions or classes.

Pitch

Explore and validate approaches to make all decorators in the library strictly AST-friendly, preserving traceability for remapped targets.

Validation tasks to explore:

• Identify specific remap decorators breaking static analysis.
• Investigate mechanisms to preserve AST traceability across the board.
• Determine the feasibility, maintainability, and runtime overhead of these approaches.

Alternatives

No specific alternatives proposed yet; this issue serves to initiate exploration and validation of potential implementations.

Additional context

No response

[gabrielfruet]

Are you accepting contributions? I'm trying to take a look at this issue and have a better grasp of the repo.

[Borda]

Are you accepting contributions? I'm trying to take a look at this issue and have a better grasp of the repo.

Cool! I love contributors 🐰

[gabrielfruet]

Hey, after trying and experimenting a bit, this is what I've found:

The good news is that @deprecated for functions and methods already works fine with static analysis tools.

The real gap is with deprecated_class and deprecated_instance. These are semantically different, one you call to get instances, the other you access for reading from a wrapped object. I tried
giving them a single shared Protocol, but that doesn't work since claiming both have __call__ isn't true for instance proxies.

I'm thinking we should split them into separate protocols so the type system matches the actual behavior. The trade-off is more Protocol boilerplate and a breaking change for anyone using the current shared Protocol in their type hints.

Alternatively, we could keep them unified with better documentation, but we'd lose the type safety.

What do you think? Does splitting them make sense, or should we prioritize keeping the current structure?

[gabrielfruet]

@Borda Looks good to you? if so I can submit a PR

[Borda]

I'm thinking we should split them into separate protocols so the type system matches the actual behavior. The trade-off is more Protocol boilerplate and a breaking change for anyone using the current shared Protocol in their type hints.

@gabrielfruet Let's give it a try, could send a draft PR pls :)
I think that the bright new features are not yet that much adopted, so let's see how much of a breaking change it would be and if we can mitigate it to reduce user friction...