blob: 66c0f8a64d6edd9bcd80518e9b806800b2cb1ce6 [file] [log] [blame]
Guido van Rossum99603b02007-07-20 00:22:32 +00001"""Helper to provide extensibility for pickle.
Fred Drake78a6a362000-10-11 22:16:45 +00002
3This is only useful to add pickle support for extension types defined in
4C, not for instances of user-defined classes.
5"""
6
Guido van Rossumcf356fd2003-01-31 20:34:07 +00007__all__ = ["pickle", "constructor",
8 "add_extension", "remove_extension", "clear_extension_cache"]
Skip Montanaroe99d5ea2001-01-20 19:54:20 +00009
Guido van Rossum47065621997-04-09 17:44:11 +000010dispatch_table = {}
Guido van Rossum47065621997-04-09 17:44:11 +000011
Fred Drake78a6a362000-10-11 22:16:45 +000012def pickle(ob_type, pickle_function, constructor_ob=None):
Florent Xicluna5d1155c2011-10-28 14:45:05 +020013 if not callable(pickle_function):
Fred Drake78a6a362000-10-11 22:16:45 +000014 raise TypeError("reduction functions must be callable")
Guido van Rossum47065621997-04-09 17:44:11 +000015 dispatch_table[ob_type] = pickle_function
16
Jeremy Hyltonf8ecde52003-06-27 16:58:43 +000017 # The constructor_ob function is a vestige of safe for unpickling.
18 # There is no reason for the caller to pass it anymore.
19 if constructor_ob is not None:
20 constructor(constructor_ob)
21
Guido van Rossum47065621997-04-09 17:44:11 +000022def constructor(object):
Florent Xicluna5d1155c2011-10-28 14:45:05 +020023 if not callable(object):
Fred Drake78a6a362000-10-11 22:16:45 +000024 raise TypeError("constructors must be callable")
Guido van Rossum47065621997-04-09 17:44:11 +000025
Guido van Rossum0dd32e22007-04-11 05:40:58 +000026# Example: provide pickling support for complex numbers.
Guido van Rossum47065621997-04-09 17:44:11 +000027
Guido van Rossum0dd32e22007-04-11 05:40:58 +000028try:
29 complex
30except NameError:
31 pass
32else:
Guido van Rossum72be3061997-05-20 18:03:22 +000033
Guido van Rossum0dd32e22007-04-11 05:40:58 +000034 def pickle_complex(c):
35 return complex, (c.real, c.imag)
36
37 pickle(complex, pickle_complex, complex)
Guido van Rossum3926a632001-09-25 16:25:58 +000038
Guido van Rossum298e4212003-02-13 16:30:16 +000039# Support for pickling new-style objects
Guido van Rossum3926a632001-09-25 16:25:58 +000040
Guido van Rossum3926a632001-09-25 16:25:58 +000041def _reconstructor(cls, base, state):
Guido van Rossum298e4212003-02-13 16:30:16 +000042 if base is object:
43 obj = object.__new__(cls)
44 else:
45 obj = base.__new__(cls, state)
Guido van Rossumd8faa362007-04-27 19:54:29 +000046 if base.__init__ != object.__init__:
47 base.__init__(obj, state)
Guido van Rossum3926a632001-09-25 16:25:58 +000048 return obj
Guido van Rossum3926a632001-09-25 16:25:58 +000049
50_HEAPTYPE = 1<<9
51
Guido van Rossumbe532422003-02-21 22:20:31 +000052# Python code for object.__reduce_ex__ for protocols 0 and 1
53
54def _reduce_ex(self, proto):
55 assert proto < 2
Guido van Rossum3926a632001-09-25 16:25:58 +000056 for base in self.__class__.__mro__:
Guido van Rossum00fb0c92001-11-24 21:04:31 +000057 if hasattr(base, '__flags__') and not base.__flags__ & _HEAPTYPE:
Guido van Rossum3926a632001-09-25 16:25:58 +000058 break
59 else:
60 base = object # not really reachable
61 if base is object:
62 state = None
63 else:
Guido van Rossum2a6f5b32001-12-27 16:27:28 +000064 if base is self.__class__:
Collin Winterce36ad82007-08-30 01:19:48 +000065 raise TypeError("can't pickle %s objects" % base.__name__)
Guido van Rossum3926a632001-09-25 16:25:58 +000066 state = base(self)
Guido van Rossum6cef6d52001-09-28 18:13:29 +000067 args = (self.__class__, base, state)
68 try:
Guido van Rossum00fb0c92001-11-24 21:04:31 +000069 getstate = self.__getstate__
Guido van Rossum6cef6d52001-09-28 18:13:29 +000070 except AttributeError:
Guido van Rossum3f50cdc2003-02-10 21:31:27 +000071 if getattr(self, "__slots__", None):
72 raise TypeError("a class that defines __slots__ without "
73 "defining __getstate__ cannot be pickled")
Guido van Rossum00fb0c92001-11-24 21:04:31 +000074 try:
75 dict = self.__dict__
76 except AttributeError:
77 dict = None
78 else:
79 dict = getstate()
Guido van Rossum6cef6d52001-09-28 18:13:29 +000080 if dict:
81 return _reconstructor, args, dict
82 else:
83 return _reconstructor, args
Guido van Rossum255f3ee2003-01-29 06:14:11 +000084
Guido van Rossumbe532422003-02-21 22:20:31 +000085# Helper for __reduce_ex__ protocol 2
Guido van Rossum5aac4e62003-02-06 22:57:00 +000086
87def __newobj__(cls, *args):
88 return cls.__new__(cls, *args)
89
Guido van Rossum5aac4e62003-02-06 22:57:00 +000090def _slotnames(cls):
91 """Return a list of slot names for a given class.
92
93 This needs to find slots defined by the class and its bases, so we
94 can't simply return the __slots__ attribute. We must walk down
95 the Method Resolution Order and concatenate the __slots__ of each
96 class found there. (This assumes classes don't modify their
97 __slots__ attribute to misrepresent their slots after the class is
98 defined.)
99 """
100
101 # Get the value from a cache in the class if possible
102 names = cls.__dict__.get("__slotnames__")
103 if names is not None:
104 return names
105
106 # Not cached -- calculate the value
107 names = []
108 if not hasattr(cls, "__slots__"):
109 # This class has no slots
110 pass
111 else:
112 # Slots found -- gather slot names from all base classes
113 for c in cls.__mro__:
114 if "__slots__" in c.__dict__:
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000115 slots = c.__dict__['__slots__']
116 # if class has a single slot, it can be given as a string
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000117 if isinstance(slots, str):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000118 slots = (slots,)
119 for name in slots:
120 # special descriptors
121 if name in ("__dict__", "__weakref__"):
122 continue
123 # mangled names
124 elif name.startswith('__') and not name.endswith('__'):
125 names.append('_%s%s' % (c.__name__, name))
126 else:
127 names.append(name)
Guido van Rossum5aac4e62003-02-06 22:57:00 +0000128
129 # Cache the outcome in the class if at all possible
130 try:
131 cls.__slotnames__ = names
132 except:
133 pass # But don't die if we can't
134
135 return names
136
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000137# A registry of extension codes. This is an ad-hoc compression
138# mechanism. Whenever a global reference to <module>, <name> is about
139# to be pickled, the (<module>, <name>) tuple is looked up here to see
140# if it is a registered extension code for it. Extension codes are
141# universal, so that the meaning of a pickle does not depend on
142# context. (There are also some codes reserved for local use that
143# don't have this restriction.) Codes are positive ints; 0 is
144# reserved.
145
Guido van Rossumd4b920c2003-02-04 01:54:49 +0000146_extension_registry = {} # key -> code
147_inverted_registry = {} # code -> key
148_extension_cache = {} # code -> object
Guido van Rossum99603b02007-07-20 00:22:32 +0000149# Don't ever rebind those names: pickling grabs a reference to them when
Tim Peters5b7da392003-02-04 00:21:07 +0000150# it's initialized, and won't see a rebinding.
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000151
152def add_extension(module, name, code):
153 """Register an extension code."""
154 code = int(code)
Tim Peters2d629652003-02-04 05:06:17 +0000155 if not 1 <= code <= 0x7fffffff:
Collin Winterce36ad82007-08-30 01:19:48 +0000156 raise ValueError("code out of range")
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000157 key = (module, name)
Guido van Rossumd4b920c2003-02-04 01:54:49 +0000158 if (_extension_registry.get(key) == code and
159 _inverted_registry.get(code) == key):
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000160 return # Redundant registrations are benign
Guido van Rossumd4b920c2003-02-04 01:54:49 +0000161 if key in _extension_registry:
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000162 raise ValueError("key %s is already registered with code %s" %
Guido van Rossumd4b920c2003-02-04 01:54:49 +0000163 (key, _extension_registry[key]))
164 if code in _inverted_registry:
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000165 raise ValueError("code %s is already in use for key %s" %
Guido van Rossumd4b920c2003-02-04 01:54:49 +0000166 (code, _inverted_registry[code]))
167 _extension_registry[key] = code
168 _inverted_registry[code] = key
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000169
170def remove_extension(module, name, code):
171 """Unregister an extension code. For testing only."""
172 key = (module, name)
Guido van Rossumd4b920c2003-02-04 01:54:49 +0000173 if (_extension_registry.get(key) != code or
174 _inverted_registry.get(code) != key):
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000175 raise ValueError("key %s is not registered with code %s" %
176 (key, code))
Guido van Rossumd4b920c2003-02-04 01:54:49 +0000177 del _extension_registry[key]
178 del _inverted_registry[code]
179 if code in _extension_cache:
180 del _extension_cache[code]
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000181
182def clear_extension_cache():
Guido van Rossumd4b920c2003-02-04 01:54:49 +0000183 _extension_cache.clear()
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000184
185# Standard extension code assignments
186
187# Reserved ranges
188
189# First Last Count Purpose
190# 1 127 127 Reserved for Python standard library
Guido van Rossumcef9db62003-02-07 20:56:38 +0000191# 128 191 64 Reserved for Zope
Guido van Rossum255f3ee2003-01-29 06:14:11 +0000192# 192 239 48 Reserved for 3rd parties
193# 240 255 16 Reserved for private use (will never be assigned)
194# 256 Inf Inf Reserved for future assignment
195
196# Extension codes are assigned by the Python Software Foundation.