another docs problem - imp

[rurpy@yahoo.com]

Another Python docs problem...

I was trying to use imp.find_module ().
[color=blue][color=green][color=darkred]
>>> imp.find_module ("mymod", "./subdir")[/color][/color][/color]
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[color=blue][color=green][color=darkred]
>>> imp.find_module ("mymod", ["./subdir"])[/color][/color][/color]

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.)

[Tony Meyer]

Re: another docs problem - imp

[rurpy@yahoo.com]
[color=blue]
> Another Python docs problem...
>
> I was trying to use imp.find_module ().
> [...]
> 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.)[/color]

Why not submit a bug report/patch for the documentation?
Documentation patches are fine in plain text (the maintainers will
take care of the necessary markup) and a submitted report will get
attended to, even it if takes a while - a post here is more-than-
likely to be missed by those that maintain the documentation. It
would take about the same amount of time as a post...

=Tony.Meyer

[rurpy@yahoo.com]

Re: another docs problem - imp


Tony Meyer wrote:[color=blue]
> [rurpy@yahoo.com]
>[color=green]
> > Another Python docs problem...
> >
> > I was trying to use imp.find_module ().
> > [...]
> > 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.)[/color]
>
> Why not submit a bug report/patch for the documentation?[/color]

I will.
[color=blue]
> Documentation patches are fine in plain text (the maintainers will
> take care of the necessary markup) and a submitted report will get
> attended to, even it if takes a while - a post here is more-than-
> likely to be missed by those that maintain the documentation. It[/color]

I didn't post here for the maintainers' sake. The answer is
right in the text you quoted.
[color=blue]
> would take about the same amount of time as a post...[/color]

[Fredrik Lundh]

Re: another docs problem - imp

rurpy@yahoo.com wrote:
[color=blue]
> Turns out that you have to do[color=green][color=darkred]
> >>> imp.find_module ("mymod", ["./subdir"])[/color][/color]
>
> I saw not a hint of this in the docs. In fact
> they seem to say that the first (unworking)
> form *should* work.[/color]

from the find_module documentation:

find_module( name[, path])


Try to find the module _name_ on the search path _path_.
If _path_ is a list of directory names, each directory is
searched for files /.../. Invalid names in the list are
silently ignored (but all list items must be strings).
If _path_ is omitted or None, the list of directory names
given by _sys.path_ is searched /.../

it's not obvious how anyone can interpret the alternatives "a
list where all items are strings / omitted / None" as "not a hint
that a list is expected" and "a single string *should* work (i.e.
be treated as a pathname, rather than a sequence)".

</F>

[rurpy@yahoo.com]

Re: another docs problem - imp


"Fredrik Lundh" <fredrik@python ware.com> wrote:[color=blue]
> rurpy@yahoo.com wrote:
>[color=green]
> > Turns out that you have to do[color=darkred]
> > >>> imp.find_module ("mymod", ["./subdir"])[/color]
> >
> > I saw not a hint of this in the docs. In fact
> > they seem to say that the first (unworking)
> > form *should* work.[/color]
>
> from the find_module documentation:
>
> find_module( name[, path])
>
> Try to find the module _name_ on the search path _path_.
> If _path_ is a list of directory names, each directory is
> searched for files /.../. Invalid names in the list are
> silently ignored (but all list items must be strings).
> If _path_ is omitted or None, the list of directory names
> given by _sys.path_ is searched /.../
>
> it's not obvious how anyone can interpret the alternatives "a
> list where all items are strings / omitted / None" as "not a hint
> that a list is expected" and "a single string *should* work (i.e.
> be treated as a pathname, rather than a sequence)".[/color]

Well, I interpreted the if's as describing special cases
addtional to the first sentence. At least one other person
apperantly had the same problem recently.

http://groups.google.com/group/comp.lang.python/msg/3c052b05157d0546?hl=en&

May I suggest that the problem is easily fixed simply
by removing the first "if".

[Fredrik Lundh]

Re: another docs problem - imp

rurpy@yahoo.com wrote:
[color=blue][color=green]
> > from the find_module documentation:
> >
> > find_module( name[, path])
> >
> > Try to find the module _name_ on the search path _path_.
> > If _path_ is a list of directory names, each directory is
> > searched for files /.../. Invalid names in the list are
> > silently ignored (but all list items must be strings).
> > If _path_ is omitted or None, the list of directory names
> > given by _sys.path_ is searched /.../
> >
> > it's not obvious how anyone can interpret the alternatives "a
> > list where all items are strings / omitted / None" as "not a hint
> > that a list is expected" and "a single string *should* work (i.e.
> > be treated as a pathname, rather than a sequence)".[/color]
>
> Well, I interpreted the if's as describing special cases
> addtional to the first sentence.[/color]

