Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/dill/__info__.py: 100%

1#!/usr/bin/env python 

2# 

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

4# Copyright (c) 2022 The Uncertainty Quantification Foundation. 

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

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

7''' 

8----------------------------- 

9dill: serialize all of python 

10----------------------------- 

11 

12About Dill 

13========== 

14 

15``dill`` extends python's ``pickle`` module for serializing and de-serializing 

16python objects to the majority of the built-in python types. Serialization 

17is the process of converting an object to a byte stream, and the inverse 

18of which is converting a byte stream back to a python object hierarchy. 

19 

20``dill`` provides the user the same interface as the ``pickle`` module, and 

21also includes some additional features. In addition to pickling python 

22objects, ``dill`` provides the ability to save the state of an interpreter 

23session in a single command. Hence, it would be feasible to save an 

24interpreter session, close the interpreter, ship the pickled file to 

25another computer, open a new interpreter, unpickle the session and 

26thus continue from the 'saved' state of the original interpreter 

27session. 

28 

29``dill`` can be used to store python objects to a file, but the primary 

30usage is to send python objects across the network as a byte stream. 

31``dill`` is quite flexible, and allows arbitrary user defined classes 

32and functions to be serialized. Thus ``dill`` is not intended to be 

33secure against erroneously or maliciously constructed data. It is 

34left to the user to decide whether the data they unpickle is from 

35a trustworthy source. 

36 

37``dill`` is part of ``pathos``, a python framework for heterogeneous computing. 

38``dill`` is in active development, so any user feedback, bug reports, comments, 

39or suggestions are highly appreciated. A list of issues is located at 

40https://github.com/uqfoundation/dill/issues, with a legacy list maintained at 

41https://uqfoundation.github.io/project/pathos/query. 

42 

43 

44Major Features 

45============== 

46 

47``dill`` can pickle the following standard types: 

48 

49 - none, type, bool, int, float, complex, bytes, str, 

50 - tuple, list, dict, file, buffer, builtin, 

51 - python classes, namedtuples, dataclasses, metaclasses, 

52 - instances of classes, 

53 - set, frozenset, array, functions, exceptions 

54 

55``dill`` can also pickle more 'exotic' standard types: 

56 

57 - functions with yields, nested functions, lambdas, 

58 - cell, method, unboundmethod, module, code, methodwrapper, 

59 - methoddescriptor, getsetdescriptor, memberdescriptor, wrapperdescriptor, 

60 - dictproxy, slice, notimplemented, ellipsis, quit 

61 

62``dill`` cannot yet pickle these standard types: 

63 

64 - frame, generator, traceback 

65 

66``dill`` also provides the capability to: 

67 

68 - save and load python interpreter sessions 

69 - save and extract the source code from functions and classes 

70 - interactively diagnose pickling errors 

71 

72 

73Current Release 

74=============== 

75 

76The latest released version of ``dill`` is available from: 

77 

78 https://pypi.org/project/dill 

79 

80``dill`` is distributed under a 3-clause BSD license. 

81 

82 

83Development Version 

84=================== 

85 

86You can get the latest development version with all the shiny new features at: 

87 

88 https://github.com/uqfoundation 

89 

90If you have a new contribution, please submit a pull request. 

91 

92 

93Installation 

94============ 

95 

96``dill`` can be installed with ``pip``:: 

97 

98 $ pip install dill 

99 

100To optionally include the ``objgraph`` diagnostic tool in the install:: 

101 

102 $ pip install dill[graph] 

103 

104For windows users, to optionally install session history tools:: 

105 

106 $ pip install dill[readline] 

107 

108 

109Requirements 

110============ 

111 

112``dill`` requires: 

113 

114 - ``python`` (or ``pypy``), **>=3.7** 

115 - ``setuptools``, **>=42** 

116 

117Optional requirements: 

118 

119 - ``objgraph``, **>=1.7.2** 

120 - ``pyreadline``, **>=1.7.1** (on windows) 

121 

122 

123Basic Usage 

124=========== 

125 

126``dill`` is a drop-in replacement for ``pickle``. Existing code can be 

127updated to allow complete pickling using:: 

128 

129 >>> import dill as pickle 

130 

131or:: 

132 

133 >>> from dill import dumps, loads 

134 

135``dumps`` converts the object to a unique byte string, and ``loads`` performs 

136the inverse operation:: 

137 

138 >>> squared = lambda x: x**2 

139 >>> loads(dumps(squared))(3) 

140 9 

141 

142There are a number of options to control serialization which are provided 

143as keyword arguments to several ``dill`` functions: 

144 

145* with *protocol*, the pickle protocol level can be set. This uses the 

146 same value as the ``pickle`` module, *DEFAULT_PROTOCOL*. 

147* with *byref=True*, ``dill`` to behave a lot more like pickle with 

148 certain objects (like modules) pickled by reference as opposed to 

149 attempting to pickle the object itself. 

150* with *recurse=True*, objects referred to in the global dictionary are 

151 recursively traced and pickled, instead of the default behavior of 

152 attempting to store the entire global dictionary. 

153* with *fmode*, the contents of the file can be pickled along with the file 

154 handle, which is useful if the object is being sent over the wire to a 

155 remote system which does not have the original file on disk. Options are 

156 *HANDLE_FMODE* for just the handle, *CONTENTS_FMODE* for the file content 

157 and *FILE_FMODE* for content and handle. 

158* with *ignore=False*, objects reconstructed with types defined in the 

159 top-level script environment use the existing type in the environment 

160 rather than a possibly different reconstructed type. 

161 

162The default serialization can also be set globally in *dill.settings*. 

163Thus, we can modify how ``dill`` handles references to the global dictionary 

164locally or globally:: 

165 

166 >>> import dill.settings 

167 >>> dumps(absolute) == dumps(absolute, recurse=True) 

168 False 

169 >>> dill.settings['recurse'] = True 

170 >>> dumps(absolute) == dumps(absolute, recurse=True) 

171 True 

172 

173``dill`` also includes source code inspection, as an alternate to pickling:: 

174 

175 >>> import dill.source 

176 >>> print(dill.source.getsource(squared)) 

177 squared = lambda x:x**2 

178 

179To aid in debugging pickling issues, use *dill.detect* which provides 

180tools like pickle tracing:: 

181 

182 >>> import dill.detect 

183 >>> with dill.detect.trace(): 

184 >>> dumps(squared) 

185 ┬ F1: <function <lambda> at 0x7fe074f8c280> 

186 ├┬ F2: <function _create_function at 0x7fe074c49c10> 

187 │└ # F2 [34 B] 

188 ├┬ Co: <code object <lambda> at 0x7fe07501eb30, file "<stdin>", line 1> 

189 │├┬ F2: <function _create_code at 0x7fe074c49ca0> 

190 ││└ # F2 [19 B] 

191 │└ # Co [87 B] 

192 ├┬ D1: <dict object at 0x7fe0750d4680> 

193 │└ # D1 [22 B] 

194 ├┬ D2: <dict object at 0x7fe074c5a1c0> 

195 │└ # D2 [2 B] 

196 ├┬ D2: <dict object at 0x7fe074f903c0> 

197 │├┬ D2: <dict object at 0x7fe074f8ebc0> 

198 ││└ # D2 [2 B] 

199 │└ # D2 [23 B] 

200 └ # F1 [180 B] 

201 

202With trace, we see how ``dill`` stored the lambda (``F1``) by first storing 

203``_create_function``, the underlying code object (``Co``) and ``_create_code`` 

204(which is used to handle code objects), then we handle the reference to 

205the global dict (``D2``) plus other dictionaries (``D1`` and ``D2``) that 

206save the lambda object's state. A ``#`` marks when the object is actually stored. 

207 

208 

209More Information 

210================ 

211 

212Probably the best way to get started is to look at the documentation at 

213http://dill.rtfd.io. Also see ``dill.tests`` for a set of scripts that 

214demonstrate how ``dill`` can serialize different python objects. You can 

215run the test suite with ``python -m dill.tests``. The contents of any 

216pickle file can be examined with ``undill``. As ``dill`` conforms to 

217the ``pickle`` interface, the examples and documentation found at 

218http://docs.python.org/library/pickle.html also apply to ``dill`` 

219if one will ``import dill as pickle``. The source code is also generally 

220well documented, so further questions may be resolved by inspecting the 

221code itself. Please feel free to submit a ticket on github, or ask a 

222question on stackoverflow (**@Mike McKerns**). 

223If you would like to share how you use ``dill`` in your work, please send 

224an email (to **mmckerns at uqfoundation dot org**). 

225 

226 

227Citation 

228======== 

229 

230If you use ``dill`` to do research that leads to publication, we ask that you 

231acknowledge use of ``dill`` by citing the following in your publication:: 

232 

233 M.M. McKerns, L. Strand, T. Sullivan, A. Fang, M.A.G. Aivazis, 

234 "Building a framework for predictive science", Proceedings of 

235 the 10th Python in Science Conference, 2011; 

236 http://arxiv.org/pdf/1202.1056 

237 

238 Michael McKerns and Michael Aivazis, 

239 "pathos: a framework for heterogeneous computing", 2010- ; 

240 https://uqfoundation.github.io/project/pathos 

241 

242Please see https://uqfoundation.github.io/project/pathos or 

243http://arxiv.org/pdf/1202.1056 for further information. 

244 

245''' 

246 

247__version__ = '0.3.6' 

248__author__ = 'Mike McKerns' 

249 

250__license__ = ''' 

251Copyright (c) 2004-2016 California Institute of Technology. 

252Copyright (c) 2016-2022 The Uncertainty Quantification Foundation. 

253All rights reserved. 

254 

255This software is available subject to the conditions and terms laid 

256out below. By downloading and using this software you are agreeing 

257to the following conditions. 

258 

259Redistribution and use in source and binary forms, with or without 

260modification, are permitted provided that the following conditions 

261are met:: 

262 

263 - Redistribution of source code must retain the above copyright 

264 notice, this list of conditions and the following disclaimer. 

265 

266 - Redistribution in binary form must reproduce the above copyright 

267 notice, this list of conditions and the following disclaimer in the 

268 documentations and/or other materials provided with the distribution. 

269 

270 - Neither the names of the copyright holders nor the names of any of 

271 the contributors may be used to endorse or promote products derived 

272 from this software without specific prior written permission. 

273 

274THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 

275"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 

276TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 

277PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 

278CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 

279EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 

280PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 

281OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 

282WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 

283OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 

284ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

285 

286'''