"copy" --- Shallow and deep copy operations
*******************************************

**Código-fonte:** Lib/copy.py

======================================================================

As instruções de atribuição no Python não copiam objetos, elas criam
ligações entre um destino e um objeto. Para coleções que são mutáveis
​​ou contêm itens mutáveis, às vezes é necessária uma cópia para que
seja possível alterar uma cópia sem alterar a outra. Este módulo
fornece operações genéricas de cópia profunda e rasa (explicadas
abaixo).

Resumo da interface:

copy.copy(obj)

   Return a shallow copy of *obj*.

copy.deepcopy(obj[, memo])

   Return a deep copy of *obj*.

copy.replace(obj, /, **changes)

   Creates a new object of the same type as *obj*, replacing fields
   with values from *changes*.

   Adicionado na versão 3.13.

exception copy.Error

   Levantada para erros específicos do módulo.

A diferença entre cópia profunda e rasa é relevante apenas para
objetos compostos (objetos que contêm outros objetos, como listas ou
instâncias de classe):

* Uma *cópia rasa* constrói um novo objeto composto e então (na medida
  do possível) insere nele *referências* aos objetos encontrados no
  original.

* Uma *cópia profunda* constrói um novo objeto composto e então,
  recursivamente, insere nele *cópias* dos objetos encontrados no
  original.

Frequentemente, existem dois problemas com operações de cópia profunda
que não existem com operações de cópia rasa:

* Objetos recursivos (objetos compostos que, direta ou indiretamente,
  contêm uma referência a si mesmos) podem causar um laço recursivo.

* Como a cópia profunda copia tudo, ela pode copiar muito, como dados
  que devem ser compartilhados entre as cópias.

A função "deepcopy()" evita esses problemas:

* mantendo um dicionário "memo" de objetos já copiados durante a
  passagem de cópia atual; e

* permitindo que as classes definidas pelo usuário substituam a
  operação de cópia ou o conjunto de componentes copiados.

Este módulo não copia tipos como módulo, método, stack trace (situação
da pilha de execução), quadro de empilhamento, arquivo, soquete,
janela ou outros tipos semelhantes. Ele "copia" funções e classes
(rasas e profundamente), devolvendo o objeto original inalterado; isso
é compatível com a maneira que estes itens são tratados pelo módulo
"pickle".

Cópias rasas de dicionários podem ser feitas usando "dict.copy()", e
de listas atribuindo uma fatia de toda a lista, por exemplo,
"lista_copiada = lista_original[:]".

As classes podem usar as mesmas interfaces para controlar a cópia que
usam para controlar o *pickling*. Veja a descrição do módulo "pickle"
para informações sobre esses métodos. Na verdade, o módulo "copy" usa
as funções pickle registradas do módulo "copyreg".

In order for a class to define its own copy implementation, it can
define special methods "__copy__()" and "__deepcopy__()".

object.__copy__(self)

   Called to implement the shallow copy operation; no additional
   arguments are passed.

object.__deepcopy__(self, memo)

   Called to implement the deep copy operation; it is passed one
   argument, the *memo* dictionary.  If the "__deepcopy__"
   implementation needs to make a deep copy of a component, it should
   call the "deepcopy()" function with the component as first argument
   and the *memo* dictionary as second argument. The *memo* dictionary
   should be treated as an opaque object.

Function "copy.replace()" is more limited than "copy()" and
"deepcopy()", and only supports named tuples created by
"namedtuple()", "dataclasses", and other classes which define method
"__replace__()".

object.__replace__(self, /, **changes)

   This method should create a new object of the same type, replacing
   fields with values from *changes*.

Ver também:

  Módulo "pickle"
     Discussão dos métodos especiais usados ​​para dar suporte à
     recuperação e restauração do estado do objeto.
