Help mode improvement.
Hi there! I want to make an improvement connected with the interactive help mode. Example: You want to check some keys in the dictionary, but you can't remember the syntax of the command. If you type something like this: help(key), the interpreter will output an error. Because help(key) is just a plain expression, and it tries to evaluate key first before even calling help(). Maybe help(*key*) could make it work? In my opinion it will be very helpful for newcomers if the interpreter could search for similar commands and output them all. Code listing: help(*key*) - [1] D.has_key() [2] D.keys() … To learn more you should type the number. I think the game is worth the candle if the suggested feature could work as fast as the current helper. Kind regards.
Stayvoid wrote:
Remember that the help() function is just a regular function, like any other. It isn't magic, and it can't accept anything that isn't a valid Python object. That won't change. help(math) won't work unless you have imported the math module first. help(key) won't work unless you actually have a name `key`, in which case it will work but it may not do what you are expecting. help(*key*) can't work because *key* is a SyntaxError. However, help('key') would work. It currently says:
help('key') no Python documentation found for 'key'
Perhaps help should be more aggressive at trying to find something useful before giving up. Or you could just encourage the beginner to use help interactively, by calling help() with no arguments, then following the prompts.
In my opinion it will be very helpful for newcomers if the interpreter could search for similar commands and output them all.
A keyword search facility, familiar to Linux users as `man -k key` or `apropos key`, might be useful. Or it might also complicate the interactive help for no good reason. Beware of trying to make help() do too much. Remember also that help() is not a substitute for the Python documentation and tutorials. It is not aimed at teaching beginners the basics. You actually need a reasonably good grasp of Python skills to get the most from the interactive help. -- Steven
On Tue, 11 Oct 2011 12:39:31 +1100 Steven D'Aprano <steve@pearwood.info> wrote:
Having help do a search if passed a string would qualify as "more aggressive", would be useful, and wouldn't break existing usage. It should be easy to tweak the help function so that if it's passed an instance of a basic_string, it compiles that into a regular expression and uses that to try and find things. The question is - what should it be searching? top-level names in sys.modules? Docstrings in sys.modules? Something else entirely? Is there anything that can be searched here that would both be more useful than the existing interactive facility and not take an inordinate amount of time to search? <mike -- Mike Meyer <mwm@mired.org> http://www.mired.org/ Independent Software developer/SCM consultant, email for more information. O< ascii ribbon campaign - stop html mail - www.asciiribbon.org
On 10/11/2011 12:06 AM, Mike Meyer wrote:
On Tue, 11 Oct 2011 12:39:31 +1100 Steven D'Aprano<steve@pearwood.info> wrote:
This strikes me as reinventing the wheel. We already have docs with both indexes and a search facility. I usually have them open when writing Python code. -- Terry Jan Reedy
Steven D'Aprano schrieb am Di, 11. Okt 2011, um 12:39:31 +1100:
A keyword search facility, familiar to Linux users as `man -k key` or `apropos key`, might be useful.
There already is "pydoc -k", also known as pydoc.help.listmodules(key="whatever") And there are some special topics like help("DICTIONARIES") for an introduction to dictionaries. I wonder if anybody *ever* found that documentation from the interactive prompt. There would certainly be a point in advertising this documentation somehow when entering the interactive help prompt. Cheers, Sven
Sven Marnach schrieb am Di, 11. Okt 2011, um 12:34:27 +0100:
I just noticed that these topics *are* advertised in the interactive help prompt, and can be listed by entering "topics". Apparently I never read the introduction text carefully enough. There is also keyword-based module searching by entering modules [keyword] at the help prompt. Sorry for the noise, Sven
On Oct 10, 2011 7:48 PM, "Stayvoid" <stayvoid@gmail.com> wrote:
I think a lot of things can be improved in help() but I wouldn't change the python language for that. Once in help(), that kind of builtin/types/modules/methods/docs searching should be more easily accessible. Right now you have to specifically know what you're looking for to find most things. --Yuval
Stayvoid <stayvoid@gmail.com> writes:
In those cases, the obvious thing to do is to get help on the type, with ‘help(dict)’. Your output pager has a search command; if it doesn't, get a better output pager. -- \ “I went to the museum where they had all the heads and arms | `\ from the statues that are in all the other museums.” —Steven | _o__) Wright | Ben Finney
Stayvoid wrote:
Remember that the help() function is just a regular function, like any other. It isn't magic, and it can't accept anything that isn't a valid Python object. That won't change. help(math) won't work unless you have imported the math module first. help(key) won't work unless you actually have a name `key`, in which case it will work but it may not do what you are expecting. help(*key*) can't work because *key* is a SyntaxError. However, help('key') would work. It currently says:
help('key') no Python documentation found for 'key'
Perhaps help should be more aggressive at trying to find something useful before giving up. Or you could just encourage the beginner to use help interactively, by calling help() with no arguments, then following the prompts.
In my opinion it will be very helpful for newcomers if the interpreter could search for similar commands and output them all.
A keyword search facility, familiar to Linux users as `man -k key` or `apropos key`, might be useful. Or it might also complicate the interactive help for no good reason. Beware of trying to make help() do too much. Remember also that help() is not a substitute for the Python documentation and tutorials. It is not aimed at teaching beginners the basics. You actually need a reasonably good grasp of Python skills to get the most from the interactive help. -- Steven
On Tue, 11 Oct 2011 12:39:31 +1100 Steven D'Aprano <steve@pearwood.info> wrote:
Having help do a search if passed a string would qualify as "more aggressive", would be useful, and wouldn't break existing usage. It should be easy to tweak the help function so that if it's passed an instance of a basic_string, it compiles that into a regular expression and uses that to try and find things. The question is - what should it be searching? top-level names in sys.modules? Docstrings in sys.modules? Something else entirely? Is there anything that can be searched here that would both be more useful than the existing interactive facility and not take an inordinate amount of time to search? <mike -- Mike Meyer <mwm@mired.org> http://www.mired.org/ Independent Software developer/SCM consultant, email for more information. O< ascii ribbon campaign - stop html mail - www.asciiribbon.org
On 10/11/2011 12:06 AM, Mike Meyer wrote:
On Tue, 11 Oct 2011 12:39:31 +1100 Steven D'Aprano<steve@pearwood.info> wrote:
This strikes me as reinventing the wheel. We already have docs with both indexes and a search facility. I usually have them open when writing Python code. -- Terry Jan Reedy
Steven D'Aprano schrieb am Di, 11. Okt 2011, um 12:39:31 +1100:
A keyword search facility, familiar to Linux users as `man -k key` or `apropos key`, might be useful.
There already is "pydoc -k", also known as pydoc.help.listmodules(key="whatever") And there are some special topics like help("DICTIONARIES") for an introduction to dictionaries. I wonder if anybody *ever* found that documentation from the interactive prompt. There would certainly be a point in advertising this documentation somehow when entering the interactive help prompt. Cheers, Sven
Sven Marnach schrieb am Di, 11. Okt 2011, um 12:34:27 +0100:
I just noticed that these topics *are* advertised in the interactive help prompt, and can be listed by entering "topics". Apparently I never read the introduction text carefully enough. There is also keyword-based module searching by entering modules [keyword] at the help prompt. Sorry for the noise, Sven
On Oct 10, 2011 7:48 PM, "Stayvoid" <stayvoid@gmail.com> wrote:
I think a lot of things can be improved in help() but I wouldn't change the python language for that. Once in help(), that kind of builtin/types/modules/methods/docs searching should be more easily accessible. Right now you have to specifically know what you're looking for to find most things. --Yuval
Stayvoid <stayvoid@gmail.com> writes:
In those cases, the obvious thing to do is to get help on the type, with ‘help(dict)’. Your output pager has a search command; if it doesn't, get a better output pager. -- \ “I went to the museum where they had all the heads and arms | `\ from the statues that are in all the other museums.” —Steven | _o__) Wright | Ben Finney
participants (8)
-
Ben Finney -
Mike Meyer -
Ron Adam -
Stayvoid -
Steven D'Aprano -
Sven Marnach -
Terry Reedy -
Yuval Greenfield