GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — bpo-20285: Improve help docs for object by csabella · Pull Request #4759 · python/cpython

Conversation

@csabella

@csabella csabella commented Dec 9, 2017 •
edited by bedevere-bot
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

Improve the docstring for object and show object methods when using help(object).

https://bugs.python.org/issue20285

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@the-knights-who-say-ni the-knights-who-say-ni added the CLA signed label Dec 9, 2017
@bedevere-bot bedevere-bot added the awaiting review label Dec 9, 2017
serhiy-storchaka
serhiy-storchaka reviewed Dec 9, 2017
View reviewed changes

@serhiy-storchaka serhiy-storchaka left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't the beginners be confused by the term "superclass"?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread Lib/pydoc.py Outdated

@serhiy-storchaka serhiy-storchaka Dec 9, 2017

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the purpose of this change?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@terryjreedy terryjreedy Dec 9, 2017

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The have help(object) print the methods defined on object, the same as it does for every other class.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@csabella csabella Dec 9, 2017

Copy link
Copy Markdown
Contributor Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One confusing thing about this module is that the argument that the docs are being created for is named is object. So, for this PR, object both can refer to the name of the argument and the class called object.

thisclass is the third value (index 2) in the sequence returned from inspect.classify_class_attrs(object), which is defined as "The class which defined this attribute" (from the docstring). When the value of the class is object, the current if statement if thisclass is builtins.object: results in that attribute being skipped from the output.

The change is to skip the logic when the argument value is not builtins.object so that the attributes will be displayed when help(object) is used. Without this change, all of the attributes are skipped because "The class which defined this attribute" is always object.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
cryvate
cryvate reviewed Dec 9, 2017
View reviewed changes
Comment thread Objects/typeobject.c Outdated

@cryvate cryvate Dec 9, 2017

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for -> of

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions

@terryjreedy terryjreedy Dec 9, 2017

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To me, 'of' has more of an implication of immediate superclass. But see my response to Serhiy.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
terryjreedy
terryjreedy requested changes Dec 9, 2017
View reviewed changes

@terryjreedy terryjreedy left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

help(someclass) prints someclass.doc and then prints the methods defined 'here' (on someclass). The goal of the issue is to improve 'help(object)' in two ways.

  1. Replace the current docstring. I think my initial proposal needs at least one word added and further changes are up for discussion.

  2. Actually print the methods defined on object. The patch lists the same methods as returned by dir(object). The pydoc change looks correct to me. I presume that the format of the typeobject change is correct since Serhiy did not say otherwise.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@bedevere-bot

bedevere-bot commented Dec 9, 2017

Copy link
Copy Markdown

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-bot bedevere-bot added awaiting changes and removed awaiting review labels Dec 9, 2017
csabella added 2 commits December 22, 2017 17:41
@csabella
bpo-20285: Improve help docs for object
c6e7fe9
@csabella
Requested changes.
6ea9419
@csabella
csabella force-pushed the bpo20285 branch from 29fd10c to 6ea9419 Compare December 22, 2017 22:41
@csabella

csabella commented Dec 22, 2017

Copy link
Copy Markdown
Contributor Author

@terryjreedy I don't quite understand what changes you'd like me to make. I changed the docstring to match what you asked about on the bug tracker for #1, but I'm not sure what you mean by 'Actually print the methods defined on object.'. Thanks!

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@terryjreedy

terryjreedy commented Feb 2, 2018

Copy link
Copy Markdown
Member

Your initial patch fixed the help output. The second has the wording I suggested on the issue. I will expand the news entry a bit.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

terryjreedy added 2 commits February 2, 2018 01:18
@terryjreedy
Merge remote-tracking branch 'upstream/master' into pr_4759
5b4d0e6
@terryjreedy
Modify news.
cc58380
@terryjreedy

terryjreedy commented Feb 12, 2018

Copy link
Copy Markdown
Member

Absent an even better suggestion, I would like to go with this docstring, resulting from pydev discussion (see the tracker).

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

terryjreedy
terryjreedy requested changes Feb 12, 2018
View reviewed changes
Comment thread Objects/typeobject.c Outdated
};

PyDoc_STRVAR(object_doc,
"object()\n--\n\nThe starting base class of all types and classes other\n"

@terryjreedy terryjreedy Feb 12, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not familiar with docstrings in C code, but it appears that 'classname()\n--\n\n' gets removed before making the rest into the class object doc attribute.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread Objects/typeobject.c Outdated

PyDoc_STRVAR(object_doc,
"object()\n--\n\nThe starting base class of all types and classes other\n"
"than itself.");

@terryjreedy terryjreedy Feb 12, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first line of a docstring, if not too long, should not have an embedded \n. So I think this should have been written

"object()\n--\n\n"
"The starting base class of all types and classes other than itself\n"

My suggested replacement would then be

"object()\n--\n\n"
"The base class of the class hierarchy.\n\n"
"When called, it accepts no arguments and returns a new featureless\n"
"instance that has no instance attributes and cannot be given any.\n"

A limit of 72 columns with a 4 column indent allows 68 chars. The longest above is 66.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
csabella added 2 commits February 12, 2018 18:25
@csabella
Improve docstring for object
6abc7f3
@csabella
Merge branch 'bpo20285' of github.com:csabella/cpython into bpo20285
fce40fe
@csabella

csabella commented Feb 12, 2018

Copy link
Copy Markdown
Contributor Author

@terryjreedy I've applied the changes. Thanks!

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@csabella
csabella requested review from serhiy-storchaka and terryjreedy May 23, 2019 23:10
@terryjreedy
Merge remote-tracking branch 'origin/master' into pr_4759
51b59fd
terryjreedy
terryjreedy approved these changes May 24, 2019
View reviewed changes
@bedevere-bot bedevere-bot added awaiting merge and removed awaiting changes labels May 24, 2019
@terryjreedy

terryjreedy commented May 24, 2019

Copy link
Copy Markdown
Member

help(object) now looks correct on my machine, after the update merge. Rather than run test suite locally, I pushed to have patch to core object tested with current code on all CI systems. I believe there have been other patches to object.c since last CI run.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@csabella

csabella commented May 24, 2019

Copy link
Copy Markdown
Contributor Author

Thanks @terryjreedy! It looks like all the CI tests have passed, so I"m going to merge this.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@csabella
csabella merged commit c95c93d into python:master May 24, 2019
@bedevere-bot bedevere-bot removed the awaiting merge label May 24, 2019
@csabella
csabella deleted the bpo20285 branch May 24, 2019 10:43
DinoV pushed a commit to DinoV/cpython that referenced this pull request Jan 14, 2020
@csabella @DinoV
bpo-20285: Improve help docs for object (pythonGH-4759)
b921be6
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@terryjreedy terryjreedy terryjreedy approved these changes
@serhiy-storchaka serhiy-storchaka Awaiting requested review from serhiy-storchaka
+1 more reviewer
@cryvate cryvate cryvate left review comments
Reviewers whose approvals may not affect merge requirements

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

6 participants

@csabella @bedevere-bot @terryjreedy @serhiy-storchaka @cryvate @the-knights-who-say-ni
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.