Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcopy.tex @ 27998:e27f58a50737 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
SF bug #690377: Dud footnote reference in distutils docs
author Raymond Hettinger <python@rcn.com>
date Fri, 21 Feb 2003 02:47:09 +0000
parents 1879a48a3133
children 687b0c8254fa
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{copy} ---
10154
d37f03124c54 Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9549
diff changeset
2 Shallow and deep copy operations}
11077
6193cc145b8c Usage nit: a bunch of "nor"s should have been a single "or".
Fred Drake <fdrake@acm.org>
parents: 10154
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8602
diff changeset
4 \declaremodule{standard}{copy}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8602
diff changeset
5 \modulesynopsis{Shallow and deep copy operations.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8602
diff changeset
6
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 This module provides generic (shallow and deep) copying operations.
10154
d37f03124c54 Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9549
diff changeset
9 \withsubitem{(in copy)}{\ttindex{copy()}\ttindex{deepcopy()}}
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 Interface summary:
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
12
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
13 \begin{verbatim}
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 import copy
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
16 x = copy.copy(y) # make a shallow copy of y
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
17 x = copy.deepcopy(y) # make a deep copy of y
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
18 \end{verbatim}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
19 %
9549
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
20 For module specific errors, \exception{copy.error} is raised.
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 The difference between shallow and deep copying is only relevant for
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 compound objects (objects that contain other objects, like lists or
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 class instances):
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
25
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 \begin{itemize}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
27
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 \item
7096
5bb884527446 Consistency: "{\bf ...}" ==> "\strong{...}"
Fred Drake <fdrake@acm.org>
parents: 6862
diff changeset
29 A \emph{shallow copy} constructs a new compound object and then (to the
5bb884527446 Consistency: "{\bf ...}" ==> "\strong{...}"
Fred Drake <fdrake@acm.org>
parents: 6862
diff changeset
30 extent possible) inserts \emph{references} into it to the objects found
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 in the original.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
32
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 \item
7096
5bb884527446 Consistency: "{\bf ...}" ==> "\strong{...}"
Fred Drake <fdrake@acm.org>
parents: 6862
diff changeset
34 A \emph{deep copy} constructs a new compound object and then,
5bb884527446 Consistency: "{\bf ...}" ==> "\strong{...}"
Fred Drake <fdrake@acm.org>
parents: 6862
diff changeset
35 recursively, inserts \emph{copies} into it of the objects found in the
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 original.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
37
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 \end{itemize}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
39
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 Two problems often exist with deep copy operations that don't exist
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 with shallow copy operations:
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 \begin{itemize}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 \item
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 Recursive objects (compound objects that, directly or indirectly,
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 contain a reference to themselves) may cause a recursive loop.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
48
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 \item
9549
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
50 Because deep copy copies \emph{everything} it may copy too much,
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
51 e.g., administrative data structures that should be shared even
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
52 between copies.
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
53
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 \end{itemize}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
55
9549
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
56 The \function{deepcopy()} function avoids these problems by:
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
57
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 \begin{itemize}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
59
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 \item
8602
ce362b9ba836 Document __copy__() and __deepcopy__() methods.
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
61 keeping a ``memo'' dictionary of objects already copied during the current
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 copying pass; and
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
63
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \item
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 letting user-defined classes override the copying operation or the
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 set of components copied.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
67
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 \end{itemize}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
69
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 This version does not copy types like module, class, function, method,
11077
6193cc145b8c Usage nit: a bunch of "nor"s should have been a single "or".
Fred Drake <fdrake@acm.org>
parents: 10154
diff changeset
71 stack trace, stack frame, file, socket, window, array, or any similar
6193cc145b8c Usage nit: a bunch of "nor"s should have been a single "or".
Fred Drake <fdrake@acm.org>
parents: 10154
diff changeset
72 types.
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
73
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 Classes can use the same interfaces to control copying that they use
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 to control pickling: they can define methods called
9549
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
76 \method{__getinitargs__()}, \method{__getstate__()} and
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
77 \method{__setstate__()}. See the description of module
10154
d37f03124c54 Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9549
diff changeset
78 \refmodule{pickle}\refstmodindex{pickle} for information on these
11077
6193cc145b8c Usage nit: a bunch of "nor"s should have been a single "or".
Fred Drake <fdrake@acm.org>
parents: 10154
diff changeset
79 methods. The \module{copy} module does not use the
6193cc145b8c Usage nit: a bunch of "nor"s should have been a single "or".
Fred Drake <fdrake@acm.org>
parents: 10154
diff changeset
80 \refmodule[copyreg]{copy_reg} registration module.
10154
d37f03124c54 Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9549
diff changeset
81 \withsubitem{(copy protocol)}{\ttindex{__getinitargs__()}
d37f03124c54 Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9549
diff changeset
82 \ttindex{__getstate__()}\ttindex{__setstate__()}}
8602
ce362b9ba836 Document __copy__() and __deepcopy__() methods.
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
83
ce362b9ba836 Document __copy__() and __deepcopy__() methods.
Guido van Rossum <guido@python.org>
parents: 7877
diff changeset
84 In order for a class to define its own copy implementation, it can
9549
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
85 define special methods \method{__copy__()} and
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
86 \method{__deepcopy__()}. The former is called to implement the
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
87 shallow copy operation; no additional arguments are passed. The
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
88 latter is called to implement the deep copy operation; it is passed
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
89 one argument, the memo dictionary. If the \method{__deepcopy__()}
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
90 implementation needs to make a deep copy of a component, it should
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
91 call the \function{deepcopy()} function with the component as first
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
92 argument and the memo dictionary as second argument.
10154
d37f03124c54 Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9549
diff changeset
93 \withsubitem{(copy protocol)}{\ttindex{__copy__()}\ttindex{__deepcopy__()}}
9549
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
94
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
95 \begin{seealso}
15066
1879a48a3133 Fix really bad typo, noted by Neil Schemenauer <nas@arctrix.com>.
Fred Drake <fdrake@acm.org>
parents: 15061
diff changeset
96 \seemodule{pickle}{Discussion of the special methods used to
9549
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
97 support object state retrieval and restoration.}
485c0bdfe8a0 Markup improvements to help with conversions.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
98 \end{seealso}