classification
Title: no copy.copy problem description
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, giampaolo.rodola, orsenthil, python-dev, techtonik, terry.reedy
Priority: normal Keywords:

Created on 2010-06-17 23:18 by techtonik, last changed 2012-02-09 10:38 by techtonik. This issue is now closed.

Messages (10)
msg108069 - (view) Author: anatoly techtonik (techtonik) Date: 2010-06-17 23:18
`copy` module covers very important aspect of Python programming. However its documentation doesn't provide any intro or overview of this problem starting right from details. When people meet `copy` construction in the code - the refer to module documentation and its doesn't completely answer two basic questions they have:

1. why copy module is needed (i.e. what's the problem with var assignment)
2. when and where it should be used
msg108299 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-06-21 19:13
The intro paragraph currently (3.2a) consists of
"This module provides generic (shallow and deep) copying operations."

This could be expanded to '''
Assignment statements create bindings between a target and an object. They never duplicate or copy an existing 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. Sequences can be shallow copied by slicing the entire sequence(s[:]). (See below for the meaning of 'shallow'.) Some objects can be shallow copied with their class constructors (tuple, list, set, dict). This module provides generic shallow *and* deep copying operations. The latter is not otherwise available in an single operation or call.'''
msg108300 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-06-21 19:21
Shorter and better version.

Assignment statements create bindings between a target and an object. They never duplicate or copy an existing 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). Shallow copies can also be obtained by whole sequence slicing (s[:]) and some class constructors (tuple, list, set, dict).
msg108355 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2010-06-22 10:16
I am +0 on this change. The existing introduction is fine and the
discussion where shallow and deep copy is discussed is more important.

It is okay to assume that the reader is aware of the assignment
operation nature, i.e. it does not create a copy and you need this
module.  

The doc change suggested by Terry could be helpful in the tutorial
where a copy module is mentioned.
msg108413 - (view) Author: anatoly techtonik (techtonik) Date: 2010-06-22 19:58
> The doc change suggested by Terry could be helpful in the tutorial
> where a copy module is mentioned.

Can you post a link to this tutorial here?
msg108433 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2010-06-23 03:13
> Can you post a link to this tutorial here?

Section 9.1 and 9.2 of the docs.python.org/tutorial
It may not be as explicit as you might want it to be, but it does sets
up background that assignments do not copy the object.
msg152938 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-02-09 10:23
New changeset 0e050b38e92b by Senthil Kumaran in branch '2.7':
Issue #9021: Add an introduction to the copy module. Doc changes suggested by Terry Reedy.
http://hg.python.org/cpython/rev/0e050b38e92b
msg152939 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-02-09 10:28
New changeset a352e24b9907 by Senthil Kumaran in branch '3.2':
Issue #9021 - Introduce copy module better. Doc changes suggested by Terry
http://hg.python.org/cpython/rev/a352e24b9907

New changeset bf6f306ad5cf by Senthil Kumaran in branch 'default':
merge from 3.2
http://hg.python.org/cpython/rev/bf6f306ad5cf
msg152940 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2012-02-09 10:29
Added suggested changes to the documentation. Thanks.
msg152941 - (view) Author: anatoly techtonik (techtonik) Date: 2012-02-09 10:38
Perfectionist in me says that now copy.copy theory should be diluted with examples for those who can't grasp the concept of "binding of variables", but the patch perfectly covers the original user story. Thanks.
History
Date User Action Args
2012-02-09 10:38:51techtoniksetmessages: + msg152941
2012-02-09 10:29:15orsenthilsetstatus: open -> closed
type: behavior
messages: + msg152940

resolution: fixed
stage: resolved
2012-02-09 10:28:07python-devsetmessages: + msg152939
2012-02-09 10:23:00python-devsetnosy: + python-dev
messages: + msg152938
2010-06-23 03:13:17orsenthilsetmessages: + msg108433
2010-06-22 19:58:09techtoniksetmessages: + msg108413
2010-06-22 10:16:28orsenthilsetnosy: + orsenthil
messages: + msg108355
2010-06-21 19:21:47terry.reedysetmessages: + msg108300
2010-06-21 19:13:51terry.reedysetnosy: + terry.reedy

messages: + msg108299
versions: + Python 3.1
2010-06-17 23:57:08giampaolo.rodolasetnosy: + giampaolo.rodola
2010-06-17 23:18:31techtonikcreate