'Add a view used to render static assets such as images
and CSS files.
The ``name`` argument is a string representing an
application-relative local URL prefix.  It may alternately be a full
URL.
The ``path`` argument is the path on disk where the static files
reside.  This can be an absolute path, a package-relative path, or a
:term:`asset specification`.
The ``cache_max_age`` keyword argument is input to set the
``Expires`` and ``Cache-Control`` headers for static assets served.
Note that this argument has no effect when the ``name`` is a *url
prefix*.  By default, this argument is ``None``, meaning that no
particular Expires or Cache-Control headers are set in the response.
The ``permission`` keyword argument is used to specify the
:term:`permission` required by a user to execute the static view.  By
default, it is the string
:data:`pyramid.security.NO_PERMISSION_REQUIRED`, a special sentinel
which indicates that, even if a :term:`default permission` exists for
the current application, the static view should be renderered to
completely anonymous users.  This default value is permissive
because, in most web apps, static assets seldom need protection from
viewing.  If ``permission`` is specified, the security checking will
be performed against the default root factory ACL.
Any other keyword arguments sent to ``add_static_view`` are passed on
to :meth:`pyramid.config.Configurator.add_route` (e.g. ``factory``,
perhaps to define a custom factory with a custom ACL for this static
view).
*Usage*
The ``add_static_view`` function is typically used in conjunction
with the :meth:`pyramid.request.Request.static_url` method.
``add_static_view`` adds a view which renders a static asset when
some URL is visited; :meth:`pyramid.request.Request.static_url`
generates a URL to that asset.
The ``name`` argument to ``add_static_view`` is usually a simple URL
prefix (e.g. ``\'images\'``).  When this is the case, the
:meth:`pyramid.request.Request.static_url` API will generate a URL
which points to a Pyramid view, which will serve up a set of assets
that live in the package itself. For example:
.. code-block:: python
add_static_view(\'images\', \'mypackage:images/\')
Code that registers such a view can generate URLs to the view via
:meth:`pyramid.request.Request.static_url`:
.. code-block:: python
request.static_url(\'mypackage:images/logo.png\')
When ``add_static_view`` is called with a ``name`` argument that
represents a URL prefix, as it is above, subsequent calls to
:meth:`pyramid.request.Request.static_url` with paths that start with
the ``path`` argument passed to ``add_static_view`` will generate a
URL something like ``http://<Pyramid app URL>/images/logo.png``,
which will cause the ``logo.png`` file in the ``images`` subdirectory
of the ``mypackage`` package to be served.
``add_static_view`` can alternately be used with a ``name`` argument
which is a *URL*, causing static assets to be served from an external
webserver.  This happens when the ``name`` argument is a fully
qualified URL (e.g. starts with ``http://`` or similar).  In this
mode, the ``name`` is used as the prefix of the full URL when
generating a URL using :meth:`pyramid.request.Request.static_url`.
Furthermore, if a protocol-relative URL (e.g. ``//example.com/images``)
is used as the ``name`` argument, the generated URL will use the
protocol of the request (http or https, respectively).
For example, if ``add_static_view`` is called like so:
.. code-block:: python
add_static_view(\'http://example.com/images\', \'mypackage:images/\')
Subsequently, the URLs generated by
:meth:`pyramid.request.Request.static_url` for that static view will
be prefixed with ``http://example.com/images`` (the external webserver
listening on ``example.com`` must be itself configured to respond
properly to such a request.):
.. code-block:: python
static_url(\'mypackage:images/logo.png\', request)
See :ref:`static_assets_section` for more information.'

@action_method
def add_static_view(self, name, path, **kw):

    spec = self._make_spec(path)
    info = self._get_static_info()
    info.add(self, name, spec, **kw)
