blob: 02ef0e5ee7d35bd36885575d9e5d7a6833e097a0 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`copy` --- Shallow and deep copy operations
2================================================
3
4.. module:: copy
5 :synopsis: Shallow and deep copy operations.
6
Senthil Kumaran5b14d732012-02-09 18:26:59 +08007Assignment statements in Python do not copy objects, they create bindings
8between a target and an object. For collections that are mutable or contain
9mutable items, a copy is sometimes needed so one can change one copy without
10changing the other. This module provides generic shallow and deep copy
11operations (explained below).
Georg Brandl116aa622007-08-15 14:28:22 +000012
Georg Brandl116aa622007-08-15 14:28:22 +000013
Georg Brandla59750f2009-09-09 16:51:05 +000014Interface summary:
Georg Brandl116aa622007-08-15 14:28:22 +000015
Georg Brandla59750f2009-09-09 16:51:05 +000016.. function:: copy(x)
Georg Brandl116aa622007-08-15 14:28:22 +000017
Georg Brandla59750f2009-09-09 16:51:05 +000018 Return a shallow copy of *x*.
19
20
21.. function:: deepcopy(x)
22
23 Return a deep copy of *x*.
24
25
26.. exception:: error
27
28 Raised for module specific errors.
29
Georg Brandl116aa622007-08-15 14:28:22 +000030
Georg Brandl116aa622007-08-15 14:28:22 +000031The difference between shallow and deep copying is only relevant for compound
32objects (objects that contain other objects, like lists or class instances):
33
34* A *shallow copy* constructs a new compound object and then (to the extent
35 possible) inserts *references* into it to the objects found in the original.
36
37* A *deep copy* constructs a new compound object and then, recursively, inserts
38 *copies* into it of the objects found in the original.
39
40Two problems often exist with deep copy operations that don't exist with shallow
41copy operations:
42
43* Recursive objects (compound objects that, directly or indirectly, contain a
44 reference to themselves) may cause a recursive loop.
45
46* Because deep copy copies *everything* it may copy too much, e.g.,
47 administrative data structures that should be shared even between copies.
48
49The :func:`deepcopy` function avoids these problems by:
50
51* keeping a "memo" dictionary of objects already copied during the current
52 copying pass; and
53
54* letting user-defined classes override the copying operation or the set of
55 components copied.
56
57This module does not copy types like module, method, stack trace, stack frame,
58file, socket, window, array, or any similar types. It does "copy" functions and
59classes (shallow and deeply), by returning the original object unchanged; this
60is compatible with the way these are treated by the :mod:`pickle` module.
61
Thomas Wouters89d996e2007-09-08 17:39:28 +000062Shallow copies of dictionaries can be made using :meth:`dict.copy`, and
63of lists by assigning a slice of the entire list, for example,
64``copied_list = original_list[:]``.
65
Georg Brandl116aa622007-08-15 14:28:22 +000066.. index:: module: pickle
67
68Classes can use the same interfaces to control copying that they use to control
69pickling. See the description of module :mod:`pickle` for information on these
Martin Panter2e4571a2015-11-14 01:07:43 +000070methods. In fact, the :mod:`copy` module uses the registered
71pickle functions from the :mod:`copyreg` module.
Georg Brandl116aa622007-08-15 14:28:22 +000072
73.. index::
74 single: __copy__() (copy protocol)
75 single: __deepcopy__() (copy protocol)
76
77In order for a class to define its own copy implementation, it can define
78special methods :meth:`__copy__` and :meth:`__deepcopy__`. The former is called
79to implement the shallow copy operation; no additional arguments are passed.
80The latter is called to implement the deep copy operation; it is passed one
81argument, the memo dictionary. If the :meth:`__deepcopy__` implementation needs
82to make a deep copy of a component, it should call the :func:`deepcopy` function
83with the component as first argument and the memo dictionary as second argument.
84
85
86.. seealso::
87
88 Module :mod:`pickle`
89 Discussion of the special methods used to support object state retrieval and
90 restoration.
91