docstring: Use update_wrapper to propagate the types

[vallsv]

Propagated the types when @docstring is used.

See update_wrapper: https://docs.python.org/3/library/functools.html#functools.update_wrapper

The downfall is that we probably can't override the types, but that's probably not a common usecase.

As the documentation is on it's own a specification, IMO there is no way to distinguish the doc and the types -> If you have to tune the type you probably should not use the @docstring helper because you also have to tune the documentation.

Checklist:

• The PR title is formatted as: <Module or Topic>: <Action> <Summary> (see contributing guidelines)

---

[payno]

Do we want to specify the assigned and updated. According to the name of the function I would expect to have only __doc__ ?

[vallsv]

To me this function is not properly named.

[payno]

Indeed I think this is related to the questions of thomas.

• If the behavior change -> the function might be renamed
• then if the behavior change the question is: is it safe for the existing source code ? This function is also exposed publicly so changing the behavior on other source code might be an issue.

[t20100]

That sounds risky to propagate the typing in @docstring: The test in this PR is an example of what can happen.

If copying typing is needed, a different decorator would be best IMO.

[vallsv]

The test in this PR is an example of what can happen.

I don't understand what you mean.

To me, we should have an @overrideannotation, but that's exactly how @docstring is used.

So, in fact i would be in favor of renaming this helper. Even if we only support classname as argument (which is safer in this case).

[t20100]

You can achieve the same with @functools.wraps with almost the same syntax:

class A:
    def f(self, a: int, b: str = "") -> str:
        """docstring"""
        return f"{a}-{b}"

class B(A):
    @functools.wraps(A.f)
    def f(self, a, b):
        return "B"

I would keep @docstring to only update the docstring and use @functools.wraps to replace it.