[Python-Dev] class Foo(object) vs class Foo: should be clearly explained in python 2 and 3 doc

[John Yeuk Hon Wong]

Hi.

Referring to my discussion on [1] and then on #python this afternoon.

A little background would help people to understand where this was 
coming from.

1. I write Python 2 code and have done zero Python-3 specific code.
2. I have always been using class Foo(object) so I do not know the new 
style is no longer required in Python 3. I feel "stupid" and "wrong" by 
thinking (object) is still a convention in Python 3.
3. Many Python 2 tutorials do not use object as the base class whether 
for historical reason, or lack of information/education, and can cause 
confusing to newcomers searching for answers when they consult the 
official documentation.

While Python 3 code no longer requires object be the base class for the 
new-style class definition, I believe (object) is still required if one 
has to write a 2-3 compatible code. But this was not explained or warned 
anywhere in Python 2 and Python 3 code, AFAIK. (if I am wrong, please 
correct me)

I propose the followings:

* It is desirable to state boldly to users that (object) is no longer 
needed in Python-3 **only** code and warn users to revert to (object) 
style if the code needs to be 2 and 3 compatible.

* In addition, Python 2 doc [2] should be fixed by introducing the 
new-style classes. This problem was noted a long long time ago according 
to [4].

* I would like to see warnings from suggested action item 1 on [2] and 
[3], for python 2 and 3 documentations.

Possible objections(s):

* We are pushing toward Python 3, some years later we don't need to 
maintain both Python 2 and 3 code. And many people, especially the 
newcomers will probably have no need to maintain Python 2 and 3 
compatible codes.

My answer to that is we need to be careful with marketing. First, it is 
a little embarrassing to assume and to find out the assumption is not 
entirely accurate. Secondly, Python 2 will not go away any time soon and 
most tutorials available on the Internet today are still written for 
Python 2. Furthermore, this CAN be a "gotcha" for new developers knowing 
only Python 3 writing Python 2 & 3 compatible code.

* Books can do a better job

I haven't actually reviewed/read any Python 3 books knowing most of my 
code should work without bothering Python 3-2 incompatibility yet.
So I don't have an accurate answer, but a very very quick glance over a 
popular Python 3 book (I am not sure if naming it out is ethical or not 
so I am going to grey it out here) the book just writes class Foo: and 
doesn't note the different between 2 and 3 with classes. It is not wrong 
since the book is about programming in Python 3, NOT writing 2 and 3, 
but this is where the communication breaks. Docs and books don't give 
all the answers needed.


P.S. Sorry if I should've have asked on #python-dev first or made a 
ticket but I've decided to send to mailing list before making a bug ticket.
First time!

Thanks.

Best,
Yeuk Hon

[1]: https://news.ycombinator.com/item?id=8154471

[2]: https://docs.python.org/2/tutorial/classes.html
https://docs.python.org/3/tutorial/classes.html

[3]: https://docs.python.org/3/tutorial/classes.html

[4]: https://www.python.org/doc/newstyle/