13.3. ADVANCED: SERVING STATIC ASSETS USING A VIEW CALLABLE

If the request “application URL” of the running system is http://example.com, the css_url generated above would be: http://example.com/static1/foo.css. The js_url generated above would be http://example.com/static2/foo.js.

One benefit of using the static_url() function rather than constructing static URLs “by hand” is that if you need to change the name of a static URL declaration, the generated URLs will continue to resolve properly after the rename.

URLs may also be generated by static_url() to static assets that live outside the Pyramid application. This will happen when the add_static_view() API associated with the path fed to static_url() is a URL instead of a view name. For example, the name argument may be http://example.com while the the path given may be mypackage:images:

1	config.add_static_view(name=’http://example.com/images’,
2	path=’mypackage:images’)

Under such a configuration, the URL generated by static_url for assets which begin with mypackage:images will be prefixed with http://example.com/images:

1

2

request.static_url(’mypackage:images/logo.png’)

# -> http://example.com/images/logo.png

Using static_url() in conjunction with a add_static_view() makes it possible to put static media on a separate webserver during production (if the name argument to add_static_view() is a URL), while keeping static media package-internal and served by the development webserver during development (if the name argument to add_static_view() is a URL prefix). To create such a circumstance, we suggest using the pyramid.registry.Registry.settings API in conjunction with a setting in the application .ini file named media_location. Then set the value of media_location to either a prefix or a URL depending on whether the application is being run in development or in production (use a different .ini file for production than you do for development). This is just a suggestion for a pattern; any setting name other than media_location could be used.

13.3 Advanced: Serving Static Assets Using a View Callable

For more flexibility, static assets can be served by a view callable which you register manually. For example, if you’re using URL dispatch, you may want static assets to only be available as a fallback if no previous route matches. Alternately, you might like to serve a particular static asset manually, because its download requires authentication.

Note that you cannot use the static_url() API to generate URLs against assets made accessible by registering a custom static view.

157

13. STATIC ASSETS

13.3.1 Root-Relative Custom Static View (URL Dispatch Only)

The pyramid.static.static_view helper class generates a Pyramid view callable. This view callable can serve static assets from a directory. An instance of this class is actually used by the add_static_view() configuration method, so its behavior is almost exactly the same once it’s configured.

latex-warning.png

The following example will not work for applications that use traversal, it will only work if you use URL dispatch exclusively. The root-relative route we’ll be registering will always be matched before traversal takes place, subverting any views registered via add_view (at least those without a route_name). A static_view static view cannot be made root-relative when you use traversal unless it’s registered as a Not Found view.

To serve files within a directory located on your filesystem at /path/to/static/dir as the result of a “catchall” route hanging from the root that exists at the end of your routing table, create an instance of the static_view class inside a static.py file in your application root as below.

1

2

from pyramid.static import static_view

static_view = static_view(’/path/to/static/dir’, use_subpath=True)

latex-note.png

For better cross-system flexibility, use an asset specification as the argument to static_view instead of a physical absolute filesystem path, e.g. mypackage:static instead of /path/to/mypackage/static.

Subsequently, you may wire the files that are served by this view up to be accessible as /<filename> using a configuration method in your application’s startup code.

158

	13.3. ADVANCED: SERVING STATIC ASSETS USING A VIEW CALLABLE
1	# .. every other add_route declaration should come
2	# before this one, as it will, by default, catch all requests
3
4	config.add_route(’catchall_static’, ’/*subpath’)
5	config.add_view(’myapp.static.static_view’, route_name=’catchall_static’)

The special name *subpath above is used by the static_view view callable to signify the path of the file relative to the directory you’re serving.

13.3.2 Registering A View Callable to Serve a “Static” Asset

You can register a simple view callable to serve a single static asset. To do so, do things “by hand”. First define the view callable.

1	import os
2	from pyramid.response import FileResponse
3
4	def favicon_view(request):

5here = os.path.dirname(__file__)

6 icon = os.path.join(here, ’static’, ’favicon.ico’)

7return FileResponse(icon, request=request)

The above bit of code within favicon_view computes “here”, which is a path relative to the Python file in which the function is defined. It then creates a pyramid.response.FileResponse using the file path as the response’s path argument and the request as the response’s request argument. pyramid.response.FileResponse will serve the file as quickly as possible when it’s used this way. It makes sure to set the right content length and content_type too based on the file extension of the file you pass.

You might register such a view via configuration as a view callable that should be called as the result of a traversal:

1 config.add_view(’myapp.views.favicon_view’, name=’favicon.ico’)

Or you might register it to be the view callable for a particular route:

1

2

config.add_route(’favicon’, ’/favicon.ico’) config.add_view(’myapp.views.favicon_view’, route_name=’favicon’)

Because this is a simple view callable, it can be protected with a permission or can be configured to respond under different circumstances using view predicate arguments.

159