The first sentence says that the _path_ argument is a search path.
It does not say that it can be a string; that's something you made
up all by yourself.
[color=blue]
> May I suggest that the problem is easily fixed simply
> by removing the first "if".[/color]

Like

Try to find the module _name_ on the search path _path_.
_path_ is a list of directory names, each directory is searched
for files.

? So what happens when pupry reads this, and gets annoyed that he
always has to pass in a list ? It's probably better if you learn to read
technical documentation a bit more carefully.


.... and don't give me any "you're defending the status quo" crap in
response to this. There are lots of things to do in the library reference,
and a few of us are working on it (using different approaches), but
trust me, optimizing for a few

1 - I think I know how this works
2 - oh, it didn't work. let's check the documentation
3 - I think I've found a way to interpret the documentation as if
it allows me to do what I'm doing. it doesn't explicitly say that
I can do this, but it doesn't explicitly rule it out either, so I'm
probably right. I'll try again. maybe it works this time.
4 - (2 hours later) maybe I should try one of the alternatives that
is mentioned in the documentation. oh, it did work if I follow the
instructions. now I'm REALLY pissed, and am going to spend
another hour arguing about this on the internet.

practitioners, over the

1 - I think I know how this works
2 - oh, it didn't work. let's check the documentation.
3 - it says "can be a list" or "can be omitted". let's try one of
those. oh, it worked.

crowd is not on the list.

This reminds me of the old story when the local bus company made it
possible to pay with special "bus cards", which works like this:

1 - enter the bus
2 - put your card in the card reader slot
3 - if the card reader beeps annoyingly and flashes red, talk to
the driver. otherwise, get your card and get seated.

and some local rurpy's wrote long letters to the editor arguing that it
was a disgrace that the bus company didn't publish more information
in advance; maybe an illustrative folder sent to everyone in the area
would have been a nice idea, or some television spots showing how
to put the card in the reader? The reply from the bus company was
a gem:

"it's really very simple, and you only have to learn this once"

It may have taken you two hours, but now you know that strings are
sequences too, and that you cannot treat a number of if-sentences or
can be-sentences in a piece of text as "what I originally thought *plus*
what it says."

The latter is likely to save your many hours in your continued career as
a professional (no matter what your profession really is).

</F>

[rurpy@yahoo.com]

Re: another docs problem - imp

"Fredrik Lundh" <fredrik@python ware.com> wrote in message
news:mailman.30 6.1136963981.27 775.python-list@python.org ...[color=blue]
> rurpy@yahoo.com wrote:
>[color=green][color=darkred]
> > > from the find_module documentation:
> > >
> > > find_module( name[, path])
> > >
> > > Try to find the module _name_ on the search path _path_.
> > > If _path_ is a list of directory names, each directory is
> > > searched for files /.../. Invalid names in the list are
> > > silently ignored (but all list items must be strings).
> > > If _path_ is omitted or None, the list of directory names
> > > given by _sys.path_ is searched /.../
> > >
> > > it's not obvious how anyone can interpret the alternatives "a
> > > list where all items are strings / omitted / None" as "not a hint
> > > that a list is expected" and "a single string *should* work (i.e.
> > > be treated as a pathname, rather than a sequence)".[/color]
> >
> > Well, I interpreted the if's as describing special cases
> > addtional to the first sentence.[/color]
>
> The first sentence says that the _path_ argument is a search path.
> It does not say that it can be a string; that's something you made
> up all by yourself.[/color]

Correct it does not say it's a string. But your implication that
one can therefore conclude that it is not a string is silly.[color=blue]
>From unittest:
> assert_( expr[, msg])
> failUnless( expr[, msg])
> Signal a test failure if expr is false; the explanation for the error
> will be msg if given, otherwise it will be None.[/color]
I should conclude that msg is not a string because
it doesn't say it is a string?
[color=blue][color=green]
> > May I suggest that the problem is easily fixed simply
> > by removing the first "if".[/color]
>
> Like
>
> Try to find the module _name_ on the search path _path_.
> _path_ is a list of directory names, each directory is searched
> for files.
>
> ? So what happens when pupry reads this, and gets annoyed that he
> always has to pass in a list ? It's probably better if you learn to read
> technical documentation a bit more carefully.[/color]

Reading more carefully is always useful. But that does
not remove the obligation of the writer to write clearly and
unambiguously. Why would pupry think s/he always has
to pass in a list when the syntax description clearly shows
the arument is optional, and the following "if" sentence states
it is optional? But perhaps you are right; perhaps something
like "_path_is a optional list of..." would be clearer.
[color=blue]
> ... and don't give me any "you're defending the status quo" crap in
> response to this. There are lots of things to do in the library reference,
> and a few of us are working on it (using different approaches), but
> trust me, optimizing for a few[/color]

