Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

import functools 

import warnings 

 

__all__ = ["_deprecated"] 

 

 

def _deprecated(msg, stacklevel=2): 

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

def wrap(fun): 

if isinstance(fun, type): 

warnings.warn( 

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

category=RuntimeWarning, stacklevel=2) 

return fun 

 

@functools.wraps(fun) 

def call(*args, **kwargs): 

warnings.warn(msg, category=DeprecationWarning, 

stacklevel=stacklevel) 

return fun(*args, **kwargs) 

call.__doc__ = msg 

return call 

 

return wrap 

 

 

class _DeprecationHelperStr(object): 

""" 

Helper class used by deprecate_cython_api 

""" 

def __init__(self, content, message): 

self._content = content 

self._message = message 

 

def __hash__(self): 

return hash(self._content) 

 

def __eq__(self, other): 

res = (self._content == other) 

if res: 

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

stacklevel=2) 

return res 

 

 

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

""" 

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

 

Only functions can be deprecated; typedefs etc. cannot. 

 

Parameters 

---------- 

module : module 

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

routine_name : str 

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

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

new_name : str 

New name to include in the deprecation warning message 

message : str 

Additional text in the deprecation warning message 

 

Examples 

-------- 

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

module ``.pyx`` file: 

 

>>> from scipy._lib.deprecation import deprecate_cython_api 

>>> import scipy.linalg.cython_blas as mod 

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

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

>>> del deprecate_cython_api, mod 

 

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

deprecation warning when they are imported. 

 

""" 

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

 

if new_name is None: 

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

else: 

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

(old_name, new_name) 

 

if message is not None: 

depdoc += "\n" + message 

 

d = module.__pyx_capi__ 

 

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

j = 0 

has_fused = False 

while True: 

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

if fused_name in d: 

has_fused = True 

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

j += 1 

else: 

break 

 

# If not, apply deprecation to the named routine 

if not has_fused: 

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