News

[17/Sep/2009:19:20] Release 0.5 includes Open Flash Chart support.

[01/Jul/2009:10:50] Repoze.who authentication tutorial added

[22/Jun/2009:11:36] AJAX calculator tutorial added.

[01/May/2009:14:15] MVC/SQL based wiki tutorial added.



Contact Email:



view source
W1200_1000.
DirectoryConfig.
whiff



Download instructions
at whiff.sourceforge.net
project page
.
WHIFF DOCUMENTION

Directory configuration

A python API permits configuration of WHIFF directories.

Contents:
Module root directory applications
Installing resources
Installing static resources
Standard resources
Distributed resources implementations
Directory __init__ files
Served directory content
Recognizing templates and files in a directory
Importing applications or other root directories into a directory
WHIFF applications always reside in a WHIFF directory and each WHIFF directory must be configured to find the applications it contains as well as any external resources needed by that directory. The directory may also be configured for a standard "look and feel" and for standard error handling behaviour.

WHIFF directories can be configured in a number of ways, including

Module root directory applications

To install WHIFF applications in a web server configure a module root application to contain the applications and install that application as a WSGI application under the web server, using the standard mechanism for installing WSGI applications for the web server configuration.

When a web server "hands" a request to WHIFF the primary entry point that initially receives the request is a module root application for a WHIFF directory. To create a module root application, import a Python module corresponding to the directory you want to serve and use the resolver.moduleRootApplication constructor to wrap the module into a root application.

The signature for the resolver.moduleRootApplication constructor is as follows:

class moduleRootApplication(WsgiComponent):
    "Make a module into a WSGI app which serves its content (subject to security restrictions)"
    
    def __init__(self,
                 # the server relative URL prefix for the directory
                 root_path="",
                 # the module/directory to serve
                 root_module=None,
                 # the application to handle "not found" urls
                 on_not_found=default_not_found_app,
                 # middleware to use to wrap all applications (overridden via "no-filter")
                 filter_middleware=None,
                 # middleware to handle uncaught exceptions
                 exception_middleware=None,
                 # additional environment entries to insert for each request
                 environment=None,
                 # resource gateway object
                 resourceGateway=None, 
                 ):
The root_path parameter tells the application how to parse request URLs. The root_path must be a prefix of all URLs for incoming requests -- if it is not the request will be refused as a security precaution.

Here is an example CGI script that constructs a root application for the resumes tutorial.

#!/Library/Frameworks/Python.framework/Versions/Current/bin/python

import sys

import wsgiref.handlers
import whiff.resolver

from whiff.resources import sessionDirectory

# add the path to the directory containing the "resumes" root directory to the python path
sys.path.append("/Users/Aaron/whiff/doc")
import resumes

# create a WSGI application to serve the resume directory
application = whiff.resolver.moduleRootApplication("/cgi-bin/resumes.cgi", resumes)

# add HTTP session resource
sessions = sessionDirectory.directorySessionFinder("/tmp/sessions", timeout=60*60)
application.registerResourceFinder(prefix="session", finder=sessions)
    
# add user profile resource
profiles = sessionDirectory.directoryProfileFinder("/tmp/profiles")
application.registerResourceFinder(prefix="profile", finder=profiles)

# serve a CGI request using the directory
wsgiref.handlers.CGIHandler().run(application)
This example constructs the root directory application and then attaches two resources to the application before using the application to respond a CGI request. Resource allocation is described in the following sections.

Installing resources

Root applications containing components that require external resources such as access to user profile storage or external databases may be configured to find those resources using the WHIFF resource interface.  
×
The application may use other mechanisms to locate external resources also -- but using the WHIFF resource interface allows the resource implementation to be "stubbed" or swapped with another implementation easily without effecting the main application implementation.

To attach a resource to a root application, construct a filter object for finding and allocating the resource, and attach the resource to the root application using the registerResourceFinder method.

The following code fragment from the example above allocates a resource finder for storing user profiles as files in a directory, and attaches the resource to the root application using the prefix "profile"

# add user profile resource
profiles = sessionDirectory.directoryProfileFinder("/tmp/profiles")
application.registerResourceFinder(prefix="profile", finder=profiles)
Once this the "profile" resource is installed an application executing on behalf of a user with a profile may get or put profile entries using the resource path for the entry. A configuration template might use the putResource standard middleware to put the Name profile entry like this:
{{include "whiff_middleware/putResource"}}
    {{using path}} ["profile", "item", "Name"] {{/using}}
    {{using value}}Hunter S. Thompson{{/using}}
{{/include}}
A configuration template might use the GetResource standard middleware to get the Name profile entry like this:
{{include "whiff_middleware/getResource"}}
    ["profile", "item", "Name"]
{{/include}}
When the application executes the fragment would expand to the stored profile value Hunter S. Thompson.

Installing static resources

WHIFF provides a streamlined interface for deploying simple read only resource values.
application.registerStaticResource(prefix="ApplicationName", 
	resourceValue="Global Thermonuclear War")
The path to this static resource would be ["ApplicationName"]. Static resources may have any sort of value, including objects with complex interfaces such as user authentication filters.

Standard resources

By default any WHIFF root directory is automatically configured with a number of resources. These resources store global parameters for a single HTTP request. These resources are useful primarily for advanced usage and they are also used by internal WHIFF components.

The cgi standard resource

