\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}