[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / lib / node66.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="pickle-protocol.html" />
<link rel="prev" href="node65.html" />
<link rel="parent" href="module-pickle.html" />
<link rel="next" href="pickle-protocol.html" />
<meta name='aesop' content='information' />
<title>3.14.4 What can be pickled and unpickled?</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="3.14.3 Usage"
  href="node65.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="3.14 pickle  "
  href="module-pickle.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="3.14.5 The pickle protocol"
  href="pickle-protocol.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node65.html">3.14.3 Usage</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-pickle.html">3.14 pickle  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="pickle-protocol.html">3.14.5 The pickle protocol</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0051440000000000000000">
3.14.4 What can be pickled and unpickled?</A>
</H2>

<P>
The following types can be pickled:

<P>

<UL>
<LI><code>None</code>, <code>True</code>, and <code>False</code>

<P>
</LI>
<LI>integers, long integers, floating point numbers, complex numbers

<P>
</LI>
<LI>normal and Unicode strings

<P>
</LI>
<LI>tuples, lists, sets, and dictionaries containing only picklable objects

<P>
</LI>
<LI>functions defined at the top level of a module

<P>
</LI>
<LI>built-in functions defined at the top level of a module

<P>
</LI>
<LI>classes that are defined at the top level of a module

<P>
</LI>
<LI>instances of such classes whose <tt class="member">__dict__</tt> or
<tt class="method">__setstate__()</tt> is picklable  (see
section&nbsp;<A href="pickle-protocol.html#pickle-protocol">3.14.5</A> for details)

<P>
</LI>
</UL>

<P>
Attempts to pickle unpicklable objects will raise the
<tt class="exception">PicklingError</tt> exception; when this happens, an unspecified
number of bytes may have already been written to the underlying file.

<P>
Note that functions (built-in and user-defined) are pickled by ``fully
qualified'' name reference, not by value.  This means that only the
function name is pickled, along with the name of module the function
is defined in.  Neither the function's code, nor any of its function
attributes are pickled.  Thus the defining module must be importable
in the unpickling environment, and the module must contain the named
object, otherwise an exception will be raised.<A NAME="tex2html17"
  HREF="#foot8971"><SUP>3.5</SUP></A>
<P>
Similarly, classes are pickled by named reference, so the same
restrictions in the unpickling environment apply.  Note that none of
the class's code or data is pickled, so in the following example the
class attribute <code>attr</code> is not restored in the unpickling
environment:

<P>
<div class="verbatim"><pre>
class Foo:
    attr = 'a class attr'

picklestring = pickle.dumps(Foo)
</pre></div>

<P>
These restrictions are why picklable functions and classes must be
defined in the top level of a module.

<P>
Similarly, when class instances are pickled, their class's code and
data are not pickled along with them.  Only the instance data are
pickled.  This is done on purpose, so you can fix bugs in a class or
add methods to the class and still load objects that were created with
an earlier version of the class.  If you plan to have long-lived
objects that will see many versions of a class, it may be worthwhile
to put a version number in the objects so that suitable conversions
can be made by the class's <tt class="method">__setstate__()</tt> method.

<P>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot8971">... raised.</A><A
 HREF="node66.html#tex2html17"><SUP>3.5</SUP></A></DT>
<DD>The exception
raised will likely be an <tt class="exception">ImportError</tt> or an
<tt class="exception">AttributeError</tt> but it could be something else.

</DD>
</DL>
<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="3.14.3 Usage"
  href="node65.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="3.14 pickle  "
  href="module-pickle.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="3.14.5 The pickle protocol"
  href="pickle-protocol.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node65.html">3.14.3 Usage</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-pickle.html">3.14 pickle  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="pickle-protocol.html">3.14.5 The pickle protocol</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="pickle-protocol.html" />
	13	<link rel="prev" href="node65.html" />
	14	<link rel="parent" href="module-pickle.html" />
	15	<link rel="next" href="pickle-protocol.html" />
	16	<meta name='aesop' content='information' />
	17	<title>3.14.4 What can be pickled and unpickled?</title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="3.14.3 Usage"
	25	href="node65.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="3.14 pickle "
	28	href="module-pickle.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="3.14.5 The pickle protocol"
	31	href="pickle-protocol.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="node65.html">3.14.3 Usage</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="module-pickle.html">3.14 pickle </A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="pickle-protocol.html">3.14.5 The pickle protocol</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION0051440000000000000000">
	56	3.14.4 What can be pickled and unpickled?</A>
	57	</H2>
	58
	59	<P>
	60	The following types can be pickled:
	61
	62	<P>
	63
	64	<UL>
65	<LI><code>None</code>, <code>True</code>, and <code>False</code>
66
67	<P>
68	</LI>
69	<LI>integers, long integers, floating point numbers, complex numbers
70
71	<P>
72	</LI>
73	<LI>normal and Unicode strings
74
75	<P>
76	</LI>
77	<LI>tuples, lists, sets, and dictionaries containing only picklable objects
78
79	<P>
80	</LI>
81	<LI>functions defined at the top level of a module
82
83	<P>
84	</LI>
85	<LI>built-in functions defined at the top level of a module
86
87	<P>
88	</LI>
89	<LI>classes that are defined at the top level of a module
90
91	<P>
92	</LI>
93	<LI>instances of such classes whose <tt class="member">__dict__</tt> or
94	<tt class="method">__setstate__()</tt> is picklable (see
95	section <A href="pickle-protocol.html#pickle-protocol">3.14.5</A> for details)
96
97	<P>
98	</LI>
99	</UL>
100
101	<P>
102	Attempts to pickle unpicklable objects will raise the
103	<tt class="exception">PicklingError</tt> exception; when this happens, an unspecified
104	number of bytes may have already been written to the underlying file.
105
106	<P>
107	Note that functions (built-in and user-defined) are pickled by ``fully
108	qualified'' name reference, not by value. This means that only the
109	function name is pickled, along with the name of module the function
110	is defined in. Neither the function's code, nor any of its function
111	attributes are pickled. Thus the defining module must be importable
112	in the unpickling environment, and the module must contain the named
113	object, otherwise an exception will be raised.<A NAME="tex2html17"
114	HREF="#foot8971"><SUP>3.5</SUP></A>
115	<P>
116	Similarly, classes are pickled by named reference, so the same
117	restrictions in the unpickling environment apply. Note that none of
118	the class's code or data is pickled, so in the following example the
119	class attribute <code>attr</code> is not restored in the unpickling
120	environment:
121
122	<P>
123	<div class="verbatim"><pre>
124	class Foo:
125	attr = 'a class attr'
126
127	picklestring = pickle.dumps(Foo)
128	</pre></div>
129
130	<P>
131	These restrictions are why picklable functions and classes must be
132	defined in the top level of a module.
133
134	<P>
135	Similarly, when class instances are pickled, their class's code and
136	data are not pickled along with them. Only the instance data are
137	pickled. This is done on purpose, so you can fix bugs in a class or
138	add methods to the class and still load objects that were created with
139	an earlier version of the class. If you plan to have long-lived
140	objects that will see many versions of a class, it may be worthwhile
141	to put a version number in the objects so that suitable conversions
142	can be made by the class's <tt class="method">__setstate__()</tt> method.
143
144	<P>
145	<BR><HR><H4>Footnotes</H4>
146	<DL>
147	<DT><A NAME="foot8971">... raised.</A><A
148	HREF="node66.html#tex2html17"><SUP>3.5</SUP></A></DT>
149	<DD>The exception
150	raised will likely be an <tt class="exception">ImportError</tt> or an
151	<tt class="exception">AttributeError</tt> but it could be something else.
152
153	</DD>
154	</DL>
155	<DIV CLASS="navigation">
156	<div class='online-navigation'>
157	<p></p><hr />
158	<table align="center" width="100%" cellpadding="0" cellspacing="2">
159	<tr>
160	<td class='online-navigation'><a rel="prev" title="3.14.3 Usage"
161	href="node65.html"><img src='../icons/previous.png'
162	border='0' height='32' alt='Previous Page' width='32' /></A></td>
163	<td class='online-navigation'><a rel="parent" title="3.14 pickle "
164	href="module-pickle.html"><img src='../icons/up.png'
165	border='0' height='32' alt='Up One Level' width='32' /></A></td>
166	<td class='online-navigation'><a rel="next" title="3.14.5 The pickle protocol"
167	href="pickle-protocol.html"><img src='../icons/next.png'
168	border='0' height='32' alt='Next Page' width='32' /></A></td>
169	<td align="center" width="100%">Python Library Reference</td>
170	<td class='online-navigation'><a rel="contents" title="Table of Contents"
171	href="contents.html"><img src='../icons/contents.png'
172	border='0' height='32' alt='Contents' width='32' /></A></td>
173	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
174	border='0' height='32' alt='Module Index' width='32' /></a></td>
175	<td class='online-navigation'><a rel="index" title="Index"
176	href="genindex.html"><img src='../icons/index.png'
177	border='0' height='32' alt='Index' width='32' /></A></td>
178	</tr></table>
179	<div class='online-navigation'>
180	<b class="navlabel">Previous:</b>
181	<a class="sectref" rel="prev" href="node65.html">3.14.3 Usage</A>
182	<b class="navlabel">Up:</b>
183	<a class="sectref" rel="parent" href="module-pickle.html">3.14 pickle </A>
184	<b class="navlabel">Next:</b>
185	<a class="sectref" rel="next" href="pickle-protocol.html">3.14.5 The pickle protocol</A>
186	</div>
187	</div>
188	<hr />
189	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
190	</DIV>
191	<!--End of Navigation Panel-->
192	<ADDRESS>
193	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
194	</ADDRESS>
195	</BODY>
196	</HTML>