Commit da67ff86 authored by Joseph Weston's avatar Joseph Weston

implement decorator for deprecating function parameters

Also implement a specialization of this decorator for the 'args'
parameter, so as to avoid boilerplate (i.e. redefining the help
string everywhere the decorator is used).

The deprecation decorator can also be called directly with no
parameters to raise the warning. This is necessary because
methods of Cython cdef classes do not seem to play well with
this decorator (even after applying @cython.bind(True)), so
we need to call it directly from the body of the method.
parent fa02680f
......@@ -12,6 +12,7 @@ import numbers
import inspect
import warnings
import importlib
import functools
from contextlib import contextmanager
__all__ = ['KwantDeprecationWarning', 'UserCodeError']
......@@ -41,6 +42,46 @@ class UserCodeError(Exception):
pass
def deprecate_parameter(parameter_name, version=None, help=None,
stacklevel=3):
"""Trigger a deprecation warning if the wrapped function is called
with the provided parameter."""
message = ("The '{}' parameter has been deprecated since version {} -- {}"
.format(parameter_name, version, help))
def warn():
warnings.warn(message, KwantDeprecationWarning,
stacklevel=stacklevel)
def wrapper(f=None):
# Instead of being used as a decorator, can be called with
# no arguments to just raise the warning.
if f is None:
warn()
return
sig = inspect.signature(f)
@functools.wraps(f)
def inner(*args, **kwargs):
# If the named argument is truthy
if sig.bind(*args, **kwargs).arguments.get(parameter_name):
warn()
return f(*args, **kwargs)
return inner
return wrapper
# Deprecation for 'args' parameter; defined once to minimize boilerplate,
# as this parameter is present all over Kwant.
deprecate_args = deprecate_parameter('args', version=1.4, help=
"Instead, provide named parameters as a dictionary via 'params'.")
def interleave(seq):
"""Return an iterator that yields pairs of elements from a sequence.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment