I agree; callables aren't particularily well documented, and most of what I have makes too many assumptions. I apologize if some of this is review; I plan to turn this into a blog post soon, so I'm writing in "blog-mode" :).
In Python, callable objects are anything that can be, well, "called". In this case, "called" means "can have () after it". Functions and methods are the most common callables; in Python classes are callable, and
any instance of a class with a __call__ method is also callable. If you've used C++ and overloaded operator() (so-called functors), this should seem familiar.
WSGI sepcification describaes a WSGI application as a callable taking two arguments and returning and iterable (I'm not going to go into the details on iterable). For example:
def simple_app(environ, start_response):
"""Simplest possible application object"""
status = '200 OK'
response_headers = [('Content-type','text/plain')]
return ['Hello world!\n']
Now, this has simple_app as a a function, but it doesn't have to be. It could also be an instance of a class defining __call__; it could even be a class itself that implements the iterator protocol (thankfully, you don't see that very often).
Let's say you want to deploy the sample app above, and it's in a file called simple.wsgi in your application root:
<scriptMapping scriptName="simple.wsgi" physicalPath="~/simple.wsgi" callable="simple_app" />
Because the sample doesn't use "application" (the default, by convention), NWSGI needs to know what the name of the callable is so that it can call it and run the application.
This is all well and good, but we don't necessarily have to create a .wsgi file for every application. Most applications (f.e. Trac) provide a suitable application function already; why not use it directly?
<path path="C:\trac" />
<scriptMapping scriptName="trac.wsgi" callable="trac.web.main.dispatch_request" />
If you provide a dotted path to callable, it will try to import the module ("trac.web.main") and run the callable ("dispatch_request"). This removes the need for a .wsgi file at all.
That leaves the last common case: an application class that defines __call__. In this case, NWSGI needs an instance of the class to work with, so there's a handy shortcut:
<path path="C:\django" />
<scriptMapping scriptName="django.wsgi" callable="django.core.handlers.wsgi.WSGIHandler()" />
Notice the "()" at the end: this tells NWSGI to create an instance of the WSGIHandler class and use the instance as the WSGI application. This is limited to classes that take no arguments only.
I hope that helps. Let me know if there's anything that's still not clear, or where th wording could be improved, etc.