Rooba
/
cpython
mirror of https://github.com/python/cpython.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add module reference for cPickle to index. 

Consistency:  Always use trailing "()" for function and method names in text.

Consistency:  Always mark parameter names with \var{} in text.

Change questionable text about CORBA to definate text about XDR; "CORBA" isn't
enough to specify an external representation, and I'm not sure the comment is
right if we say "IIOP".  I know its right about XDR if we only mention shared
object references and not recursive structures.
This commit is contained in:
Fred Drake 1998-01-09 22:36:51 +00:00
parent 12d9da5827
commit cf7e830869
2 changed files with 42 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
Doc/lib/libpickle.tex
View File

@ -29,10 +29,10 @@ objects on ``dbm''-style database files.
\strong{Note:} The \code{pickle} module is rather slow. A \strong{Note:} The \code{pickle} module is rather slow. A
reimplementation of the same algorithm in C, which is up to 1000 times reimplementation of the same algorithm in C, which is up to 1000 times
faster, is available as the \code{cPickle} module. This has the same faster, is available as the \code{cPickle}\refbimodindex{cPickle}
interface except that \code{Pickler} and \code{Unpickler} are factory module. This has the same interface except that \code{Pickler} and
functions, not classes (so they cannot be used as a base class for \code{Unpickler} are factory functions, not classes (so they cannot be
inheritance). used as a base class for inheritance).
Unlike the built-in module \code{marshal}, \code{pickle} handles the Unlike the built-in module \code{marshal}, \code{pickle} handles the
following correctly: following correctly:
@ -50,9 +50,12 @@ following correctly:
The data format used by \code{pickle} is Python-specific. This has The data format used by \code{pickle} is Python-specific. This has
the advantage that there are no restrictions imposed by external the advantage that there are no restrictions imposed by external
standards such as CORBA (which probably can't represent pointer standards such as XDR%
sharing or recursive objects); however it means that non-Python \index{XDR}
programs may not be able to reconstruct pickled Python objects. \index{External Data Representation}
(which can't represent pointer sharing); however
it means that non-Python programs may not be able to reconstruct
pickled Python objects.
By default, the \code{pickle} data format uses a printable \ASCII{} By default, the \code{pickle} data format uses a printable \ASCII{}
representation. This is slightly more voluminous than a binary representation. This is slightly more voluminous than a binary
@ -82,8 +85,8 @@ data stream. Such objects are referenced by a name, which is an
arbitrary string of printable \ASCII{} characters. The resolution of arbitrary string of printable \ASCII{} characters. The resolution of
such names is not defined by the \code{pickle} module --- the such names is not defined by the \code{pickle} module --- the
persistent object module will have to implement a method persistent object module will have to implement a method
\code{persistent_load}. To write references to persistent objects, \code{persistent_load()}. To write references to persistent objects,
the persistent module must define a method \code{persistent_id} which the persistent module must define a method \code{persistent_id()} which
returns either \code{None} or the persistent ID of the object. returns either \code{None} or the persistent ID of the object.
There are some restrictions on the pickling of class instances. There are some restrictions on the pickling of class instances.
@ -93,16 +96,16 @@ Furthermore, all its instance variables must be picklable.
\renewcommand{\indexsubitem}{(pickle protocol)} \renewcommand{\indexsubitem}{(pickle protocol)}
When a pickled class instance is unpickled, its \code{__init__} method When a pickled class instance is unpickled, its \code{__init__()} method
is normally \emph{not} invoked. \strong{Note:} This is a deviation is normally \emph{not} invoked. \strong{Note:} This is a deviation
from previous versions of this module; the change was introduced in from previous versions of this module; the change was introduced in
Python 1.5b2. The reason for the change is that in many cases it is Python 1.5b2. The reason for the change is that in many cases it is
desirable to have a constructor that requires arguments; it is a desirable to have a constructor that requires arguments; it is a
(minor) nuisance to have to provide a \code{__getinitargs__} method. (minor) nuisance to have to provide a \code{__getinitargs__()} method.
If it is desirable that the \code{__init__} method be called on If it is desirable that the \code{__init__()} method be called on
unpickling, a class can define a method \code{__getinitargs__()}, unpickling, a class can define a method \code{__getinitargs__()},
which should return a {\em tuple} containing the arguments to be which should return a \emph{tuple} containing the arguments to be
passed to the class constructor (\code{__init__()}). This method is passed to the class constructor (\code{__init__()}). This method is
called at pickle time; the tuple it returns is incorporated in the called at pickle time; the tuple it returns is incorporated in the
pickle for the instance. pickle for the instance.
@ -171,9 +174,9 @@ A shorthand is:
x = pickle.load(f) x = pickle.load(f)
\end{verbatim}\ecode \end{verbatim}\ecode
% %
The \code{Pickler} class only calls the method \code{f.write} with a The \code{Pickler} class only calls the method \code{f.write()} with a
string argument. The \code{Unpickler} calls the methods \code{f.read} string argument. The \code{Unpickler} calls the methods \code{f.read()}
(with an integer argument) and \code{f.readline} (without argument), (with an integer argument) and \code{f.readline()} (without argument),
both returning a string. It is explicitly allowed to pass non-file both returning a string. It is explicitly allowed to pass non-file
objects here, as long as they have the right methods. objects here, as long as they have the right methods.
\ttindex{Unpickler} \ttindex{Unpickler}
@ -213,7 +216,7 @@ the same \code{Pickler} instance. These must then be matched to the
same number of calls to the \code{load()} instance of the same number of calls to the \code{load()} instance of the
corresponding \code{Unpickler} instance. If the same object is corresponding \code{Unpickler} instance. If the same object is
pickled by multiple \code{dump()} calls, the \code{load()} will all pickled by multiple \code{dump()} calls, the \code{load()} will all
yield references to the same object. {\em Warning}: this is intended yield references to the same object. \emph{Warning}: this is intended
for pickling multiple objects without intervening modifications to the for pickling multiple objects without intervening modifications to the
objects or their parts. If you modify an object and then pickle it objects or their parts. If you modify an object and then pickle it
again using the same \code{Pickler} instance, the object is not again using the same \code{Pickler} instance, the object is not
@ -237,7 +240,7 @@ text pickle format is used.
\begin{funcdesc}{load}{file} \begin{funcdesc}{load}{file}
Read a pickled object from the open file object \var{file}. This is Read a pickled object from the open file object \var{file}. This is
equivalent to \code{Unpickler(file).load()}. equivalent to \code{Unpickler(\var{file}).load()}.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{dumps}{object\optional{, bin}} \begin{funcdesc}{dumps}{object\optional{, bin}}

39
Doc/libpickle.tex
View File

@ -29,10 +29,10 @@ objects on ``dbm''-style database files.
\strong{Note:} The \code{pickle} module is rather slow. A \strong{Note:} The \code{pickle} module is rather slow. A
reimplementation of the same algorithm in C, which is up to 1000 times reimplementation of the same algorithm in C, which is up to 1000 times
faster, is available as the \code{cPickle} module. This has the same faster, is available as the \code{cPickle}\refbimodindex{cPickle}
interface except that \code{Pickler} and \code{Unpickler} are factory module. This has the same interface except that \code{Pickler} and
functions, not classes (so they cannot be used as a base class for \code{Unpickler} are factory functions, not classes (so they cannot be
inheritance). used as a base class for inheritance).
Unlike the built-in module \code{marshal}, \code{pickle} handles the Unlike the built-in module \code{marshal}, \code{pickle} handles the
following correctly: following correctly:
@ -50,9 +50,12 @@ following correctly:
The data format used by \code{pickle} is Python-specific. This has The data format used by \code{pickle} is Python-specific. This has
the advantage that there are no restrictions imposed by external the advantage that there are no restrictions imposed by external
standards such as CORBA (which probably can't represent pointer standards such as XDR%
sharing or recursive objects); however it means that non-Python \index{XDR}
programs may not be able to reconstruct pickled Python objects. \index{External Data Representation}
(which can't represent pointer sharing); however
it means that non-Python programs may not be able to reconstruct
pickled Python objects.
By default, the \code{pickle} data format uses a printable \ASCII{} By default, the \code{pickle} data format uses a printable \ASCII{}
representation. This is slightly more voluminous than a binary representation. This is slightly more voluminous than a binary
@ -82,8 +85,8 @@ data stream. Such objects are referenced by a name, which is an
arbitrary string of printable \ASCII{} characters. The resolution of arbitrary string of printable \ASCII{} characters. The resolution of
such names is not defined by the \code{pickle} module --- the such names is not defined by the \code{pickle} module --- the
persistent object module will have to implement a method persistent object module will have to implement a method
\code{persistent_load}. To write references to persistent objects, \code{persistent_load()}. To write references to persistent objects,
the persistent module must define a method \code{persistent_id} which the persistent module must define a method \code{persistent_id()} which
returns either \code{None} or the persistent ID of the object. returns either \code{None} or the persistent ID of the object.
There are some restrictions on the pickling of class instances. There are some restrictions on the pickling of class instances.
@ -93,16 +96,16 @@ Furthermore, all its instance variables must be picklable.
\renewcommand{\indexsubitem}{(pickle protocol)} \renewcommand{\indexsubitem}{(pickle protocol)}
When a pickled class instance is unpickled, its \code{__init__} method When a pickled class instance is unpickled, its \code{__init__()} method
is normally \emph{not} invoked. \strong{Note:} This is a deviation is normally \emph{not} invoked. \strong{Note:} This is a deviation
from previous versions of this module; the change was introduced in from previous versions of this module; the change was introduced in
Python 1.5b2. The reason for the change is that in many cases it is Python 1.5b2. The reason for the change is that in many cases it is
desirable to have a constructor that requires arguments; it is a desirable to have a constructor that requires arguments; it is a
(minor) nuisance to have to provide a \code{__getinitargs__} method. (minor) nuisance to have to provide a \code{__getinitargs__()} method.
If it is desirable that the \code{__init__} method be called on If it is desirable that the \code{__init__()} method be called on
unpickling, a class can define a method \code{__getinitargs__()}, unpickling, a class can define a method \code{__getinitargs__()},
which should return a {\em tuple} containing the arguments to be which should return a \emph{tuple} containing the arguments to be
passed to the class constructor (\code{__init__()}). This method is passed to the class constructor (\code{__init__()}). This method is
called at pickle time; the tuple it returns is incorporated in the called at pickle time; the tuple it returns is incorporated in the
pickle for the instance. pickle for the instance.
@ -171,9 +174,9 @@ A shorthand is:
x = pickle.load(f) x = pickle.load(f)
\end{verbatim}\ecode \end{verbatim}\ecode
% %
The \code{Pickler} class only calls the method \code{f.write} with a The \code{Pickler} class only calls the method \code{f.write()} with a
string argument. The \code{Unpickler} calls the methods \code{f.read} string argument. The \code{Unpickler} calls the methods \code{f.read()}
(with an integer argument) and \code{f.readline} (without argument), (with an integer argument) and \code{f.readline()} (without argument),
both returning a string. It is explicitly allowed to pass non-file both returning a string. It is explicitly allowed to pass non-file
objects here, as long as they have the right methods. objects here, as long as they have the right methods.
\ttindex{Unpickler} \ttindex{Unpickler}
@ -213,7 +216,7 @@ the same \code{Pickler} instance. These must then be matched to the
same number of calls to the \code{load()} instance of the same number of calls to the \code{load()} instance of the
corresponding \code{Unpickler} instance. If the same object is corresponding \code{Unpickler} instance. If the same object is
pickled by multiple \code{dump()} calls, the \code{load()} will all pickled by multiple \code{dump()} calls, the \code{load()} will all
yield references to the same object. {\em Warning}: this is intended yield references to the same object. \emph{Warning}: this is intended
for pickling multiple objects without intervening modifications to the for pickling multiple objects without intervening modifications to the
objects or their parts. If you modify an object and then pickle it objects or their parts. If you modify an object and then pickle it
again using the same \code{Pickler} instance, the object is not again using the same \code{Pickler} instance, the object is not
@ -237,7 +240,7 @@ text pickle format is used.
\begin{funcdesc}{load}{file} \begin{funcdesc}{load}{file}
Read a pickled object from the open file object \var{file}. This is Read a pickled object from the open file object \var{file}. This is
equivalent to \code{Unpickler(file).load()}. equivalent to \code{Unpickler(\var{file}).load()}.
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{dumps}{object\optional{, bin}} \begin{funcdesc}{dumps}{object\optional{, bin}}