diff --git a/pep-0702.rst b/pep-0702.rst index 6b487ee1c..d1c4c1c2c 100644 --- a/pep-0702.rst +++ b/pep-0702.rst @@ -179,10 +179,13 @@ Here is how type checkers should handle usage of this library: library.foo(1) # error: Use of deprecated overload for foo. Only str will be allowed. library.foo("x") # no error + ham = Ham() # no error (already reported above) + Runtime behavior ---------------- -The ``@deprecated`` parameter takes two keyword-only arguments: +In addition to the positional-only ``message`` argument, +the ``@deprecated`` decorator takes two keyword-only arguments: * ``category``: A warning class. Defaults to :exc:`DeprecationWarning`. If this is set to ``None``, no warning is issued at runtime and the decorator returns @@ -192,7 +195,7 @@ The ``@deprecated`` parameter takes two keyword-only arguments: deprecated object is called. Internally, the implementation will add the number of stack frames it uses in wrapper code. -If the decorated object is a class, the decorator wraps the ``__new__`` methods +If the decorated object is a class, the decorator wraps the ``__new__`` method such that instantiating the class issues a warning. If the decorated object is a callable, the decorator returns a new callable that wraps the original callable but raises a warning when called. Otherwise, the decorator raises a ``TypeError`` @@ -207,6 +210,10 @@ To accommodate runtime introspection, the decorator sets an attribute callables it generates for deprecated classes and functions. The value of the attribute is the message passed to the decorator. +If a ``Protocol`` with the ``@runtime_checkable`` decorator is marked as deprecated, +the ``__deprecated__`` attribute should not be considered a member of the protocol, +so its presence should not affect ``isinstance`` checks. + For compatibility with :func:`typing.get_overloads`, the ``@deprecated`` decorator should be placed after the ``@overload`` decorator. @@ -259,7 +266,8 @@ A runtime implementation of the ``@deprecated`` decorator is `available `__. The ``pyanalyze`` type checker has `prototype support `__ -for emitting deprecation errors. +for emitting deprecation errors, as does +`Pyright `__. Rejected ideas ============== @@ -301,18 +309,6 @@ show that this feature is not commonly needed. Features for deprecating more kinds of objects could be added in a future PEP. -Open issues -=========== - -``skip_file_prefixes`` ----------------------- - -Python 3.12 `will have support `__ -for a ``skip_file_prefixes`` argument to :func:`warnings.warn`, which allows -control of where a warning is raised in a more intuitive manner than ``stacklevel``. -Should this feature be exposed in ``@deprecated``? If so, how would we provide a -backport in ``typing_extensions``? - Acknowledgments ===============