ref: b2526c7d909b2ce321faef34d49b1b70434cf360
dir: /sys/src/cmd/python/Doc/lib/libcopy.tex/
\section{\module{copy} ---
Shallow and deep copy operations}
\declaremodule{standard}{copy}
\modulesynopsis{Shallow and deep copy operations.}
This module provides generic (shallow and deep) copying operations.
\withsubitem{(in copy)}{\ttindex{copy()}\ttindex{deepcopy()}}
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, \exception{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 \emph{shallow copy} constructs a new compound object and then (to the
extent possible) inserts \emph{references} into it to the objects found
in the original.
\item
A \emph{deep copy} constructs a new compound object and then,
recursively, inserts \emph{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 \emph{everything} it may copy too much,
e.g., administrative data structures that should be shared even
between copies.
\end{itemize}
The \function{deepcopy()} function avoids these problems by:
\begin{itemize}
\item
keeping a ``memo'' dictionary 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 module does not copy types like module, method,
stack trace, stack frame, file, socket, window, array, or any similar
types. It does ``copy'' functions and classes (shallow and deeply),
by returning the original object unchanged; this is compatible with
the way these are treated by the \module{pickle} module.
\versionchanged[Added copying functions]{2.5}
Classes can use the same interfaces to control copying that they use
to control pickling. See the description of module
\refmodule{pickle}\refstmodindex{pickle} for information on these
methods. The \module{copy} module does not use the
\refmodule[copyreg]{copy_reg} registration module.
In order for a class to define its own copy implementation, it can
define special methods \method{__copy__()} and
\method{__deepcopy__()}. The former is called to implement the
shallow copy operation; no additional arguments are passed. The
latter is called to implement the deep copy operation; it is passed
one argument, the memo dictionary. If the \method{__deepcopy__()}
implementation needs to make a deep copy of a component, it should
call the \function{deepcopy()} function with the component as first
argument and the memo dictionary as second argument.
\withsubitem{(copy protocol)}{\ttindex{__copy__()}\ttindex{__deepcopy__()}}
\begin{seealso}
\seemodule{pickle}{Discussion of the special methods used to
support object state retrieval and restoration.}
\end{seealso}