pyramid.static

class static_view(root_dir, cache_max_age=3600, package_name=None, use_subpath=False, index='index.html', reload=False, content_encodings=())

An instance of this class is a callable which can act as a Pyramid view callable; this view will serve static files from a directory on disk based on the root_dir you provide to its constructor.

The directory may contain subdirectories (recursively); the static view implementation will descend into these directories as necessary based on the components of the URL in order to resolve a path into a response.

You may pass an absolute or relative filesystem path or a asset specification representing the directory containing static files as the root_dir argument to this class' constructor.

If the root_dir path is relative, and the package_name argument is None, root_dir will be considered relative to the directory in which the Python file which calls static resides. If the package_name name argument is provided, and a relative root_dir is provided, the root_dir will be considered relative to the Python package specified by package_name (a dotted path to a Python package).

cache_max_age influences the Expires and Max-Age response headers returned by the view (default is 3600 seconds or one hour).

use_subpath influences whether request.subpath will be used as PATH_INFO when calling the underlying WSGI application which actually serves the static files. If it is True, the static application will consider request.subpath as PATH_INFO input. If it is False, the static application will consider request.environ[PATH_INFO] as PATH_INFO input. By default, this is False.

reload controls whether a cache of files is maintained or the asset subsystem is queried per-request to determine what files are available. By default, this is False and new files added while the process is running are not recognized.

content_encodings is a list of alternative file encodings supported in the Accept-Encoding HTTP Header. Alternative files are found using file extensions defined in mimetypes.encodings_map. An encoded asset will be returned with the Content-Encoding header set to the selected encoding. If the asset contains alternative encodings then the Accept-Encoding value will be added to the response's Vary header. By default, the list is empty and no alternatives will be supported.

Note

If the root_dir is relative to a package, or is a asset specification the Pyramid pyramid.config.Configurator method can be used to override assets within the named root_dir package-relative directory. However, if the root_dir is absolute, configuration will not be able to override the assets it contains.

Changed in version 2.0: Added reload and content_encodings options.

find_best_match(request, files)

Return (path | None, encoding).

find_resource_path(name)

Return the absolute path to the resource or None if it doesn't exist.

get_possible_files(resource_name)

Return a sorted list of (size, encoding, path) entries.

get_resource_name(request)

Return the computed name of the requested resource.

The returned file is not guaranteed to exist.

class ManifestCacheBuster(manifest_spec, reload=False)

An implementation of ICacheBuster which uses a supplied manifest file to map an asset path to a cache-busted version of the path.

The manifest_spec can be an absolute path or a asset specification pointing to a package-relative file.

The manifest file is expected to conform to the following simple JSON format:

{
    "css/main.css": "css/main-678b7c80.css",
    "images/background.png": "images/background-a8169106.png",
}

By default, it is a JSON-serialized dictionary where the keys are the source asset paths used in calls to static_url(). For example:

>>> request.static_url('myapp:static/css/main.css')
"http://www.example.com/static/css/main-678b7c80.css"

The file format and location can be changed by subclassing and overriding parse_manifest().

If a path is not found in the manifest it will pass through unchanged.

If reload is True then the manifest file will be reloaded when changed. It is not recommended to leave this enabled in production.

If the manifest file cannot be found on disk it will be treated as an empty mapping unless reload is False.

New in version 1.6.

static exists(path)

Test whether a path exists. Returns False for broken symbolic links

static getmtime(filename)

Return the last modification time of a file, reported by os.stat().

property manifest

The current manifest dictionary.

parse_manifest(content)

Parse the content read from the manifest_path into a dictionary mapping.

Subclasses may override this method to use something other than json.loads to load any type of file format and return a conforming dictionary.

class QueryStringCacheBuster(param='x')

An implementation of ICacheBuster which adds a token for cache busting in the query string of an asset URL.

The optional param argument determines the name of the parameter added to the query string and defaults to 'x'.

To use this class, subclass it and provide a tokenize method which accepts request, pathspec, kw and returns a token.

New in version 1.6.

class QueryStringConstantCacheBuster(token, param='x')

An implementation of ICacheBuster which adds an arbitrary token for cache busting in the query string of an asset URL.

The token parameter is the token string to use for cache busting and will be the same for every request.

The optional param argument determines the name of the parameter added to the query string and defaults to 'x'.

New in version 1.6.