# HG changeset patch # User paulb # Date 1132454226 0 # Node ID f0e5c72e3b703c3e9bd4bfa9e7622e8bc30a8c90 # Parent 34f43e9349baa17742bbc7c40d5b2873ddbadba4 [project @ 2005-11-20 02:37:06 by paulb] Added reference documentation for repositories, static content and resource mapping. diff -r 34f43e9349ba -r f0e5c72e3b70 docs/developing.html --- a/docs/developing.html Sun Nov 20 02:36:31 2005 +0000 +++ b/docs/developing.html Sun Nov 20 02:37:06 2005 +0000 @@ -78,4 +78,8 @@ be reviewed when encountering problems with input and output text:

Deployment

The following topics (illustrated by the programs found in the other subdirectories of the examples directory) describe how WebStack applications may be deployed in server environments:

\ No newline at end of file +Features in Server Environments

Useful Additions

WebStack +provides a number of potentially useful modules either providing +resource classes for direct use in applications, or providing other +kinds of classes and functions which may be used to perform particular +activities.

The following resources are provided for direct use in applications:

WebStack also provides modules which provide session-like access to different kinds of repositories:

\ No newline at end of file diff -r 34f43e9349ba -r f0e5c72e3b70 docs/directory-repository.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/directory-repository.html Sun Nov 20 02:37:06 2005 +0000 @@ -0,0 +1,32 @@ + + + + DirectoryRepository - Simple Access to Files in a Directory + + +

DirectoryRepository - Simple Access to Files in a Directory

+

In applications it is often convenient to be able to save or remember information provided or edited by a user. Whilst sessions +often provide a convenient means of remembering such information, they +have certain limitations, notably that they are only available to a +particular user and cannot be shared with other users, and that their +data is stored in a form that is not necessarily convenient to access +by other tools or systems.

The principle behind the DirectoryRepository +class is that it stores information as files in a designated directory, +that such files can be accessed by any resource with access to that +directory, and that a certain degree of locking is provided to avoid +contention between resources. Once created, instances of DirectoryRepository +can be accessed almost like sessions, although it is possible to obtain +the full paths to files in the repository and to use file objects and +methods to obtain and deposit content in such files.

WebStack API - DirectoryRepository Initialisation

The DirectoryRepository class (found in the WebStack.Repositories.Directory module) accepts the following parameters when being initialised:

path
This parameter specifies the path to the directory in the filesystem where repository files are to be stored.
fsencoding
This +optional parameter specifies the character encoding employed by the +filesystem to represent filenames. If left unspecified, the +implementation will attempt to guess the correct encoding or, where +supported, to use Unicode filenames.
delay
This +optional parameter specifies a delay period for which a program will be +made to wait if a repository file is found to be locked by another +process.

Initialisation Strategies

One might choose to initialise a repository in the initialisation method of a resource:

# Inside a module defining a resource...

class MyResource:
    def __init__(self):
        repository_dir = os.path.join(os.path.split(__file__)[0], "repository")
        self.repository = DirectoryRepository(repository_dir, "iso-8859-1")

Here, the repository will reside alongside the resource's module in the filesystem.

Session-like Access

One might use a repository with a session-like API as follows:

# Given a name and some data, possibly provided in user input, store the data in the repository.

repository[name] = data

Note that DirectoryRepository +places some restrictions on the values that can be used as keys in the +session-like API since each key must correspond to a filename within +the designated directory.

Advanced Access

The DirectoryRepository class also provides various methods to support access to files in the repository using standard file objects and methods:

# Given a name and some data...

repository.lock(name)
f = open(repository.full_path(name), "wb")
try:
    f.write(data)
finally:
    f.close()
    repository.unlock(name)

The usage of try and finally +clauses is important to ensure that files are not left locked and +inaccessible due to unhandled exceptions being raised. See the API documentation for the DirectoryRepository class for more information about the available methods and their behaviour.

\ No newline at end of file diff -r 34f43e9349ba -r f0e5c72e3b70 docs/directory-resource.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/directory-resource.html Sun Nov 20 02:37:06 2005 +0000 @@ -0,0 +1,39 @@ + + + + DirectoryResource - Serving Static Content + + +

DirectoryResource - Serving Static Content

+

The DirectoryResource class provides a means to +serve static files from within a particular directory in the +filesystem. By inspecting the remainder of the path information +supplied in an incoming request, instances of DirectoryResource may identify files and serve their contents as a response to such a request.

There are various situations where providing static content is virtually essential:

By instantiating DirectoryResource classes and deploying them in conjunction with MapResource objects (see the "ResourceMap - Simple Mappings from Names to Resources" +document), it should be possible to retain control of the serving of +static content within a WebStack application. Note, however, that the +performance of a system can be improved if the job of serving static +content is delegated to a specialised Web server solution - one might, +for example, set up an Apache Web server to serve things like +stylesheets, script files and images, and then link to the locations of +such things in the Web pages generated by the WebStack application.

WebStack API - The DirectoryResource Class

+

Given a directory from which files shall be served, DirectoryResource uses a simple method to identify files to serve. First, it examines the virtual "path info" and takes the first component of that information. For example, consider the following path information:

/styles.css

Here, DirectoryResource identifies the file to be served as having the name styles.css. Note that any trailing path information would be ignored; for example:

/styles/abc

Here, the file to be served would be identified as having the name styles.

Handling Missing Files

Where +no file exists in the specified directory with the identified +name, a "file not found" response code is set by the resource and a +message is emitted. To modify the simple behaviour of DirectoryResource in this regard, it is recommended that a subclass of DirectoryResource is defined with its own implementation of the not_found method.

