From time to time we need to deprecate functionality, this is a guide as to how we implement deprecation.
Toolkit retains deprecated features for a period of two releases. Thus features deprecated in 1.7.0 are removed in 1.9.0.
Use the @deprecated
decorator with a comment and change the docstring to
use the Sphinx deprecation syntax.
@deprecated("Use util.run_fast() instead.")
def run_slow():
"""Run slowly
.. deprecated:: 1.9.0
Use :func:`run_fast` instead.
"""
run_fast() # Call new function if possible
Deprecated features should call the new functionality if possible. This may not always be possible, such as the cases of drastic changes. But it is the preferred approach to reduce maintenance of the old code.
Note
This applies only to feature deprecation and renamed functions. Announcements for corrections are at the coders discretion.
Thus by examples:
run_slow
function has been deprecated and replaced by the faster and
more correct run_fast
. Users of run_slow
are advised to migrate
their code.run_slow
function has been deprecated and replaced by run_fast
and will be removed in the next version. Users of run_slow
are advised
to migrate their code.run_slow
function has been removed, use run_fast
instead.