Merge remote-tracking branch 'upstream/pcreate-to-cookiecutter' into pcreate-to-cookiecutter

6 files changed, 74 insertions, 13 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index b22b31bf9..d21edc7b4 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -116,14 +116,6 @@ callable:
 
 .. note::
 
-   Both :meth:`pyramid.config.Configurator.add_notfound_view` and
-   :class:`pyramid.view.notfound_view_config` are new as of Pyramid 1.3.
-   Older Pyramid documentation instructed users to use ``add_view`` instead,
-   with a ``context`` of ``HTTPNotFound``.  This still works; the convenience
-   method and decorator are just wrappers around this functionality.
-
-.. warning::
-
    When a Not Found View callable accepts an argument list as described in
    :ref:`request_and_context_view_definitions`, the ``context`` passed as the
    first argument to the view callable will be the
@@ -131,6 +123,13 @@ callable:
    available, the resource context will still be available as
    ``request.context``.
 
+.. warning::
+
+   The :term:`Not Found View` callables are only invoked when a
+   :exc:`~pyramid.httpexceptions.HTTPNotFound` exception is raised. If the
+   exception is returned from a view then it will be treated as a regular
+   response object and it will not trigger the custom view.
+
 .. index::
    single: forbidden view
 
@@ -210,6 +209,13 @@ Here's some sample code that implements a minimal forbidden view:
    whether the ``pyramid.debug_authorization`` environment setting is true or
    false.
 
+.. warning::
+
+   The :term:`forbidden view` callables are only invoked when a
+   :exc:`~pyramid.httpexceptions.HTTPForbidden` exception is raised. If the
+   exception is returned from a view then it will be treated as a regular
+   response object and it will not trigger the custom view.
+
 .. index::
    single: request factory
 
@@ -744,7 +750,9 @@ The API that must be implemented by a class that provides
           """ Accept the resource and request and set self.physical_path and
           self.virtual_path """
           self.virtual_path =  some_function_of(resource, request)
+          self.virtual_path_tuple =  some_function_of(resource, request)
           self.physical_path =  some_other_function_of(resource, request)
+          self.physical_path_tuple =  some_function_of(resource, request)
 
 The default context URL generator is available for perusal as the class
 :class:`pyramid.traversal.ResourceURL` in the `traversal module
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 570cb2285..c3c2ba64c 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -22,7 +22,7 @@ the following sections.
 .. sidebar:: Python Versions
 
     As of this writing, :app:`Pyramid` is tested against Python 2.7,
-    Python 3.4, Python 3.5, PyPy.
+    Python 3.4, Python 3.5, Python 3.6, and PyPy.
 
 :app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux,
 Mac OS X, and FreeBSD, as well as on Windows platforms.  It is also known to
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 47638579b..adad196e4 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -860,7 +860,7 @@ Every release of Pyramid has 100% statement coverage via unit and integration
 tests, as measured by the ``coverage`` tool available on PyPI.  It also has
 greater than 95% decision/condition coverage as measured by the
 ``instrumental`` tool available on PyPI. It is automatically tested by Travis,
-and Jenkins on Python 2.7, Python 3.4, Python 3.5, and PyPy
+and Jenkins on Python 2.7, Python 3.4, Python 3.5, Python 3.6, and PyPy
 after each commit to its GitHub repository. Official Pyramid add-ons are held
 to a similar testing standard.  We still find bugs in Pyramid and its official
 add-ons, but we've noticed we find a lot more of them while working on other
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index 71bd176f6..77c637571 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -1045,3 +1045,45 @@ Another good production alternative is :term:`Green Unicorn` (aka
 mod_wsgi, although it depends, in its default configuration, on having a
 buffering HTTP proxy in front of it.  It does not, as of this writing, work on
 Windows.
+
+Automatically Reloading Your Code
+---------------------------------
+
+During development, it can be really useful to automatically have the
+webserver restart when you make changes. ``pserve`` has a ``--reload`` switch
+to enable this. It uses the
+`hupper <http://docs.pylonsproject.org/projects/hupper/en/latest/>` package
+to enable this behavior. When your code crashes, ``hupper`` will wait for
+another change or the ``SIGHUP`` signal before restarting again.
+
+inotify support
+~~~~~~~~~~~~~~~
+
+By default, ``hupper`` will poll the filesystem for changes to all python
+code. This can be pretty inefficient in larger projects. To be nicer to your
+hard drive, you should install the
+`watchdog <http://pythonhosted.org/watchdog/>` package in development.
+``hupper`` will automatically use ``watchdog`` to more efficiently poll the
+filesystem.
+
+Monitoring Custom Files
+~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, ``pserve --reload`` will monitor all imported Python code
+(everything in ``sys.modules``) as well as the config file passed to
+``pserve`` (e.g. ``development.ini``). You can instruct ``pserve`` to watch
+other files for changes as well by defining a ``[pserve]`` section in your
+configuration file. For example, let's say your application loads the
+``favicon.ico`` file at startup and stores it in memory to efficiently
+serve it many times. When you change it you want ``pserve`` to restart:
+
+.. code-block:: ini
+
+    [pserve]
+    watch_files =
+        myapp/static/favicon.ico
+
+Paths may be absolute or relative to the configuration file. They may also
+be an :term:`asset specification`. These paths are passed to ``hupper`` which
+has some basic support for globbing. Acceptable glob patterns depend on the
+version of Python being used.
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index a1319e45f..5b24201a9 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -157,6 +157,12 @@ The following session factories exist at the time of this writing.
 ======================= ======= =============================
 Session Factory         Backend   Description
 ======================= ======= =============================
+pyramid_nacl_session_   PyNaCl_ Defines an encrypting,
+                                pickle-based cookie
+                                serializer, using PyNaCl to
+                                generate the symmetric
+                                encryption for the cookie
+                                state.
 pyramid_redis_sessions_ Redis_  Server-side session library
                                 for Pyramid, using Redis for
                                 storage.
@@ -165,6 +171,9 @@ pyramid_beaker_         Beaker_ Session factory for Pyramid
                                 sessioning system.
 ======================= ======= =============================
 
+.. _pyramid_nacl_session: https://pypi.python.org/pypi/pyramid_nacl_session
+.. _PyNaCl: https://pynacl.readthedocs.io/en/latest/secret/
+
 .. _pyramid_redis_sessions: https://pypi.python.org/pypi/pyramid_redis_sessions
 .. _Redis: http://redis.io/
 
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 7cb8e0306..3b683ff79 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -252,7 +252,7 @@ Non-Predicate Arguments
     def myview(request):
       ...
 
-  Is similar to doing::
+  Is similar to decorating the view callable directly::
 
     @view_config(...)
     @decorator2
@@ -260,8 +260,10 @@ Non-Predicate Arguments
     def myview(request):
       ...
 
-  All view callables in the decorator chain must return a response object
-  implementing :class:`pyramid.interfaces.IResponse` or raise an exception:
+  An important distinction is that each decorator will receive a response
+  object implementing :class:`pyramid.interfaces.IResponse` instead of the
+  raw value returned from the view callable. All decorators in the chain must
+  return a response object or raise an exception:
 
   .. code-block:: python