[issue29506] Incorrect documentation for the copy module
New submission from Pedro: 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. ---------- assignee: docs@python components: Documentation messages: 287367 nosy: docs@python, pgacv2 priority: normal severity: normal status: open title: Incorrect documentation for the copy module versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Changes by Mariatta Wijaya <mariatta.wijaya@gmail.com>: ---------- stage: -> needs patch versions: -Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Zachary Ware added the comment: 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. ---------- nosy: +zach.ware _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Mariatta Wijaya added the comment: How about ``` Because deep copy copies everything, it may copy too much, including the administrative data structures. ``` ? ---------- nosy: +Mariatta _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Steven D'Aprano added the comment: 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." ---------- nosy: +steven.daprano _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Marco Buttu added the comment: +1 for the Steven's suggestion ---------- nosy: +marco.buttu _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Pedro added the comment: "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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
R. David Murray added the comment: I prefer Steven's formulation. The parenthetical is more distracting than clarifying, I think. I agree that 'administrative' is confusing and unnecessary. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Serhiy Storchaka added the comment: 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. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Marco Buttu added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Changes by Sanyam Khurana <sanyam.khurana01@gmail.com>: ---------- pull_requests: +114 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- nosy: +ncoghlan _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
R. David Murray added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Nick Coghlan added the comment: Assigning to myself since Sanyam submitted the related PR at the PyCon Pune sprints. ---------- assignee: docs@python -> ncoghlan _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Nick Coghlan added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Nick Coghlan added the comment: 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/19e04942562a980ad2519f6ff79c455a747... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- pull_requests: +1208 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- pull_requests: +1209 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- pull_requests: +1210 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Nick Coghlan added the comment: 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/a524d6307273e3920d410452ace89610c84... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Nick Coghlan added the comment: 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/bd18351c31573ab9a8580677004370a774a... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Nick Coghlan added the comment: 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/ab16dc180e362e4cdb9eb163fae0a75664d... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
Changes by Nick Coghlan <ncoghlan@gmail.com>: ---------- resolution: -> fixed stage: needs patch -> resolved status: open -> closed type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29506> _______________________________________
participants (9)
-
Marco Buttu -
Mariatta Wijaya
-
Nick Coghlan
-
Pedro
-
R. David Murray
-
Sanyam Khurana
-
Serhiy Storchaka
-
Steven D'Aprano
-
Zachary Ware