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

[Tony Meyer]

[ru***@yahoo.com]

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

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]

Tony Meyer wrote:

[ru***@yahoo.com]

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.)
Why not submit a bug report/patch for the documentation?

I will.
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
I didn't post here for the maintainers' sake. The answer is
right in the text you quoted.
would take about the same amount of time as a post...

[Fredrik Lundh]

ru***@yahoo.com wrote:

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.

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]

"Fredrik Lundh" <fr*****@python ware.com> wrote:

ru***@yahoo.com wrote:

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.

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

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....57d0546?hl=en&
May I suggest that the problem is easily fixed simply
by removing the first "if".

[Fredrik Lundh]

ru***@yahoo.com wrote:

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)".
Well, I interpreted the if's as describing special cases
addtional to the first sentence.

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.
May I suggest that the problem is easily fixed simply
by removing the first "if".

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]

"Fredrik Lundh" <fr*****@python ware.com> wrote in message
news:ma******** *************** *************** @python.org...

ru***@yahoo.com wrote:

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)".
Well, I interpreted the if's as describing special cases
addtional to the first sentence.

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.

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.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. I should conclude that msg is not a string because
it doesn't say it is a string?

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

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.

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.
... 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
"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.
1 - I think I know how this works Wrong, I had no idea how it worked and read the docs
first. 2 - oh, it didn't work. let's check the documentation Yes, read it a second time, didn't see the alternate interpretation. 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. 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. 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. 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.
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.

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]

ru***@yahoo.com wrote:

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.

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.

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.

I should conclude that msg is not a string because
it doesn't say it is a string?

nice logic, there.

</F>

[Steve Holden]

ru***@yahoo.com wrote:

"Fredrik Lundh" <fr*****@python ware.com> wrote in message
news:ma******** *************** *************** @python.org...

ru***@yahoo.c om wrote:

from the find_module documentation:

find_module( name[, path])

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

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

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

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.
"few" has nothing to do with it.
So you think the docs should be changed if just *one* person can't
understand them. Or maybe *two*? or *ten*?
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.
As is your insistence on debating the point rather than submitting a
change request via sourceforge.

1 - I think I know how this works
Wrong, I had no idea how it worked and read the docs
first.

2 - oh, it didn't work. let's check the documentation

Yes, read it a second time, didn't see the alternate interpretation.

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.

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.

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.

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.

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.

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 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 [phone] [phone]
Holden Web LLC www.holdenweb.com
PyCon TX 2006 www.python.org/pycon/

[Kent Johnson]

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