Mailman 3 [issue14112] tutorial intro talks of "shallow copy" concept without explanation - docs

[issue14112] tutorial intro talks of "shallow copy" concept without explanation

older
[issue32118] Docs: add note about...

Tshepang Lekhonkhobe

24 Feb 2012 24 Feb '12

7:50 p.m.

New submission from Tshepang Lekhonkhobe <tshepang@gmail.com>: Relevant line: http://hg.python.org/cpython/file/e2eccc906354/Doc/tutorial/introduction.rst... When the concept is introduced, it appears like there's an assumption that the reader would know what it means. I'm curious if it's that common a term that it should be taken for granted, or if it deserves a definition. ---------- assignee: docs@python components: Documentation messages: 154151 nosy: docs@python, tshepang priority: normal severity: normal status: open title: tutorial intro talks of "shallow copy" concept without explanation versions: Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Show replies by date

Éric Araujo

25 Feb 25 Feb

7:35 a.m.

Éric Araujo <merwok@netwok.org> added the comment: I think it’s a common English term (i.e. “shallow water” to describe a small lake-like thing where you can go without swimming), but non-native speakers may not know it (I don’t remember if I knew it before learning Python, for example). What about this: All slice operations return a new list containing the requested elements. This -means that the following slice returns a shallow copy of the list *a*:: +means that the following slice returns a shallow copy (see the documentation of +the :mod:`copy` module for a definition) of the list *a*:: (BTW, you can use syntax like Doc/tutorial/introduction.rst:487 to have links generated; see http://docs.python.org/devguide/triaging#generating-special-links-in-a-comme... —also linked from the “Comment” label in the form, but it isn’t obvious that it’s a link). ---------- nosy: +eric.araujo, ezio.melotti, terry.reedy versions: +Python 2.7, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Tshepang Lekhonkhobe

9:51 a.m.

Tshepang Lekhonkhobe <tshepang@gmail.com> added the comment: On Sat, Feb 25, 2012 at 09:35, Éric Araujo <report@bugs.python.org> wrote:

...

What about this:

All slice operations return a new list containing the requested elements. This -means that the following slice returns a shallow copy of the list *a*:: +means that the following slice returns a shallow copy (see the documentation of +the :mod:`copy` module for a definition) of the list *a*::

That's kool, though I like Ezio's idea of putting it on a glossary (and then linking to it) even more.

...

(BTW, you can use syntax like Doc/tutorial/introduction.rst:487 to have links generated; see http://docs.python.org/devguide/triaging#generating-special-links-in-a-comme... —also linked from the “Comment” label in the form, but it isn’t obvious that it’s a link).

Thanks for the pointer. Note however that I chose my approach because it shows the info at a specific revision, in case the content changes later on. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Ezio Melotti

8:09 a.m.

Ezio Melotti <ezio.melotti@gmail.com> added the comment: Even if they know the meaning of "shallow" (which is not a really common word AFAICT), they might not know what it means in this context. Adding an entry to glossary might be a better solution. In this context I think the best solution would be to actually show the implication of having a shallow copy with another short example (hijacking the reader to some other page where they can find some in-depth description of what "shallow" might do more harm than good). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Tim Golden

9:18 a.m.

Tim Golden <mail@timgolden.me.uk> added the comment: On 25/02/2012 08:09, Ezio Melotti wrote:

...

Even if they know the meaning of "shallow" (which is not a really common word AFAICT)

FWIW it's pretty much the only way of saying what it means. I've no idea how many people used it last year or anything, but if I needed to express the concept of the opposite of deep I would struggle to find another word. Except, perhaps, the doublespeak-like "not deep". Undeep? Double-plus undeep? ---------- nosy: +tim.golden _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Ramchandra Apte

9:20 a.m.

Ramchandra Apte <maniandram01@gmail.com> added the comment: +1 for Éric Araujo's idea. ---------- nosy: +ramchandra.apte _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Ezio Melotti

9:54 a.m.

Ezio Melotti <ezio.melotti@gmail.com> added the comment:

...

FWIW it's pretty much the only way of saying what it means.

However, even using "not deep" here would still be ambiguous. What's a deep copy? What's a non-deep copy? Using "shallow" might be a problem, but the real problem is that regardless of the wording, the reader might not know what this is all about. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Éric Araujo

2:57 p.m.

Éric Araujo <merwok@netwok.org> added the comment: A link to a glossary may be better than a link to the top of the copy module. I wonder if we could use glossary markup in the copy module docs instead of adding terms to the global glossary. Tim: I like “undeep”, it’s used to describe a geographical feature of a river in The Lord of the Rings. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Ned Deily

10:11 p.m.

Ned Deily <nad@acm.org> added the comment: "shallow copy" and "deep copy" are both standard computer science terms by no means unique to or invented by Python. We should be cautious about documentation bloat and trying to redefine standard terms. http://en.wikipedia.org/wiki/Object_copy#Shallow_copy ---------- nosy: +ned.deily _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Tshepang Lekhonkhobe

26 Feb 26 Feb

12:02 a.m.

Tshepang Lekhonkhobe <tshepang@gmail.com> added the comment: On Sun, Feb 26, 2012 at 00:11, Ned Deily <report@bugs.python.org> wrote:

...

"shallow copy" and "deep copy" are both standard computer science terms by no means unique to or invented by Python. We should be cautious about documentation bloat and trying to redefine standard terms.

http://en.wikipedia.org/wiki/Object_copy#Shallow_copy

Do they mean exactly the same thing in Python as what Wikipedia says? In that case, are links to Wikipedia allowed? Anyways, some explanation (or link) would be needed since many people without a background in computer science are going to read the tutorial. I think the term is not common enough that it can be taken for granted that newbies to Python (readers of the tutorial) will know it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Terry J. Reedy

12:12 a.m.

Terry J. Reedy <tjreedy@udel.edu> added the comment: 'Shallow' is a common English word: "Stay in shallow water until you learn to swim!" But that is not the issue here. I think the underlying issue is that the first sentence "All slice operations return a new list containing the requested elements." is wrong. Python lists, like shopping lists, do not 'contain' objects. Both contain references to objects (copies of their identifieres) and thereby define an abstract collection. A shallow copy of a collection object copies references (ids). A deep copy also copies objects themselves. (The Wikipedia article says much the same, but to me much less clearly.) If we start with a true sentence "Slice operations return a new list containing references to a subsequence of the original elements." or "Slice operations return a new list that defines a subsequence of the original sequence of objects", then I do not think more *needs* to be said. We could optionally add "Since no objects are copied, slices are shallow copies." both to emphasize that no objects are copied and to introduced the notion of shallow copy. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Raymond Hettinger

2:07 a.m.

Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: FWIW, the shallow/deep terminology is not unique to Python and is commonly used in computer science. In my experience teaching Python, the terms are somewhat self-descriptive and only become perplexing when someone over-explains them. That said, a glossary entry is appropriate. ---------- assignee: docs@python -> rhettinger nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Ezio Melotti

14 Oct 14 Oct

2:32 a.m.

Ezio Melotti added the comment: Here is a patch that adds glossary entries for deep and shallow copy. I tried to keep them simple and clear enough. FWIW http://docs.python.org/3.4/library/copy.html also has a definition of the terms. If my definitions are OK I will add links to the terms were appropriate. ---------- keywords: +patch nosy: +georg.brandl stage: -> patch review type: -> enhancement versions: +Python 3.4 -Python 3.2 Added file: http://bugs.python.org/file32107/issue14112.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Georg Brandl

4:30 a.m.

Georg Brandl added the comment: The text talks about containers which, although often the case, is not general enough; copy() and deepcopy() can work with any object. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

Tim Golden

24 Oct 24 Oct

9:57 a.m.

Changes by Tim Golden <mail@timgolden.me.uk>: ---------- nosy: -tim.golden _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________