13. STATIC ASSETS

1

2

from pyramid.renderers import render_to_response render_to_response(’myapp:templates/some_template.pt’, {}, request)

“Under the hood”, when this API is called, Pyramid attempts to make sense out of the string myapp:templates/some_template.pt provided by the developer. This string is an asset specification. It is composed of two parts:

•The package name (myapp)

•The asset name (templates/some_template.pt), relative to the package directory. The two parts are separated by the colon character.

Pyramid uses the Python pkg_resources API to resolve the package name and asset name to an absolute (operating-system-specific) file name. It eventually passes this resolved absolute filesystem path to the Chameleon templating engine, which then uses it to load, parse, and execute the template file.

There is a second form of asset specification: a relative asset specification. Instead of using an “absolute” asset specification which includes the package name, in certain circumstances you can omit the package name from the specification. For example, you might be able to use templates/mytemplate.pt instead of myapp:templates/some_template.pt. Such asset specifications are usually relative to a “current package.” The “current package” is usually the package which contains the code that uses the asset specification. Pyramid APIs which accept relative asset specifications typically describe what the asset is relative to in their individual documentation.

13.2 Serving Static Assets

Pyramid makes it possible to serve up static asset files from a directory on a filesystem to an application user’s browser. Use the pyramid.config.Configurator.add_static_view() to instruct Pyramid to serve static assets such as JavaScript and CSS files. This mechanism makes a directory of static files available at a name relative to the application root URL, e.g. /static or as an external URL.

latex-note.png

add_static_view() cannot serve a single file, nor can it serve a directory of static files directly relative to the root URL of a Pyramid application. For these features, see Advanced: Serving Static Assets Using a View Callable.

154

13.2. SERVING STATIC ASSETS

Here’s an example of a use of add_static_view() that will serve files up from the /var/www/static directory of the computer which runs the Pyramid application as URLs beneath the /static URL prefix.

1

2

# config is an instance of pyramid.config.Configurator config.add_static_view(name=’static’, path=’/var/www/static’)

The name prepresents a URL prefix. In order for files that live in the path directory to be served, a URL that requests one of them must begin with that prefix. In the example above, name is static, and path is /var/www/static. In English, this means that you wish to serve the files that live in /var/www/static as sub-URLs of the /static URL prefix. Therefore, the file /var/www/static/foo.css will be returned when the user visits your application’s URL

/static/foo.css.

A static directory named at path may contain subdirectories recursively, and any subdirectories may hold files; these will be resolved by the static view as you would expect. The Content-Type header returned by the static view for each particular type of file is dependent upon its file extension.

By default, all files made available via add_static_view() are accessible by completely anonymous users. Simple authorization can be required, however. To protect a set of static files using a permission, in addition to passing the required name and path arguments, also pass the permission keyword argument to add_static_view(). The value of the permission argument represents the permission that the user must have relative to the current context when the static view is invoked. A user will be required to possess this permission to view any of the files represented by path of the static view. If your static assets must be protected by a more complex authorization scheme, see Advanced: Serving Static Assets Using a View Callable.

Here’s another example that uses an asset specification instead of an absolute path as the path argument. To convince add_static_view() to serve files up under the /static URL from the a/b/c/static directory of the Python package named some_package, we can use a fully qualified asset specification as the path:

1

2

# config is an instance of pyramid.config.Configurator config.add_static_view(name=’static’, path=’some_package:a/b/c/static’)

The path provided to add_static_view() may be a fully qualified asset specification or an absolute path.

Instead of representing a URL prefix, the name argument of a call to add_static_view() can alternately be a URL. Each of examples we’ve seen so far have shown usage of the name argument as a URL prefix. However, when name is a URL, static assets can be served from an external webserver. In this mode, the name is used as the URL prefix when generating a URL using pyramid.request.Request.static_url().

155

13. STATIC ASSETS

For example, add_static_view() may be fed a name argument which is http://example.com/images:

1

2

3

# config is an instance of pyramid.config.Configurator config.add_static_view(name=’http://example.com/images’,

path=’mypackage:images’)

Because add_static_view() is provided with a name argument that is the URL http://example.com/images, subsequent calls to static_url() with paths that start with the path argument passed to add_static_view() will generate a URL something like http://example.com/images/logo.png. The external webserver listening on example.com must be itself configured to respond properly to such a request. The static_url() API is discussed in more detail later in this chapter.

13.2.1 Generating Static Asset URLs

When a add_static_view() method is used to register a static asset directory, a special helper API named pyramid.request.Request.static_url() can be used to generate the appropriate URL for an asset that lives in one of the directories named by the static registration path attribute.

For example, let’s assume you create a set of static declarations like so:

1

2

config.add_static_view(name=’static1’, path=’mypackage:assets/1’) config.add_static_view(name=’static2’, path=’mypackage:assets/2’)

These declarations create URL-accessible directories which have URLs that begin with /static1 and /static2, respectively. The assets in the assets/1 directory of the mypackage package are consulted when a user visits a URL which begins with /static1, and the assets in the assets/2 directory of the mypackage package are consulted when a user visits a URL which begins with /static2.

You needn’t generate the URLs to static assets “by hand” in such a configuration. Instead, use the static_url() API to generate them for you. For example:

1 from pyramid.chameleon_zpt import render_template_to_response

2

3 def my_view(request):

4css_url = request.static_url(’mypackage:assets/1/foo.css’)

5js_url = request.static_url(’mypackage:assets/2/foo.js’)

6return render_template_to_response(’templates/my_template.pt’,

7	css_url = css_url,
8	js_url = js_url)

156