The importable name mechanism.¶
There are two different mechanisms by which you can specify a WSGI application to modjy. This page describes the importable mechanism. The execfile mechanism is described on a different page.
The importable mechanism uses a single string which specifies an importable name, which when imported should deliver a python callable object. As described above, this can be any python callable. The importable name is specified as a single string. However, there are some small variations on how that string is specified, depending on the nature of the callable.
- Simple callable: if the target application is directly callable, e.g. a simple function, then you need only specify the name of the callable/function, and it will be called directly by modjy. Example: *some_framework.web.handlers.WSGIHandlerFunction*
- Instance: if the target application is an instantiable object, e.g. a class, then it will need to be instantiated before it can be called. To do this, supply parentheses/brackets after the name. Example: some_framework.web.handlers.WSGIHandlerClass(). In this case, modjy will locate the definition of the WSGIHandlerClass in some_framework.web.handlers, create an instance of that class, and use that as the application. Note that when the application instance is called to service a WSGI request, the method that will be invoked is the _call_ method.
- Instance method: if you want to use a class instance to service WSGI requests, but need to specify a specific method, then add the handler method name onto the end of the importable name. Example: some_framework.web.handlers.WSGIHandlerClass().handler. With this example, modjy will locate the WSGIHandlerClass, as described above, create an instance of it, and then use the handler method of that instance as that application callable.
The importable name mechanism and reloading¶
Reloading is not supported with the importable name mechanism. When the importable name mechanism is used, the value of the reload_on_mod parameter is ignored.
The importable name mechanism and caching¶
Caching means that the same application callable object will be re-used repeatedly, to save object creation overhead. You have the choice of whether or not to enable caching using the cache_callables parameter, described in the modjy configuration reference.
If caching is disabled when using the importable name mechanism, this means that a new application object will be created for every new request, when appropriate. When the application is a simple callable, as described above, then caching has no meaning, since there is no instance to be re-used. When the application is an instantiable, as described above, then new instances will be created for every request.
If caching is enabled and the application callable is a class instance, then the same instance will be reused for every single request.