Poor documentation of new-style classes

[hfuru]

BPO	960340
Nosy	@birkenfeld, @rhettinger

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2006-03-31.16:06:10.000>
created_at = <Date 2004-05-25.19:30:14.000>
labels = ['docs']
title = 'Poor documentation of new-style classes'
updated_at = <Date 2006-03-31.16:06:10.000>
user = 'https://bugs.python.org/hfuru'

bugs.python.org fields:

activity = <Date 2006-03-31.16:06:10.000>
actor = 'jimjjewett'
assignee = 'none'
closed = True
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2004-05-25.19:30:14.000>
creator = 'hfuru'
dependencies = []
files = []
hgrepos = []
issue_num = 960340
keywords = []
message_count = 8.0
messages = ['20880', '20881', '20882', '20883', '20884', '20885', '20886', '20887']
nosy_count = 5.0
nosy_names = ['georg.brandl', 'rhettinger', 'jimjjewett', 'hfuru', 'zseil']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue960340'
versions = ['Python 2.3']

[hfuru]

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

[jimjjewett]

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.

[rhettinger]

Logged In: YES
user_id=80475

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

[jimjjewett]

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

[hfuru]

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

[zseil]

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.

[birkenfeld]

Logged In: YES
user_id=849994

Added index entries in 43480. All else seems to be explained
properly now.

[jimjjewett]

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.