Deprecation Best Prcatices
While refactoring code moving modules, functions, classes and methods is often needed. To not break third party code imports from the old place or usage of old functions or methods must work for while. Deprecated methods are usually removed with the next major release of Plone. Following the semantic versioning guideline is recommended.
Enable Deprecation Warnings
plone.recipe.zope2instance add the option
deprecation-warnings = on to the buildouts
Vanilla Deprecation Messages
Python offers a built-in
DeprecationWarning which can be issued using standard libraries
For details read the official documentation.
In short it works like so
import warnings warnings.warn('deprecated', DeprecationWarning)
Moving Whole Modules
Given a package
old.pkg with a module
foo.py need to be moved to a package
zope.deprecation offers a helper.
At the old place create a new
foo.pyand add to it
from zope.deprecation import moved moved('new.pkg.bar', 'Version 2.0')
Now you can still import the namespace from
bar at the old place, but get a deprecation warning:
DeprecationWarning: old.pkg.foo has moved to new.pkg.bar. Import of old.pkg.foo will become unsupported in Version 2.0
Moving Whole Packages
This is the same as moving a module, just create for each module a file.