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.
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
.
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.
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 content_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" : WebStack.Generic.ContentType("text/html", "utf-8")}
Note that the .
character is omitted from the filename extension. Where it is tedious
to create content type objects and where the same character encoding
applies for all types of files, it is possible to use the media_types
and default_encoding
parameters instead.
The API documentation for the DirectoryResource
class provides more information on the usage of the class.
The DirectoryResource
class (found in the WebStack.Resources.Static
module) accepts the following parameters when being initialised:
directory
media_types
unrecognised_media_type
media_types
parameter.content_types
WebStack.Generic.ContentType
).unrecognised_content_type
content_types
parameter.default_encoding
media_types
and unrecognised_media_type
parameters. If not specified, no character encoding will be stated for content associated with such media types.urlencoding
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", media_types={"css" : "text/css"}),
"scripts" : DirectoryResource("/usr/share/apps/MyApp/scripts", media_types={"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
.