classification
Title: Why isn't "in" called a comparison operation?
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, fdrake, miss-islington, ncoghlan, r.david.murray, rhettinger, serhiy.storchaka, terry.reedy, wim.glenn
Priority: normal Keywords: patch

Created on 2016-11-04 20:36 by wim.glenn, last changed 2018-09-11 18:38 by serhiy.storchaka.

Files
File name Uploaded Description Edit
patch.diff wim.glenn, 2016-11-04 20:35 suggested changes to stdtypes documentation review
newpatch.diff wim.glenn, 2016-11-04 22:08 alternate proposal which corrects language but does not classify 'in' as a comparison. review
Pull Requests
URL Status Linked Edit
PR 9086 merged wim.glenn, 2018-09-07 03:33
PR 9171 merged miss-islington, 2018-09-11 17:45
PR 9172 merged miss-islington, 2018-09-11 17:45
Messages (16)
msg280080 - (view) Author: wim glenn (wim.glenn) * Date: 2016-11-04 20:35
Regarding 

    https://docs.python.org/3/library/stdtypes.html#comparisons

There is a line at the bottom claiming:

> Two more operations with the same syntactic priority, in and not in, are supported only by sequence types (below).

The claim is incorrect because `in` and `not in` are also supported by non-sequence types such as sets, mappings, etc for membership testing.

Is there any good reason why we don't include them in the table of comparison operations, and say that there are ten comparison operations in python?  They do support comparison chaining in the same way: 

    >>> 'x' in 'xy' in 'xyz'
    True
    >>> 0 in {0} in [{0}]
    True
msg280083 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-11-04 20:56
It should really say "only by types that support iteration".  They are not comparison operations, they are containment predicates.
msg280085 - (view) Author: wim glenn (wim.glenn) * Date: 2016-11-04 21:00
Well, that wouldn't be true either.  Because you can easily implement objects which support membership tests but don't support iteration.
msg280086 - (view) Author: wim glenn (wim.glenn) * Date: 2016-11-04 21:02
I want to add that the grammar explicitly mentions them as comparisons

    https://docs.python.org/3/reference/grammar.html

And they are also listed in the comparisons section of the expressions documentation

    https://docs.python.org/3/reference/expressions.html#comparisons

So the docs seem to be contradicting themselves here.
msg280090 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-11-04 21:11
At a grammar and implementation level, the "in" and "not in" operators are treated like comparisons (same precedence and opcodes), but at a semantic level, I concur with David Murray and don't think of these as being comparisons at all.   Accordingly, I prefer the current presentation
and agree with David that the note should be revised to say "only by types that support iteration".
msg280093 - (view) Author: wim glenn (wim.glenn) * Date: 2016-11-04 22:08
Perhaps it's better to call a spade a spade here - if they're implemented as comparisons, then why not document them as comparisons?

A colleague has mentioned one point that sets `in` and `not in` apart from the other comparisons in the table: comparisons are generally made between objects of the same type (with the exception of numbers).  But membership "comparisons" are made between different types (with the exception of substring checks).  

Here is an alternate patch which leaves the table alone, but corrects the inaccuracy in the note.
msg280094 - (view) Author: Fred L. Drake, Jr. (fdrake) (Python committer) Date: 2016-11-04 22:17
"in" and "not in" are not comparisons, regardless of implementation mechanics (which could change).

They aren't really dependent on iteration, though they often correlate with iteration.

I'd rather see them described as "containment tests" or something similar.
msg280128 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-11-06 03:17
newpatch.diff looks fine.
msg280625 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-11-12 00:45
"Two more operations with the same syntactic priority, in and not in, are supported ..."

could be changed to

