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

[Terry Reedy]

On 8/9/2014 2:44 PM, John Yeuk Hon Wong wrote:
> 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.

If someone else tried to make you feel that way, they are Code of 
Conduct violators who should be ignored. If you are beating yourself on 
the head, stop.

> 3. Many Python 2 tutorials do not use object as the base class whether
> for historical reason, or lack of information/education,

Probably both. Either way, the result is a disservice to readers.

> and can cause confusing to newcomers searching for answers
 > when they consult the official documentation.

I and some other people STRONGLY recommend that newcomers start with 
Python 3 and Python 3 docs and completely ignore Python 2 unless they 
cannot.

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

I think 'boldly' and 'warn' are a bit overstated.

> * In addition, Python 2 doc [2] should be fixed by introducing the
> new-style classes.

Definitely. The 2.x tutorial start with class x: and continues that way 
half way through the chapter.  I think it should start with class 
x(object): and at the end of the first half, briefly mention that class 
x in 2.x gets something slightly different that beginners can mostly 
ignore, while class x: in 3.x == class x(object): and that the latter 
works the same for both.

The 3.x tutorial, in the same place could *briefly* mention that class 
x: == class x(object): and the the latter is usually only used in code 
that also runs on 2.x or has been converted without removing the extra 
code.  The 3.x tutorial should *not* mention old style classes.

 > This problem was noted a long long time ago according to [4].

The opening statement "Unfortunately, new-style classes have not yet 
been integrated into Python's standard documention." is perhaps a decade 
out of date.  That page should not have been included in the new site 
design without being modified.

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

-- 
Terry Jan Reedy