Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/numpy/_utils/__init__.py: 40%

1""" 

2This is a module for defining private helpers which do not depend on the 

3rest of NumPy. 

4 

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""" 

10 

11import functools 

12import warnings 

13 

14from ._convertions import asbytes, asunicode 

15 

16 

17def set_module(module): 

18 """Private decorator for overriding __module__ on a function or class. 

19 

20 Example usage:: 

21 

22 @set_module('numpy') 

23 def example(): 

24 pass 

25 

26 assert example.__module__ == 'numpy' 

27 """ 

28 def decorator(func): 

29 if module is not None: 

30 if isinstance(func, type): 

31 try: 

32 func._module_source = func.__module__ 

33 except (AttributeError): 

34 pass 

35 

36 func.__module__ = module 

37 return func 

38 return decorator 

39 

40 

41def _rename_parameter(old_names, new_names, dep_version=None): 

42 """ 

43 Generate decorator for backward-compatible keyword renaming. 

44 

45 Apply the decorator generated by `_rename_parameter` to functions with a 

46 renamed parameter to maintain backward-compatibility. 

47 

48 After decoration, the function behaves as follows: 

49 If only the new parameter is passed into the function, behave as usual. 

50 If only the old parameter is passed into the function (as a keyword), raise 

51 a DeprecationWarning if `dep_version` is provided, and behave as usual 

52 otherwise. 

53 If both old and new parameters are passed into the function, raise a 

54 DeprecationWarning if `dep_version` is provided, and raise the appropriate 

55 TypeError (function got multiple values for argument). 

56 

57 Parameters 

58 ---------- 

59 old_names : list of str 

60 Old names of parameters 

61 new_name : list of str 

62 New names of parameters 

63 dep_version : str, optional 

64 Version of NumPy in which old parameter was deprecated in the format 

65 'X.Y.Z'. If supplied, the deprecation message will indicate that 

66 support for the old parameter will be removed in version 'X.Y+2.Z' 

67 

68 Notes 

69 ----- 

70 Untested with functions that accept *args. Probably won't work as written. 

71 

72 """ 

73 def decorator(fun): 

74 @functools.wraps(fun) 

75 def wrapper(*args, **kwargs): 

76 __tracebackhide__ = True # Hide traceback for py.test 

77 for old_name, new_name in zip(old_names, new_names): 

78 if old_name in kwargs: 

79 if dep_version: 

80 end_version = dep_version.split('.') 

81 end_version[1] = str(int(end_version[1]) + 2) 

82 end_version = '.'.join(end_version) 

83 msg = (f"Use of keyword argument `{old_name}` is " 

84 f"deprecated and replaced by `{new_name}`. " 

85 f"Support for `{old_name}` will be removed " 

86 f"in NumPy {end_version}.") 

87 warnings.warn(msg, DeprecationWarning, stacklevel=2) 

88 if new_name in kwargs: 

89 msg = (f"{fun.__name__}() got multiple values for " 

90 f"argument now known as `{new_name}`") 

91 raise TypeError(msg) 

92 kwargs[new_name] = kwargs.pop(old_name) 

93 return fun(*args, **kwargs) 

94 return wrapper 

95 return decorator