Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit cf7e830

Browse files
freddrakefreddrake
committed
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.
1 parent 12d9da5 commit cf7e830

2 files changed

Lines changed: 42 additions & 36 deletions

File tree

‎Doc/lib/libpickle.tex‎

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,10 @@ \section{Standard Module \sectcode{pickle}}
2929

3030
\strong{Note:} The \code{pickle} module is rather slow. A
3131
reimplementation of the same algorithm in C, which is up to 1000 times
32-
faster, is available as the \code{cPickle} module. This has the same
33-
interface except that \code{Pickler} and \code{Unpickler} are factory
34-
functions, not classes (so they cannot be used as a base class for
35-
inheritance).
32+
faster, is available as the \code{cPickle}\refbimodindex{cPickle}
33+
module. This has the same interface except that \code{Pickler} and
34+
\code{Unpickler} are factory functions, not classes (so they cannot be
35+
used as a base class for inheritance).
3636

3737
Unlike the built-in module \code{marshal}, \code{pickle} handles the
3838
following correctly:
@@ -50,9 +50,12 @@ \section{Standard Module \sectcode{pickle}}
5050

5151
The data format used by \code{pickle} is Python-specific. This has
5252
the advantage that there are no restrictions imposed by external
53-
standards such as CORBA (which probably can't represent pointer
54-
sharing or recursive objects); however it means that non-Python
55-
programs may not be able to reconstruct pickled Python objects.
53+
standards such as XDR%
54+
\index{XDR}
55+
\index{External Data Representation}
56+
(which can't represent pointer sharing); however
57+
it means that non-Python programs may not be able to reconstruct
58+
pickled Python objects.
5659

5760
By default, the \code{pickle} data format uses a printable \ASCII{}
5861
representation. This is slightly more voluminous than a binary
@@ -82,8 +85,8 @@ \section{Standard Module \sectcode{pickle}}
8285
arbitrary string of printable \ASCII{} characters. The resolution of
8386
such names is not defined by the \code{pickle} module --- the
8487
persistent object module will have to implement a method
85-
\code{persistent_load}. To write references to persistent objects,
86-
the persistent module must define a method \code{persistent_id} which
88+
\code{persistent_load()}. To write references to persistent objects,
89+
the persistent module must define a method \code{persistent_id()} which
8790
returns either \code{None} or the persistent ID of the object.
8891

8992
There are some restrictions on the pickling of class instances.
@@ -93,16 +96,16 @@ \section{Standard Module \sectcode{pickle}}
9396

9497
\renewcommand{\indexsubitem}{(pickle protocol)}
9598

96-
When a pickled class instance is unpickled, its \code{__init__} method
99+
When a pickled class instance is unpickled, its \code{__init__()} method
97100
is normally \emph{not} invoked. \strong{Note:} This is a deviation
98101
from previous versions of this module; the change was introduced in
99102
Python 1.5b2. The reason for the change is that in many cases it is
100103
desirable to have a constructor that requires arguments; it is a
101-
(minor) nuisance to have to provide a \code{__getinitargs__} method.
104+
(minor) nuisance to have to provide a \code{__getinitargs__()} method.
102105

103-
If it is desirable that the \code{__init__} method be called on
106+
If it is desirable that the \code{__init__()} method be called on
104107
unpickling, a class can define a method \code{__getinitargs__()},
105-
which should return a {\em tuple} containing the arguments to be
108+
which should return a \emph{tuple} containing the arguments to be
106109
passed to the class constructor (\code{__init__()}). This method is
107110
called at pickle time; the tuple it returns is incorporated in the
108111
pickle for the instance.
@@ -171,9 +174,9 @@ \section{Standard Module \sectcode{pickle}}
171174
x = pickle.load(f)
172175
\end{verbatim}\ecode
173176
%
174-
The \code{Pickler} class only calls the method \code{f.write} with a
175-
string argument. The \code{Unpickler} calls the methods \code{f.read}
176-
(with an integer argument) and \code{f.readline} (without argument),
177+
The \code{Pickler} class only calls the method \code{f.write()} with a
178+
string argument. The \code{Unpickler} calls the methods \code{f.read()}
179+
(with an integer argument) and \code{f.readline()} (without argument),
177180
both returning a string. It is explicitly allowed to pass non-file
178181
objects here, as long as they have the right methods.
179182
\ttindex{Unpickler}
@@ -213,7 +216,7 @@ \section{Standard Module \sectcode{pickle}}
213216
same number of calls to the \code{load()} instance of the
214217
corresponding \code{Unpickler} instance. If the same object is
215218
pickled by multiple \code{dump()} calls, the \code{load()} will all
216-
yield references to the same object. {\em Warning}: this is intended
219+
yield references to the same object. \emph{Warning}: this is intended
217220
for pickling multiple objects without intervening modifications to the
218221
objects or their parts. If you modify an object and then pickle it
219222
again using the same \code{Pickler} instance, the object is not
@@ -237,7 +240,7 @@ \section{Standard Module \sectcode{pickle}}
237240

238241
\begin{funcdesc}{load}{file}
239242
Read a pickled object from the open file object \var{file}. This is
240-
equivalent to \code{Unpickler(file).load()}.
243+
equivalent to \code{Unpickler(\var{file}).load()}.
241244
\end{funcdesc}
242245

243246
\begin{funcdesc}{dumps}{object\optional{, bin}}

‎Doc/libpickle.tex‎

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,10 @@ \section{Standard Module \sectcode{pickle}}
2929

3030
\strong{Note:} The \code{pickle} module is rather slow. A
3131
reimplementation of the same algorithm in C, which is up to 1000 times
32-
faster, is available as the \code{cPickle} module. This has the same
33-
interface except that \code{Pickler} and \code{Unpickler} are factory
34-
functions, not classes (so they cannot be used as a base class for
35-
inheritance).
32+
faster, is available as the \code{cPickle}\refbimodindex{cPickle}
33+
module. This has the same interface except that \code{Pickler} and
34+
\code{Unpickler} are factory functions, not classes (so they cannot be
35+
used as a base class for inheritance).
3636

3737
Unlike the built-in module \code{marshal}, \code{pickle} handles the
3838
following correctly:
@@ -50,9 +50,12 @@ \section{Standard Module \sectcode{pickle}}
5050

5151
The data format used by \code{pickle} is Python-specific. This has
5252
the advantage that there are no restrictions imposed by external
53-
standards such as CORBA (which probably can't represent pointer
54-
sharing or recursive objects); however it means that non-Python
55-
programs may not be able to reconstruct pickled Python objects.
53+
standards such as XDR%
54+
\index{XDR}
55+
\index{External Data Representation}
56+
(which can't represent pointer sharing); however
57+
it means that non-Python programs may not be able to reconstruct
58+
pickled Python objects.
5659

5760
By default, the \code{pickle} data format uses a printable \ASCII{}
5861
representation. This is slightly more voluminous than a binary
@@ -82,8 +85,8 @@ \section{Standard Module \sectcode{pickle}}
8285
arbitrary string of printable \ASCII{} characters. The resolution of
8386
such names is not defined by the \code{pickle} module --- the
8487
persistent object module will have to implement a method
85-
\code{persistent_load}. To write references to persistent objects,
86-
the persistent module must define a method \code{persistent_id} which
88+
\code{persistent_load()}. To write references to persistent objects,
89+
the persistent module must define a method \code{persistent_id()} which
8790
returns either \code{None} or the persistent ID of the object.
8891

8992
There are some restrictions on the pickling of class instances.
@@ -93,16 +96,16 @@ \section{Standard Module \sectcode{pickle}}
9396

9497
\renewcommand{\indexsubitem}{(pickle protocol)}
9598

96-
When a pickled class instance is unpickled, its \code{__init__} method
99+
When a pickled class instance is unpickled, its \code{__init__()} method
97100
is normally \emph{not} invoked. \strong{Note:} This is a deviation
98101
from previous versions of this module; the change was introduced in
99102
Python 1.5b2. The reason for the change is that in many cases it is
100103
desirable to have a constructor that requires arguments; it is a
101-
(minor) nuisance to have to provide a \code{__getinitargs__} method.
104+
(minor) nuisance to have to provide a \code{__getinitargs__()} method.
102105

103-
If it is desirable that the \code{__init__} method be called on
106+
If it is desirable that the \code{__init__()} method be called on
104107
unpickling, a class can define a method \code{__getinitargs__()},
105-
which should return a {\em tuple} containing the arguments to be
108+
which should return a \emph{tuple} containing the arguments to be
106109
passed to the class constructor (\code{__init__()}). This method is
107110
called at pickle time; the tuple it returns is incorporated in the
108111
pickle for the instance.
@@ -171,9 +174,9 @@ \section{Standard Module \sectcode{pickle}}
171174
x = pickle.load(f)
172175
\end{verbatim}\ecode
173176
%
174-
The \code{Pickler} class only calls the method \code{f.write} with a
175-
string argument. The \code{Unpickler} calls the methods \code{f.read}
176-
(with an integer argument) and \code{f.readline} (without argument),
177+
The \code{Pickler} class only calls the method \code{f.write()} with a
178+
string argument. The \code{Unpickler} calls the methods \code{f.read()}
179+
(with an integer argument) and \code{f.readline()} (without argument),
177180
both returning a string. It is explicitly allowed to pass non-file
178181
objects here, as long as they have the right methods.
179182
\ttindex{Unpickler}
@@ -213,7 +216,7 @@ \section{Standard Module \sectcode{pickle}}
213216
same number of calls to the \code{load()} instance of the
214217
corresponding \code{Unpickler} instance. If the same object is
215218
pickled by multiple \code{dump()} calls, the \code{load()} will all
216-
yield references to the same object. {\em Warning}: this is intended
219+
yield references to the same object. \emph{Warning}: this is intended
217220
for pickling multiple objects without intervening modifications to the
218221
objects or their parts. If you modify an object and then pickle it
219222
again using the same \code{Pickler} instance, the object is not
@@ -237,7 +240,7 @@ \section{Standard Module \sectcode{pickle}}
237240

238241
\begin{funcdesc}{load}{file}
239242
Read a pickled object from the open file object \var{file}. This is
240-
equivalent to \code{Unpickler(file).load()}.
243+
equivalent to \code{Unpickler(\var{file}).load()}.
241244
\end{funcdesc}
242245

243246
\begin{funcdesc}{dumps}{object\optional{, bin}}

0 commit comments

Comments
 (0)