Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2This is a module for defining private helpers which do not depend on the
3rest of NumPy.
5Everything in here must be self-contained so that it can be
6imported anywhere else without creating circular imports.
7If a utility requires the import of NumPy, it probably belongs
8in ``numpy._core``.
9"""
11import functools
12import warnings
13from ._convertions import asunicode, asbytes
16def set_module(module):
17 """Private decorator for overriding __module__ on a function or class.
19 Example usage::
21 @set_module('numpy')
22 def example():
23 pass
25 assert example.__module__ == 'numpy'
26 """
27 def decorator(func):
28 if module is not None:
29 func.__module__ = module
30 return func
31 return decorator
34def _rename_parameter(old_names, new_names, dep_version=None):
35 """
36 Generate decorator for backward-compatible keyword renaming.
38 Apply the decorator generated by `_rename_parameter` to functions with a
39 renamed parameter to maintain backward-compatibility.
41 After decoration, the function behaves as follows:
42 If only the new parameter is passed into the function, behave as usual.
43 If only the old parameter is passed into the function (as a keyword), raise
44 a DeprecationWarning if `dep_version` is provided, and behave as usual
45 otherwise.
46 If both old and new parameters are passed into the function, raise a
47 DeprecationWarning if `dep_version` is provided, and raise the appropriate
48 TypeError (function got multiple values for argument).
50 Parameters
51 ----------
52 old_names : list of str
53 Old names of parameters
54 new_name : list of str
55 New names of parameters
56 dep_version : str, optional
57 Version of NumPy in which old parameter was deprecated in the format
58 'X.Y.Z'. If supplied, the deprecation message will indicate that
59 support for the old parameter will be removed in version 'X.Y+2.Z'
61 Notes
62 -----
63 Untested with functions that accept *args. Probably won't work as written.
65 """
66 def decorator(fun):
67 @functools.wraps(fun)
68 def wrapper(*args, **kwargs):
69 for old_name, new_name in zip(old_names, new_names):
70 if old_name in kwargs:
71 if dep_version:
72 end_version = dep_version.split('.')
73 end_version[1] = str(int(end_version[1]) + 2)
74 end_version = '.'.join(end_version)
75 msg = (f"Use of keyword argument `{old_name}` is "
76 f"deprecated and replaced by `{new_name}`. "
77 f"Support for `{old_name}` will be removed "
78 f"in NumPy {end_version}.")
79 warnings.warn(msg, DeprecationWarning, stacklevel=2)
80 if new_name in kwargs:
81 msg = (f"{fun.__name__}() got multiple values for "
82 f"argument now known as `{new_name}`")
83 raise TypeError(msg)
84 kwargs[new_name] = kwargs.pop(old_name)
85 return fun(*args, **kwargs)
86 return wrapper
87 return decorator