[Python-ideas] Extend the warnings module with Deprecation utility methods and classes

[Ilya Kulakov]

Sooner or later authors and maintainers of libraries change public 
interfaces of their creations. 
Usually one of the two approaches is taken:

1. Outright breaking change
2. Soft deprecation later followed by [1]

While [1] is perfectly suitable for libraries with limited audience, [2] is 
what popular libraries
have to do (to remain popular).

Python's stdlib contributed to the process via PEP 230 and, recently, PEP 
565.
The `warn` function and subclasses of Warning are omnipresent. However, 
when it comes
to practical application it's still up to a developer to write utility 
methods and classes.


I propose that Python should extend the warnings module with a set of 
utilities to cover
basic needs as seen across the industry. The extension should include:

1. A decorator for functions
2. A decorator for classes
3. A context manager


Function Decorator

A function can be deprecated:

- Via a rename when an author decides there is a better name
- Via a change of its interface
- By becoming obsolete

Therefore the job of the decorator is to modify the behavior such as upon a 
call:

- A warning is issued
- Optionally an aliased (new) function is called
- Optionally both positional and keyword arguments are mapped to satisfy 
new interface;
might be followed by an extra warning for each remap


Class Decorator

A class can be deprecated:

- Via a rename when an author decides there is a better name
- By becoming obsolete

Therefore a job of the decorator is to ensure that:

- A warning is issued when class is either instantiated or used as a base 
class
- If aliased, subclasses of a deprecated class (from the end user 
perspective) pass `issubclass` and `isinstance` checks against an aliased 
new class
- If aliased, subclasses of a new class pass `issubclass` and `isinstance` 
checks against a deprecated class


Context Manager

Context manager is useful when behavior of a particular function changes 
without visible changes to its name or interface.
E.g. when author realizes (too late) that arguments are mutually exclusive. 
Instead of introducing a breaking change outright, better solution is to 
wrap that particular case with a warning and consistent behavior.


Each of these utilities should allow to specify a condition via a callable. 
E.g. when deprecation only makes sense for certain platforms or python 
interpreter versions.


I think most if not all can be implemented using existing runtime and 
stdlib. But before diving into code, what do you think of this idea overall?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20180830/59e57578/attachment-0001.html>