Types of Served Files

Given +that a file exists in the specified directory, it is usually critical +that the file is served along with special file type information so +that a user's Web browser may understand the nature of the file's +content. For example, a file containing a Web page must be served with +a file type indicating that the contents of the file are HTML (or some +variant thereof). Instances of DirectoryResource employ +a special registry mapping filename extensions to file types in order +to automate the process of deciding what type a file might be.

Using the media_types parameter (see below), one might choose to serve all files whose names have the .html extension with the HTML file (or content) type. This would be expressed with the following dictionary:

{"html" : "text/html"}

Note that the . +character is omitted from the filename extension and that the file type +(or more correctly, the media type) does not include character set +information.

Further Reading

The API documentation for the DirectoryResource class provides more information on the usage of the class.

Initialisation

The DirectoryResource class (found in the WebStack.Resources.Static module) accepts the following parameters when being initialised:

+
directory
The directory from which static files shall be served.
media_types
A dictionary or dictionary-like object mapping filename extensions to MIME types.
unrecognised_media_type
An optional parameter setting the MIME type for files whose extensions do not map to any MIME type according to the media_types parameter.
urlencoding
When +specified, this parameter forces a particular interpretation of "URL +encoded" character values in the path. Otherwise, the default encoding +is employed to interpret such values. (See "URLs and Paths" for an explanation of "URL encoded" values.)

Combining MapResource with DirectoryResource

One might combine MapResource with DirectoryResource to provide stylesheet and script file directories for an application as follows:

from WebStack.Resources.ResourceMap import MapResource
from WebStack.Resources.Static import DirectoryResource

# This is where the application's resources would be obtained.

app_resource = ...

# Here is where we combine MapResource and DirectoryResource.
# Note that one would not necessarily hard-code directory paths into the application.

top_resource = MapResource({
    "styles" : DirectoryResource("/usr/share/apps/MyApp/styles", {"css" : "text/css"}),
    "scripts" : DirectoryResource("/usr/share/apps/MyApp/scripts", {"js" : "text/javascript"}),
    "" : app_resource
    })

In the above example, any file in the styles directory whose name ends with .css is served as text/css. Similarly, any file in the scripts directory whose name ends with .js is served as text/javascript.

\ No newline at end of file diff -r 34f43e9349ba -r f0e5c72e3b70 docs/resource-map.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/resource-map.html Sun Nov 20 02:37:06 2005 +0000 @@ -0,0 +1,39 @@ + + + + ResourceMap - Simple Mappings from Names to Resources + + + +

ResourceMap - Simple Mappings from Names to Resources

+

The ResourceMap module provides classes (although +currently only one class is supplied) which act as standard WebStack +resources, but which examine the path or URL from incoming requests and +direct such requests to other resources based on the contents of the +path or URL. In other words, such classes map names or patterns to +WebStack resources and dispatch requests accordingly.

Introducing MapResource

The "Treating the Path Like a Filesystem" document contains an example involving the MapResource class; this class is initialised with a dictionary mapping names to resources as described below.

+

WebStack API - The MapResource Class

+ +

The MapResource +class (found in the +WebStack.Resources.ResourceMap module) maps names to +resource objects, where to select a resource the +corresponding name must match the first component discovered +in the virtual "path info". For example, +consider the following virtual "path info" (where there may have been +more information in the path, but this has already been processed):

/documents/news/2005/article.html

Here, the name documents +would match the above virtual "path info". Meanwhile, after processing +more of the information, we might have the following remains of the +path:

/2005/article.html

Here, the name 2005 would match, leaving the following information unprocessed:

/article.html

Here, the name article.html would match. However, let us consider the following original virtual "path info" instead:

/documents/news/2005/

After processing the leading components, we may instead end up with this:

/

Here, only an empty string as the name will specifically match the above.

Further Reading

The API documentation for the MapResource +class provides more detail on the subject of name matching, including +the special "catch all" name and a discussion of the pass-through +parameter.

Initialisation

MapResource objects are initialised with the following parameters:

mapping
A dictionary or dictionary-like object mapping names to resource objects. See above and the API documentation for a description of names.
pass_through
Indicates +whether a component should be removed from the virtual "path info" if +no specific match was made with any of the names, but if the "catch +all" name selected a resource. By default, this parameter is set to a +false value.
directory_redirects
Indicates whether a trailing / character should be added to paths which do not end with such a character, causing a redirect if such a character has to be added.
urlencoding
When +specified, this parameter forces a particular interpretation of "URL +encoded" character values in the path. Otherwise, the default encoding +is employed to interpret such values. (See "URLs and Paths" for an explanation of "URL encoded" values.)
+ +
\ No newline at end of file diff -r 34f43e9349ba -r f0e5c72e3b70 docs/sessions.html --- a/docs/sessions.html Sun Nov 20 02:36:31 2005 +0000 +++ b/docs/sessions.html Sun Nov 20 02:37:06 2005 +0000 @@ -1,12 +1,10 @@ - - + - Sessions and Persistent Information - - - + + Sessions and Persistent Information + +

Sessions and Persistent Information

The term "session" is a technical term describing information which @@ -29,8 +27,7 @@ persistent information - data is addressed or accessed using each user's identity, and the information is partitioned in such a way that sessions cannot be shared between users.

- +
@@ -54,8 +51,8 @@
-

Access to persistent information in general can be done by using -database access libraries, for example - see "Integrating +

Access to persistent information in general can be done in a simple fashion by using +repositories (see "DirectoryRepository - Simple Access to Files in a Directory") or, for example, by using database access libraries - see "Integrating with Other Systems" for more details.

More About Sessions

- - + \ No newline at end of file