Skip to content

gh-137574: Add Support For Special Names in help #137966

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 23 commits into
base: main
Choose a base branch
from

Conversation

adqm
Copy link
Contributor

@adqm adqm commented Aug 19, 2025

Following on from #137574, this is an attempt to provide better help for special names from the built-in help function.

The original question was about help('__name__') and help('__dict__'), which suggested help for the str and dict built-in types, respectively, instead of reporting an error that no help was available for those topics. I also took this a step further, adding help for the special method names described on the 'Data Model' page of the language reference, as well as '__name__' and '__main__'.

Here's a quick summary of the changes I made:

  • When requesting help on a name '__x__', only report on the result of getattr(builtins, '__x__') if it is a type or a built-in function, preventing the confusion described above.

  • Added help for __name__, __main__, and the special method names as help topics.

  • Added "specialnames" as a new top-level category, and included it as a suggestion if we were looking up a name starting and ending with __.

  • Added a reference to the online Python docs in the message when a help topic isn't found, and slightly changed the wording of that message, hoping not to imply that things that don't have associated help topics aren't documented at all.

If any of these changes is a bridge too far, I can roll them back. Two other concerns, as well:

  • The code style of pydoc.py doesn't match what ruff would output, in a number of places. I opted to mimic the existing code's style rather than using input that ruff would be happy with; I can reformat, though, if that would be better.

  • One of the tests I added (which tests that each dunder method shows up in its help output) is quite slow. I could rework that so that it only tests a few names if that test being slow is a problem.


📚 Documentation preview 📚: https://cpython-previews--137966.org.readthedocs.build/

@AA-Turner
Copy link
Member

This PR is way too big. Also, don't regenerate pydoc_data, it's done during the release process.

@ZeroIntensity
Copy link
Member

I think the majority of the diff is from pydoc_data.

@AA-Turner
Copy link
Member

I'm on mobile so it's hard to tell (the pydoc data diff doesn't even render). I'll look at the PR substantively over the week though.

@adqm
Copy link
Contributor Author

adqm commented Aug 20, 2025

It is definitely true that most of the diff here is coming from pydoc_data (and another big chunk from the hard-coded list of dunder methods in pydoc.py).

I had regenerated pydoc_data because part of the change here was adding a couple of topics to it; without it, some of the new topics (__main__, __name__, __instancecheck__, __subclasscheck__) won't work. For now I've reverted all of the changes to pydoc_data other than the ones that are relevant to the additions here; and I can roll those back, too, if that's better (though again, those new topics won't have their help output without regenerating the file locally).

@ZeroIntensity
Copy link
Member

though again, those new topics won't have their help output without regenerating the file locally

I think that's fine, we want to keep the diff down as much as possible. Someone (presumably Hugo) will regenerate it when it's time to do 3.15a1.

@adqm
Copy link
Contributor Author

adqm commented Aug 20, 2025

OK, sounds fair. Some of my new tests won't pass without the additions to pydoc_data, though; should I remove those tests, too?

@ZeroIntensity
Copy link
Member

Hm, I'm not sure then. We should look into previous PRs to see what they did.

@adqm
Copy link
Contributor Author

adqm commented Aug 20, 2025

Taking a quick look at git log --patch Lib/pydoc_data/, it looks like there are some (but not many) changes to pydoc_data in between releases. For example, 6266689 and 447a151 seem to be a similar kind of change to what I'm proposing here (adding a reference to the docs and to pydoc) .

I'll leave things here for now (the changes to pydoc_data are only those relevant to the changes in this PR), but I can of course still revert things later if need be.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants