- a GIF image file contained within a Python package or contained within any subdirectory of a Python package.
- a CSS file contained within a Python package or contained within any subdirectory of a Python package.
- A directory within a package that does not have an
__init__.pyin it (if it possessed an
__init__.pyit would be a package).
- a :term:`Chameleon` or :term:`Mako` template file contained within a Python package.
The use of assets is quite common in most web development projects. For
example, when you create a :app:`Pyramid` application using one of the
available scaffolds, as described in :ref:`creating_a_project`, the
directory representing the application contains a Python :term:`package`.
Within that Python package, there are directories full of files which are
static assets. For example, there's a
static directory which contains
.gif files. These asset files are delivered when
a user visits an application URL.
Understanding Asset Specifications
Let's imagine you've created a :app:`Pyramid` application that uses a
:term:`Chameleon` ZPT template via the
:func:`pyramid.renderers.render_to_response` API. For example, the
application might address the asset using the :term:`asset specification`
myapp:templates/some_template.pt using that API within a
file inside a
"Under the hood", when this API is called, :app:`Pyramid` attempts to make
sense out of the string
myapp:templates/some_template.pt provided by the
developer. This string is an :term:`asset specification`. It is composed of
- The package name (
- The asset name (
templates/some_template.pt), relative to the package directory.
The two parts are separated by the colon character.
:app:`Pyramid` uses the Python :term:`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
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. :app:`Pyramid` APIs which accept relative asset
specifications typically describe what the asset is relative to in their
Serving Static Assets
:app:`Pyramid` makes it possible to serve up static asset files from a
directory on a filesystem to an application user's browser. Use the
:meth:`pyramid.config.Configurator.add_static_view` to instruct
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.
:meth:`~pyramid.config.Configurator.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 :app:`Pyramid` application. For these features, see :ref:`advanced_static`.
Here's an example of a use of
:meth:`~pyramid.config.Configurator.add_static_view` that will serve files up
/var/www/static directory of the computer which runs the
:app:`Pyramid` application as URLs beneath the
/static URL prefix.
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,
/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
prefix. Therefore, the file
/var/www/static/foo.css will be returned
when the user visits your application's URL
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
:meth:`~pyramid.config.Configurator.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
path arguments, also pass the
keyword argument to :meth:`~pyramid.config.Configurator.add_static_view`.
The value of the
permission argument represents the :term:`permission`
that the user must have relative to the current :term:`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,
Here's another example that uses an :term:`asset specification` instead of an
absolute path as the
path argument. To convince
:meth:`~pyramid.config.Configurator.add_static_view` to serve files up under
/static URL from the
a/b/c/static directory of the Python package
some_package, we can use a fully qualified :term:`asset
specification` as the
path provided to :meth:`~pyramid.config.Configurator.add_static_view`
may be a fully qualified :term:`asset specification` or an absolute path.
Instead of representing a URL prefix, the
name argument of a call to
:meth:`~pyramid.config.Configurator.add_static_view` can alternately be a
URL. Each of examples we've seen so far have shown usage of the
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 :func:`pyramid.url.static_url`.
For example, :meth:`~pyramid.config.Configurator.add_static_view` may
be fed a
name argument which is
Because :meth:`~pyramid.config.Configurator.add_static_view` is provided with
name argument that is the URL
calls to :func:`~pyramid.url.static_url` with paths that start with the
path argument passed to
:meth:`~pyramid.config.Configurator.add_static_view` will generate a URL
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 :func:`~pyramid.url.static_url` API is
discussed in more detail later in this chapter.
Generating Static Asset URLs
When a :meth:`~pyramid.config.Configurator.add_static_view` method is used to
register a static asset directory, a special helper API named
:func:`pyramid.url.static_url` can be used to generate the appropriate URL
for an asset that lives in one of the directories named by the static
For example, let's assume you create a set of static declarations like so:
These declarations create URL-accessible directories which have URLs that
/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
You needn't generate the URLs to static assets "by hand" in such a configuration. Instead, use the :func:`~pyramid.url.static_url` API to generate them for you. For example:
If the request "application URL" of the running system is
css_url generated above would be:
above would be
One benefit of using the :func:`~pyramid.url.static_url` function rather than
constructing static URLs "by hand" is that if you need to change the
of a static URL declaration, the generated URLs will continue to resolve
properly after the rename.
URLs may also be generated by :func:`~pyramid.url.static_url` to static assets
that live outside the :app:`Pyramid` application. This will happen when
the :meth:`~pyramid.config.Configurator.add_static_view` API associated with
the path fed to :func:`~pyramid.url.static_url` is a URL instead of a view
name. For example, the
name argument may be
path given may be
Under such a configuration, the URL generated by
assets which begin with
mypackage:images will be prefixed with
Using :func:`~pyramid.url.static_url` in conjunction with a
:meth:`~pyramid.configuration.Configurator.add_static_view` makes it possible
to put static media on a separate webserver during production (if the
name argument to :meth:`~pyramid.config.Configurator.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
:meth:`~pyramid.config.Configurator.add_static_view` is a URL prefix). To
create such a circumstance, we suggest using the
:attr:`pyramid.registry.Registry.settings` API in conjunction with a setting
in the application
.ini file named
media_location. Then set the
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
could be used.
Advanced: Serving Static Assets Using a View Callable
For more flexibility, static assets can be served by a :term:`view callable` which you register manually. For example, if you're using :term:`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 :func:`~pyramid.url.static_url` API to generate URLs against assets made accessible by registering a custom static view.
Root-Relative Custom Static View (URL Dispatch Only)
The :class:`pyramid.view.static` 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 :meth:`~pyramid.config.Configurator.add_static_view` configuration method, so its behavior is almost exactly the same once it's configured.
The following example will not work for applications that use
:term:`traversal`, it will only work if you use :term:`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
:class:`~pyramid.view.static` static view cannot be made root-relative when
you use traversal.
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
:class:`~pyramid.view.static` class inside a
static.py file in your
application root as below.
For better cross-system flexibility, use an :term:`asset
specification` as the argument to :class:`~pyramid.view.static` instead of
a physical absolute filesystem path, e.g.
mypackage:static instead of
Subsequently, you may wire the files that are served by this view up to be
/<filename> using a configuration method in your
application's startup code.
The special name
*subpath above is used by the
:class:`~pyramid.view.static` view callable to signify the path of the file
relative to the directory you're serving.
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.
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
uses the Python
open function to obtain a file handle to a file within
static, and returns a response using the open the file
handle as the response's
app_iter. It makes sure to set the right
You might register such a view via configuration as a view callable that should be called as the result of a traversal:
Or you might register it to be the view callable for a particular route:
It can often be useful to override specific assets from "outside" a given :app:`Pyramid` application. For example, you may wish to reuse an existing :app:`Pyramid` application more or less unchanged. However, some specific template file owned by the application might have inappropriate HTML, or some static asset (such as a logo file or some CSS file) might not be appropriate. You could just fork the application entirely, but it's often more convenient to just override the assets that are inappropriate and reuse the application "as is". This is particularly true when you reuse some "core" application over and over again for some set of customers (such as a CMS application, or some bug tracking application), and you want to make arbitrary visual modifications to a particular application deployment without forking the underlying code.
To this end, :app:`Pyramid` contains a feature that makes it possible to "override" one asset with one or more other assets. In support of this feature, a :term:`Configurator` API exists named :meth:`pyramid.config.Configurator.override_asset`. This API allows you to override the following kinds of assets defined in any Python package:
- Individual :term:`Chameleon` templates.
- A directory containing multiple Chameleon templates.
- Individual static files served up by an instance of the
- A directory of static files served up by an instance of the
- Any other asset (or set of assets) addressed by code that uses the setuptools :term:`pkg_resources` API.
The :term:`ZCML` directive named
asset serves the same purpose
as the :meth:`~pyramid.config.Configurator.override_asset` method.
An individual call to :meth:`~pyramid.config.Configurator.override_asset` can override a single asset. For example:
The string value passed to both
override_with sent to
override_asset API is called an :term:`asset specification`. The
colon separator in a specification separates the package name from the
asset name. The colon and the following asset name are optional. If they
are not specified, the override attempts to resolve every lookup into a
package from the directory of another package. For example:
Individual subdirectories within a package can also be overridden:
If you wish to override a directory with another directory, you must
make sure to attach the slash to the end of both the
specification and the
override_with specification. If you fail to
attach a slash to the end of a specification that points to a directory,
you will get unexpected results.
You cannot override a directory specification with a file specification, and vice versa: a startup error will occur if you try. You cannot override an asset with itself: a startup error will occur if you try.
Only individual package assets may be overridden. Overrides will not
traverse through subpackages within an overridden package. This means that
if you want to override assets for both
some.package.views:templates, you will need to register two overrides.
The package name in a specification may start with a dot, meaning that
the package is relative to the package in which the configuration
construction file resides (or the
package argument to the
:class:`~pyramid.config.Configurator` class construction).
Multiple calls to
override_asset which name a shared
override_with specification can be "stacked" to form a search
path. The first asset that exists in the search path will be used; if no
asset exists in the override path, the original asset is used.
Asset overrides can actually override assets other than templates and static files. Any software which uses the :func:`pkg_resources.get_resource_filename`, :func:`pkg_resources.get_resource_stream` or :func:`pkg_resources.get_resource_string` APIs will obtain an overridden file when an override is used.