Title: Remove references to nonexisting __ne__ methods
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: barry, docs@python, facundobatista, maxking, r.david.murray, rhettinger, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2020-07-26 10:18 by serhiy.storchaka, last changed 2020-08-31 20:33 by facundobatista.

Pull Requests
URL Status Linked Edit
PR 21628 open serhiy.storchaka, 2020-07-26 10:19
Messages (6)
msg374309 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-07-26 10:18
There is the documentation for method __ne__ implementations in classes Set, Mapping, Header, Charset, Binary, but all these implementations are removed now and the default implementation of object.__ne__ is used instead.
msg374331 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-07-26 17:01
This will make the docs confusing and create an uncertainty for a user: if they define __eq__, do they, can they, or should they define __ne__.  

Also, it feels weird to have lists of five rich comparison methods rather than all six.

Tthe current docs better communicate which methods you need to supply and which methods get given to you for free.   Note, there is a dependency.  The object.__ne__ method depends on __eq__, so you don't get a useful __ne__ until and __eq__ is defined.  The meaning of __ne__ does in fact get changed by these classes.

So, while this doc edit is pedantically correct, it makes the documentation less useable than before.  I vote for leaving it as-is.
msg374332 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-07-26 17:03
s/pedantic/formally but not helpfully/
msg374334 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-07-26 17:19
Is it good to provide incorrect information in the documentation? It is a matter of correctness, not style.
msg374341 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-07-26 19:51
From a user point of view, your edit makes it look like they have to supply __ne__() if they want support for the != operator.  The user would have to know the subtle details of the language to know this is not the case.  In documentation, more so than in code, explicit is better than implicit.

The tables that we have now do a good job of communicating, "if you supply these methods, then these other methods follow automatically".  It matters very little where those methods were defined in the __mro__.  In Python 2.7, collections.Set used to explicitly define __ne__ and now it just inherits it from object, but that is close to being just an implementation detail.  From a user point of view, it is the same.

It would fine to add a technical implementation note somewhere, perhaps as a footnote to the "Mixin Methods" column.  But mostly, the documentation is more useful and clear as it stands now.  In my professional life, I teach engineers directly from these tables, so I have extensive experience with the user's point of view on these particular docs.
msg376167 - (view) Author: Facundo Batista (facundobatista) * (Python committer) Date: 2020-08-31 20:33
From a "consumer" POV, it's totally useful to see that `__ne__` is part of what Set (and others) provides, even if it's implemented in the Set class itself or wherever.

So +1 to leave it like it's currently is.
Date User Action Args
2020-08-31 20:33:11facundobatistasetnosy: + facundobatista
messages: + msg376167
2020-07-26 19:51:59rhettingersetmessages: + msg374341
2020-07-26 17:19:41serhiy.storchakasetmessages: + msg374334
2020-07-26 17:03:50rhettingersetmessages: + msg374332
2020-07-26 17:01:41rhettingersetnosy: + rhettinger
messages: + msg374331
2020-07-26 10:19:52serhiy.storchakasetkeywords: + patch
stage: patch review
pull_requests: + pull_request20769
2020-07-26 10:18:46serhiy.storchakacreate