[ python-Bugs-960340 ] Poor documentation of new-style classes

[SourceForge.net]

Bugs item #960340, was opened at 2004-05-25 21:30
Message generated for change (Comment added) made by hfuru
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=960340&group_id=5470

Category: Documentation
Group: Python 2.3
Status: Open
Resolution: None
Priority: 5
Submitted By: Hallvard B Furuseth (hfuru)
Assigned to: Nobody/Anonymous (nobody)
Summary: Poor documentation of new-style classes

Initial Comment:
The Python Reference Manual (info file python-ref)
talks a lot about new-style classes, but does
not say what they are, except in a brief note
buried in node 'Coercion rules'.  The library
reference does say that object() creates such
classes, that too lacks a way to look up
'new-style classes' and find object().

Also, since 'object' is a type, it seems strange
that the Library Reference has it in the
'Built-in Functions' node instead of a node
about (callable) types.  The same applies to
several other types.  If you want to keep them
there, at least add index entries for them in
the Class-Exception-Object Index.

This refers to the doc in info-2.3.3.tar.bz2
from <http://docs.python.org/download.html>.


----------------------------------------------------------------------

>Comment By: Hallvard B Furuseth (hfuru)
Date: 2004-06-01 20:37

Message:
Logged In: YES 
user_id=726647

Index to the language reference, yes.  And I think the
types of classes should be lifted to the header of a
paragraph.  Maybe just something like this, before
the Programmer's note:

New-style vs. old-style/classic classes:
Subclasses of 'object' are called new-style classes, other
classes are called old-style or classic classes.  Note
that all standard types such as 'int' and 'dict' are
subclasses of 'object'.  [If that latest part is true.
It seems to be about right, anyway.]

Maybe you had better also explain here or in section 3.1
(Objects, values and types) that not all objects are
subclasses of 'object'.

----------------------------------------------------------------------

Comment By: Jim Jewett (jimjjewett)
Date: 2004-05-26 15:48

Message:
Logged In: YES 
user_id=764593

That's a start, but I do think "classic class", "old class", and 
"new-style class" should show up in the index to the language 
reference as well.

One obvious (but perhaps not sufficient?) place is the 
programmers note at the bottom of 7.6, class definitions.  
<URL: http://www.python.org/dev/doc/devel/ref/class.html >

Just change:

"For new-style classes, descriptors ..."

to:

"For new-style classes (those inheriting from object), 
descriptors ..."

The language lawyer reference also seems like the right place 
to list all the differences between classic and new classes, but 
I am less certain how to do that properly.  (And it starts to be 
an Enhancement request.)


----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2004-05-26 06:45

Message:
Logged In: YES 
user_id=80475

The glossary in the tutorial was added to meet this need.

----------------------------------------------------------------------

Comment By: Jim Jewett (jimjjewett)
Date: 2004-05-26 00:13

Message:
Logged In: YES 
user_id=764593

object() doesn't create a new-style class; it creates an 
instance of class object.

Note that the definition of a new-style class is just a class 
inheriting from object, so object itself is a new-style class.

That said, the distributed documentation should probably have 
something more about "new-style" vs "old-style" classes, and 
should have a reference in the index.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=960340&group_id=5470