Feature: Specify what replaces an API call...

[BenjamenMeyer]

This looks quite interesting; however, it'd be highly beneficial to be able to optionally specify what is replacing the call.

import deprecation

@deprecation.deprecated(deprecated_in="1.0", removed_in="2.0",
                        current_version=__version__,
                        details="Reasoning for change", replaced_by=bar)
def foo():
    """Do some stuff"""
    return bar()

def bar():
    """Do some stuff using new API"""
    return 1

details could probably be used more for reasoning behind the change while replaced_by could be used to explicitly note the new method if it was provided.

NOTE: replaced_by could either be an object or a string. If an object then the string could be formed via '.'.join([replaced_by.__module__, replaced_by.__name__]).

Output text related to replaced_by should simply be:

Please update usage of "foo" to "bar".

Reasoning: By calling out explicitly this way some uniformity is provided in the messaging to users.
Yes, this could be achieved by details but then the calling project would have to implement a standard on how to write out details in a way that clearly communicates the change to the user. By reserving details for more detailed reasoning (ex: foo had a security issue and needed to go away because X) and taking in replaced_by type argument the updated API can be consistently and reliably communicated.

NOTE: This might be one aspect of #17, but it probably stands on its own since (a) it could be achieved without #17 and (b) #17 would only enhance the capability.

[briancurtin]

I have some UI/UX things to think through on putting this all together, but overall I like this and agree that it stands on its own from #17.