mirror of
https://github.com/python/cpython.git
synced 2024-12-01 03:01:36 +01:00
96 lines
2.8 KiB
TeX
96 lines
2.8 KiB
TeX
\section{Standard Module \module{copy}}
|
|
\label{module-copy}
|
|
\stmodindex{copy}
|
|
\setindexsubitem{(copy function)}
|
|
\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 \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}
|
|
|
|
Python's \code{deepcopy()} operation 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
|
|
\code{__getinitargs__()}, \code{__getstate__()} and
|
|
\code{__setstate__()}. See the description of module \code{pickle}
|
|
for information on these methods.
|
|
The copy module does not use the \module{copy_reg} registration
|
|
module.
|
|
\refstmodindex{pickle}
|
|
\setindexsubitem{(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__()}\ttindex{__copy__} and
|
|
\method{__deepcopy__()}\ttindex{__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.
|