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

[Raymond Hettinger]

Raymond Hettinger  added the comment:

Thanks Terry.

--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Raymond Hettinger  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[miss-islington]

Change by miss-islington :


--
pull_requests: +15160
pull_request: https://github.com/python/cpython/pull/15469

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Raymond Hettinger  added the comment:


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


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Change by Raymond Hettinger :


--
pull_requests: +15157
pull_request: https://github.com/python/cpython/pull/15465

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy  added the comment:

With /like/link/ I agree.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Raymond Hettinger  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Change by Raymond Hettinger :


--
pull_requests: +15113
pull_request: https://github.com/python/cpython/pull/15408

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Tim Golden]

Changes by Tim Golden :


--
nosy:  -tim.golden

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Georg Brandl]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Raymond Hettinger]

Raymond Hettinger  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Terry J. Reedy]

Terry J. Reedy  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Tshepang Lekhonkhobe]

Tshepang Lekhonkhobe  added the comment:

On Sun, Feb 26, 2012 at 00:11, Ned Deily  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ned Deily]

Ned Deily  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

Ezio Melotti  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Tshepang Lekhonkhobe]

Tshepang Lekhonkhobe  added the comment:

On Sat, Feb 25, 2012 at 09:35, Éric Araujo  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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ramchandra Apte]

Ramchandra Apte  added the comment:

+1 for Éric Araujo's idea.

--
nosy: +ramchandra.apte

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Tim Golden]

Tim Golden  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Ezio Melotti]

Ezio Melotti  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Éric Araujo  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-comment 
—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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Tshepang Lekhonkhobe]

New submission from Tshepang Lekhonkhobe :

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.

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

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com