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(1) # error: Use of deprecated overload for foo. Only str will be allowed.
library.foo("x") # no error library.foo("x") # no error
ham = Ham() # no error (already reported above)
Runtime behavior 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 * ``category``: A warning class. Defaults to :exc:`DeprecationWarning`. If this
is set to ``None``, no warning is issued at runtime and the decorator returns 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 deprecated object is called. Internally, the implementation will add the number of
stack frames it uses in wrapper code. 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 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 callable, the decorator returns a new callable that wraps the original callable but
raises a warning when called. Otherwise, the decorator raises a ``TypeError`` 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. callables it generates for deprecated classes and functions.
The value of the attribute is the message passed to the decorator. 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`` For compatibility with :func:`typing.get_overloads`, the ``@deprecated``
decorator should be placed after the ``@overload`` decorator. 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>`__. `available <https://github.com/python/typing_extensions/pull/105>`__.
The ``pyanalyze`` type checker has The ``pyanalyze`` type checker has
`prototype support <https://github.com/quora/pyanalyze/pull/578>`__ `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 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 Features for deprecating more kinds of objects could be added in a future
PEP. 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 Acknowledgments
=============== ===============