tutorial intro talks of "shallow copy" concept without explanation

[tshepang]

BPO	14112
Nosy	@birkenfeld, @rhettinger, @terryjreedy, @ned-deily, @ezio-melotti, @merwok
PRs	bpo-14112: Add link for users to explore shallowness in greater depth #15408 bpo-14112: Allow beginners to explore shallowness in greater depth ;-) #15465 [3.8] bpo-14112: Allow beginners to explore shallowness in greater depth ;-) (GH-15465) #15469
Files	issue14112.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2019-08-24.18:33:45.881>
created_at = <Date 2012-02-24.19:50:04.401>
labels = ['type-feature', 'docs']
title = 'tutorial intro talks of "shallow copy" concept without explanation'
updated_at = <Date 2019-08-24.18:33:45.880>
user = 'https://bugs.python.org/tshepang'

bugs.python.org fields:

activity = <Date 2019-08-24.18:33:45.880>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2019-08-24.18:33:45.881>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2012-02-24.19:50:04.401>
creator = 'tshepang'
dependencies = []
files = ['32107']
hgrepos = []
issue_num = 14112
keywords = ['patch']
message_count = 19.0
messages = ['154151', '154198', '154206', '154218', '154219', '154227', '154228', '154254', '154285', '154289', '154290', '154293', '199834', '199838', '350261', '350321', '350391', '350393', '350394']
nosy_count = 9.0
nosy_names = ['georg.brandl', 'rhettinger', 'terry.reedy', 'ned.deily', 'ezio.melotti', 'eric.araujo', 'docs@python', 'tshepang', 'Ramchandra Apte']
pr_nums = ['15408', '15465', '15469']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue14112'
versions = ['Python 2.7', 'Python 3.3', 'Python 3.4']

[tshepang]

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.

[merwok]

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).

[ezio-melotti]

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).

[tjguk]

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?

[RamchandraApte]

+1 for Éric Araujo's idea.

[tshepang]

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.

[ezio-melotti]

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.

[merwok]

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.

[ned-deily]

"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

[tshepang]

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.

[terryjreedy]

'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.

[rhettinger]

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.

[ezio-melotti]

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.

[birkenfeld]

The text talks about containers which, although often the case, is not general enough; copy() and deepcopy() can work with any object.

[rhettinger]

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).

[terryjreedy]

With /like/link/ I agree.

[rhettinger]

New changeset 69ee87e by Raymond Hettinger in branch 'master':
bpo-14112: Allow beginners to explore shallowness in greater depth ;-) (GH-15465)
69ee87e

[rhettinger]

New changeset a842494 by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-14112: Allow beginners to explore shallowness in greater depth ;-) (GH-15465) (GH-15469)
a842494

[rhettinger]

Thanks Terry.