- New API class: ``pyramid.static.static_view``. This supersedes the

  deprecated ``pyramid.view.static`` class.  ``pyramid.satic.static_view`` by
  default serves up documents as the result of the request's ``path_info``,
  attribute rather than it's ``subpath`` attribute (the inverse was true of
  ``pyramid.view.static``, and still is).  ``pyramid.static.static_view``
  exposes a ``use_subpath`` flag for use when you don't want the static view
  to behave like the older deprecated version.

- The ``pyramid.view.static`` class has been deprecated in favor of the newer
  ``pyramid.static.static_view`` class.  A deprecation warning is raised when
  it is used.  You should replace it with a reference to
  ``pyramid.static.static_view`` with the ``use_subpath=True`` argument.

4 files changed, 38 insertions, 20 deletions

diff --git a/docs/api.rst b/docs/api.rst
index be7942502..a7e1566d3 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -28,6 +28,7 @@ documentation is organized alphabetically by module name.
    api/security
    api/session
    api/settings
+   api/static
    api/testing
    api/threadlocal
    api/traversal
diff --git a/docs/api/static.rst b/docs/api/static.rst
new file mode 100644
index 000000000..c28473584
--- /dev/null
+++ b/docs/api/static.rst
@@ -0,0 +1,11 @@
+.. _static_module:
+
+:mod:`pyramid.static`
+---------------------
+
+.. automodule:: pyramid.static
+
+  .. autoclass:: static_view
+     :members:
+     :inherited-members:
+
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 0d50b0106..d57687477 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -299,7 +299,7 @@ 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
+The :class:`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
 :meth:`~pyramid.config.Configurator.add_static_view` configuration method, so
@@ -310,26 +310,27 @@ its behavior is almost exactly the same once it's configured.
    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.view.static` static view cannot be made root-relative when
-   you use traversal.
+   :class:`~pyramid.static.static_view` static view cannot be made
+   root-relative when you use traversal unless it's registered as a
+   :term:`NotFound 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.view.static` class inside a ``static.py`` file in your
-application root as below.
+:class:`~pyramid.static.static_view` class inside a ``static.py`` file in
+your application root as below.
 
 .. ignore-next-block
 .. code-block:: python
    :linenos:
 
-   from pyramid.view import static
-   static_view = static('/path/to/static/dir')
+   from pyramid.static import static
+   static_view = static_view('/path/to/static/dir', use_subpath=True)
 
 .. note:: 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
-   ``/path/to/mypackage/static``.
+   specification` as the argument to :class:`~pyramid.static.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
@@ -345,8 +346,8 @@ application's startup code.
    config.add_view('myapp.static.static_view', route_name='catchall_static')
 
 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.
+:class:`~pyramid.static.static_view` 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -425,10 +426,10 @@ feature, a :term:`Configurator` API exists named
 - A directory containing multiple Chameleon templates.
 
 - Individual static files served up by an instance of the
-  ``pyramid.view.static`` helper class.
+  ``pyramid.static.static_view`` helper class.
 
 - A directory of static files served up by an instance of the
-  ``pyramid.view.static`` helper class.
+  ``pyramid.static.static_view`` helper class.
 
 - Any other asset (or set of assets) addressed by code that uses the
   setuptools :term:`pkg_resources` API.
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index 97adaeafd..a0a6a108c 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -431,8 +431,9 @@ Using ``*subpath`` in a Route Pattern
 There are certain extremely rare cases when you'd like to influence the
 traversal :term:`subpath` when a route matches without actually performing
 traversal.  For instance, the :func:`pyramid.wsgi.wsgiapp2` decorator and the
-:class:`pyramid.view.static` helper attempt to compute ``PATH_INFO`` from the
-request's subpath, so it's useful to be able to influence this value.
+:class:`pyramid.static.static_view` helper attempt to compute ``PATH_INFO``
+from the request's subpath when its ``use_subpath`` argument is ``True``, so
+it's useful to be able to influence this value.
 
 When ``*subpath`` exists in a pattern, no path is actually traversed,
 but the traversal algorithm will return a :term:`subpath` list implied
@@ -442,12 +443,16 @@ commonly in route declarations that look like this:
 .. code-block:: python
    :linenos:
 
+   from pryamid.static import static_view
+
+   www = static_view('mypackage:static', use_subpath=True)
+
    config.add_route('static', '/static/*subpath')
-   config.add_view('mypackage.views.static_view', route_name='static')
+   config.add_view(www, route_name='static')
 
-Where ``mypackage.views.static_view`` is an instance of
-:class:`pyramid.view.static`.  This effectively tells the static helper to
-traverse everything in the subpath as a filename.
+``mypackage.views.www`` is an instance of
+:class:`pyramid.static.static_view`.  This effectively tells the static
+helper to traverse everything in the subpath as a filename.
 
 Corner Cases
 ------------