Recently I needed to do just that on an API and went with the decorator approach.
Having this on the stdlib would be nice, and we can make it more powerful
than just raising a warning. For instance, we could attach a `deprecated = True`
to the function object so that framework authors can use that to handle
depreciation as well - think flask endpoints.
Another option is to have an `alternative` optional kwarg in the decorator,
something like
def new_function():
....
@deprecated(alternative=new_function)
def old_function():
...
This would raise a warning stating that `new_function` should be used
in the place of `old_function`
