mirror of
https://github.com/python/cpython.git
synced 2025-10-31 05:31:20 +00:00
0200928e8d
* Include memo in the documented signature of copy.deepcopy() The memo argument is mentioned lower on the doc page under writing a `__deepcopy__` method, but is not included in the documented function signature. This makes it easy to miss, and can lead to incorrect/buggy implementations of `__deepcopy__` -- which is exatly what just happpend to me!
95 lines
3.3 KiB
ReStructuredText
95 lines
3.3 KiB
ReStructuredText
:mod:`copy` --- Shallow and deep copy operations
|
|
================================================
|
|
|
|
.. module:: copy
|
|
:synopsis: Shallow and deep copy operations.
|
|
|
|
**Source code:** :source:`Lib/copy.py`
|
|
|
|
--------------
|
|
|
|
Assignment statements in Python do not copy objects, they create bindings
|
|
between a target and an object. For collections that are mutable or contain
|
|
mutable items, a copy is sometimes needed so one can change one copy without
|
|
changing the other. This module provides generic shallow and deep copy
|
|
operations (explained below).
|
|
|
|
|
|
Interface summary:
|
|
|
|
.. function:: copy(x)
|
|
|
|
Return a shallow copy of *x*.
|
|
|
|
|
|
.. function:: deepcopy(x[, memo])
|
|
|
|
Return a deep copy of *x*.
|
|
|
|
|
|
.. exception:: error
|
|
|
|
Raised for module specific errors.
|
|
|
|
|
|
The difference between shallow and deep copying is only relevant for compound
|
|
objects (objects that contain other objects, like lists or class instances):
|
|
|
|
* A *shallow copy* constructs a new compound object and then (to the extent
|
|
possible) inserts *references* into it to the objects found in the original.
|
|
|
|
* A *deep copy* constructs a new compound object and then, recursively, inserts
|
|
*copies* into it of the objects found in the original.
|
|
|
|
Two problems often exist with deep copy operations that don't exist with shallow
|
|
copy operations:
|
|
|
|
* Recursive objects (compound objects that, directly or indirectly, contain a
|
|
reference to themselves) may cause a recursive loop.
|
|
|
|
* Because deep copy copies everything it may copy too much, such as data
|
|
which is intended to be shared between copies.
|
|
|
|
The :func:`deepcopy` function avoids these problems by:
|
|
|
|
* keeping a ``memo`` dictionary of objects already copied during the current
|
|
copying pass; and
|
|
|
|
* letting user-defined classes override the copying operation or the set of
|
|
components copied.
|
|
|
|
This module does not copy types like module, method, stack trace, stack frame,
|
|
file, socket, window, array, or any similar types. It does "copy" functions and
|
|
classes (shallow and deeply), by returning the original object unchanged; this
|
|
is compatible with the way these are treated by the :mod:`pickle` module.
|
|
|
|
Shallow copies of dictionaries can be made using :meth:`dict.copy`, and
|
|
of lists by assigning a slice of the entire list, for example,
|
|
``copied_list = original_list[:]``.
|
|
|
|
.. index:: module: pickle
|
|
|
|
Classes can use the same interfaces to control copying that they use to control
|
|
pickling. See the description of module :mod:`pickle` for information on these
|
|
methods. In fact, the :mod:`copy` module uses the registered
|
|
pickle functions from the :mod:`copyreg` module.
|
|
|
|
.. index::
|
|
single: __copy__() (copy protocol)
|
|
single: __deepcopy__() (copy protocol)
|
|
|
|
In order for a class to define its own copy implementation, it can define
|
|
special methods :meth:`__copy__` and :meth:`__deepcopy__`. The former is called
|
|
to implement the shallow copy operation; no additional arguments are passed.
|
|
The latter is called to implement the deep copy operation; it is passed one
|
|
argument, the ``memo`` dictionary. If the :meth:`__deepcopy__` implementation needs
|
|
to make a deep copy of a component, it should call the :func:`deepcopy` function
|
|
with the component as first argument and the memo dictionary as second argument.
|
|
|
|
|
|
.. seealso::
|
|
|
|
Module :mod:`pickle`
|
|
Discussion of the special methods used to support object state retrieval and
|
|
restoration.
|
|
|