b.symbol_versioning : module documentation

Part of bzrlib

Symbol versioning

The methods here allow for api symbol versioning.

Function deprecated_in Generate a message that something was deprecated in a release.
Function set_warning_method Set the warning method to be used by this module.
Function deprecation_string Generate an automatic deprecation string for a_callable.
Function deprecated_function Decorate a function so that use of it will trigger a warning.
Function deprecated_method Decorate a method so that use of it will trigger a warning.
Function deprecated_passed Return True if parameter_value was used.
Class DeprecatedDict A dictionary that complains when read or written.
Function deprecated_list Create a list that warns when modified
Function suppress_deprecation_warnings Call this function to suppress all deprecation warnings.
Function activate_deprecation_warnings Call this function to activate deprecation warnings.
Function _decorate_docstring Undocumented
Function _populate_decorated Populate attributes like __name__ and __doc__ on the decorated callable.
Function _dict_deprecation_wrapper Returns a closure that emits a warning and calls the superclass
Function _check_for_filter Check if there is already a filter for deprecation warnings.
Function _remove_filter_callable Build and returns a callable removing filter from the warnings.
def deprecated_in(version_tuple):

Generate a message that something was deprecated in a release.

>>> deprecated_in((1, 4, 0))
'%s was deprecated in version 1.4.0.'
def set_warning_method(method):
Set the warning method to be used by this module.

It should take a message and a warning category as warnings.warn does.

def deprecation_string(a_callable, deprecation_version):
Generate an automatic deprecation string for a_callable.
Parametersa_callableThe callable to substitute into deprecation_version.
deprecation_versionA deprecation format warning string. This should have a single %s operator in it. a_callable will be turned into a nice python symbol and then substituted into deprecation_version.
def deprecated_function(deprecation_version):
Decorate a function so that use of it will trigger a warning.
def deprecated_method(deprecation_version):
Decorate a method so that use of it will trigger a warning.

To deprecate a static or class method, use

@staticmethod @deprecated_function def ...

To deprecate an entire class, decorate __init__.

def deprecated_passed(parameter_value):
Return True if parameter_value was used.
def _decorate_docstring(callable, deprecation_version, label, decorated_callable):
Undocumented
def _populate_decorated(callable, deprecation_version, label, decorated_callable):
Populate attributes like __name__ and __doc__ on the decorated callable.
def _dict_deprecation_wrapper(wrapped_method):
Returns a closure that emits a warning and calls the superclass
def deprecated_list(deprecation_version, variable_name, initial_value, extra=None):
Create a list that warns when modified
Parametersdeprecation_versionstring for the warning format to raise, typically from deprecated_in()
initial_valueThe contents of the list
variable_nameThis allows better warnings to be printed
extraExtra info to print when printing a warning
def _check_for_filter(error_only):
Check if there is already a filter for deprecation warnings.
Parameterserror_onlyOnly match an 'error' filter
ReturnsTrue if a filter is found, False otherwise
def _remove_filter_callable(filter):
Build and returns a callable removing filter from the warnings.
ParametersfilterThe filter to remove (can be None).
ReturnsA callable that will remove filter from warnings.filters.
def suppress_deprecation_warnings(override=True):
Call this function to suppress all deprecation warnings.

When this is a final release version, we don't want to annoy users with lots of deprecation warnings. We only want the deprecation warnings when running a dev or release candidate.

ParametersoverrideIf True, always set the ignore, if False, only set the ignore if there isn't already a filter.
ReturnsA callable to remove the new warnings this added.
def activate_deprecation_warnings(override=True):
Call this function to activate deprecation warnings.

When running in a 'final' release we suppress deprecation warnings. However, the test suite wants to see them. So when running selftest, we re-enable the deprecation warnings.

Note: warnings that have already been issued under 'ignore' will not be reported after this point. The 'warnings' module has already marked them as handled, so they don't get issued again.

ParametersoverrideIf False, only add a filter if there isn't an error filter already. (This slightly differs from suppress_deprecation_warnings, in because it always overrides everything but -Werror).
ReturnsA callable to remove the new warnings this added.
API Documentation for Bazaar, generated by pydoctor at 2022-06-16 00:25:16.