This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: has_key doc could be clearer
Type: Stage:
Components: Documentation Versions: Python 2.7, Python 2.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: LambertDW, benjamin.peterson, darcy@druid.net, georg.brandl, giampaolo.rodola, loewis, terry.reedy
Priority: normal Keywords:

Created on 2008-10-30 17:48 by terry.reedy, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (14)
msg75374 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2008-10-30 17:48
2.6 lib ref builtin types, mappings, has_key doc now says
"dict.has_key(key) is equivalent to key in d, but deprecated."
Posters on c.l.p found this confusing.  Which is deprecated?
I agree that this could be confusing to a beginner.

D'Arcy J.M. Cain suggests
"dict.has_key(key) is deprecated.  Use "key in dict" instead."
Or "Use the replacement ..."
Or "Use the new version ..."
msg75376 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2008-10-30 18:17
Out of curiosity: is that really ambiguous in plain English?
msg75378 - (view) Author: Giampaolo Rodola' (giampaolo.rodola) * (Python committer) Date: 2008-10-30 20:03
English is not my first language but it seems obvious to me that the
suggestion is using:

>>> key in dict

...instead of:

>>> dict.has_key(key)


The only thing which may be confusing is the dictionary which is first
called "dict" and then "d", in which case the following modification
should be made:

- dict.has_key(key) is equivalent to key in d, but deprecated.
+ dict.has_key(key) is equivalent to key in dict, but deprecated.
msg75381 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-10-30 21:20
If I understand English correctly, I don't see an ambiguity.

Probably the poster(s) on c.l.p didn't look properly and read something
like "equivalent to key in d, but the latter is deprecated".

The d/dict inconsistency should be fixed.
msg75416 - (view) Author: David W. Lambert (LambertDW) Date: 2008-10-31 14:05
The D'Arcy J.M. Cain wording is clearer.

"dict.has_key(key) is deprecated.  Use "key in dict" instead." would
improve python.
msg75417 - (view) Author: D'Arcy J.M. Cain (darcy@druid.net) Date: 2008-10-31 14:46
The original is not technically ambiguous modulo the dict/d issue.  The
suggested text just makes it more obvious.

We just don't want to reduce the possibility of no confusion.  :-)
msg75424 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2008-10-31 17:32
I believe "deprecated" at the end is the sort of dangling modifier
deprecated by English style books I have read. I felt it to be
sufficiently awkward and potentially confusing, at least for a moment,
to be worth a few minutes to report and change.  Another suggestion for
improvement:

"dict.has_key(key), now deprecated, is equivalent to key in dict, the
recommended replacement."

With or without the (optional) final phrase, this is smoother and
impossible to misread.
msg75427 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-10-31 20:42
After consulting with an English teacher who agreed that the phrasing
was awkward, I fix it up in r67070.
msg75433 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2008-10-31 23:04
Benjamin: Thanks for asking your teacher! It's curious that all the
foreigners have no problems with the formulation, and all the native
speakers do... There is clearly something to the English language that
we haven't mastered yet.
msg75443 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2008-11-01 16:08
Benjamin: I thank you too for verifying that I was not crazy.

Martin: I noticed native/non-native split too, and chalked it up to a
subtle difference between German and English.

For future reference, the problem with the original, as I see it now, is
a subtle interaction between syntax and semantics.  The original
sentence combined two thoughts about has_key.  The two should be either
coordinate (parallel in form) or one should be clearly subordinate.  A
subordinate modifier should generally be closer to the subject,
especially if it is much shorter.  Making that so was one of my
suggestions.  The coordinate form would be 'but it is deprecated'.  But
this does not work because 'it' would be somewhat ambiguous because of
the particular first modifier.  

The following pair of sentences illustrate what I am trying to say.
  Guido was once a Nederlander, but he moved to America.
  Guido was once a student of Professor X, but he moved to America.
In English, the second 'he' is ambiguous because of the particular first
modifier.