"optimize": to make as perfect, effective, or functional as possible.
(Merriam Webster New Collegiate)

"few" has nothing to do with it.
If this required a huge amount of work, your resistance
would be understandable. Since the wording changes
are petty minor your flamage over this is puzzling.
[color=blue]
> 1 - I think I know how this works[/color]
Wrong, I had no idea how it worked and read the docs
first.[color=blue]
> 2 - oh, it didn't work. let's check the documentation[/color]
Yes, read it a second time, didn't see the alternate interpretation.[color=blue]
> 3 - I think I've found a way to interpret the documentation as if
> it allows me to do what I'm doing. it doesn't explicitly say that
> I can do this, but it doesn't explicitly rule it out either, so I'm
> probably right. I'll try again. maybe it works this time.[/color]
Nope. It was "hmm, seems to clearly state that it
takes a path argument." Since I was dealing with a
single directory, and (this stuff dealing with imports
and all) had just before been thinking about sys.path
solutions, I was primed to accept that the argument
was a string and assumed I must be doing something
wrong." <later> "Is there any source? Nope
must be C." <later> "How about google". Oh here
is someone with same problem, Damn, no answer.
Ohh here is some one else, different problem but
he tried both find_module(.., "xxx") and (..,"[xxx]")
and the latter didn't generate the error message.[color=blue]
> 4 - (2 hours later) maybe I should try one of the alternatives that
> is mentioned in the documentation. oh, it did work if I follow the
> instructions. now I'm REALLY pissed, and am going to spend
> another hour arguing about this on the internet.[/color]
No. As I said, I did not see your way of interpreting the
documentation until you posted. And I had no plans
to argue about it. I posted for the reasons I gave,
and made a suggestion about how the documention
could be improved.
Well, in your attempt at mind reading you at least
got one out of four.
[color=blue]
> practitioners, over the
> 1 - I think I know how this works
> 2 - oh, it didn't work. let's check the documentation.
> 3 - it says "can be a list" or "can be omitted". let's try one of
> those. oh, it worked.[/color]

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

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...

[Fredrik Lundh]

Re: another docs problem - imp

rurpy@yahoo.com wrote:
[color=blue][color=green]
> > The first sentence says that the _path_ argument is a search path.
> > It does not say that it can be a string; that's something you made
> > up all by yourself.[/color]
>
> Correct it does not say it's a string. But your implication that
> one can therefore conclude that it is not a string is silly.
>[color=green]
> >From unittest:
> > assert_( expr[, msg])
> > failUnless( expr[, msg])
> > Signal a test failure if expr is false; the explanation for the error
> > will be msg if given, otherwise it will be None.[/color]
>
> I should conclude that msg is not a string because
> it doesn't say it is a string?[/color]

nice logic, there.

</F>

[Steve Holden]

Re: another docs problem - imp

rurpy@yahoo.com wrote:[color=blue]
> "Fredrik Lundh" <fredrik@python ware.com> wrote in message
> news:mailman.30 6.1136963981.27 775.python-list@python.org ...
>[color=green]
>>rurpy@yahoo.c om wrote:
>>
>>[color=darkred]
>>>>from the find_module documentation:
>>>>
>>>> find_module( name[, path])
>>>>[/color][/color][/color]
[...][color=blue]
>
> Reading more carefully is always useful. But that does
> not remove the obligation of the writer to write clearly and
> unambiguously. Why would pupry think s/he always has
> to pass in a list when the syntax description clearly shows
> the arument is optional, and the following "if" sentence states
> it is optional? But perhaps you are right; perhaps something
> like "_path_is a optional list of..." would be clearer.
>[/color]
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.[color=blue]
>[color=green]
>>... and don't give me any "you're defending the status quo" crap in
>>response to this. There are lots of things to do in the library reference,
>>and a few of us are working on it (using different approaches), but
>>trust me, optimizing for a few[/color]
>
>
> "optimize": to make as perfect, effective, or functional as possible.
> (Merriam Webster New Collegiate)
>[/color]
Reliance on dictionary definitions is often the sign of rigid thinking.
If you can't produce your own definition and defend it you'd probably be
better of not quoting a definition in the first place.
[color=blue]
> "few" has nothing to do with it.[/color]

