Fredrik Lundh said:
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?
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...
