Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`copy` --- Shallow and deep copy operations |
| 2 | ================================================ |
| 3 | |
| 4 | .. module:: copy |
| 5 | :synopsis: Shallow and deep copy operations. |
| 6 | |
Senthil Kumaran | 5b14d73 | 2012-02-09 18:26:59 +0800 | [diff] [blame] | 7 | Assignment statements in Python do not copy objects, they create bindings |
| 8 | between a target and an object. For collections that are mutable or contain |
| 9 | mutable items, a copy is sometimes needed so one can change one copy without |
| 10 | changing the other. This module provides generic shallow and deep copy |
| 11 | operations (explained below). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
Georg Brandl | a59750f | 2009-09-09 16:51:05 +0000 | [diff] [blame] | 14 | Interface summary: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 15 | |
Georg Brandl | a59750f | 2009-09-09 16:51:05 +0000 | [diff] [blame] | 16 | .. function:: copy(x) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | |
Georg Brandl | a59750f | 2009-09-09 16:51:05 +0000 | [diff] [blame] | 18 | 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 Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | The difference between shallow and deep copying is only relevant for compound |
| 32 | objects (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 | |
| 40 | Two problems often exist with deep copy operations that don't exist with shallow |
| 41 | copy 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 | |
| 49 | The :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 | |
| 57 | This module does not copy types like module, method, stack trace, stack frame, |
| 58 | file, socket, window, array, or any similar types. It does "copy" functions and |
| 59 | classes (shallow and deeply), by returning the original object unchanged; this |
| 60 | is compatible with the way these are treated by the :mod:`pickle` module. |
| 61 | |
Thomas Wouters | 89d996e | 2007-09-08 17:39:28 +0000 | [diff] [blame] | 62 | Shallow copies of dictionaries can be made using :meth:`dict.copy`, and |
| 63 | of lists by assigning a slice of the entire list, for example, |
| 64 | ``copied_list = original_list[:]``. |
| 65 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 66 | .. index:: module: pickle |
| 67 | |
| 68 | Classes can use the same interfaces to control copying that they use to control |
| 69 | pickling. See the description of module :mod:`pickle` for information on these |
Ezio Melotti | 78b18d4 | 2012-11-08 11:04:57 +0200 | [diff] [blame] | 70 | methods. In fact, :mod:`copy` module uses the registered pickle functions from |
| 71 | :mod:`copyreg` module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
| 73 | .. index:: |
| 74 | single: __copy__() (copy protocol) |
| 75 | single: __deepcopy__() (copy protocol) |
| 76 | |
| 77 | In order for a class to define its own copy implementation, it can define |
| 78 | special methods :meth:`__copy__` and :meth:`__deepcopy__`. The former is called |
| 79 | to implement the shallow copy operation; no additional arguments are passed. |
| 80 | The latter is called to implement the deep copy operation; it is passed one |
| 81 | argument, the memo dictionary. If the :meth:`__deepcopy__` implementation needs |
| 82 | to make a deep copy of a component, it should call the :func:`deepcopy` function |
| 83 | with 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 | |