The read only cgi standard resource stores form input element parameters sent by the HTTP request. The resource path ["cgi"] gets the sequence of names for all cgi parameters. The resource path ["cgi", null] gets the dictionary of names to sequences of values for all cgi parameters. The resource path ["cgi", "NAME"] gets the list of values for the cgi parameter named NAME.

The local standard resource

The local standard resource provides a scratch area which allows different parts of an application to share information. For example an application component concerned with setting HTML style parameters may use the local resource to store style names to be used by other components which generate HTML fragments. The resource path ["local", "NAME"] gets or puts a value named NAME in the local storage resource.

The counter standard resource

The counter standard resource may be used to keep counts. For example a numbered sequence of paragraphs split across two columns may be numbered consistently using a counter stored in the counter resource. To initialize the counter NAME to the value 100, put 100 to the resource path ["counter", "NAME"]. Getting the resource path ["counter", "NAME"] will return the current value for the NAME counter (100) and increment the value (setting it to 101 for the next get).

The freshName standard resource

The read only freshName standard resource is used to generate javascript variable names or DOM identifiers or other names which are guaranteed to be "fresh" -- that is, they have not been used by any other part of the application. Fresh names can be useful, for example, to allow an application component to generate 5 similar javascript functions and assign the functions different names which are guaranteed to not collide with any other name used by the application. A get for the resource path ["freshName", "NAME"] will evaluate to something like NAME542 where NAME542 has not been used by any other part of the application.

Distributed resources implementations

The WHIFF infrastructure includes a number of resource filter implementations which can be useful as examples for how to build a filter for a resource and can also be used directly in an application. Applications may also implement and deploy their own special purpose resources. The interface required for resource finder implementations is described in the Resource Implementation documentation.

The following resource finder implementations are included in the WHIFF distribution.

Directory __init__ files

A module interpreted as a root application may be any Python module which contains the special global assignment
__wsgi_directory__ = True
If this entry is missing WHIFF will refuse to serve any content from the module. This restriction is a security precaution to prevent WHIFF from serving private content accidentally.

Normally the module interpreted as a root application will be a Python package and the __wsgi_directory__ will be placed in the __init__.py initializer for the module.

Served directory content

WHIFF interprets components of a root directory module as WSGI applications only if they have been marked as applications. Other entries in the module will not be served as a security precaution.

Modules within a root directory may be configured as sub-directories or applications or they may not be recognized as WHIFF components at all. The URL naming a contained module is the URL of the parent module joined with the name of the contained module. For example if the URL of the parent directory is http://my.server.com/parent/directory and the module is named mysub then the URL locating the module is http://my.server.com/parent/directory/mysub .

Other modules contained in the root directory will also be interpreted as WHIFF application containers if they contain the __wsgi_directory__ = True marking.

Other modules contained in the root directory which contain a function named __wsgi__ will be interpreted as WSGI applications where the __wsgi__ function defines the application to respond to web requests on behalf of the module.

Other modules contained in the root directory which contain a constructor named __middleware__ will be interpreted as WSGI middleware applications where the __middleware__ callable defines a constructor for creating middleware components on behalf of the module.

There are other ways to install WSGI functionality in a root directory which WHIFF will recognized, but they are not documented here at the moment, and they are not recommended for normal use.

Recognizing templates and files in a directory

By default a module root application will not serve any configuration templates or other external files contained in the module directory unless the __init__.py configuration for the module specifies otherwise. To direct a root module to serve configuration template files and files with recognized extensions add a line in the __init__.py like this:
resolver.publish_templates(__path__[0], globals(), 
	mime_extensions=True, directory_middleware=True)
This function call will search the module directory (located at __path__[0]) and create recognized WHIFF applications to respond to configuration templates and files with extensions that correspond to recognized MIME types. For example if the directory contains a file named Application.whiff the content of the file will be interpreted as a configuration template and requests with the relative URL Application will be served by that template. If the directory contains a file named Picture.jpg the content of the file will be interpreted as a JPEG image and requests with the relative URL Picture.jpg will be served the contents of that file.

If the keyword directory_middleware=True is specified then the directory will also respond to the relative URL "." by returning an HTML directory listing (this is useful for testing, but may not be advisable for "production" deploys).

Importing applications or other root directories into a directory

The directory __init__.py file may include standard Python import statements in order to make applications available from that directory.

An __init__.py can import a simple application or middleware for local use. For example a directory which makes extensive use of the Mako templating engine may include

from whiff.middleware.mako import MakoFile
in the __init__.py, and this will allow all the components in the directory to use the directive
{{include "MakoFile"}} ... {{/include}}
in place of the more verbose path to the MakoFile middleware
{{include "whiff_middleware/mako/MakoFile"}} ... {{/include}}

Furthermore a directory may import another root directory module to "mount" another application within the directory. For example the following sequence mounts the root directory gfChat in the file /usr/local/apache2/wsgi/top/__init__.py, to install the WHIFF "chat" demo on my test server under the directory top.

import gfChat
Furthermore application constructors which require parameters may be parameterized in the __init__.py file. For example the following declaration parameterizes the "python source code demo" on my test server.
from whiff.servers.fsCSI import fsCSI
search = fsCSI.getApplication("/export/archive", "/export/Python-2.6.1")
Subsections:

++ Implementing a resource finder    
×
This section describes how to implement a special purpose resource for an application.

0 comments.
Care to comment?
name: (required)
- email (not published):
comment: (required)

<< security number? >>