classification
Title: Improve object.__doc__ and help(object) output
Type: behavior Stage: commit review
Components: Documentation, Library (Lib) Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: cheryl.sabella, docs@python, martin.panter, r.david.murray, serhiy.storchaka, terry.reedy
Priority: normal Keywords: patch

Created on 2014-01-17 00:59 by terry.reedy, last changed 2018-02-12 00:22 by terry.reedy.

Pull Requests
URL Status Linked Edit
PR 4759 open cheryl.sabella, 2017-12-09 01:34
Messages (12)
msg208317 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-01-17 00:59
>>> 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.
msg208363 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-01-17 21:17
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.
msg208364 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-01-17 21:21
Rather, 'all classes' should be 'all new-style classes'.
msg307898 - (view) Author: Cheryl Sabella (cheryl.sabella) * Date: 2017-12-09 13:02
Hi Terry,

I've submitted a PR for this.  Thanks!
msg307914 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-12-09 19:51
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'.
msg307916 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-12-09 21:14
"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.
msg307927 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-12-09 22:46
How about "The starting base class of all types and classes other than itself." (Object.__bases__ = ().)
msg311478 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-02-02 06:12
It is better to ask Guido or other language expert.
msg311479 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-02-02 06:35
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.
msg311482 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-02-02 06:53
I posted "Is object the most base type?  (bpo-20285)" on pydev.
msg311492 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2018-02-02 14:09
If you want to be precise you could say "The last class in every __mro__ list."
msg312025 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-02-12 00:22
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.
History
Date User Action Args
2018-02-12 00:22:31terry.reedysetmessages: + msg312025
versions: + Python 3.6, Python 3.7
2018-02-02 14:09:04r.david.murraysetnosy: + r.david.murray
messages: + msg311492
2018-02-02 06:53:32terry.reedysetmessages: + msg311482
2018-02-02 06:35:52terry.reedysetmessages: + msg311479
versions: - Python 3.6, Python 3.7
2018-02-02 06:12:05serhiy.storchakasetmessages: + msg311478
2018-02-02 05:29:37terry.reedysetassignee: docs@python -> terry.reedy
stage: patch review -> commit review
components: + Library (Lib)
versions: + Python 3.6, Python 3.8
2017-12-09 22:46:19terry.reedysetmessages: + msg307927
2017-12-09 21:14:46serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg307916
2017-12-09 19:51:55terry.reedysetmessages: + msg307914
2017-12-09 13:02:53cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg307898
2017-12-09 01:35:14cheryl.sabellasetassignee: docs@python

nosy: + docs@python
components: + Documentation
versions: + Python 3.7, - Python 2.7, Python 3.3, Python 3.4
2017-12-09 01:34:05cheryl.sabellasetkeywords: + patch
stage: test needed -> patch review
pull_requests: + pull_request4662
2015-01-12 02:02:26martin.pantersetnosy: + martin.panter
2014-01-17 21:21:25terry.reedysetmessages: + msg208364
2014-01-17 21:17:49terry.reedysetmessages: + msg208363
2014-01-17 00:59:11terry.reedycreate