Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.10/site-packages/dill/_shims.py: 59%

1#!/usr/bin/env python 

2# 

3# Author: Mike McKerns (mmckerns @caltech and @uqfoundation) 

4# Author: Anirudh Vegesana (avegesan@cs.stanford.edu) 

5# Copyright (c) 2021-2025 The Uncertainty Quantification Foundation. 

6# License: 3-clause BSD. The full license text is available at: 

7# - https://github.com/uqfoundation/dill/blob/master/LICENSE 

8""" 

9Provides shims for compatibility between versions of dill and Python. 

10 

11Compatibility shims should be provided in this file. Here are two simple example 

12use cases. 

13 

14Deprecation of constructor function: 

15~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

16Assume that we were transitioning _import_module in _dill.py to 

17the builtin function importlib.import_module when present. 

18 

19@move_to(_dill) 

20def _import_module(import_name): 

21 ... # code already in _dill.py 

22 

23_import_module = Getattr(importlib, 'import_module', Getattr(_dill, '_import_module', None)) 

24 

25The code will attempt to find import_module in the importlib module. If not 

26present, it will use the _import_module function in _dill. 

27 

28Emulate new Python behavior in older Python versions: 

29~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 

30CellType.cell_contents behaves differently in Python 3.6 and 3.7. It is 

31read-only in Python 3.6 and writable and deletable in 3.7. 

32 

33if _dill.OLD37 and _dill.HAS_CTYPES and ...: 

34 @move_to(_dill) 

35 def _setattr(object, name, value): 

36 if type(object) is _dill.CellType and name == 'cell_contents': 

37 _PyCell_Set.argtypes = (ctypes.py_object, ctypes.py_object) 

38 _PyCell_Set(object, value) 

39 else: 

40 setattr(object, name, value) 

41... # more cases below 

42 

43_setattr = Getattr(_dill, '_setattr', setattr) 

44 

45_dill._setattr will be used when present to emulate Python 3.7 functionality in 

46older versions of Python while defaulting to the standard setattr in 3.7+. 

47 

48See this PR for the discussion that lead to this system: 

49https://github.com/uqfoundation/dill/pull/443 

50""" 

51 

52import inspect 

53import sys 

54 

55_dill = sys.modules['dill._dill'] 

56 

57 

58class Reduce(object): 

59 """ 

60 Reduce objects are wrappers used for compatibility enforcement during 

61 unpickle-time. They should only be used in calls to pickler.save and 

62 other Reduce objects. They are only evaluated within unpickler.load. 

63 

64 Pickling a Reduce object makes the two implementations equivalent: 

65 

66 pickler.save(Reduce(*reduction)) 

67 

68 pickler.save_reduce(*reduction, obj=reduction) 

69 """ 

70 __slots__ = ['reduction'] 

71 def __new__(cls, *reduction, **kwargs): 

72 """ 

73 Args: 

74 *reduction: a tuple that matches the format given here: 

75 https://docs.python.org/3/library/pickle.html#object.__reduce__ 

76 is_callable: a bool to indicate that the object created by 

77 unpickling `reduction` is callable. If true, the current Reduce 

78 is allowed to be used as the function in further save_reduce calls 

79 or Reduce objects. 

80 """ 

81 is_callable = kwargs.get('is_callable', False) # Pleases Py2. Can be removed later 

82 if is_callable: 

83 self = object.__new__(_CallableReduce) 

84 else: 

85 self = object.__new__(Reduce) 

86 self.reduction = reduction 

87 return self 

88 def __repr__(self): 

89 return 'Reduce%s' % (self.reduction,) 

90 def __copy__(self): 

91 return self # pragma: no cover 

92 def __deepcopy__(self, memo): 

93 return self # pragma: no cover 

94 def __reduce__(self): 

95 return self.reduction 

96 def __reduce_ex__(self, protocol): 

97 return self.__reduce__() 

98 

99class _CallableReduce(Reduce): 

100 # A version of Reduce for functions. Used to trick pickler.save_reduce into 

101 # thinking that Reduce objects of functions are themselves meaningful functions. 

102 def __call__(self, *args, **kwargs): 

103 reduction = self.__reduce__() 

104 func = reduction[0] 

105 f_args = reduction[1] 

106 obj = func(*f_args) 

107 return obj(*args, **kwargs) 

108 

109__NO_DEFAULT = _dill.Sentinel('Getattr.NO_DEFAULT') 

110 

111def Getattr(object, name, default=__NO_DEFAULT): 

112 """ 

113 A Reduce object that represents the getattr operation. When unpickled, the 

114 Getattr will access an attribute 'name' of 'object' and return the value 

115 stored there. If the attribute doesn't exist, the default value will be 

116 returned if present. 

117 

118 The following statements are equivalent: 

119 

120 Getattr(collections, 'OrderedDict') 

121 Getattr(collections, 'spam', None) 

122 Getattr(*args) 

123 

124 Reduce(getattr, (collections, 'OrderedDict')) 

125 Reduce(getattr, (collections, 'spam', None)) 

126 Reduce(getattr, args) 

127 

128 During unpickling, the first two will result in collections.OrderedDict and 

129 None respectively because the first attribute exists and the second one does 

130 not, forcing it to use the default value given in the third argument. 

131 """ 

132 

133 if default is Getattr.NO_DEFAULT: 

134 reduction = (getattr, (object, name)) 

135 else: 

136 reduction = (getattr, (object, name, default)) 

137 

138 return Reduce(*reduction, is_callable=callable(default)) 

139 

140Getattr.NO_DEFAULT = __NO_DEFAULT 

141del __NO_DEFAULT 

142 

143def move_to(module, name=None): 

144 def decorator(func): 

145 if name is None: 

146 fname = func.__name__ 

147 else: 

148 fname = name 

149 module.__dict__[fname] = func 

150 func.__module__ = module.__name__ 

151 return func 

152 return decorator 

153 

154def register_shim(name, default): 

155 """ 

156 A easier to understand and more compact way of "softly" defining a function. 

157 These two pieces of code are equivalent: 

158 

159 if _dill.OLD3X: 

160 def _create_class(): 

161 ... 

162 _create_class = register_shim('_create_class', types.new_class) 

163 

164 if _dill.OLD3X: 

165 @move_to(_dill) 

166 def _create_class(): 

167 ... 

168 _create_class = Getattr(_dill, '_create_class', types.new_class) 

169 

170 Intuitively, it creates a function or object in the versions of dill/python 

171 that require special reimplementations, and use a core library or default 

172 implementation if that function or object does not exist. 

173 """ 

174 func = globals().get(name) 

175 if func is not None: 

176 _dill.__dict__[name] = func 

177 func.__module__ = _dill.__name__ 

178 

179 if default is Getattr.NO_DEFAULT: 

180 reduction = (getattr, (_dill, name)) 

181 else: 

182 reduction = (getattr, (_dill, name, default)) 

183 

184 return Reduce(*reduction, is_callable=callable(default)) 

185 

186###################### 

187## Compatibility Shims are defined below 

188###################### 

189 

190_CELL_EMPTY = register_shim('_CELL_EMPTY', None) 

191 

192_setattr = register_shim('_setattr', setattr) 

193_delattr = register_shim('_delattr', delattr)