cpython/Doc/lib/libcopy.tex

95 lines
2.9 KiB
TeX
Raw Normal View History

\section{\module{copy} ---
1999-02-12 16:40:49 -04:00
Shallow and deep copy operations}
\declaremodule{standard}{copy}
\modulesynopsis{Shallow and deep copy operations.}
1995-02-15 11:53:08 -04:00
This module provides generic (shallow and deep) copying operations.
1999-02-12 16:40:49 -04:00
\withsubitem{(in copy)}{\ttindex{copy()}\ttindex{deepcopy()}}
1995-02-15 11:53:08 -04:00
Interface summary:
\begin{verbatim}
1995-02-15 11:53:08 -04:00
import copy
1995-03-13 06:03:32 -04:00
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.
1995-02-15 11:53:08 -04:00
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
1995-02-15 11:53:08 -04:00
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
1995-02-15 11:53:08 -04:00
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.
1995-02-15 11:53:08 -04:00
\end{itemize}
The \function{deepcopy()} function avoids these problems by:
1995-02-15 11:53:08 -04:00
\begin{itemize}
\item
keeping a ``memo'' dictionary of objects already copied during the current
1995-02-15 11:53:08 -04:00
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,
stack trace, stack frame, file, socket, window, array, or any similar
types.
1995-02-15 11:53:08 -04:00
Classes can use the same interfaces to control copying that they use
to control pickling. See the description of module
1999-02-12 16:40:49 -04:00
\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.
1999-02-12 16:40:49 -04:00
\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}