another docs problem - imp

[rurpy]

Another Python docs problem...

I was trying to use imp.find_module ().

imp.find_module ("mymod", "./subdir") ImportError: No frozen submodule named ./subdir.mymod

subdir/mymod.py definately exists, has reasonable
permissions, etc.

After a lot of reading and re-reading the docs,
trying various things, I Googled on the error
message and lo, there was a message from
2002 by someone ranting about how hard
it was to do things in Python sometimes (no it
was not from me).

Turns out that you have to do imp.find_module ("mymod", ["./subdir"])

I saw not a hint of this in the docs. In fact
they seem to say that the first (unworking)
form *should* work. Bye bye about two
hours altogether...

I thought I would post this and hopefully help
someone else in the future (since I noticed
an unanswered posting here from Mar 2005
about the same problem.)

[Steve Holden]

Kent Johnson wrote:

Steve Holden wrote:

Clearly. So get your sleeves rolled up and provide a fix. Then you too
will get your name in the Python documentation contributors' list.

Is there such a list? I have contributed many doc patches and if such
glory is mine I would like to know it!

Kent

There *is* one:

http://docs.python.org/acks.html

but I don;t get to decide who goes on it.

regards
Steve
--
Steve Holden [phone] [phone]
Holden Web LLC www.holdenweb.com
PyCon TX 2006 www.python.org/pycon/

[Fredrik Lundh]

Kent Johnson wrote:

Clearly. So get your sleeves rolled up and provide a fix. Then you too
will get your name in the Python documentation contributors' list.

Is there such a list? I have contributed many doc patches and if such
glory is mine I would like to know it!

unfortunately, your name don't seem to be mentioned in the Doc version
history either:

[Doc]$ svn log | grep -i Kent
Fix typo reported by Kent Engström, and a bunch of broken markup.
[Doc]$

do you have more details (a reference to a page you've contributed to should
be enough).

or could it be that your submissions are still sitting in the SF tracker ?

</F>

[Kent Johnson]

Fredrik Lundh wrote:

Kent Johnson wrote:

Is there such a list? I have contributed many doc patches and if such
glory is mine I would like to know it!

unfortunately, your name don't seem to be mentioned in the Doc version
history either:

do you have more details (a reference to a page you've contributed to should
be enough).

or could it be that your submissions are still sitting in the SF tracker ?

There are twelve closed doc bugs in SF tracker that I submitted
(username kjohnson); I think most of these were accepted. They're all
pretty minor but certainly as big as the change this thread is
discussing. I also recently helped Andrew Kuchling rewrite the
BeginnersGuide in the Wiki.

A note to rurpy and anyone else with a complaint about the docs: it
really is very easy to suggest a change in SF. In my experience most
suggestions are accepted very quickly. It's an easy way to help make
Python better. Definitely easier than fighting on c.l.py about whether
the docs are confusing.

Kent

[rurpy]

Steve Holden wrote:

ru***@yahoo.com wrote: [...snip...] Well, perhaps if you'd read the intro to the documentation (more
carefully), or if you were more used to reading programming manuals,
you'd quickly have recognised

[, path]

as meaning precisely that the path argument is optional.
I did realize that. (And I have read enough other
programming manuals that reading more will not
affect my recognition of anything.) The issue was
not the optionality of the argument, it was the
type of the argument when it was supplied.

[...snip...]
So you think the docs should be changed if just *one* person can't
understand them. Or maybe *two*? or *ten*?
I don't know how many people had trouble
with the text. But there were some postings,
and the number of people is almost certainly
orders of magnitude larger than the number
that post.
I continue to think that the way I interpreted it
was valid, so it *is* ambiguous, even if most
people quickly disambiguate it correctly. If
you accept that, it should be clarified even if
the number was *one*.

[...snip...]

How about
1 - read some clear unambiguous documentation.
2 - write the code and it works as described.

Excellent. So now you only have to fix the docs and that's what everyone
will do from now on.

My grandfather used to own a hardware store.
He frequently said he took every customer
complaint very seriously. "For every customer
who complains, there are a 100 that just take their
business elsewhere."
I wonder how many people had a problem with
this and lost time. Not as extreme as my case,
maybe just rereading it a few times. And of course
this particular piece of documentation is not an
isolated instance. If you are happy with the status
quo, if it is "good enough" fine. I am not.

...snipped long anacdote about busses...

Clearly. So get your sleeves rolled up and provide a fix. Then you too
will get your name in the Python documentation contributors' list.

I would be sufficient reward just to get good, clear,
complete accurate python docs.
I agree that things that are difficult to understand could usefully be
fixed. Since this is the open source world I'm unsure as to why you feel
somebody else should fix it. It's also fairly obvious since you failed
to find other complaints about this issue in your Google search that it
isn't a frequent cause of complaint.

I never suggested someone else should fix it. I am willing
to submit either a doc bug reports, or patches provided
that there is a reasonable chance it will result in a positive
change. I am not willing to invest a lot of time summiting
things that are ignored or dumped in the bit bucket. So
in part, my post here was to gauge the reaction to proposed
change.

Frequency of public complaints is a *lousy* criteria. Very
few people are going to complain publicly, especially here
where suggestions that Python is not perfect are often met
with derision or silence. That was the whole point of the
grandfather story.

[Christoph Zwerschke]

I assume one cause of the misunderstandin g was the name "path" for the
search path. If it had been named "paths" it would have been more
obvious. But Python is only following a common standard here. Since
environment variables are called PATH, CLASSPATH etc. it was only
logical to use PYTHONPATH and sys.path etc. Therefore the imp module
uses "pathname" where it is only a single path.

Probably the people who once invented the env variables didn't care
about writing PATHS because it sounds like PATH anyway (or is there a
difference? I am German).

Anyway, the docs are technically correct. Maybe the best solution would
not to improve the docs but to allow path to be a string in which case
it would be treated as [string].

-- Christoph