[Python-ideas] doc anomalies

[Rustom Mody]

On Mon, Apr 13, 2015 at 6:51 PM, Steven D'Aprano <steve at pearwood.info> wrote:
> On Mon, Apr 13, 2015 at 10:51:05AM +0530, Rustom Mody wrote:
>
>> In python3 please check
>> help()
>> followed by
>> PACKAGES
>> and
>> DYNAMICFEATURES
>>
>> Do those help texts look helpful/meaningful?
>
> PACKAGES certainly looks helpful and meaningful, if it were reached via
> IMPORTING instead :-)
>
> If I wanted to know about packages, and got five pages of text about
> importing, I would be rather confused and annoyed.
>
> I would like to see PACKAGES lead to a short description of packages and
> their structure, the special role of __init__.py and __main__.py, and,
> hmmm, I think they are called "namespace packages"? They're a fairly new
> feature, and I've never used them. It may also include "See also
> IMPORT."
>
> DYNAMICFEATURES is also useful, though less useful than it could be due
> to excessive jargon that isn't defined. What's a free variable? Can we
> see examples of what dynamic features can and cannot be used?
>
> I actually expected to see a lot more dynamic features discussed:
>
> - getattr, setattr, delattr
> - exec
> - eval
> - compile
> - introspection via the inspect module, dir and vars
> - Python equivalents to Java-like "reflection"
>
> and probably more, but that may just mean my idea of dynamic features
> are different to the author of that help text.
>
>
>> Is this the right list for such questions?
> But since we're here, a few comments come to mind for discussion...
>
> (1) Help topics seem to be case sensitive. That's not very helpful:
>
> help> packages
> no Python documentation found for 'packages'
>
> help> PACKAGES
> [masses of text]
>
> (2) Hitting the enter key with nothing on the help? prompt exits help.
> That's downright ugly.
>
> (3) Does help() have an "apropos" or "search" feature, for searching the
> bodies of help pages for keywords?

Thanks Steven -- those are helpful points.

>
> Personally, I would have started by asking on the python-list list
> (comp.lang.python) and then gone straight to raising an issue on the
> bugtracker, if there was an issue to raise.
>

As I said, earlier, it looks as though a few students will be working
with me on python-internals related projects.
I was looking at some trivial bugs to fix to get my (our) toes wet.

[One thing one learns as a wizened old programmer is that when we
write a loop we try it on zero and one iteration before trying it on 1
million]

Tal has suggested that I join the mentor list which I have done.