Deprecation Helpers¶
FlaskBB publicly provides tools for handling deprecations and are open to use by plugins or other extensions to FlaskBB. For example if a plugin wants to deprecate a particular function it could do:
from flaskbb.deprecation import FlaskBBDeprecation, deprecated
class RemovedInPluginV2(FlaskBBDeprecation):
version = (2, 0, 0)
@deprecated(category=RemovedInPluginV2)
def thing_removed_in_plugin_v2():
...
When used in live code, a warning will be issue like:
warning: RemovedInPluginV2: thing_removed_in_plugin_v2 and will be removed
in version 2.0.0.
Optionally, a message can be provided to give further information about the warning:
@deprecated(message="Use plugin.frobinator instead.", category=RemovedInPluginV2)
def thing_also_removed_in_plugin_v2():
...
This will produce a warning like:
warning: RemovedInPluginV2: thing_removed_in_plugin_v2 and will be removed
in version 2.0.0. Use plugin.frobinator instead.
If a decorated function has a docstring, the entire warning message will be appended to it for introspection and documentation purposes.
Helpers¶
-
class
flaskbb.deprecation.
FlaskBBWarning
[source]¶ Base class for any warnings that FlaskBB itself needs to issue, provided for convenient filtering.
-
class
flaskbb.deprecation.
FlaskBBDeprecation
[source]¶ Base class for deprecations originating from FlaskBB, subclasses must provide a version attribute that represents when deprecation becomes a removal:
class RemovedInPluginv3(FlaskBBDeprecation): version = (3, 0, 0)
-
flaskbb.deprecation.
deprecated
(message='', category=<class 'flaskbb.deprecation.RemovedInFlaskBB3'>)[source]¶ Flags a function or method as deprecated, should not be used on classes as it will break inheritance and introspection.
Parameters: - message – Optional message to display along with deprecation warning.
- category – Warning category to use, defaults to RemovedInFlaskBB3, if provided must be a subclass of FlaskBBDeprecation.