Skip to content

Improve object.__doc__ and help(object) output #64484

Closed
Closed
Improve object.__doc__ and help(object) output#64484
Assignees
terryjreedy
Labels
3.7 (EOL)end of life3.8 (EOL)end of lifedocsDocumentation in the Doc dirstdlibStandard Library Python modules in the Lib/ directorytype-bugAn unexpected behavior, bug, or error

Description

@terryjreedy
terryjreedy
opened on Jan 17, 2014
BPO 20285
Nosy @terryjreedy, @bitdancer, @vadmium, @serhiy-storchaka, @csabella
PRs
  • bpo-20285: Improve help docs for object #4759
    		•

    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 = 'https://github.com/terryjreedy'
closed_at = <Date 2019-05-24.10:44:12.359>
created_at = <Date 2014-01-17.00:59:11.587>
labels = ['3.7', '3.8', 'type-bug', 'library', 'docs']
title = 'Improve object.__doc__ and help(object) output'
updated_at = <Date 2019-05-24.10:44:12.359>
user = 'https://github.com/terryjreedy'

    bugs.python.org fields:

    activity = <Date 2019-05-24.10:44:12.359>
actor = 'cheryl.sabella'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2019-05-24.10:44:12.359>
closer = 'cheryl.sabella'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2014-01-17.00:59:11.587>
creator = 'terry.reedy'
dependencies = []
files = []
hgrepos = []
issue_num = 20285
keywords = ['patch']
message_count = 13.0
messages = ['208317', '208363', '208364', '307898', '307914', '307916', '307927', '311478', '311479', '311482', '311492', '312025', '343367']
nosy_count = 6.0
nosy_names = ['terry.reedy', 'r.david.murray', 'docs@python', 'martin.panter', 'serhiy.storchaka', 'cheryl.sabella']
pr_nums = ['4759']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue20285'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

    Activity

    1. terryjreedy commented on Jan 17, 2014

      @terryjreedy
      terryjreedy
      on Jan 17, 2014
      MemberAuthor
      >>> 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.

    2. terryjreedy
      added
      type-bugAn unexpected behavior, bug, or error
      on Jan 17, 2014

    3. terryjreedy commented on Jan 17, 2014

      @terryjreedy
      terryjreedy
      on Jan 17, 2014
      MemberAuthor

      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.

    4. terryjreedy commented on Jan 17, 2014

      @terryjreedy
      terryjreedy
      on Jan 17, 2014
      MemberAuthor

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

    5. csabella
      added
      docsDocumentation in the Doc dir
      3.7 (EOL)end of life
      on Dec 9, 2017
    6. csabella
      assigned
      docspython
      on Dec 9, 2017

    7. csabella commented on Dec 9, 2017

      @csabella
      csabella
      on Dec 9, 2017
      Contributor

      Hi Terry,

      I've submitted a PR for this. Thanks!

    8. terryjreedy commented on Dec 9, 2017

      @terryjreedy
      terryjreedy
      on Dec 9, 2017
      MemberAuthor

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

    9. serhiy-storchaka commented on Dec 9, 2017

      @serhiy-storchaka
      serhiy-storchaka
      on Dec 9, 2017
      Member

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

    10. terryjreedy commented on Dec 9, 2017

      @terryjreedy
      terryjreedy
      on Dec 9, 2017
      MemberAuthor

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

    11. terryjreedy
      added
      3.8 (EOL)end of life
      stdlibStandard Library Python modules in the Lib/ directory
      on Feb 2, 2018
    12. terryjreedy
      assigned
      terryjreedy
      and unassigned
      docspython
      on Feb 2, 2018

    13. serhiy-storchaka commented on Feb 2, 2018

      @serhiy-storchaka
      serhiy-storchaka
      on Feb 2, 2018
      Member

      It is better to ask Guido or other language expert.

    14. terryjreedy commented on Feb 2, 2018

      @terryjreedy
      terryjreedy
      on Feb 2, 2018
      MemberAuthor

      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.

    15. terryjreedy
      removed
      3.7 (EOL)end of life
      on Feb 2, 2018

    16. terryjreedy commented on Feb 2, 2018

      @terryjreedy
      terryjreedy
      on Feb 2, 2018
      MemberAuthor

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

    17. bitdancer commented on Feb 2, 2018

      @bitdancer
      bitdancer
      on Feb 2, 2018
      Member

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

    18. terryjreedy commented on Feb 12, 2018

      @terryjreedy
      terryjreedy
      on Feb 12, 2018
      MemberAuthor

      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.

    19. terryjreedy
      added
      3.7 (EOL)end of life
      on Feb 12, 2018

    20. csabella commented on May 24, 2019

      @csabella
      csabella
      on May 24, 2019
      Contributor

      New changeset c95c93d by Cheryl Sabella in branch 'master':
      bpo-20285: Improve help docs for object (GH-4759)
      c95c93d

    21. csabella
      closed this as completedon May 24, 2019
    22. ezio-melotti
      transferred this issue fromon Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    Labels

    3.7 (EOL)end of life3.8 (EOL)end of lifedocsDocumentation in the Doc dirstdlibStandard Library Python modules in the Lib/ directorytype-bugAn unexpected behavior, bug, or error

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions