blob: 4e43585d65c9f7da4ff9fdd26575cd54c5fda762 [file] [log] [blame]
Fred Drake3a0351c1998-04-04 07:23:21 +00001\section{Standard Module \module{copy}}
Guido van Rossume47da0a1997-07-17 16:34:52 +00002\label{module-copy}
Guido van Rossumd1883581995-02-15 15:53:08 +00003\stmodindex{copy}
Fred Drake19479911998-02-13 06:58:54 +00004\setindexsubitem{(copy function)}
Guido van Rossumd1883581995-02-15 15:53:08 +00005\ttindex{copy}
6\ttindex{deepcopy}
7
8This module provides generic (shallow and deep) copying operations.
9
10Interface summary:
11
Fred Drake19479911998-02-13 06:58:54 +000012\begin{verbatim}
Guido van Rossumd1883581995-02-15 15:53:08 +000013import copy
14
Guido van Rossum6bb1adc1995-03-13 10:03:32 +000015x = copy.copy(y) # make a shallow copy of y
16x = copy.deepcopy(y) # make a deep copy of y
Fred Drake19479911998-02-13 06:58:54 +000017\end{verbatim}
Guido van Rossume47da0a1997-07-17 16:34:52 +000018%
Guido van Rossum470be141995-03-17 16:07:09 +000019For module specific errors, \code{copy.error} is raised.
Guido van Rossumd1883581995-02-15 15:53:08 +000020
21The difference between shallow and deep copying is only relevant for
22compound objects (objects that contain other objects, like lists or
23class instances):
24
25\begin{itemize}
26
27\item
Fred Drakeaf8a0151998-01-14 14:51:31 +000028A \emph{shallow copy} constructs a new compound object and then (to the
29extent possible) inserts \emph{references} into it to the objects found
Guido van Rossumd1883581995-02-15 15:53:08 +000030in the original.
31
32\item
Fred Drakeaf8a0151998-01-14 14:51:31 +000033A \emph{deep copy} constructs a new compound object and then,
34recursively, inserts \emph{copies} into it of the objects found in the
Guido van Rossumd1883581995-02-15 15:53:08 +000035original.
36
37\end{itemize}
38
39Two problems often exist with deep copy operations that don't exist
40with shallow copy operations:
41
42\begin{itemize}
43
44\item
45Recursive objects (compound objects that, directly or indirectly,
46contain a reference to themselves) may cause a recursive loop.
47
48\item
Fred Drakeaf8a0151998-01-14 14:51:31 +000049Because deep copy copies \emph{everything} it may copy too much, e.g.\
Guido van Rossumd1883581995-02-15 15:53:08 +000050administrative data structures that should be shared even between
51copies.
52
53\end{itemize}
54
55Python's \code{deepcopy()} operation avoids these problems by:
56
57\begin{itemize}
58
59\item
60keeping a table of objects already copied during the current
61copying pass; and
62
63\item
64letting user-defined classes override the copying operation or the
65set of components copied.
66
67\end{itemize}
68
69This version does not copy types like module, class, function, method,
70nor stack trace, stack frame, nor file, socket, window, nor array, nor
71any similar types.
72
73Classes can use the same interfaces to control copying that they use
74to control pickling: they can define methods called
75\code{__getinitargs__()}, \code{__getstate__()} and
76\code{__setstate__()}. See the description of module \code{pickle}
77for information on these methods.
Fred Drake54820dc1997-12-15 21:56:05 +000078\refstmodindex{pickle}
Fred Drake19479911998-02-13 06:58:54 +000079\setindexsubitem{(copy protocol)}
Guido van Rossumd1883581995-02-15 15:53:08 +000080\ttindex{__getinitargs__}
81\ttindex{__getstate__}
82\ttindex{__setstate__}