With the CPython sprint, I was thinking about a lib to mark a function/class as deprecated. Example: #!/usr/bin/env python import sys import deprecation # from an external lib or from a stdlib module __version__ = (1,0) @deprecation.deprecated(python=(3,7,), msg='use foo_v2') def foo(): pass @deprecation.deprecated(program=(1,2), msg='use bar_v2') def bar(): pass @deprecation.deprecated(python=(3,7), msg='use inspect.signature()') @deprecation.deprecated(python=(3,7), to_use=inspect.signature) def getfullargspec(*args, **kwargs): pass The deprecated decorator should check the version of the software and the version of Python if asked with the arguments. it will raise warnings.warn with PendingDeprecationWarning or DeprecationWarning. Can be used in the documentation, via introspection. It's just an idea, there is no code, no specs but if you are interested I think I can try to propose a real solution with an external library and if this idea seems to be interesting, I will propose a PEP for 3.5 or 3.6. The interest of this lib, we can parse the source code and find the deprecated functions/classes with a small tool and the maintenance of the code should be improved. Please, could you give me your feedback? Thank you, Stephane -- Stéphane Wirtel - http://wirtel.be - @matrixise