So you think the docs should be changed if just *one* person can't
understand them. Or maybe *two*? or *ten*?
[color=blue]
> If this required a huge amount of work, your resistance
> would be understandable. Since the wording changes
> are petty minor your flamage over this is puzzling.
>[/color]
As is your insistence on debating the point rather than submitting a
change request via sourceforge.[color=blue]
>[color=green]
>> 1 - I think I know how this works[/color]
>
> Wrong, I had no idea how it worked and read the docs
> first.
>[color=green]
>> 2 - oh, it didn't work. let's check the documentation[/color]
>
> Yes, read it a second time, didn't see the alternate interpretation.
>[color=green]
>> 3 - I think I've found a way to interpret the documentation as if
>> it allows me to do what I'm doing. it doesn't explicitly say that
>> I can do this, but it doesn't explicitly rule it out either, so I'm
>> probably right. I'll try again. maybe it works this time.[/color]
>
> Nope. It was "hmm, seems to clearly state that it
> takes a path argument." Since I was dealing with a
> single directory, and (this stuff dealing with imports
> and all) had just before been thinking about sys.path
> solutions, I was primed to accept that the argument
> was a string and assumed I must be doing something
> wrong." <later> "Is there any source? Nope
> must be C." <later> "How about google". Oh here
> is someone with same problem, Damn, no answer.
> Ohh here is some one else, different problem but
> he tried both find_module(.., "xxx") and (..,"[xxx]")
> and the latter didn't generate the error message.
>[color=green]
>> 4 - (2 hours later) maybe I should try one of the alternatives that
>> is mentioned in the documentation. oh, it did work if I follow the
>> instructions. now I'm REALLY pissed, and am going to spend
>> another hour arguing about this on the internet.[/color]
>
> No. As I said, I did not see your way of interpreting the
> documentation until you posted. And I had no plans
> to argue about it. I posted for the reasons I gave,
> and made a suggestion about how the documention
> could be improved.
> Well, in your attempt at mind reading you at least
> got one out of four.
>
>[color=green]
>>practitioners , over the
>> 1 - I think I know how this works
>> 2 - oh, it didn't work. let's check the documentation.
>> 3 - it says "can be a list" or "can be omitted". let's try one of
>> those. oh, it worked.[/color]
>
>
> How about
> 1 - read some clear unambiguous documentation.
> 2 - write the code and it works as described.
>[/color]
Excellent. So now you only have to fix the docs and that's what everyone
will do from now on.
[color=blue]
> 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...
>[/color]
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 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.

regards
Steve
--
Steve Holden +44 150 684 7255 +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006 www.python.org/pycon/

[Kent Johnson]

Re: another docs problem - imp

Steve Holden wrote:[color=blue]
> Clearly. So get your sleeves rolled up and provide a fix. Then you too
> will get your name in the Python documentation contributors' list.[/color]

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

Kent

[Steve Holden]

Re: another docs problem - imp

Kent Johnson wrote:[color=blue]
> Steve Holden wrote:
>[color=green]
>>Clearly. So get your sleeves rolled up and provide a fix. Then you too
>>will get your name in the Python documentation contributors' list.[/color]
>
>
> Is there such a list? I have contributed many doc patches and if such
> glory is mine I would like to know it!
>
> Kent[/color]

There *is* one:

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

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

regards
Steve
--
Steve Holden +44 150 684 7255 +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006 www.python.org/pycon/

[Fredrik Lundh]

Re: another docs problem - imp

Kent Johnson wrote:
[color=blue][color=green]
>> Clearly. So get your sleeves rolled up and provide a fix. Then you too
>> will get your name in the Python documentation contributors' list.[/color]
>
> Is there such a list? I have contributed many doc patches and if such
> glory is mine I would like to know it![/color]

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]

Re: another docs problem - imp

Fredrik Lundh wrote:[color=blue]
> Kent Johnson wrote:[color=green]
>>Is there such a list? I have contributed many doc patches and if such
>>glory is mine I would like to know it![/color]
>
> 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 ?[/color]

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@yahoo.com]

Re: another docs problem - imp


Steve Holden wrote:[color=blue]
> rurpy@yahoo.com wrote:[/color]
[...snip...][color=blue]
> 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.[/color]

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...]
[color=blue]
> So you think the docs should be changed if just *one* person can't
> understand them. Or maybe *two*? or *ten*?[/color]

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...]
[color=blue][color=green]
> > How about
> > 1 - read some clear unambiguous documentation.
> > 2 - write the code and it works as described.
> >[/color]
> Excellent. So now you only have to fix the docs and that's what everyone
> will do from now on.
>[color=green]
> > 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...
> >[/color]
> Clearly. So get your sleeves rolled up and provide a fix. Then you too
> will get your name in the Python documentation contributors' list.[/color]

I would be sufficient reward just to get good, clear,
complete accurate python docs.
[color=blue]
> 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.[/color]

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]

Re: another docs problem - imp

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