classification
Title: Incorrect documentation for the copy module
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ncoghlan Nosy List: Mariatta, docs@python, marco.buttu, ncoghlan, pgacv2, r.david.murray, serhiy.storchaka, steven.daprano, zach.ware
Priority: normal Keywords:

Created on 2017-02-08 22:02 by pgacv2, last changed 2017-04-09 10:58 by ncoghlan. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 151 merged CuriousLearner, 2017-02-18 09:37
PR 1061 merged ncoghlan, 2017-04-09 10:25
PR 1062 merged ncoghlan, 2017-04-09 10:25
PR 1063 merged ncoghlan, 2017-04-09 10:33
Messages (16)
msg287367 - (view) Author: Pedro (pgacv2) Date: 2017-02-08 22:02
The docs for the copy module contain a bullet that says the following:

"Because deep copy copies everything it may copy too much, e.g., even administrative data structures that should be shared even between copies."

There should be a "not" between "should" and "be shared." I think the second "even" can be dropped, too.
msg287368 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2017-02-08 22:14
That line is correct, the point is that deep copy will duplicate even the things that you may *want* to be shared.

See also #27416.  I'm not sure what we can do to further clarify that line, but it is certainly easy to misread.
msg287369 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2017-02-08 22:21
How about

```
Because deep copy copies everything, it may copy too much, including the administrative data structures.
```

?
msg287375 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2017-02-09 01:16
What about "administrative data structures" that should be copied?

I think that "administrative data structures" is a red herring: there could be data that needs copying, and data that needs sharing and shouldn't be copied, independent of what the data is used for.

"Because deepcopy copies everything it may copy too much, such as data which is intended to be shared between copies."
msg287398 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-02-09 10:27
+1 for the Steven's suggestion
msg287414 - (view) Author: Pedro (pgacv2) Date: 2017-02-09 12:50
"Because deepcopy copies everything it may copy too much, such as data which is intended to be shared (instead of duplicated) between copies."

A bit more explicit?
msg287421 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-02-09 14:57
I prefer Steven's formulation.  The parenthetical is more distracting than clarifying, I think.  I agree that 'administrative' is confusing and unnecessary.
msg287426 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-02-09 15:11
Current documentation looks correct to me. What is the problem with it?

Steven's formulation says about "deepcopy", but current documentation says about common issues of "deep copy" and describes how copy.deepcopy() solves them.
msg287427 - (view) Author: Marco Buttu (marco.buttu) * Date: 2017-02-09 15:24
Serhiy is right about "deep copy" instead of "deepcopy", but IMO the Steven's proposal (with the "deep copy" correction) is much clearer than the current doc.
msg290629 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-03-27 17:21
Looking over the PR, and especially in the context of Serhiy's point about this being about 'deep copy' and not 'deepcopy', I think this would be clearer if it were shortened even further, to just:

"Because deep copy copies everything, it may copy data that is intended to be shared between copies."

After all, what deepcopy does it provide a way for a class to implement that sharing when a deepcopy is done.
msg291368 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-04-09 10:03
Assigning to myself since Sanyam submitted the related PR at the PyCon Pune sprints.
msg291369 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-04-09 10:17
I'm going to merge Sanyam's PR as-is, as while David's reformulation shorten the overall sentence, it complicates the core description of the problem (copying things that you didn't want copied) by merging it with the stereotypical example of why you might not want to copy something (i.e. you intended to share a common reference between otherwise independent copies).
msg291370 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-04-09 10:22
New changeset 19e04942562a980ad2519f6ff79c455a7472783b by Nick Coghlan (Sanyam Khurana) in branch 'master':
bpo-29506: Clarify deep copy note in copy module
https://github.com/python/cpython/commit/19e04942562a980ad2519f6ff79c455a7472783b
msg291373 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-04-09 10:57
New changeset a524d6307273e3920d410452ace89610c843f051 by Nick Coghlan in branch '3.6':
bpo-29506: Clarify deep copy note in copy module
https://github.com/python/cpython/commit/a524d6307273e3920d410452ace89610c843f051
msg291374 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-04-09 10:57
New changeset bd18351c31573ab9a8580677004370a774a4eaae by Nick Coghlan in branch '3.5':
bpo-29506: Clarify deep copy note in copy module
https://github.com/python/cpython/commit/bd18351c31573ab9a8580677004370a774a4eaae
msg291375 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-04-09 10:57
New changeset ab16dc180e362e4cdb9eb163fae0a75664dcea3e by Nick Coghlan in branch '2.7':
bpo-29506: Clarify deep copy note in copy module
https://github.com/python/cpython/commit/ab16dc180e362e4cdb9eb163fae0a75664dcea3e
History
Date User Action Args
2017-04-09 10:58:19ncoghlansetstatus: open -> closed
type: enhancement
resolution: fixed
stage: needs patch -> resolved
2017-04-09 10:57:31ncoghlansetmessages: + msg291375
2017-04-09 10:57:17ncoghlansetmessages: + msg291374
2017-04-09 10:57:06ncoghlansetmessages: + msg291373
2017-04-09 10:33:59ncoghlansetpull_requests: + pull_request1210
2017-04-09 10:25:59ncoghlansetpull_requests: + pull_request1209
2017-04-09 10:25:08ncoghlansetpull_requests: + pull_request1208
2017-04-09 10:22:32ncoghlansetmessages: + msg291370
2017-04-09 10:17:02ncoghlansetmessages: + msg291369
2017-04-09 10:03:19ncoghlansetassignee: docs@python -> ncoghlan
messages: + msg291368
2017-03-27 17:21:15r.david.murraysetmessages: + msg290629
2017-02-18 11:45:37ncoghlansetnosy: + ncoghlan
2017-02-18 09:37:59CuriousLearnersetpull_requests: + pull_request114
2017-02-09 15:24:03marco.buttusetmessages: + msg287427
2017-02-09 15:11:11serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg287426
2017-02-09 14:57:55r.david.murraysetnosy: + r.david.murray
messages: + msg287421
2017-02-09 12:50:47pgacv2setmessages: + msg287414
2017-02-09 10:27:50marco.buttusetnosy: + marco.buttu
messages: + msg287398
2017-02-09 01:16:40steven.dapranosetnosy: + steven.daprano
messages: + msg287375
2017-02-08 22:21:32Mariattasetnosy: + Mariatta
messages: + msg287369
2017-02-08 22:14:56zach.waresetnosy: + zach.ware
messages: + msg287368
2017-02-08 22:07:35Mariattasetstage: needs patch
versions: - Python 3.3, Python 3.4
2017-02-08 22:02:44pgacv2create