pyiron_base.utils.deprecate module

Utility functions used in pyiron. In order to be accessible from anywhere in pyiron, they must remain free of any imports from pyiron!

class pyiron_base.utils.deprecate.Deprecator(message=None, version=None, pending=False)

Bases: object

Decorator class to mark functions and methods as deprecated with a uniform warning message at the time the function is called. The message has the form

{function_name} is deprecated: {message}. It is not guaranteed to be in service after {version}.

unless pending=True was given. Then the message will be

{function_name} will be deprecated in a future version: {message}.

If message and version are not initialized or given during the decorating call the respective parts are left out from the message.

>>> deprecate = Deprecator()
>>> @deprecate
... def foo(a, b):
...     pass
>>> foo(1, 2)
DeprecationWarning: __main__.foo is deprecated

>>> @deprecate("use bar() instead")
... def foo(a, b):
...     pass
>>> foo(1, 2)
DeprecationWarning: __main__.foo is deprecated: use bar instead

>>> @deprecate("use bar() instead", version="0.4.0")
... def foo(a, b):
...     pass
>>> foo(1, 2)
DeprecationWarning: __main__.foo is deprecated: use bar instead.  It is not
guaranteed to be in service in vers. 0.4.0

>>> deprecate = Deprecator(message="pyiron says no!", version="0.5.0")
>>> @deprecate
... def foo(a, b):
...     pass
>>> foo(1, 2)
DeprecationWarning: __main__.foo is deprecated: pyiron says no!  It is not
guaranteed to be in service in vers. 0.5.0

Alternatively the decorator can also be called with arguments set to a dictionary mapping names of keyword arguments to deprecation messages. In this case the warning will only be emitted when the decorated function is called with arguments in that dictionary.

>>> deprecate = Deprecator()
>>> @deprecate(arguments={"bar": "use baz instead."})
... def foo(bar=None, baz=None):
...     pass
>>> foo(baz=True)
>>> foo(bar=True)
DeprecationWarning: __main__.foo(bar=True) is deprecated: use baz instead.

As a short cut, it is also possible to pass the values in the arguments dict directly as keyword arguments to the decorator.

>>> @deprecate(bar="use baz instead.")
... def foo(bar=None, baz=None):
...     pass
>>> foo(baz=True)
>>> foo(bar=True)
DeprecationWarning: __main__.foo(bar=True)  is deprecated: use baz instead.

wrap(function)

Wrap the given function to emit a DeprecationWarning at call time. The warning message is constructed from the given message and version. If arguments is set then the warning is only emitted, when the decorated function is called with keyword arguments found in that dictionary.

Parameters:

function (function) – function to mark as deprecated

Returns:

raises DeprecationWarning when given function is called

Return type:

function