added docs for pickle, shelve and copy

1 files changed, 79 insertions, 0 deletions

diff --git a/Doc/libcopy.tex b/Doc/libcopy.tex
new file mode 100644
index 0000000..f7f9744
--- /dev/null
+++ b/Doc/libcopy.tex
@@ -0,0 +1,79 @@
+\section{Built-in module \sectcode{copy}}
+\stmodindex{copy}
+\ttindex{copy}
+\ttindex{deepcopy}
+
+This module provides generic (shallow and deep) copying operations.
+
+Interface summary:
+
+\begin{verbatim}
+import copy
+
+x = copy.copy(y)	# make a shallow copy of y
+x = copy.deepcopy(y)	# make a deep copy of y
+\end{verbatim}
+
+For module specific errors, \code{copy.Error} is raised.
+
+The difference between shallow and deep copying is only relevant for
+compound objects (objects that contain other objects, like lists or
+class instances):
+
+\begin{itemize}
+
+\item
+A {\em shallow copy} constructs a new compound object and then (to the
+extent possible) inserts {\em references} into it to the objects found
+in the original.
+
+\item
+A {\em deep copy} constructs a new compound object and then,
+recursively, inserts {\em copies} into it of the objects found in the
+original.
+
+\end{itemize}
+
+Two problems often exist with deep copy operations that don't exist
+with shallow copy operations:
+
+\begin{itemize}
+
+\item
+Recursive objects (compound objects that, directly or indirectly,
+contain a reference to themselves) may cause a recursive loop.
+
+\item
+Because deep copy copies {\em everything} it may copy too much, e.g.
+administrative data structures that should be shared even between
+copies.
+
+\end{itemize}
+
+Python's \code{deepcopy()} operation avoids these problems by:
+
+\begin{itemize}
+
+\item
+keeping a table of objects already copied during the current
+copying pass; and
+
+\item
+letting user-defined classes override the copying operation or the
+set of components copied.
+
+\end{itemize}
+
+This version does not copy types like module, class, function, method,
+nor stack trace, stack frame, nor file, socket, window, nor array, nor
+any similar types.
+
+Classes can use the same interfaces to control copying that they use
+to control pickling: they can define methods called
+\code{__getinitargs__()}, \code{__getstate__()} and
+\code{__setstate__()}.  See the description of module \code{pickle}
+for information on these methods.
+\stmodindex{pickle}
+\ttindex{__getinitargs__}
+\ttindex{__getstate__}
+\ttindex{__setstate__}