Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/scipy/_lib/deprecation.py: 36%

1import functools 

2import warnings 

3 

4__all__ = ["_deprecated"] 

5 

6 

7def _deprecated(msg, stacklevel=2): 

8 """Deprecate a function by emitting a warning on use.""" 

9 def wrap(fun): 

10 if isinstance(fun, type): 

11 warnings.warn( 

12 "Trying to deprecate class {!r}".format(fun), 

13 category=RuntimeWarning, stacklevel=2) 

14 return fun 

15 

16 @functools.wraps(fun) 

17 def call(*args, **kwargs): 

18 warnings.warn(msg, category=DeprecationWarning, 

19 stacklevel=stacklevel) 

20 return fun(*args, **kwargs) 

21 call.__doc__ = fun.__doc__ 

22 return call 

23 

24 return wrap 

25 

26 

27class _DeprecationHelperStr: 

28 """ 

29 Helper class used by deprecate_cython_api 

30 """ 

31 def __init__(self, content, message): 

32 self._content = content 

33 self._message = message 

34 

35 def __hash__(self): 

36 return hash(self._content) 

37 

38 def __eq__(self, other): 

39 res = (self._content == other) 

40 if res: 

41 warnings.warn(self._message, category=DeprecationWarning, 

42 stacklevel=2) 

43 return res 

44 

45 

46def deprecate_cython_api(module, routine_name, new_name=None, message=None): 

47 """ 

48 Deprecate an exported cdef function in a public Cython API module. 

49 

50 Only functions can be deprecated; typedefs etc. cannot. 

51 

52 Parameters 

53 ---------- 

54 module : module 

55 Public Cython API module (e.g. scipy.linalg.cython_blas). 

56 routine_name : str 

57 Name of the routine to deprecate. May also be a fused-type 

58 routine (in which case its all specializations are deprecated). 

59 new_name : str 

60 New name to include in the deprecation warning message 

61 message : str 

62 Additional text in the deprecation warning message 

63 

64 Examples 

65 -------- 

66 Usually, this function would be used in the top-level of the 

67 module ``.pyx`` file: 

68 

69 >>> from scipy._lib.deprecation import deprecate_cython_api 

70 >>> import scipy.linalg.cython_blas as mod 

71 >>> deprecate_cython_api(mod, "dgemm", "dgemm_new", 

72 ... message="Deprecated in Scipy 1.5.0") 

73 >>> del deprecate_cython_api, mod 

74 

75 After this, Cython modules that use the deprecated function emit a 

76 deprecation warning when they are imported. 

77 

78 """ 

79 old_name = "{}.{}".format(module.__name__, routine_name) 

80 

81 if new_name is None: 

82 depdoc = "`%s` is deprecated!" % old_name 

83 else: 

84 depdoc = "`%s` is deprecated, use `%s` instead!" % \ 

85 (old_name, new_name) 

86 

87 if message is not None: 

88 depdoc += "\n" + message 

89 

90 d = module.__pyx_capi__ 

91 

92 # Check if the function is a fused-type function with a mangled name 

93 j = 0 

94 has_fused = False 

95 while True: 

96 fused_name = "__pyx_fuse_{}{}".format(j, routine_name) 

97 if fused_name in d: 

98 has_fused = True 

99 d[_DeprecationHelperStr(fused_name, depdoc)] = d.pop(fused_name) 

100 j += 1 

101 else: 

102 break 

103 

104 # If not, apply deprecation to the named routine 

105 if not has_fused: 

106 d[_DeprecationHelperStr(routine_name, depdoc)] = d.pop(routine_name) 

107