[Python-Dev] @deprecated (was: Useful thread project for 2.5?)

[Stephan Richter]

On Tuesday 08 March 2005 18:05, Jim Jewett wrote:
>     ... compiler recognition of "@deprecated" in doc comments.
>
> Michael Chermside suggested:
>
>     ===== code =====
>     import warnings
>
>     def deprecated(func):
>         """This is a decorator which can be used to mark functions
>         as deprecated. It will result in a warning being emmitted
>         when the function is used."""
>         def newFunc(*args, **kwargs):
>             warnings.warn("Call to deprecated function.")
>             return func(*args, **kwargs)
>         return newFunc
>
>     ===== example =====
> ...
>     UserWarning: Call to deprecated function.

This is a recipe for disaster. Creating a new function from the old can have 
unwanted side effects, since you effectively change the object. For example, 
if someone is monkey patching this function, then the deprecation warning 
gets lost. 

In Zope 3's deprecation package, we have decided to put a special deprecation 
proxy around the module (instead of the function) and register a list of 
attribute names (note that it does not matter whether its a class, function 
or other type of object) that are deprecated. The advantage is that you get a 
deprecation warning just by looking up the object.

See: http://svn.zope.org/Zope3/trunk/src/zope/deprecation/

Disclaimer: This code is a bit experimental and might not be the best 
solution. It is currently used in the trunk and does a pretty good job, 
though.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training