This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Poor documentation of new-style classes
Type: Stage:
Components: Documentation Versions: Python 2.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: georg.brandl, hfuru, jimjjewett, rhettinger, zseil
Priority: normal Keywords:

Created on 2004-05-25 19:30 by hfuru, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (8)
msg20880 - (view) Author: Hallvard B Furuseth (hfuru) Date: 2004-05-25 19:30
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>.
msg20881 - (view) Author: Jim Jewett (jimjjewett) Date: 2004-05-25 22:13
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.
msg20882 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2004-05-26 04:45
Logged In: YES 
user_id=80475

The glossary in the tutorial was added to meet this need.
msg20883 - (view) Author: Jim Jewett (jimjjewett) Date: 2004-05-26 13:48
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.)
msg20884 - (view) Author: Hallvard B Furuseth (hfuru) Date: 2004-06-01 18:37
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'.
msg20885 - (view) Author: Ziga Seilnacht (zseil) * (Python committer) Date: 2006-03-31 14:50
Logged In: YES 
user_id=1326842

This was fixed in revision 41814, when a section
titled New-style and classic classes was added
to the reference manual. See:
http://docs.python.org/dev/ref/node33.html
This bug should be closed and resolution changed to fixed.
msg20886 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2006-03-31 15:12
Logged In: YES 
user_id=849994

Added index entries in 43480. All else seems to be explained
properly now.
msg20887 - (view) Author: Jim Jewett (jimjjewett) Date: 2006-03-31 16:06
Logged In: YES 
user_id=764593

Slight typo at http://docs.python.org/dev/ref/node33.html

manuel ==> manual

The spelling of "flavour" (rather than "flavor") also 
sticks out, but I can't say its wrong; I just hadn't seen 
British spelling on other words in the documents.
History
Date User Action Args
2022-04-11 14:56:04adminsetgithub: 40288
2004-05-25 19:30:14hfurucreate