classification
Title: Remove explicit "object" inheritance in Python 3 docs
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: asvetlov, docs@python, eric.araujo, ezio.melotti, michael.foord, nedbat, pelson, python-dev, rhettinger, terry.reedy, vinay.sajip
Priority: normal Keywords: patch

Created on 2013-03-04 14:36 by pelson, last changed 2013-03-11 10:09 by michael.foord. This issue is now closed.

Files
File name Uploaded Description Edit
pelson_doc_decorator.diff pelson, 2013-03-04 14:36 review
Messages (12)
msg183458 - (view) Author: Phil Elson (pelson) * Date: 2013-03-04 14:36
The example at http://docs.python.org/3.4/howto/descriptor.html#properties does not run due to the old style "raise AttributeError, message" form. 


This patch fixes the problem, and also goes through the docs to remove explicit sub-classing from "object". The only remaining instances of this now are:

$> grep -r -E "class .*\(object\)\:" Doc/*               
Doc/howto/pyporting.rst:   class UnicodeMixin(object):
Doc/reference/compound_stmts.rst:   class Foo(object):
Doc/tools/sphinxext/pyspecific.py:class PyDecoratorMixin(object):
Doc/whatsnew/2.6.rst:    class C(object):
Doc/whatsnew/2.2.rst:   class C(object):
Doc/whatsnew/2.2.rst:   class C(object):
Doc/whatsnew/2.2.rst:   class C(object):
Doc/whatsnew/2.2.rst:   class C(object):
Doc/whatsnew/2.2.rst:   >>> class C(object):


Which are all (minus tools/sphinxext/pyspecific) referring to python2 in some context.

I'm not bound to fixing the explicit object subclassing, so if it is better off not being here, that's fine.

Cheers,
msg183796 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-09 04:43
The respective howto and examples authors should give their OK for deleting '(object)' in case they are trying to keep one text compatible across 2 and 3. I added the other two to the nosy list.

Doc/howto/descriptor.rst -- Raymond H.
Doc/howto/sorting.rst -- Raymond H.
Doc/howto/logging-cookbook.rst -- Vinay S.
Doc/library/unittest.mock-examples.rst -- Michael F.

Since raise AttributeError(message) works in 2.x, I think that should definitely be changed in descriptor.rst.

I also think the regular docs can be changed without further ado.
Doc/library/contextlib.rst
Doc/library/functions.rst

Phil, your name does not have a Contributor Agreement *. If it should, say so and lets figure out why not. Otherwise, please fill out one at
http://www.python.org/psf/contrib/
Choose paper mail, paper scan and email, or javascript e-form.
msg183804 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2013-03-09 07:34
I'm OK with changing the logging cookbook to remove explicit subclassing from "object" in the examples.
msg183864 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2013-03-10 03:09
Why is it important to remove subclassing object?  Isn't it still good form to mention object as a base class.
msg183867 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-03-10 04:37
> Why is it important to remove subclassing object?

It's not /important/, but those are just leftovers from 2.x, and there's no reason to keep them around.

> Isn't it still good form to mention object as a base class.

I don't think so (or at least I've never seen anyone suggesting to keep or add "object" explicitly).

The patch LGTM, so unless there's a valid reason to keep the "object" around I'll commit it soon.
msg183870 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-03-10 06:46
[Ned]
> Isn't it still good form to mention object as a base class.

I don't think so.  The classes look much cleaner without it.

+1 from for removing (object) from most examples (except for the descriptor howto).

[Terry]
> The respective howto and examples authors should give their 
> OK for deleting '(object)' in case they are trying to keep 
> one text compatible across 2 and 3. I added the other two 
> to the nosy list.

Thanks Terry.  Yes, I would like to keep (object) in the text of the descriptor how-to.  As you said, it keeps the text compatible.  But also, the explicit inheritance from (object) is an aid to clarity in a document that needs to highlight that attribute access occurs in two forms, object.__getattribute__ and type.__getattribute__.
msg183884 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-03-10 16:37
New changeset 513c4aaf70d7 by Raymond Hettinger in branch '2.7':
Issue #17351: Modernize the pure Python property() example.
http://hg.python.org/cpython/rev/513c4aaf70d7
msg183885 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-03-10 16:42
New changeset bb7e01b5d362 by Raymond Hettinger in branch '3.3':
Issue #17351: Modernize the pure Python property() example.
http://hg.python.org/cpython/rev/bb7e01b5d362
msg183933 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-11 05:20
My rationale for supporting removal is this: People beginning with Py3, which is most beginners in the next decade, seeing (object), might think it necessary in certain cases or that it does something. The descriptor how-to is a) advanced and b) can have a note if needed. People who know Py2 might get a wrong idea either way, but should read some 2 to 3 guide and then will know. If a choice be needed, I would rather cater to future Python learners.

Anyway, we only need Michael's word to know for sure which to patch, or can go ahead without touching mock-examples.
msg183940 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-03-11 07:43
New changeset 4f745f7d6fca by Ezio Melotti in branch '3.2':
#17351: remove "object" inheritance from docs.  Patch by Phil Elson.
http://hg.python.org/cpython/rev/4f745f7d6fca

New changeset 8b1d3fa3b389 by Ezio Melotti in branch '3.3':
#17351: merge with 3.2.
http://hg.python.org/cpython/rev/8b1d3fa3b389

New changeset b10a9d4f08eb by Ezio Melotti in branch 'default':
#17351: merge with 3.3.
http://hg.python.org/cpython/rev/b10a9d4f08eb
msg183941 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-03-11 07:45
Fixed, thanks for the patch!
msg183945 - (view) Author: Michael Foord (michael.foord) * (Python committer) Date: 2013-03-11 10:09
If the consensus is that Python documentation should not include explicit object inheritance then fine to update mock docs accordingly. The backport docs will still use it as they are for Python 2 as well.
History
Date User Action Args
2013-03-11 10:09:59michael.foordsetmessages: + msg183945
2013-03-11 07:45:12ezio.melottisetstatus: open -> closed
messages: + msg183941

assignee: docs@python -> ezio.melotti
resolution: fixed
stage: patch review -> resolved
2013-03-11 07:43:41python-devsetmessages: + msg183940
2013-03-11 05:20:05terry.reedysetmessages: + msg183933
2013-03-11 04:58:17eric.araujosetmessages: - msg183924
2013-03-11 04:58:15eric.araujosetmessages: - msg183930
2013-03-11 04:58:13eric.araujosetmessages: - msg183923
2013-03-11 04:58:01eric.araujosetmessages: + msg183930
2013-03-11 04:33:11eric.araujosetmessages: + msg183924
2013-03-11 04:32:04eric.araujosetnosy: + eric.araujo
messages: + msg183923
2013-03-10 20:53:03asvetlovsetnosy: + asvetlov
2013-03-10 16:45:37rhettingersettitle: Fixed python3 descriptor documentation example + removal of explicit "object" inheritance in docs -> Remove explicit "object" inheritance in Python 3 docs
2013-03-10 16:42:42python-devsetmessages: + msg183885
2013-03-10 16:37:38python-devsetnosy: + python-dev
messages: + msg183884
2013-03-10 06:46:16rhettingersetmessages: + msg183870
2013-03-10 04:37:34ezio.melottisetnosy: + ezio.melotti
messages: + msg183867
2013-03-10 03:09:13nedbatsetnosy: + nedbat
messages: + msg183864
2013-03-09 07:34:15vinay.sajipsetmessages: + msg183804
2013-03-09 04:43:56terry.reedysetversions: + Python 3.2, Python 3.3, Python 3.4, - Python 3.1
nosy: + terry.reedy, michael.foord, vinay.sajip

messages: + msg183796

type: behavior
stage: patch review
2013-03-04 14:36:39pelsoncreate