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