Improve help('non-topic') response

[terryjreedy]

BPO	19980
Nosy	@terryjreedy, @ezio-melotti, @elias6, @zware, @serhiy-storchaka
Files	help-response.patch: Improve help('non-topic') response empty-help-response.patch: Issue 19980: Show error message when help('') is run from interactive prompt. issue19980.patch Issue19980.diff: Change following review issue19880v3.diff: Fixed line endings problem. issue19880v4.diff

^{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/serhiy-storchaka'
closed_at = <Date 2015-02-28.22:46:58.200>
created_at = <Date 2013-12-14.01:34:52.056>
labels = ['type-feature', 'library', 'docs']
title = "Improve help('non-topic') response"
updated_at = <Date 2015-02-28.22:46:58.198>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2015-02-28.22:46:58.198>
actor = 'serhiy.storchaka'
assignee = 'serhiy.storchaka'
closed = True
closed_date = <Date 2015-02-28.22:46:58.200>
closer = 'serhiy.storchaka'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2013-12-14.01:34:52.056>
creator = 'terry.reedy'
dependencies = []
files = ['33251', '34281', '35472', '36141', '37565', '38279']
hgrepos = []
issue_num = 19980
keywords = ['patch']
message_count = 26.0
messages = ['206157', '206159', '206777', '212690', '216084', '216142', '217668', '218721', '219154', '219166', '219695', '221098', '223847', '224177', '230029', '231506', '231507', '231514', '231519', '233206', '234910', '236896', '236903', '236918', '236921', '236922']
nosy_count = 10.0
nosy_names = ['terry.reedy', 'ezio.melotti', 'jesstess', 'docs@python', 'BreamoreBoy', 'elias', 'python-dev', 'zach.ware', 'serhiy.storchaka', 'Jessica.McKellar']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue19980'
versions = ['Python 3.5']

[terryjreedy]

>>> help(1)
# help on int
>>> help(b'a')
# help on bytes
>>> help('a')
no Python documentation found for 'a'

The reason for this unhelpful response is that strings are treated differently from all other non-class objects. (msg205861 thought this a bug.) The strings value is matched against strings that would be recognized at the help> prompt given after help().

>>> help('topics')
# list of TOPICS
>>> help('LISTS')
# information about mutable sequences

Suggestion: add something more about what to do. Example enhanced response:

No Python documentation found for 'a'. Try help('help') for information on recognized strings or help(str) for help on the str class.

I believe this could be backported since help() is intented for interactive use only.

[BreamoreBoy]

IMHO this must be changed.

>>> help('')
# nothing!!!
>>> help('a')
Help on module a:

...

I happened to have a module called a.py in the default directory.

[elias6]

I have created a patch that fixes this issue that terry.reedy described. It does not fix the problem described BreamoreBoy involving the empty string.

Please note that this is my first patch for Python so let me know if I am missing something or if I can do anything else to help.

[elias6]

Here is a patch that addresses the empty string problem described by @breamoreboy. I am not sure if this is the best way to handle it but it is better than what we have now.

[JessicaMcKellar]

Elias, thanks for your patch!

I think it's important to add the second part of Terry's suggestion which gives the user a specific next step to take, namely:

Try help('help') for information on recognized strings or help(str) for help on the str class.

Can you add that to your patch?

Additionally, we'll want to make sure we don't accidentally break this new functionality. Can you add a few test cases, for example what happens when you run help on a module (e.g. help("os"), 2) help on an instance of a class (e.g. help(1)), and help on a string that doesn't have a special meaning, (e.g. help("abcxyz"))?

I don't see any existing tests for help(), but it is an instance of site._Helper (as reported by type(help)), and site tests live in Lib/test/test_site.py. It also gets loaded into builtins, so tests could also live in Lib/test/test_builtins.py.

[terryjreedy]

help() uses lib/pydoc.py and pydoc tests are in test/test_pydoc.py
I think tests for things help does that pydoc does not do (help on topics?) should be in site.py.

[elias6]

Sorry for the late response but I have been busy with various things. I may
be able to work on this but I don't know when or how long it will take me.
I would suggest that someone else work on it if anyone wants it done any
time soon. I am sorry about this.

On Mon, Apr 14, 2014 at 7:43 AM, Jessica McKellar <report@bugs.python.org>wrote:

Jessica McKellar added the comment:

Elias, thanks for your patch!

I think it's important to add the second part of Terry's suggestion which
gives the user a specific next step to take, namely:

> Try help('help') for information on recognized strings or help(str) for
help on the str class.

Can you add that to your patch?

Additionally, we'll want to make sure we don't accidentally break this new
functionality. Can you add a few test cases, for example what happens when
you run help on a module (e.g. help("os"), 2) help on an instance of a
class (e.g. help(1)), and help on a string that doesn't have a special
meaning, (e.g. help("abcxyz"))?

I don't see any existing tests for help(), but it is an instance of
site._Helper (as reported by type(help)), and site tests live in
Lib/test/test_site.py. It also gets loaded into builtins, so tests could
also live in Lib/test/test_builtins.py.

----------
nosy: +Jessica.McKellar, jesstess

---

Python tracker <report@bugs.python.org>
<http://bugs.python.org/issue19980\>

---

[BreamoreBoy]

I propose the following. help('') returns help on strings in the same way that help([]) and help({}) returns help on lists and dicts respectively, further help(''.method) returns help on the string method or an attribute error, so this appears to me consistent. help('doh') returns enhanced output along the lines Terry suggested in msg206157. help('module') gives the path to the module as well as the help output, if any, as I think this could be useful in cases where you're looking for problems and have a stdlib module masked by a file of your own. Thoughts?

If we can come to an agreement I'll try and work up a patch.

Note that I've tried looking at the test code and it didn't make much sense to me, pointers welcome.

I've also just signed the contributor's agreement.

[BreamoreBoy]

Anybody?

[jesstess]

@breamoreboy, thanks for following up on this!

I propose the following. help('') returns help on strings in the same way that help([]) and help({}) returns help on lists and dicts respectively,

Sounds good.

further help(''.method) returns help on the string method or an attribute error, so this appears to me consistent.

This already happens (which I think you are saying, but it's a bit confusing in reading your message which functionality you are proposing to add and which functionality you are restating that already exists).

help('doh') returns enhanced output along the lines Terry suggested in msg206157.

Sounds good.

help('module') gives the path to the module as well as the help output, if any, as I think this could be useful in cases where you're looking for problems and have a stdlib module masked by a file of your own.

I think you are stating the current functionality?

Note that I've tried looking at the test code and it didn't make much sense to me, pointers welcome.

Do you have specific questions?

Terry suggests that help() tests for functionality using pydoc live in test_pydoc.py, and that help() tests for functionality not using pydoc live in test_site.py.

[BreamoreBoy]

Please find attached a first pass at a patch file. Help('') produces help for the str class as discussed. I found the difference between help('help') and help() very confusing. The former produced the help output but left you at the interactive prompt, the latter took you to the help utility. Both now take you to the help utility. I've changed the test file but two test fail, here's the output from one as they're virtually identical.

FAIL: test_input_strip (test.test_pydoc.PydocDocTest)
----------------------------------------------------------------------

Traceback (most recent call last):
  File "c:\cpython\lib\test\test_pydoc.py", line 429, in test_input_strip
    self.assertEqual(expected, result)
AssertionError: 'No P[49 chars]e\'.\nUse help("help") or just help() to get t[66 chars]ass.' != 'No P[49 chars]e\'.\r\nUse help("help") or just help() to get[70 chars]ass.'
- No Python documentation found for 'test.i_am_not_here'.
+ No Python documentation found for 'test.i_am_not_here'.
?                                                        +
- Use help("help") or just help() to get the interactive help utility.
+ Use help("help") or just help() to get the interactive help utility.
?                                                                     +
  Use help(str) for help on the str class.

I can't see where the difference between the .\nUse and .\r\nUse is coming from so thought fresh eyes would do the job.