Deprecation best practices#
While deprecation best practices are outlined in a Stack Overflow Answer and in this Deprecation library , there is no official guidance on deprecating features within Python. Thus, this topic provides deprecation best practices for PyAnsys libraries.
Whenever you deprecate a method, class, or function, you must either:
Have the old method call the new method and raise a warning
AttributeErrorif you remove the method entirely
In the docstring of the old method, provide a Sphinx Deprecated Directive that links to the new method. This way, you notify your users when you make an API change and give them a chance to change their code. Otherwise, users stop upgrading, or worse, stop using your API, due to stability concerns. For this reason, it is best to use a warning first and then use an error after a minor release or two.
import warnings class FieldAnalysis2D: """Class docstring""" def assignmaterial(self, obj, mat): """Assign a material to one or more objects. .. deprecated:: 0.4.0 Use :func:`FieldAnalysis2D.assign_material` instead. """ # one of the following: # raise a DeprecationWarning. User won't have to change anything warnings.warn( "`assignmaterial` is deprecated. Use `assign_material` instead.", DeprecationWarning, ) self.assign_material(obj, mat) # or raise an AttributeError (could also make a custom DeprecationError) raise AttributeError( "`assignmaterial` is deprecated. Use `assign_material` instead." ) def assign_material(self, obj, mat): """Assign a material to one or more objects. ... """
If you remove a method entirely, there is no reason to provide a link to the old
method. Simply raise an
AttributeError as part of the class or raise an
def hello_world(): """Print ``"hello_world"`` .. deprecated:: 0.4.0 This function has been deprecated. """ raise Exception("`my_function` has been deprecated")
Because there is no built-in deprecation error within Python, an alternate
approach is to create a custom
class DeprecationError(RuntimeError): """Used for deprecated methods and functions.""" def __init__(self, message="This feature has been deprecated."): """Empty init.""" RuntimeError.__init__(self, message)
You then use this custom
DeprecationError in place of an
def hello_world(): """Print ``"hello_world"`` .. deprecated:: 0.4.0 This function has been deprecated. """ raise DeprecationError('`my_function` has been deprecated.')