iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 702: Final tweaks (#3092) 

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
This commit is contained in:
Jelle Zijlstra 2023-04-08 06:52:51 -07:00 committed by GitHub
parent c607a47b45
commit d5bbcb9764
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 11 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
pep-0702.rst
View File

@ -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 <https://github.com/python/typing_extensions/pull/105>`__.
The ``pyanalyze`` type checker has
`prototype support <https://github.com/quora/pyanalyze/pull/578>`__
for emitting deprecation errors.
for emitting deprecation errors, as does
`Pyright <https://github.com/microsoft/pyright/issues/4456>`__.
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 <https://github.com/python/cpython/issues/39615>`__
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
===============