[issue20285] Improve object.__doc__ and help(object) output

[Cheryl Sabella]

Cheryl Sabella  added the comment:


New changeset c95c93d4eb0519beaa06e6b6e0ecca7c2a58f69c by Cheryl Sabella in 
branch 'master':
bpo-20285: Improve help docs for object (GH-4759)
https://github.com/python/cpython/commit/c95c93d4eb0519beaa06e6b6e0ecca7c2a58f69c


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Cheryl Sabella]

Change by Cheryl Sabella :


--
resolution:  -> fixed
stage: commit review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Reponses on the pydev thread, which include 3 other coredevs:

"a base for all classes." object entry in lib ref, function
"the ultimate base class of all other classes."  Martin Panter

object is neither a base or superclass of itself, so the first of each pair 
above is not quite right.

"the base class of the class heirarchy ['hierarchy']"  Steven D'Aprano
"the root of the class heirarchy"  ditto
+ quotes from Java and Ruby

Jeff Allen and Barry Warsaw like either, with BW slightly referring the first.

I was thinking about 'tree' instead of 'hierachy', but 'class tree' is wrong 
and 'directed acyclic graph of classes' a bit wordy.  While hierarchies are 
often thought of as trees, it is possible for someone to report to more than 
one person.

No one supported the status quo.

Martin also suggested a continuation:  "When called, it accepts no
arguments and returns a new unique and featureless object."

Even though object, unlike any other class, is primarily used as a base class 
rather than instance source, the latter should be included.  For other built-in 
classes, the summary line describes instances. I would leave out 'unique' as 
that could be confused with 'singleton'.


I propose the following, which follows general docstring format, but describes 
the class instead of instances in the summary line.

"The base class of the class hierarchy.

When called, it accepts no arguments and returns a new featureless instance 
that has no instance attributes and cannot be given any."

Passing arguments to object and trying to add attributes to object instances 
are two common beginner mistakes.

--
versions: +Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[R. David Murray]

R. David Murray  added the comment:

If you want to be precise you could say "The last class in every __mro__ list."

--
nosy: +r.david.murray

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Terry J. Reedy]

Terry J. Reedy  added the comment:

I posted "Is object the most base type?  (bpo-20285)" on pydev.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Since this modifies the output of a library module function for a specific 
input, I will not backport unless and until there is agreement on doing so.

--
versions:  -Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

It is better to ask Guido or other language expert.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Terry J. Reedy]

Change by Terry J. Reedy :


--
assignee: docs@python -> terry.reedy
components: +Library (Lib)
stage: patch review -> commit review
versions: +Python 3.6, Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Terry J. Reedy]

Terry J. Reedy  added the comment:

How about "The starting base class of all types and classes other than itself." 
(Object.__bases__ = ().)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

"Python class" can be read as a user type defined in Python (usually with the 
"class" statement). The term "class" in the glossary is used with this meaning 
in contrary to the term "type" which means also builtin and extension types. In 
Python 3 "object" is a base class of all types, not only user-defined class.

--
nosy: +serhiy.storchaka

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Terry J. Reedy]

Terry J. Reedy  added the comment:

After looking at https://en.wiktionary.org/wiki/base I can explain better why 
'most base class' is wrong, and felt wrong to participants in the python-list 
thread.

'Base' is actually two words.  As a noun (or verb), it comes from Ancient Greek 
βάσις (básis), a foundation from which other things extend or derive.  As an 
adjective, it comes from Late Latin bassus (“low”).

In computer science and Python, the couplet 'base class' is being used, it 
seems to me and apparently others, as a noun-noun compound, meaning, 
'foundation class', not as an adjective-noun phrase meaning 'low class' (let 
along 'depraved class').  However, 'most base class' must be parsed as '(most 
base) class', with 'base' re-interpreted as the adjective meaning 'low' (or 
worse).  The switch in meaning of 'base' is similar in 'baseball' versus  'most 
base ball'.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Cheryl Sabella]

Cheryl Sabella  added the comment:

Hi Terry,

I've submitted a PR for this.  Thanks!

--
nosy: +csabella

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Cheryl Sabella]

Change by Cheryl Sabella :


--
keywords: +patch
pull_requests: +4662
stage: test needed -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Cheryl Sabella]

Change by Cheryl Sabella :


--
assignee:  -> docs@python
components: +Documentation
nosy: +docs@python
versions: +Python 3.7 -Python 2.7, Python 3.3, Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Martin Panter]

Changes by Martin Panter :


--
nosy: +vadmium

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Terry J. Reedy]

Terry J. Reedy added the comment:

Rather, 'all classes' should be 'all new-style classes'.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Terry J. Reedy]

Terry J. Reedy added the comment:

On python-list, Jean-Michel Pichavant pointed out that the status of object is 
different in 2.7. 'for new-style classes' would have to be added. 2.7 currently 
has the same output, but the meaning is slightly different as type and class 
are slightly different there.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue20285] Improve object.__doc__ and help(object) output

[Terry J. Reedy]

New submission from Terry J. Reedy:

>>> object.__doc__
'The most base type'

Since 'most base' can be interpreted as 'least desireable', several people on 
Python list (2013 Dec, "interactive help on the base object") agree that this 
should be improved. Even is 'most base' is interpreted as a value-free 
'bottommost', there is the direction issue. Whether the root of a tree or DAG 
is at top or bottom or side depends on how the graph is drawn. I suggest

"The superclass for all Python classes."

===
>>> help(object)
Help on class object in module builtins:

class object
 |  The most base type
===

I think help(object) should display the methods defined on the object class 
just as it does on all the other classes. The apparent problem is that 
help(subclass) supresses the object methods, but it should not for object 
itself.

--
messages: 208317
nosy: terry.reedy
priority: normal
severity: normal
stage: test needed
status: open
title: Improve object.__doc__ and help(object) output
type: behavior
versions: Python 2.7, Python 3.3, Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com