| 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 |
|
| 11 |
Assignment statements in Python do not copy objects, they create bindings |
| 12 |
between a target and an object. For collections that are mutable or contain |
| 13 |
mutable items, a copy is sometimes needed so one can change one copy without |
| 14 |
changing the other. This module provides generic shallow and deep copy |
| 15 |
operations (explained below). |
| 16 |
|
| 17 |
|
| 18 |
Interface summary: |
| 19 |
|
| 20 |
.. function:: copy(obj) |
| 21 |
|
| 22 |
Return a shallow copy of *obj*. |
| 23 |
|
| 24 |
|
| 25 |
.. function:: deepcopy(obj[, memo]) |
| 26 |
|
| 27 |
Return a deep copy of *obj*. |
| 28 |
|
| 29 |
|
| 30 |
.. function:: replace(obj, /, **changes) |
| 31 |
|
| 32 |
Creates a new object of the same type as *obj*, replacing fields with values |
| 33 |
from *changes*. |
| 34 |
|
| 35 |
.. versionadded:: 3.13 |
| 36 |
|
| 37 |
|
| 38 |
.. exception:: Error |
| 39 |
|
| 40 |
Raised for module specific errors. |
| 41 |
|
| 42 |
.. _shallow_vs_deep_copy: |
| 43 |
|
| 44 |
The difference between shallow and deep copying is only relevant for compound |
| 45 |
objects (objects that contain other objects, like lists or class instances): |
| 46 |
|
| 47 |
* A *shallow copy* constructs a new compound object and then (to the extent |
| 48 |
possible) inserts *references* into it to the objects found in the original. |
| 49 |
|
| 50 |
* A *deep copy* constructs a new compound object and then, recursively, inserts |
| 51 |
*copies* into it of the objects found in the original. |
| 52 |
|
| 53 |
Two problems often exist with deep copy operations that don't exist with shallow |
| 54 |
copy operations: |
| 55 |
|
| 56 |
* Recursive objects (compound objects that, directly or indirectly, contain a |
| 57 |
reference to themselves) may cause a recursive loop. |
| 58 |
|
| 59 |
* Because deep copy copies everything it may copy too much, such as data |
| 60 |
which is intended to be shared between copies. |
| 61 |
|
| 62 |
The :func:`deepcopy` function avoids these problems by: |
| 63 |
|
| 64 |
* keeping a ``memo`` dictionary of objects already copied during the current |
| 65 |
copying pass; and |
| 66 |
|
| 67 |
* letting user-defined classes override the copying operation or the set of |
| 68 |
components copied. |
| 69 |
|
| 70 |
This module does not copy types like module, method, stack trace, stack frame, |
| 71 |
file, socket, window, or any similar types. It does "copy" functions and |
| 72 |
classes (shallow and deeply), by returning the original object unchanged; this |
| 73 |
is compatible with the way these are treated by the :mod:`pickle` module. |
| 74 |
|
| 75 |
Shallow copies of many collections can be made using the corresponding |
| 76 |
:meth:`!copy` method (such as :meth:`list.copy`, :meth:`dict.copy` or |
| 77 |
:meth:`set.copy`), and of sequences (such as lists or bytearrays) by making |
| 78 |
a slice of the entire sequence (``sequence[:]``). |
| 79 |
However, these methods and slicing can create an instance of the base type |
| 80 |
when copying an instance of a subclass, whereas :func:`copy.copy` normally |
| 81 |
returns an instance of the same type. |
| 82 |
|
| 83 |
.. index:: pair: module; pickle |
| 84 |
|
| 85 |
Classes can use the same interfaces to control copying that they use to control |
| 86 |
pickling. See the description of module :mod:`pickle` for information on these |
| 87 |
methods. In fact, the :mod:`!copy` module uses the registered |
| 88 |
pickle functions from the :mod:`copyreg` module. |
| 89 |
|
| 90 |
.. index:: |
| 91 |
single: __copy__() (copy protocol) |
| 92 |
single: __deepcopy__() (copy protocol) |
| 93 |
|
| 94 |
.. currentmodule:: None |
| 95 |
|
| 96 |
In order for a class to define its own copy implementation, it can define |
| 97 |
special methods :meth:`~object.__copy__` and :meth:`~object.__deepcopy__`. |
| 98 |
|
| 99 |
.. method:: object.__copy__(self) |
| 100 |
:noindexentry: |
| 101 |
|
| 102 |
Called to implement the shallow copy operation; |
| 103 |
no additional arguments are passed. |
| 104 |
|
| 105 |
.. method:: object.__deepcopy__(self, memo) |
| 106 |
:noindexentry: |
| 107 |
|
| 108 |
Called to implement the deep copy operation; it is passed one |
| 109 |
argument, the *memo* dictionary. If the ``__deepcopy__`` implementation needs |
| 110 |
to make a deep copy of a component, it should call the :func:`~copy.deepcopy` function |
| 111 |
with the component as first argument and the *memo* dictionary as second argument. |
| 112 |
The *memo* dictionary should be treated as an opaque object. |
| 113 |
|
| 114 |
|
| 115 |
.. index:: |
| 116 |
single: __replace__() (replace protocol) |
| 117 |
|
| 118 |
Function :func:`!copy.replace` is more limited |
| 119 |
than :func:`~copy.copy` and :func:`~copy.deepcopy`, |
| 120 |
and only supports named tuples created by :func:`~collections.namedtuple`, |
| 121 |
:mod:`dataclasses`, and other classes which define method :meth:`~object.__replace__`. |
| 122 |
|
| 123 |
.. method:: object.__replace__(self, /, **changes) |
| 124 |
:noindexentry: |
| 125 |
|
| 126 |
This method should create a new object of the same type, |
| 127 |
replacing fields with values from *changes*. |
| 128 |
|
| 129 |
.. versionadded:: 3.13 |
| 130 |
|
| 131 |
|
| 132 |
.. seealso:: |
| 133 |
|
| 134 |
Module :mod:`pickle` |
| 135 |
Discussion of the special methods used to support object state retrieval and |
| 136 |
restoration. |
| 137 |
|