<div dir="ltr">Sooner or later authors and maintainers of libraries change public interfaces of their creations. <br>Usually one of the two approaches is taken:<br><br>1. Outright breaking change<br>2. Soft deprecation later followed by [1]<br><br>While [1] is perfectly suitable for libraries with limited audience, [2] is what popular libraries<div>have to do (to remain popular).<br><br>Python's stdlib contributed to the process via PEP 230 and, recently, PEP 565.<br>The `warn` function and subclasses of Warning are omnipresent. However, when it comes<div>to practical application it's still up to a developer to write utility methods and classes.<br><br><br>I propose that Python should extend the warnings module with a set of utilities to cover</div><div>basic needs as seen across the industry. The extension should include:<br><br>1. A decorator for functions<br>2. A decorator for classes<br>3. A context manager</div><div><br><br>Function Decorator<br><br>A function can be deprecated:<br><br>- Via a rename when an author decides there is a better name<br>- Via a change of its interface<br>- By becoming obsolete<br><br>Therefore the job of the decorator is to modify the behavior such as upon a call:<br><br>- A warning is issued<br>- Optionally an aliased (new) function is called<br>- Optionally both positional and keyword arguments are mapped to satisfy new interface;<br> might be followed by an extra warning for each remap<br><br><br>Class Decorator<br><br>A class can be deprecated:<br><br>- Via a rename when an author decides there is a better name<br>- By becoming obsolete<br><br>Therefore a job of the decorator is to ensure that:<br><br>- A warning is issued when class is either instantiated or used as a base class<br>- If aliased, subclasses of a deprecated class (from the end user perspective) pass `issubclass` and `isinstance` checks against an aliased new class<br>- If aliased, subclasses of a new class pass `issubclass` and `isinstance` checks against a deprecated class<br><br><br>Context Manager<br><br>Context manager is useful when behavior of a particular function changes without visible changes to its name or interface.<br>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.<br><br><br>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.<br><br><br>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?</div></div></div>