classification
Title: Replace confusing pseudoname 'object' in special methods section.
Type: Stage: needs patch
Components: Documentation Versions: Python 3.3, Python 3.4
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, georg.brandl, peterrecore, terry.reedy
Priority: normal Keywords: patch

Created on 2010-08-07 20:04 by terry.reedy, last changed 2013-04-14 01:34 by terry.reedy.

Files
File name Uploaded Description Edit
issue9538.patch peterrecore, 2013-04-13 18:39 patched against 3.4 review
Messages (8)
msg113194 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-07 20:04
In 3.3. Special method names, 'object' is used as a pseudo class name to prefix all the special method entries. This conflicts with the usual two Python meanings.

1. 'object' is the name of a specific class. So the entry for object.__getattribute__(self, name) says to avoid circularity by calling
object.__getattribute__(self, name), which looks circular and requires a bit a mental work by the reader to properly understand. Ditto for
object.__setattr__(self, name, value) calling
object.__setattr__(self, name, value)

2. Non-specifically, 'object' is usually understood to mean any Python object, not just a class. But the signatures as written require that 'object' specifically be a class and 'object' does not convey that.

So for both reasons, I propose that the pseudoname 'object' be replaces with 'class' or 'someclass'
msg113195 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-07 20:08
I also think that in "In order to avoid infinite recursion in this method, its implementation should always call the base class method with the same name to access any attributes it needs, for example, object.__getattribute__(self, name).", 'the base class' should be 'a base class' or 'a superclass' since there might be more than one base/super class. Ditto for __setattr__.
msg113196 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-07 20:15
I filed this because I just reread the __getattr(ibute)__ entries to respond to #8722 and found myself again stumbling over the 'object' confusion.
msg113211 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-08-07 21:34
Good catch!

Names listed under language reference section 3.3.1 actually all exist on object, e.g. object.__new__¹. It is section 3.3.2 that lists names that *can* be defined but don’t have a default implementation on object, so +1 on using “someclass” here to be clear. Oh, and let’s change “class” to “someclass” too in the examples under 3.3.4, to use valid syntax and consistent naming.

I think we should not change “the base class”, since even with multiple bases a class still has one most immediate parent, found in cls.__base__ (a.k.a. cls.__bases__[0]).

¹ with the exception of __bool__ and the lack of __reduce{_ex,}__ and __subclasshook__; I’ll open a bug about those.
msg186790 - (view) Author: peter recore (peterrecore) * Date: 2013-04-13 18:39
Here is a patch that implements Eric's suggestion.  I am a new contributor and would welcome feedback on if this is correct or not.
msg186804 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-04-13 19:29
Note that Sphinx searches for "object.__foo__" when :meth:`__foo__` is used; this change will break all those links.

For that reason I'm -1 to this change: I don't see the perceived issue as problematic anyway.
msg186824 - (view) Author: peter recore (peterrecore) * Date: 2013-04-13 20:20
George,

When I build the docs with my changes, the links from the method names seem to work the same way as they do in the existing docs.
msg186874 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-04-14 01:34
The problem, for me, is that in 3.3 Data Model, 'object' is being used with a 3rd meaning, 'generic class' (or possibly 'subclass of object', if indeed every 'class' must be 'object' subclass, in the strict sense of 'object'). This is in addition to 'object' the specific class and generic Python object (which in CPython is a PyObject structure instance). The normal two meanings are often differentiated by typography: normal type for plain old object, something else for *object*.

To add a bit to the confusion, 3.3.4. Customizing instance and subclass checks changes the prefix to 'class' instead of 'object' (which is what I would do in the whole section...)

class.__instancecheck__(self, instance)
class.__subclasscheck__(self, subclass)

It then goes on to explain that it does not really mean 'generic class' but 'type/metaclass'. So, to me, the prefix here should really be 'metaclass'.

Peter, the patch applied fine to my copy of default. It is incomplete in that the replacement should be made everywhere or nowhere in 3.3, not just in 3.3.2(.0) and 3.3.2.1. However, do not bother making a new patch until there is more agreement on a change than there is now.

A possible alternative to the given proposal is an explanation in the short 3.3 header of the special use of 'object' within the section.
History
Date User Action Args
2013-04-14 01:34:08terry.reedysetmessages: + msg186874
versions: + Python 3.3, Python 3.4, - Python 3.2
2013-04-13 20:20:52peterrecoresetmessages: + msg186824
2013-04-13 19:29:18georg.brandlsetmessages: + msg186804
2013-04-13 18:39:01peterrecoresetfiles: + issue9538.patch

nosy: + peterrecore
messages: + msg186790

keywords: + patch
2010-08-07 21:34:59eric.araujosetnosy: + eric.araujo
messages: + msg113211
2010-08-07 20:15:39terry.reedysetmessages: + msg113196
2010-08-07 20:08:13terry.reedysetmessages: + msg113195
2010-08-07 20:04:37terry.reedycreate