| \section{\module{copy} --- |
| Shallow and deep copy operations.} |
| \declaremodule{standard}{copy} |
| |
| \modulesynopsis{Shallow and deep copy operations.} |
| |
| \setindexsubitem{(copy function)} |
| \ttindex{copy} |
| \ttindex{deepcopy} |
| |
| This module provides generic (shallow and deep) copying operations. |
| |
| Interface summary: |
| |
| \begin{verbatim} |
| import copy |
| |
| x = copy.copy(y) # make a shallow copy of y |
| x = copy.deepcopy(y) # make a deep copy of y |
| \end{verbatim} |
| % |
| For module specific errors, \code{copy.error} is raised. |
| |
| The difference between shallow and deep copying is only relevant for |
| compound objects (objects that contain other objects, like lists or |
| class instances): |
| |
| \begin{itemize} |
| |
| \item |
| A \emph{shallow copy} constructs a new compound object and then (to the |
| extent possible) inserts \emph{references} into it to the objects found |
| in the original. |
| |
| \item |
| A \emph{deep copy} constructs a new compound object and then, |
| recursively, inserts \emph{copies} into it of the objects found in the |
| original. |
| |
| \end{itemize} |
| |
| Two problems often exist with deep copy operations that don't exist |
| with shallow copy operations: |
| |
| \begin{itemize} |
| |
| \item |
| Recursive objects (compound objects that, directly or indirectly, |
| contain a reference to themselves) may cause a recursive loop. |
| |
| \item |
| Because deep copy copies \emph{everything} it may copy too much, e.g.\ |
| administrative data structures that should be shared even between |
| copies. |
| |
| \end{itemize} |
| |
| Python's \code{deepcopy()} operation avoids these problems by: |
| |
| \begin{itemize} |
| |
| \item |
| keeping a ``memo'' dictionary of objects already copied during the current |
| copying pass; and |
| |
| \item |
| letting user-defined classes override the copying operation or the |
| set of components copied. |
| |
| \end{itemize} |
| |
| This version does not copy types like module, class, function, method, |
| nor stack trace, stack frame, nor file, socket, window, nor array, nor |
| any similar types. |
| |
| Classes can use the same interfaces to control copying that they use |
| to control pickling: they can define methods called |
| \code{__getinitargs__()}, \code{__getstate__()} and |
| \code{__setstate__()}. See the description of module \code{pickle} |
| for information on these methods. |
| The copy module does not use the \module{copy_reg} registration |
| module. |
| \refstmodindex{pickle} |
| \setindexsubitem{(copy protocol)} |
| \ttindex{__getinitargs__} |
| \ttindex{__getstate__} |
| \ttindex{__setstate__} |
| |
| In order for a class to define its own copy implementation, it can |
| define special methods \method{__copy__()}\ttindex{__copy__} and |
| \method{__deepcopy__()}\ttindex{__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 |
| \method{__deepcopy__()} implementation needs to make a deep copy of a |
| component, it should call the \function{deepcopy()} function with the |
| component as first argument and the memo dictionary as second |
| argument. |