Baffled by readline module
Cameron Simpson
cs at cskk.id.au
Thu Mar 9 16:59:33 EST 2023
On 09Mar2023 13:08, Grant Edwards <grant.b.edwards at gmail.com> wrote:
>On 2023-03-09, Chris Angelico <rosuav at gmail.com> wrote:
>> Not sure about the history file, and I would assume that if you don't
>> configure one, history is simply lost when you restart. But with tab
>> completion, unless you need to be able to input a tab character, it
>> should be safe to ignore the feature and leave it at the defaults.
>
>Indeed, that seems to be how it works (though I never found that
>stated anywhere in the docs).
>
>What's really weird about the docs is that when it is described it
>doesn't even _mention_ that it provides command-line recall and
>editing:
[...]
I think this might be the common case of a module which wraps another
library: there's a tension between describing everything in pointless
detail and the trite "we're just shimming this library, go read its
docs".
The module documentation needs to:
- not insult the reader by saying nearly nothing ("this is just GNU
readline, hooked to Python!") I'm looking at you, many "man" pages on
a GNU based system which say "oh just go and read GNI info, it's all
over there"
- be detailed enough to enumerate the API calls and at least summarise
their semantics
- be general enough to not overprescribe so that small shifts in the
library as it evolves don't cause falsehoods in the module docs (and a
nightmarish maintenance burden)
Similar example: the "os" modules, which largely shims the OS POSIX
calls. It lists them and has a paragraph on their purpose and the
meaning of the flags (for example). But the platform specifics and fine
grained stuff is off in "man 2 foo" for the Python "os.foo" function.
[...]
>It finally dawned on me after seeing an example I found elsewhere that
>you don't call some module method to fetch the next user-entered line.
>
>You call the input() built-in.
Ah. That's not overtly stated? [...reads...] Ah, there it is in the last
sentence of the opening paragraph. Not quite as in-your-face as I'd have
liked it. That paragraph could do with being a bullet list of use cases.
Cheers,
Cameron Simpson <cs at cskk.id.au>
More information about the Python-list
mailing list