Add option to functools.update_wrapper()/@wraps to copy the coroutine flag

Feature or enhancement

Proposal:

This came up during python/cpython#122088, where it was noted that @deprecated drops the coroutine flag of a function. @deprecated uses @wraps/update_wrapper internally. This was previously discussed in #100317, where it was suggested that the flag should be copied automatically. It was ultimately decided by @gvanrossum that this is dangerous, since wrappers might decide to convert from/to coroutines.

I propose to add a flag to update_wrapper() and @wraps to optionally copy the status:

• It's more convenient to use than using the boilerplate code mentioned in the previous issue. Especially since I would assume that most wrappers want to copy this status.
• Probably more important: This makes this problem and its solution discoverable. As the @deprecated example shows, most people probably don't think about this issue when creating a wrapper. By adding a flag to the API and the documentation, this problem will be mentioned and can be discovered by users of @wraps, either while reading the documentation, or when the IDE shows the availability of the flag.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Commencez par lire functools.update_wrapper() et @wraps, puis consultez les discussions précédentes dans #100317 et python/cpython#122088 au sujet de la copie de l’état de coroutine. La tâche serait terminée lorsqu’un comportement optionnel de l’API aura été convenu, avec une implémentation, des tests et une documentation correspondants.