[mod_python] Re: Mod_python Digest, Vol 42, Issue 4

Graham Dumpleton grahamd at dscpl.com.au
Sat Sep 2 02:08:50 EDT 2006

All I can say is that we know the documentation is inadequate.

We have been waiting for a long time for the ASF to setup a wiki
page for mod_python so that we have a more flexible forum for
putting up documentation that can better explain things. Ie., a
place where documentation can be quickly added/changed as
issues come up. At the moment the documentation is LaTeX based
and a part of the source code. This doesn't lend itself to easy or quick
updates as the main site is only updated when major releases occur.
Anyway, for myself I have given up waiting for the wiki and am
turning my existing mod_python articles into my own unofficial
wiki so I can at least more quickly add new stuff. I have quite a
long list of mini articles I want to write that I have been holding off
doing due to the lack of an official wiki. Keep an eye out for more
on this in the near future.

In respect of mod_python vs mod_python.publisher, they are actually
two totally different things. In some respects, mod_python.publisher
and mod_python.psp should be released as totally separate products
from the mod_python core. That they aren't often causes a lot of
confusion as people, like yourself, see mod_python.publisher and
mod_python as one in the same, when in fact mod_python.publisher
is a higher level interface which is used in a totally different way.

In respect of AddHandler, SetHandler, MultiViews etc, you need to  
that mod_python is an extension for Apache. Thus, such things like this
aren't actually implemented by mod_python but are implemented
by Apache. To use mod_python properly, you also need to understand
Apache to some degree and that means also referring to the Apache


On 02/09/2006, at 3:51 PM, Blair P. Houghton wrote:

> Graham Dumpleton <grahamd at dscpl.com.au> wrote:
>> On 01/09/2006, at 12:01 PM, Blair P. Houghton wrote:
>> It does, in as much as the example shows that is the case. It just  
>> does
>> not spell it out in words as a requirement. Ie., it always uses   
>> "form.py/email".
> Documentation needs to explain what is going on.
>> Referencing just the script and no function name will work  
>> provided that
>> the code file contains a function called index().
>> That you use a name "handler" suggests you are getting a bit muddled
>> with the difference between basic mod_python handlers, where response
>> handler is always called handler() and name of function doesn't  
>> need  to be
>> in the URL and mod_python.publisher where with the exception of  
>> index(),
>> the function does have to be in the URL.
> I think that the fact that in one setup the default is handler()
> and in another it is index(), and that this difference is not
> made explicit early in the documentation, is the problem.
> Anyone who, like me, tries out the simpler mechanism and learns
> that the default is handler(), won't be expecting it to change
> when moving to the publisher mechanism.  I wanted to use the
> script that I had already been running, because changing more
> than one thing at a time is a recipe for error.  Of
> course, what happened is that the documentation just expected
> I'd throw away everything I'd done before and blindly type in
> the publisher example script.  Which is overly complicated for
> its purpose, which of course is a recipe for error.  So
> of course I didn't do it that way.
>>> Note that the
>>> '.py' suffix must be included also.
>> Not necessarily. Whether this is the case will depend on how  
>> Apache is
>> configured for MultiViews. Try the configuration:
>>    AddHandler mod_python .py
>>    PythonHandler mod_python.publisher
>>    PythonDebug On
>>    Options +MultiViews
>>    MultiviewsMatch Handlers
>>    AddType text/html;qs=1.0 .py
>>    AddType text/html;qs=0.9 .html
>>    AddType text/plain;qs=0.8 .txt
>> On mod_python web site, do searches for "MultiViews  
>> MultiviewsMatch" and
>> "MultiviewsMatch DirectoryIndex" for other discussions on this  
>> topic.  Ones
>> which include most are probably:
>>    http://www.modpython.org/pipermail/mod_python/2006-June/ 
>> 021435.html
>>    http://www.modpython.org/pipermail/mod_python/2006-March/ 
>> 020501.html
> This is interesting, but highly non-intuitive in the context of
> "just trying to get the thing running so I can start to do some
> productive work".
>>> I believe that the document from the live/current tree should be   
>>> moved to the document in the live/mod_python-
>>> 3.2.10 tree ASAP so that people won't be caught by this any more.
>> Those two trees are the same document, just different parts of  
>> the  same document.
> Interesting.  The "quick-start" page is a lot less "quick" than
> the "introduction" one.  And with that hairy example isn't even
> close to quick.  I think anything referring to a "quick start"
> in the document should point right at the publisher introduction
> page.  Which should use the default index() function and point
> out accessing it both explicitly and as a default in the URI.
> Because nobody who's trying to get a "quick start" is going to
> read anything called "Traversal" in the manual.
>> Both AddHandler and SetHandler approaches can work, but they are  
>> used  for
>> different reasons.
> Hmm.  I didn't even notice that one was AddHandler and the other
> was SetHandler.
> So here we have the documentation using two different ways to do
> the same thing, without, again, pointing out why, in a place where
> it would be of the most possible value to be explicit about it.
> --Blair
> _______________________________________________
> Mod_python mailing list
> Mod_python at modpython.org
> http://mailman.modpython.org/mailman/listinfo/mod_python

More information about the Mod_python mailing list