[Zope-dev] Re: [Zope-CMF] Better DeprecationWarnings (was Re: SVN: CMF/trunk/CMFDefault/Portal.py - reverted Portal.py change of r39125 to fix BBB temporarily)

[Tim Peters]

[Tres Seaver -- I think; I'm missing context for this email]
> Note that I have just figured out that we can make DeprecationWarnings
> more useful by passing the 'stacklevel' argument to 'warnings.warn';
> passing a value of 2 for that argument causes the warning to be reported
> against the *caller* of the code issuing the warning, which makes it
> possible to find and remove the deprecated use.

I can recommend the approach I use in ZODB.  There's a utility module
in ZODB, containing (among other things) functions like this one:

"""
# Raise DeprecationWarning, noting that the deprecated thing will go
# away in ZODB 3.6.  Point to the caller of our caller (i.e., at the
# code using the deprecated thing).
def deprecated36(msg):
    warnings.warn("This will be removed in ZODB 3.6:\n%s" % msg,
                  DeprecationWarning, stacklevel=3)
"""

So every gimmick that's going to go away in ZODB 3.6 imports
`deprecated36` from the utility module, and calls it with an
appropriate message.  As an intended bonus, when I release ZODB 3.6 I
can just grep for "deprecated36" to _find_ the code that's supposed to
go away (I also annotate tests and docs that should go away with
"deprecated36").  Using a common function also ensures that every
deprecation warning starts with the same string (identifying the
release in which the thing will go away).

Note:  sometimes _internals_ use deprecated gimmicks in order to
support deprecated gimmicks too, and then stacklevel=3 is too small. 
It's happened so rarely in ZODB that I haven't tried to "do something"
about that yet.