mirror of
https://github.com/python/cpython.git
synced 2024-12-01 03:01:36 +01:00
99 lines
3.1 KiB
TeX
99 lines
3.1 KiB
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 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
|
|
\method{__getinitargs__()}, \method{__getstate__()} and
|
|
\method{__setstate__()}. See the description of module
|
|
\refmodule{pickle}\refstmodindex{pickle} for information on these
|
|
methods. The \module{copy} module does not use the \module{copy_reg}
|
|
registration module.
|
|
\withsubitem{(copy protocol)}{\ttindex{__getinitargs__()}
|
|
\ttindex{__getstate__()}\ttindex{__setstate__()}}
|
|
|
|
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 disciplines used to
|
|
support object state retrieval and restoration.}
|
|
\end{seealso}
|