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
.css, .js, and .gif files. These asset files are delivered when
a user visits an application URL.

"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
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.

: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 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. :app:`Pyramid` APIs which accept relative asset
specifications typically describe what the asset is relative to in their
individual documentation.

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
:app:`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.

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.

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

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.

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 :meth:`~pyramid.request.Request.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.

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.

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 route_name). A
:class:`~pyramid.static.static_view` static view cannot be made
root-relative when you use traversal unless it's registered as a
:term:`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
:class:`~pyramid.static.static_view` class inside a static.py file in
your application root as below.

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
"here" named static, and returns a response using the open the file
handle as the response's app_iter. It makes sure to set the right
content_type too.

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:

Overriding Assets

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.

The override_asset API

The string value passed to both to_override and override_with sent to
the 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 to_override
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:templates, and
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).
For example:

Multiple calls to override_asset which name a shared to_override but
a different 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.