classification
Title: tutorial intro talks of "shallow copy" concept without explanation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Ramchandra Apte, docs@python, eric.araujo, ezio.melotti, georg.brandl, ned.deily, rhettinger, terry.reedy, tshepang
Priority: normal Keywords: patch

Created on 2012-02-24 19:50 by tshepang, last changed 2019-08-24 18:33 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
issue14112.diff ezio.melotti, 2013-10-14 02:32 review
Pull Requests
URL Status Linked Edit
PR 15408 closed rhettinger, 2019-08-23 05:15
PR 15465 merged rhettinger, 2019-08-24 17:42
PR 15469 merged miss-islington, 2019-08-24 18:15
Messages (19)
msg154151 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-02-24 19:50
Relevant line: http://hg.python.org/cpython/file/e2eccc906354/Doc/tutorial/introduction.rst#l487

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.
msg154198 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-25 07:35
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-comment —also linked from the “Comment” label in the form, but it isn’t obvious that it’s a link).
msg154206 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-02-25 08:09
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).
msg154218 - (view) Author: Tim Golden (tim.golden) * (Python committer) Date: 2012-02-25 09:18
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?
msg154219 - (view) Author: Ramchandra Apte (Ramchandra Apte) * Date: 2012-02-25 09:20
+1 for Éric Araujo's idea.
msg154227 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-02-25 09:51
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-comment —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.
msg154228 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-02-25 09:54
> 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.
msg154254 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-25 14:57
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.
msg154285 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2012-02-25 22:11
"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
msg154289 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-02-26 00:02
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.
msg154290 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-02-26 00:12
'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.
msg154293 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-02-26 02:07
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.
msg199834 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-10-14 02:32
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.
msg199838 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-10-14 04:30
The text talks about containers which, although often the case, is not general enough; copy() and deepcopy() can work with any object.
msg350261 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-23 07:36
How about we just like "shallow copy" to the copy module docs.  That way, a person can follow-up with more detail if they're interested, yet still can read-on without interruption if they choose (this entry occurs *very* early in the tutorial).
msg350321 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-08-23 18:01
With /like/link/ I agree.
msg350391 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-24 18:15
New changeset 69ee87e99cfe0b79389cffa92d126af868baf353 by Raymond Hettinger in branch 'master':
bpo-14112: Allow beginners to explore shallowness in greater depth ;-) (GH-15465)
https://github.com/python/cpython/commit/69ee87e99cfe0b79389cffa92d126af868baf353
msg350393 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-24 18:33
New changeset a8424940b4873791fc178a9f19a7bf1779a6cf42 by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-14112: Allow beginners to explore shallowness in greater depth ;-) (GH-15465) (GH-15469)
https://github.com/python/cpython/commit/a8424940b4873791fc178a9f19a7bf1779a6cf42
msg350394 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-24 18:33
Thanks Terry.
History
Date User Action Args
2019-08-24 18:33:45rhettingersetstatus: open -> closed
resolution: fixed
messages: + msg350394

stage: patch review -> resolved
2019-08-24 18:33:21rhettingersetmessages: + msg350393
2019-08-24 18:15:55miss-islingtonsetpull_requests: + pull_request15160
2019-08-24 18:15:47rhettingersetmessages: + msg350391
2019-08-24 17:42:52rhettingersetpull_requests: + pull_request15157
2019-08-23 18:01:44terry.reedysetmessages: + msg350321
2019-08-23 07:36:47rhettingersetmessages: + msg350261
2019-08-23 05:15:37rhettingersetpull_requests: + pull_request15113
2013-10-24 09:57:27tim.goldensetnosy: - tim.golden
2013-10-14 04:30:34georg.brandlsetmessages: + msg199838
2013-10-14 02:32:17ezio.melottisetfiles: + issue14112.diff

type: enhancement
versions: + Python 3.4, - Python 3.2
keywords: + patch
nosy: + georg.brandl

messages: + msg199834
stage: patch review
2012-02-26 02:07:57rhettingersetassignee: docs@python -> rhettinger

messages: + msg154293
nosy: + rhettinger
2012-02-26 00:12:04terry.reedysetmessages: + msg154290
2012-02-26 00:02:10tshepangsetmessages: + msg154289
2012-02-25 22:11:23ned.deilysetnosy: + ned.deily
messages: + msg154285
2012-02-25 14:57:17eric.araujosetmessages: + msg154254
2012-02-25 09:54:35ezio.melottisetmessages: + msg154228
2012-02-25 09:51:25tshepangsetmessages: + msg154227
2012-02-25 09:20:54Ramchandra Aptesetnosy: + Ramchandra Apte
messages: + msg154219
2012-02-25 09:18:30tim.goldensetnosy: + tim.golden
messages: + msg154218
2012-02-25 08:09:40ezio.melottisetmessages: + msg154206
2012-02-25 07:35:35eric.araujosetnosy: + eric.araujo, ezio.melotti, terry.reedy

messages: + msg154198
versions: + Python 2.7, Python 3.2
2012-02-24 19:50:04tshepangcreate