So, to me, 'but deprecated' at the end of the sentence reads as either a
misplaced subordinate form or as an abbreviated coordinate form that is
at least somewhat ambiguous because of the meaning of the other modifier.
msg75444 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2008-11-01 18:07
> The following pair of sentences illustrate what I am trying to say.
>   Guido was once a Nederlander, but he moved to America.
>   Guido was once a student of Professor X, but he moved to America.
> In English, the second 'he' is ambiguous because of the particular first
> modifier.

Ah - thanks for the explanation. I now recall that native speakers
typically associate "it" (or "he") with the *last* thing/person being
mentioned. If this is the case, it's indeed different from German;
the literal translation of the second sentence would not usually be
considered ambiguous:

   Guido war früher Student von Professor X,
   (er) ist aber nach Amerika umgezogen.

If we wanted to express that it is X who moved, we would say

   Guido war früher Student von Professor X,
   der/welcher aber nach Amerika umgezogen ist.

which translates to

   Guido was once a student of Professor X, who moved
   to America, though. (couldn't figure out how to put the
   "but" into that sentence)

So in German, it seems, backward references go typically to
the subject of the main phrase.
msg75445 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-11-01 18:14
Forgive me for playing stupid here, but I want to understand English
better. I would fully understand the confusion had the sentence been

"dict.has_key(key) is equivalent to key in d, but it is deprecated."

Terry's and Martin' example sentences are transferable to that. However,
the actual sentence was

"dict.has_key(key) is equivalent to key in d, but deprecated."

Let me try to construct a similar sentence:

"Guido was once a colleague of Joe, but much smarter."

Can the "but" clause really be taken as referring to Joe? Or is it
simply not an English sentence? ;)
msg75446 - (view) Author: D'Arcy J.M. Cain (darcy@druid.net) Date: 2008-11-01 18:24
I think a clarification is in order.  The sentence being changed was
perfectly and mathematically correct.  If you laid it out on a
blackboard and parsed it (remember those days?) you could prove that it
said the correct thing.  No one is disputing that I think.  The change
is simply to make it easier on the guy who is reading the manual in a
rush, under a deadline and who might misread it.  His fault but there is
no harm in protecting him a little.
msg75449 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2008-11-01 19:42
>> Terry's and Martin' example sentences are transferable to that.
>> However, the actual sentence was
>> "dict.has_key(key) is equivalent to key in d, but deprecated."

> The sentence being changed was perfectly and mathematically correct.

I'm not so sure about that anymore. Reading the post in

http://www.englishforums.com/English/RepetitionSubjectPronoun/cqjlw/post.htm

it now seems to me that the part after the comma is a separate sentence,
and both the subject pronoun and the verb are omitted (as an ellipsis).
So the full sentence would indeed read

"dict.has_key(key) is equivalent to key in d, but it is deprecated."

which then would be ambiguous as discussed.
History
Date User Action Args
2022-04-11 14:56:40adminsetgithub: 48493
2008-11-01 19:42:02loewissetmessages: + msg75449
2008-11-01 18:24:48darcy@druid.netsetmessages: + msg75446
2008-11-01 18:14:31georg.brandlsetmessages: + msg75445
2008-11-01 18:07:16loewissetmessages: + msg75444
2008-11-01 16:08:42terry.reedysetmessages: + msg75443
2008-10-31 23:04:46loewissetmessages: + msg75433
2008-10-31 20:42:07benjamin.petersonsetstatus: open -> closed
nosy: + benjamin.peterson
resolution: fixed
messages: + msg75427
2008-10-31 17:32:59terry.reedysetmessages: + msg75424
2008-10-31 14:46:34darcy@druid.netsetnosy: + darcy@druid.net
messages: + msg75417
2008-10-31 14:05:19LambertDWsetnosy: + LambertDW
messages: + msg75416
2008-10-30 21:20:22georg.brandlsetmessages: + msg75381
2008-10-30 20:03:40giampaolo.rodolasetnosy: + giampaolo.rodola
messages: + msg75378
2008-10-30 18:17:26loewissetnosy: + loewis
messages: + msg75376
2008-10-30 17:48:24terry.reedycreate