Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{copy}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-copy} |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 3 | \stmodindex{copy} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 4 | \renewcommand{\indexsubitem}{(copy function)} |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 5 | \ttindex{copy} |
| 6 | \ttindex{deepcopy} |
| 7 | |
| 8 | This module provides generic (shallow and deep) copying operations. |
| 9 | |
| 10 | Interface summary: |
| 11 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 12 | \bcode\begin{verbatim} |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 13 | import copy |
| 14 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 15 | x = copy.copy(y) # make a shallow copy of y |
| 16 | x = copy.deepcopy(y) # make a deep copy of y |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 17 | \end{verbatim}\ecode |
| 18 | % |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 19 | For module specific errors, \code{copy.error} is raised. |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 20 | |
| 21 | The difference between shallow and deep copying is only relevant for |
| 22 | compound objects (objects that contain other objects, like lists or |
| 23 | class instances): |
| 24 | |
| 25 | \begin{itemize} |
| 26 | |
| 27 | \item |
| 28 | A {\em shallow copy} constructs a new compound object and then (to the |
| 29 | extent possible) inserts {\em references} into it to the objects found |
| 30 | in the original. |
| 31 | |
| 32 | \item |
| 33 | A {\em deep copy} constructs a new compound object and then, |
| 34 | recursively, inserts {\em copies} into it of the objects found in the |
| 35 | original. |
| 36 | |
| 37 | \end{itemize} |
| 38 | |
| 39 | Two problems often exist with deep copy operations that don't exist |
| 40 | with shallow copy operations: |
| 41 | |
| 42 | \begin{itemize} |
| 43 | |
| 44 | \item |
| 45 | Recursive objects (compound objects that, directly or indirectly, |
| 46 | contain a reference to themselves) may cause a recursive loop. |
| 47 | |
| 48 | \item |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 49 | Because deep copy copies {\em everything} it may copy too much, e.g.\ |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 50 | administrative data structures that should be shared even between |
| 51 | copies. |
| 52 | |
| 53 | \end{itemize} |
| 54 | |
| 55 | Python's \code{deepcopy()} operation avoids these problems by: |
| 56 | |
| 57 | \begin{itemize} |
| 58 | |
| 59 | \item |
| 60 | keeping a table of objects already copied during the current |
| 61 | copying pass; and |
| 62 | |
| 63 | \item |
| 64 | letting user-defined classes override the copying operation or the |
| 65 | set of components copied. |
| 66 | |
| 67 | \end{itemize} |
| 68 | |
| 69 | This version does not copy types like module, class, function, method, |
| 70 | nor stack trace, stack frame, nor file, socket, window, nor array, nor |
| 71 | any similar types. |
| 72 | |
| 73 | Classes can use the same interfaces to control copying that they use |
| 74 | to control pickling: they can define methods called |
| 75 | \code{__getinitargs__()}, \code{__getstate__()} and |
| 76 | \code{__setstate__()}. See the description of module \code{pickle} |
| 77 | for information on these methods. |
| 78 | \stmodindex{pickle} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 79 | \renewcommand{\indexsubitem}{(copy protocol)} |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 80 | \ttindex{__getinitargs__} |
| 81 | \ttindex{__getstate__} |
| 82 | \ttindex{__setstate__} |