gh-104003: Implement PEP 702

[JelleZijlstra]

• Issue: Implement PEP 702: Marking deprecations using the type system #104003

[JelleZijlstra]

This is copied from python/typing_extensions#105.

[gvanrossum]

LGTM.

[gvanrossum]

Waiting for the other reviewers to pipe in? This seems pretty straightforward.

[AlexWaygood]

Waiting for the other reviewers to pipe in? This seems pretty straightforward.

The PEP hasn't been accepted yet!

[JelleZijlstra]

Planning to hit the merge button the moment the PEP is accepted :)

[JelleZijlstra]

PEP 702 has been accepted, but it's changed since this PR. I'll update the PR soon to put the decorator in warnings and sync the implementation from typing-extensions.

[AlexWaygood]

Would you be open to implementing this as a class, to support downstream introspection, rather than an inner function?

Hmm, the current implementation sets the __deprecated__ dunder attribute on the object returned from deprecated(). The purpose of that is supposed to be to allow third-party runtime tools to detect that the original object was decorated with @deprecated. Is that insufficient?

it'd be nicer if we could just use isinstance() 🙂

If you want to use isinstance(), you could create a runtime-checkable protocol for that ;)

from typing import Protocol, runtime_checkable

@runtime_checkable
class DeprecatedProto(Protocol):
    __deprecated__: str

[Viicos]

The purpose of that is supposed to be to allow third-party runtime tools to detect that the original object was decorated with @deprecated. Is that insufficient?

The issue is when using deprecated the way Zac-HD wrote (Annotated[T, warnings.deprecated("message")]), no object is being decorated here (in other words, deprecated("message") returns another function yet to be called with the decorated object)

[AlexWaygood]

The purpose of that is supposed to be to allow third-party runtime tools to detect that the original object was decorated with @deprecated. Is that insufficient?

The issue is when using deprecated the way Zac-HD wrote (Annotated[T, warnings.deprecated("message")]), no object is being decorated here (in other words, deprecated("message") returns another function yet to be called with the decorated object)

Got it. What if we did something like this?

diff --git a/Lib/warnings.py b/Lib/warnings.py
index 36da0e75c6..fc8a10e71f 100644
--- a/Lib/warnings.py
+++ b/Lib/warnings.py
@@ -621,6 +621,7 @@ def wrapper(*args, **kwargs):
                 f"a class or callable, not {arg!r}"
             )

+    decorator.__origin__ = deprecated
     return decorator

Then third-party code could do checks like this:

from typing import get_origin
from warnings import decorated

if get_origin(obj) is deprecated:
    ...  # it was a wrapper function returned by `warnings.deprecated("message")`

[Viicos]

Doesn't seem to be get_origin's primary use (maybe docs should be updated), but that would avoid completely refactoring the current implementation!

[AlexWaygood]

Doesn't seem to be get_origin's primary use

It's already sorta awkwardly overloaded in what it means tbh — the __origin__ attribute of ParamSpecArgs instances doesn't really have the same semantics as the __origin__ attribute of generic aliases :)

[Zac-HD]

A class seems somewhat more elegant to me, but yeah, that would work.

[JelleZijlstra]

I'm OK with making it a class. It's not what the object is meant for, but it's a reasonable extension.

Using __origin__ feels hacky and wouldn't provide an easy way to get the deprecation message out.

[AlexWaygood]

Despite static typing being the original motivation for the feature, I would actually put the runtime effect first here:

Suggested change

	* The new :func:`warnings.deprecated` decorator provides a way to communicate
	deprecations to :term:`static type checkers <static type checker>` and
	to warn on usage of deprecated classes and functions.
	* The new :func:`warnings.deprecated` decorator provides an ergonomic way to
	mark a class or function as deprecated. A deprecation warning will be
	emitted whenever a decorated function or class is used at runtime. The
	decorator is also understood by
	:term:`static type checkers <static type checker>`, which will emit warnings
	if they identify a decorated function or class being used.

[JelleZijlstra]

I still want to put the type checker effect first because that's the unique part. You can write a decorator that generates runtime warnings yourself; the new and exciting part is that this decorator is also understood by static type checkers.

[AlexWaygood]

You can do, sure, but do people? It was possible to reimplement itertools.batched in a few lines of code before Python 3.12, but lots of people were still very excited by its inclusion in the stdlib in Python 3.12.

I think this new decorator here could prove pretty popular with people who don't use static typing! But, I don't feel strongly; it looks fine to me now :)

[JelleZijlstra]

Sure, there are lots of third-party deprecation decorators. The Deprecated library, I think Flask has one internally (David Lord mentioned it in PEP 702 discussions), I know at Quora we have one internally.

[AlexWaygood]

I'm not sure if that's meant to be a point in agreement or in disagreement with the point I'm making that this decorator could prove pretty popular with people who don't use static typing. Anyway, as I say, I'm happy with the docs now!

[JelleZijlstra]

Thanks @AlexWaygood for the review! I pushed some changes.

[AlexWaygood]

LGTM