The containment tests in and not in have the same priority as comparisons and are supported ..."
msg282472 - (view) Author: wim glenn (wim.glenn) * Date: 2016-12-05 22:15
1 month later.. is newpatch.diff OK to merge or any further improvements needed?  thanks
msg306412 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-11-17 07:45
Also see https://bugs.python.org/issue32055 regarding the prospect of bringing the implementation into line with the intuitive semantics, and preventing implicit comparison chaining for containment tests.
msg325015 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-09-11 15:04
I think that "types that are :term:`iterable` or implement the :meth:`__contains__` method" is too low-level for this section.

In this section we tell about builtin types. From those the types that support `in` and `not in` are list, tuple, dict, set, frozenset, str, bytes, bytearray, memoryview, and iterator types. We can just enumerate them or use general word. Calling the "sequence types" is not correct, but fortunately all of them are iterable, so that we can say just "iterable types described below". Or enumerate categories of types, as they are named in the below subsections: "iterator types, sequence types, str, binary sequence types, set types and dict", with links to corresponding subsections.
msg325037 - (view) Author: miss-islington (miss-islington) Date: 2018-09-11 17:44
New changeset 08bcf647d8a92e4bd47531588b284c6820b7a7ef by Miss Islington (bot) (wim glenn) in branch 'master':
bpo-28617 Fixed docs inaccuracies about the types that support membership tests (GH-9086)
https://github.com/python/cpython/commit/08bcf647d8a92e4bd47531588b284c6820b7a7ef
msg325042 - (view) Author: miss-islington (miss-islington) Date: 2018-09-11 18:13
New changeset 3e648f8371e342ccfa663ad77e82a538fcc8c9fb by Miss Islington (bot) in branch '3.7':
bpo-28617 Fixed docs inaccuracies about the types that support membership tests (GH-9086)
https://github.com/python/cpython/commit/3e648f8371e342ccfa663ad77e82a538fcc8c9fb
msg325044 - (view) Author: miss-islington (miss-islington) Date: 2018-09-11 18:18
New changeset 889f080a4d5cdb1cfb901b953f4b89f3ea806bbe by Miss Islington (bot) in branch '3.6':
bpo-28617 Fixed docs inaccuracies about the types that support membership tests (GH-9086)
https://github.com/python/cpython/commit/889f080a4d5cdb1cfb901b953f4b89f3ea806bbe
msg325047 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-09-11 18:38
Humm, why the bot merges in the master branch?
History
Date User Action Args
2018-09-11 18:38:28serhiy.storchakasetmessages: + msg325047
2018-09-11 18:18:19miss-islingtonsetmessages: + msg325044
2018-09-11 18:13:38miss-islingtonsetmessages: + msg325042
2018-09-11 17:45:51miss-islingtonsetpull_requests: + pull_request8613
2018-09-11 17:45:41miss-islingtonsetpull_requests: + pull_request8612
2018-09-11 17:44:56miss-islingtonsetnosy: + miss-islington
messages: + msg325037
2018-09-11 15:04:47serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg325015
2018-09-07 03:33:00wim.glennsetstage: commit review -> patch review
pull_requests: + pull_request8545
2017-11-17 07:45:07ncoghlansetnosy: + ncoghlan
messages: + msg306412
2016-12-05 22:15:42wim.glennsetmessages: + msg282472
2016-11-12 00:45:55terry.reedysetversions: - Python 3.3, Python 3.4
nosy: + terry.reedy

messages: + msg280625

stage: commit review
2016-11-06 03:17:01rhettingersetmessages: + msg280128
2016-11-04 22:17:24fdrakesetnosy: + fdrake
messages: + msg280094
2016-11-04 22:08:35wim.glennsetfiles: + newpatch.diff

messages: + msg280093
2016-11-04 21:11:43rhettingersetnosy: + rhettinger
messages: + msg280090
2016-11-04 21:02:00wim.glennsetmessages: + msg280086
2016-11-04 21:00:21wim.glennsetmessages: + msg280085
2016-11-04 20:56:44r.david.murraysetnosy: + r.david.murray
messages: + msg280083
2016-11-04 20:36:00wim.glenncreate