Hi python-ideas, The subject is by no means new nor unique, and in fact has been discussed on python-ideas at least once <https://mail.python.org/archives/list/python-ideas@python.org/thread/OPY3E4VFGV6KDALYS3YYKIYBNY363WGA/#HBOGGZT2ETWFYX2UN67D52554I2N6UP> before as well as in python/mypy#2403 <https://github.com/python/mypy/issues/2403>.. However, to date, there seems to be no standard way of deprecating things declaratively, and ~every major library has its own internal API for that. For example, * numpy.deprecate, * similar decorators in pandas <https://github.com/pandas-dev/pandas/blob/42adb9f80fb6a048995087276eda2a16ea1cfb66/pandas/util/_decorators.py#L18> and TensorFlow <https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/util/deprecation.py>, * twisted.python.deprecate <https://twistedmatrix.com/documents/current/api/twisted.python.deprecate.html>, * warn_about_renamed_method <https://github.com/django/django/blob/ca9872905559026af82000e46cde6f7dedc897b6/django/utils/deprecation.py#L19> in Django, * etc etc. The proliferation of deprecation APIs itself is not a problem, but it does make it difficult (if not impossible) for language tooling to consume that deprecation information and help users of these libraries write better code. Imagine, if there was a standard way to flag something as deprecated. That would allow, for example, an IDE or a linter to statically flag a particular usage site as problematic and, assuming such information is available, to suggest an auto-generated fix (see @Deprecated in Kotlin <https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-deprecated/>, for example). What do you think? Is anyone interested in discussing this further and perhaps sketching an API which could work reasonably well for library authors as well as for tooling? Cheers, Sergei
I like the idea in principle. Could be as simple the presence of a __deprecated__ attribute on the class or function being deprecated. A simple decorator could set it. On Mon, 2021-07-12 at 19:37 +0100, Sergei Lebedev wrote:
Hi python-ideas,
The subject is by no means new nor unique, and in fact has been discussed on python-ideas at least once before as well as in python/mypy#2403..
However, to date, there seems to be no standard way of deprecating things declaratively, and ~every major library has its own internal API for that. For example,
* numpy.deprecate, * similar decorators in pandas and TensorFlow, * twisted.python.deprecate, * warn_about_renamed_method in Django, * etc etc.
The proliferation of deprecation APIs itself is not a problem, but it does make it difficult (if not impossible) for language tooling to consume that deprecation information and help users of these libraries write better code.
Imagine, if there was a standard way to flag something as deprecated. That would allow, for example, an IDE or a linter to statically flag a particular usage site as problematic and, assuming such information is available, to suggest an auto-generated fix (see @Deprecated in Kotlin, for example).
What do you think? Is anyone interested in discussing this further and perhaps sketching an API which could work reasonably well for library authors as well as for tooling?
Cheers, Sergei _______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-leave@python.org https://mail.python.org/mailman3/lists/python-ideas.python.org/ Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/EABCXC... Code of Conduct: http://python.org/psf/codeofconduct/
Sergei Lebedev writes:
The proliferation of deprecation APIs itself is not a problem, but it does make it difficult (if not impossible) for language tooling to consume that deprecation information and help users of these libraries write better code.
We don't know that it's not a problem, though. To get this discussion properly kicked off, the first thing that should be checked is what is common and what is not in the many existing APIs, and make proposals about the odd features (whether to include them in the standard API or not), as well as reconciling similar features that are implemented differently. At the other end, the 'deprecations' module, on PyPI I guess (searching for "deprecation doc" found at the readthedocs manual, not the package itself), seems to be a minimal API likely to be a common core. (However the restriction that the deprecation date has to be set to set the target removal date seems odd to me.)
Imagine, if there was a standard way to flag something as deprecated.
But there *is* a stdlib way to flag something as deprecated (DeprecationWarning), but issuing those warnings is a user option, off by default. The reasons why that standard API is not used, but every library auther prefers a module-specific API, need to be addressed. And somebody cared enough about 'deprecations' to bring it to version 2.06, which suggests they're using it quite a bit.
What do you think? Is anyone interested in discussing this further and perhaps sketching an API which could work reasonably well for library authors as well as for tooling?
I'll lurk in the discussion, but this is not something I've felt a need for in the past. It's not the place where you'd expect to see this discussion, but in the mypy issue you mention, Guido's specific invitation to do exactly this apparently met with complete silence, which is not a good sign (but not necessarily a bad one, either). One general comment: I expect that something that works for consumers of deprecation information wouldt work for library authors, too. The problem is the API for filtering out unwanted information (eg, deprecations in imported libraries you're unable or unwilling to vendor, removals far enough in the future you're happy to postpone the work), without too much work on the consumer's side (most consumers will not be willing to do more than "on" vs "off", and currently they prefer "off" for DeprecationWarning itself). Steve
participants (3)
-
Paul Bryan -
Sergei Lebedev -
Stephen J. Turnbull