oslo_log.versionutils

Helpers for comparing version strings.

class oslo_log.versionutils.deprecated(as_of, in_favor_of=None, remove_in=2, what=None)

A decorator to mark callables as deprecated.

This decorator logs a deprecation message when the callable it decorates is used. The message will include the release where the callable was deprecated, the release where it may be removed and possibly an optional replacement. It also logs a message when a deprecated exception is being caught in a try-except block, but not when subclasses of that exception are being caught.

Examples:

  1. Specifying the required deprecated release
>>> @deprecated(as_of=deprecated.ICEHOUSE)
... def a(): pass
  1. Specifying a replacement:
>>> @deprecated(as_of=deprecated.ICEHOUSE, in_favor_of='f()')
... def b(): pass
  1. Specifying the release where the functionality may be removed:
>>> @deprecated(as_of=deprecated.ICEHOUSE, remove_in=+1)
... def c(): pass
  1. Specifying the deprecated functionality will not be removed:
>>> @deprecated(as_of=deprecated.ICEHOUSE, remove_in=None)
... def d(): pass
  1. Specifying a replacement, deprecated functionality will not be removed:
>>> @deprecated(as_of=deprecated.ICEHOUSE, in_favor_of='f()',
...             remove_in=None)
... def e(): pass

Warning

The hook used to detect when a deprecated exception is being caught does not work under Python 3. Deprecated exceptions are still logged if they are thrown.

oslo_log.versionutils.deprecation_warning(what, as_of, in_favor_of=None, remove_in=2, logger=<logging.Logger object>)

Warn about the deprecation of a feature.

Parameters:
  • what – name of the thing being deprecated.
  • as_of – the release deprecating the callable.
  • in_favor_of – the replacement for the callable (optional)
  • remove_in – an integer specifying how many releases to wait before removing (default: 2)
  • logger – the logging object to use for reporting (optional).
oslo_log.versionutils.register_options()

Register configuration options used by this library.

oslo_log.versionutils.report_deprecated_feature(logger, msg, *args, **kwargs)

Call this function when a deprecated feature is used.

If the system is configured for fatal deprecations then the message is logged at the ‘critical’ level and DeprecatedConfig will be raised.

Otherwise, the message will be logged (once) at the ‘warn’ level.

Raises:DeprecatedConfig if the system is configured for fatal deprecations.