Merge branch 'master' of github.com:Pylons/pyramid

6 files changed, 253 insertions, 136 deletions

diff --git a/docs/narr/MyProject/myproject/tests.py b/docs/narr/MyProject/myproject/tests.py
index 64dcab1d5..8c60407e5 100644
--- a/docs/narr/MyProject/myproject/tests.py
+++ b/docs/narr/MyProject/myproject/tests.py
@@ -15,3 +15,40 @@ class ViewTests(unittest.TestCase):
         request = testing.DummyRequest()
         info = my_view(request)
         self.assertEqual(info['project'], 'MyProject')
+
+class ViewIntegrationTests(unittest.TestCase):
+    def setUp(self):
+        """ This sets up the application registry with the
+        registrations your application declares in its ``includeme``
+        function.
+        """
+        self.config = testing.setUp()
+        self.config.include('myproject')
+
+    def tearDown(self):
+        """ Clear out the application registry """
+        testing.tearDown()
+
+    def test_my_view(self):
+        from myproject.views import my_view
+        request = testing.DummyRequest()
+        result = my_view(request)
+        self.assertEqual(result.status, '200 OK')
+        body = result.app_iter[0]
+        self.assertTrue('Welcome to' in body)
+        self.assertEqual(len(result.headerlist), 2)
+        self.assertEqual(result.headerlist[0],
+                         ('Content-Type', 'text/html; charset=UTF-8'))
+        self.assertEqual(result.headerlist[1], ('Content-Length',
+                                                str(len(body))))
+
+class FunctionalTests(unittest.TestCase):
+    def setUp(self):
+        from myproject import main
+        app = main({})
+        from webtest import TestApp
+        self.testapp = TestApp(app)
+
+    def test_root(self):
+        res = self.testapp.get('/', status=200)
+        self.assertTrue('Pyramid' in res.body)
diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py
index 8c019af51..9f34540a7 100644
--- a/docs/narr/MyProject/setup.py
+++ b/docs/narr/MyProject/setup.py
@@ -1,30 +1,42 @@
-import os
+"""Setup for the MyProject package.
 
+"""
+import os
 from setuptools import setup, find_packages
 
-here = os.path.abspath(os.path.dirname(__file__))
-with open(os.path.join(here, 'README.txt')) as f:
-    README = f.read()
-with open(os.path.join(here, 'CHANGES.txt')) as f:
-    CHANGES = f.read()
 
-requires = [
+HERE = os.path.abspath(os.path.dirname(__file__))
+
+
+with open(os.path.join(HERE, 'README.txt')) as fp:
+    README = fp.read()
+
+
+with open(os.path.join(HERE, 'CHANGES.txt')) as fp:
+    CHANGES = fp.read()
+
+
+REQUIRES = [
     'pyramid',
     'pyramid_chameleon',
     'pyramid_debugtoolbar',
     'waitress',
     ]
 
+TESTS_REQUIRE = [
+    'webtest'
+    ]
+
 setup(name='MyProject',
       version='0.0',
       description='MyProject',
       long_description=README + '\n\n' + CHANGES,
       classifiers=[
-        "Programming Language :: Python",
-        "Framework :: Pyramid",
-        "Topic :: Internet :: WWW/HTTP",
-        "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
-        ],
+          'Programming Language :: Python',
+          'Framework :: Pyramid',
+          'Topic :: Internet :: WWW/HTTP',
+          'Topic :: Internet :: WWW/HTTP :: WSGI :: Application',
+      ],
       author='',
       author_email='',
       url='',
@@ -32,11 +44,10 @@ setup(name='MyProject',
       packages=find_packages(),
       include_package_data=True,
       zip_safe=False,
-      install_requires=requires,
-      tests_require=requires,
-      test_suite="myproject",
+      install_requires=REQUIRES,
+      tests_require=TESTS_REQUIRE,
+      test_suite='myproject',
       entry_points="""\
       [paste.app_factory]
       main = myproject:main
-      """,
-      )
+      """)
diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst
index 95863848b..fc908c2b4 100644
--- a/docs/narr/assets.rst
+++ b/docs/narr/assets.rst
@@ -276,15 +276,62 @@ to put static media on a separate webserver during production (if the
 ``name`` argument to :meth:`~pyramid.config.Configurator.add_static_view` is
 a URL), while keeping static media package-internal and served by the
 development webserver during development (if the ``name`` argument to
-:meth:`~pyramid.config.Configurator.add_static_view` is a URL prefix).  To
-create such a circumstance, we suggest using the
-:attr:`pyramid.registry.Registry.settings` API in conjunction with a setting
-in the application ``.ini`` file named ``media_location``.  Then set the
-value of ``media_location`` to either a prefix or a URL depending on whether
-the application is being run in development or in production (use a different
-``.ini`` file for production than you do for development).  This is just a
-suggestion for a pattern; any setting name other than ``media_location``
-could be used.
+:meth:`~pyramid.config.Configurator.add_static_view` is a URL prefix).
+
+For example, we may define a :ref:`custom setting <adding_a_custom_setting>`
+named ``media_location`` which we can set to an external URL in production
+when our assets are hosted on a CDN.
+
+.. code-block:: python
+   :linenos:
+
+   media_location = settings.get('media_location', 'static')
+
+   config = Configurator(settings=settings)
+   config.add_static_view(path='myapp:static', name=media_location)
+
+Now we can optionally define the setting in our ini file:
+
+.. code-block:: ini
+   :linenos:
+
+   # production.ini
+   [app:main]
+   use = egg:myapp#main
+
+   media_location = http://static.example.com/
+
+It is also possible to serve assets that live outside of the source by
+referring to an absolute path on the filesystem. There are two ways to
+accomplish this.
+
+First, :meth:`~pyramid.config.Configurator.add_static_view`
+supports taking an absolute path directly instead of an asset spec. This works
+as expected, looking in the file or folder of files and serving them up at
+some URL within your application or externally. Unfortunately, this technique
+has a drawback that it is not possible to use the
+:meth:`~pyramid.request.Request.static_url` method to generate URLs, since it
+works based on an asset spec.
+
+The second approach, available in Pyramid 1.6+, uses the asset overriding
+APIs described in the :ref:`overriding_assets_section` section. It is then
+possible to configure a "dummy" package which then serves its file or folder
+from an absolute path.
+
+.. code-block:: python
+
+   config.add_static_view(path='myapp:static_images', name='static')
+   config.override_asset(to_override='myapp:static_images/',
+                         override_with='/abs/path/to/images/')
+
+From this configuration it is now possible to use
+:meth:`~pyramid.request.Request.static_url` to generate URLs to the data
+in the folder by doing something like
+``request.static_url('myapp:static_images/foo.png')``. While it is not
+necessary that the ``static_images`` file or folder actually exist in the
+``myapp`` package, it is important that the ``myapp`` portion points to a
+valid package. If the folder does exist then the overriden folder is given
+priority if the file's name exists in both locations.
 
 .. index::
    single: Cache Busting
@@ -701,3 +748,6 @@ files.  Any software which uses the
 :func:`pkg_resources.get_resource_string` APIs will obtain an overridden file
 when an override is used.
 
+As of Pyramid 1.6, it is also possible to override an asset by supplying an
+absolute path to a file or directory. This may be useful if the assets are
+not distributed as part of a Python package.
diff --git a/docs/narr/router.rst b/docs/narr/router.rst
index ac3deefdc..e82b66801 100644
--- a/docs/narr/router.rst
+++ b/docs/narr/router.rst
@@ -9,6 +9,9 @@
 Request Processing
 ==================
 
+.. image:: ../_static/pyramid_request_processing.svg
+   :alt: Request Processing
+
 Once a :app:`Pyramid` application is up and running, it is ready to accept
 requests and return responses.  What happens from the time a :term:`WSGI`
 request enters a :app:`Pyramid` application through to the point that
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 8db23a33b..2dc0c76af 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -6,13 +6,28 @@
 Security
 ========
 
-:app:`Pyramid` provides an optional declarative authorization system
-that can prevent a :term:`view` from being invoked based on an
+:app:`Pyramid` provides an optional, declarative, security system.
+Security in :app:`Pyramid` is separated into authentication and
+authorization. The two systems communicate via :term:`principal`
+identifiers. Authentication is merely the mechanism by which credentials
+provided in the :term:`request` are resolved to one or more
+:term:`principal` identifiers. These identifiers represent the users and
+groups that are in effect during the request. Authorization then determines
+access based on the :term:`principal` identifiers, the requested
+:term:`permission`, and a :term:`context`.
+
+The :app:`Pyramid` authorization system
+can prevent a :term:`view` from being invoked based on an
 :term:`authorization policy`. Before a view is invoked, the
 authorization system can use the credentials in the :term:`request`
 along with the :term:`context` resource to determine if access will be
 allowed.  Here's how it works at a high level:
 
+- A user may or may not have previously visited the application and
+  supplied authentication credentials, including a :term:`userid`.  If
+  so, the application may have called
+  :func:`pyramid.security.remember` to remember these.
+
 - A :term:`request` is generated when a user visits the application.
 
 - Based on the request, a :term:`context` resource is located through
@@ -25,7 +40,9 @@ allowed.  Here's how it works at a high level:
   context as well as other attributes of the request.
 
 - If an :term:`authentication policy` is in effect, it is passed the
-  request; it returns some number of :term:`principal` identifiers.
+  request. It will return some number of :term:`principal` identifiers.
+  To do this, the policy would need to determine the authenticated
+  :term:`userid` present in the request.
 
 - If an :term:`authorization policy` is in effect and the :term:`view
   configuration` associated with the view callable that was found has
@@ -41,15 +58,6 @@ allowed.  Here's how it works at a high level:
 - If the authorization policy denies access, the view callable is not
   invoked; instead the :term:`forbidden view` is invoked.
 
-Security in :app:`Pyramid`, unlike many systems, cleanly and explicitly
-separates authentication and authorization. Authentication is merely the
-mechanism by which credentials provided in the :term:`request` are
-resolved to one or more :term:`principal` identifiers. These identifiers
-represent the users and groups in effect during the request.
-Authorization then determines access based on the :term:`principal`
-identifiers, the :term:`view callable` being invoked, and the
-:term:`context` resource.
-
 Authorization is enabled by modifying your application to include an
 :term:`authentication policy` and :term:`authorization policy`.
 :app:`Pyramid` comes with a variety of implementations of these
@@ -104,7 +112,8 @@ For example:
 
 The above configuration enables a policy which compares the value of an "auth
 ticket" cookie passed in the request's environment which contains a reference
-to a single :term:`principal` against the principals present in any
+to a single :term:`userid` and matches that userid's
+:term:`principals <principal>` against the principals present in any
 :term:`ACL` found in the resource tree when attempting to call some
 :term:`view`.
 
@@ -595,36 +604,53 @@ that implements the following interface:
        """ An object representing a Pyramid authentication policy. """
 
        def authenticated_userid(self, request):
-           """ Return the authenticated userid or ``None`` if no
-           authenticated userid can be found. This method of the policy 
-           should ensure that a record exists in whatever persistent store is 
-           used related to the user (the user should not have been deleted); 
-           if a record associated with the current id does not exist in a 
-           persistent store, it should return ``None``."""
+           """ Return the authenticated :term:`userid` or ``None`` if
+           no authenticated userid can be found. This method of the
+           policy should ensure that a record exists in whatever
+           persistent store is used related to the user (the user
+           should not have been deleted); if a record associated with
+           the current id does not exist in a persistent store, it
+           should return ``None``.
+
+           """
 
        def unauthenticated_userid(self, request):
-           """ Return the *unauthenticated* userid.  This method performs the
-           same duty as ``authenticated_userid`` but is permitted to return the
-           userid based only on data present in the request; it needn't (and
-           shouldn't) check any persistent store to ensure that the user record
-           related to the request userid exists."""
+           """ Return the *unauthenticated* userid.  This method
+           performs the same duty as ``authenticated_userid`` but is
+           permitted to return the userid based only on data present
+           in the request; it needn't (and shouldn't) check any
+           persistent store to ensure that the user record related to
+           the request userid exists.
+
+           This method is intended primarily a helper to assist the
+           ``authenticated_userid`` method in pulling credentials out
+           of the request data, abstracting away the specific headers,
+           query strings, etc that are used to authenticate the request.
+
+           """
 
        def effective_principals(self, request):
            """ Return a sequence representing the effective principals
-           including the userid and any groups belonged to by the current
-           user, including 'system' groups such as
-           ``pyramid.security.Everyone`` and
-           ``pyramid.security.Authenticated``. """
+           typically including the :term:`userid` and any groups belonged
+           to by the current user, always including 'system' groups such
+           as ``pyramid.security.Everyone`` and
+           ``pyramid.security.Authenticated``.
 
-       def remember(self, request, principal, **kw):
+           """
+
+       def remember(self, request, userid, **kw):
            """ Return a set of headers suitable for 'remembering' the
-           principal named ``principal`` when set in a response.  An
-           individual authentication policy and its consumers can decide
-           on the composition and meaning of **kw. """
-       
+           :term:`userid` named ``userid`` when set in a response.  An
+           individual authentication policy and its consumers can
+           decide on the composition and meaning of **kw.
+
+           """
+
        def forget(self, request):
            """ Return a set of headers suitable for 'forgetting' the
-           current user on subsequent requests. """
+           current user on subsequent requests.
+
+           """
 
 After you do so, you can pass an instance of such a class into the
 :class:`~pyramid.config.Configurator.set_authentication_policy` method
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index e001ad81c..ecda57489 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -128,8 +128,9 @@ functions accepts various arguments that influence the environment of the
 test.  See the :ref:`testing_module` API for information about the extra
 arguments supported by these functions.
 
-If you also want to make :func:`~pyramid.threadlocal.get_current_request` return something
-other than ``None`` during the course of a single test, you can pass a
+If you also want to make :func:`~pyramid.threadlocal.get_current_request`
+return something other than ``None`` during the course of a single test, you
+can pass a
 :term:`request` object into the :func:`pyramid.testing.setUp` within the
 ``setUp`` method of your test:
 
@@ -333,66 +334,49 @@ Creating Integration Tests
 --------------------------
 
 In :app:`Pyramid`, a *unit test* typically relies on "mock" or "dummy"
-implementations to give the code under test only enough context to run.
+implementations to give the code under test enough context to run.
 
 "Integration testing" implies another sort of testing.  In the context of a
-:app:`Pyramid` integration test, the test logic tests the functionality of
-some code *and* its integration with the rest of the :app:`Pyramid`
+:app:`Pyramid` integration test, the test logic exercises the functionality of
+the code under test *and* its integration with the rest of the :app:`Pyramid`
 framework.
 
-In :app:`Pyramid` applications that are plugins to Pyramid, you can create an
-integration test by including its ``includeme`` function via
-:meth:`pyramid.config.Configurator.include` in the test's setup code.  This
-causes the entire :app:`Pyramid` environment to be set up and torn down as if
-your application was running "for real".  This is a heavy-hammer way of
-making sure that your tests have enough context to run properly, and it tests
-your code's integration with the rest of :app:`Pyramid`.
+Creating an integration test for a :app:`Pyramid` application usually means
+invoking the application's ``includeme`` function via
+:meth:`pyramid.config.Configurator.include` within the test's setup code.  This
+causes the entire :app:`Pyramid` environment to be set up, simulating what
+happens when your application is run "for real".  This is a heavy-hammer way of
+making sure that your tests have enough context to run properly, and tests your
+code's integration with the rest of :app:`Pyramid`.
 
-Let's demonstrate this by showing an integration test for a view.  The below
-test assumes that your application's package name is ``myapp``, and that
-there is a ``views`` module in the app with a function with the name
-``my_view`` in it that returns the response 'Welcome to this application'
-after accessing some values that require a fully set up environment.
+.. seealso::
 
-.. code-block:: python
-   :linenos:
+   See also :ref:`including_configuration`
 
-   import unittest
+Let's demonstrate this by showing an integration test for a view.
 
-   from pyramid import testing
+Given the following view definition, which assumes that your application's
+:term:`package` name is ``myproject``, and within that :term:`package` there
+exists a module ``views``, which in turn contains a :term:`view` function named
+``my_view``:
 
-   class ViewIntegrationTests(unittest.TestCase):
-       def setUp(self):
-           """ This sets up the application registry with the
-           registrations your application declares in its ``includeme`` 
-           function.
-           """
-           import myapp
-           self.config = testing.setUp()
-           self.config.include('myapp')
+   .. literalinclude:: MyProject/myproject/views.py
+      :linenos:
+      :lines: 1-6
+      :language: python
 
-       def tearDown(self):
-           """ Clear out the application registry """
-           testing.tearDown()
+You'd then create a ``tests`` module within your ``myproject`` package,
+containing the following test code:
 
-       def test_my_view(self):
-           from myapp.views import my_view
-           request = testing.DummyRequest()
-           result = my_view(request)
-           self.assertEqual(result.status, '200 OK')
-           body = result.app_iter[0]
-           self.assertTrue('Welcome to' in body)
-           self.assertEqual(len(result.headerlist), 2)
-           self.assertEqual(result.headerlist[0],
-                            ('Content-Type', 'text/html; charset=UTF-8'))
-           self.assertEqual(result.headerlist[1], ('Content-Length',
-                                                   str(len(body))))
-
-Unless you cannot avoid it, you should prefer writing unit tests that use the
-:class:`~pyramid.config.Configurator` API to set up the right "mock"
-registrations rather than creating an integration test.  Unit tests will run
-faster (because they do less for each test) and the result of a unit test is
-usually easier to make assertions about.
+   .. literalinclude:: MyProject/myproject/tests.py
+      :linenos:
+      :pyobject: ViewIntegrationTests
+      :language: python
+
+Writing unit tests that use the :class:`~pyramid.config.Configurator` API to
+set up the right "mock" registrations is often preferred to creating
+integration tests.  Unit tests will run faster (because they do less for each
+test) and are usually easier to reason about.
 
 .. index::
    single: functional tests
@@ -404,34 +388,40 @@ Creating Functional Tests
 
 Functional tests test your literal application.
 
-The below test assumes that your application's package name is ``myapp``, and
-that there is a view that returns an HTML body when the root URL is invoked.
-It further assumes that you've added a ``tests_require`` dependency on the
-``WebTest`` package within your ``setup.py`` file.  :term:`WebTest` is a
-functional testing package written by Ian Bicking.
+In Pyramid, functional tests are typically written using the :term:`WebTest`
+package, which provides APIs for invoking HTTP(S) requests to your application.
 
-.. code-block:: python
-   :linenos:
+Regardless of which testing :term:`package` you use, ensure to add a
+``tests_require`` dependency on that package to to your application's
+``setup.py`` file:
 
-   import unittest
+   .. literalinclude:: MyProject/setup.py
+      :linenos:
+      :emphasize-lines: 26-28,48
+      :language: python
 
-   class FunctionalTests(unittest.TestCase):
-       def setUp(self):
-           from myapp import main
-           app = main({})
-           from webtest import TestApp
-           self.testapp = TestApp(app)
-
-       def test_root(self):
-           res = self.testapp.get('/', status=200)
-           self.assertTrue('Pyramid' in res.body)
-
-When this test is run, each test creates a "real" WSGI application using the
-``main`` function in your ``myapp.__init__`` module and uses :term:`WebTest`
-to wrap that WSGI application.  It assigns the result to ``self.testapp``.
-In the test named ``test_root``, we use the testapp's ``get`` method to
-invoke the root URL.  We then assert that the returned HTML has the string
-``Pyramid`` in it.
+Assuming your :term:`package` is named ``myproject``, which contains a
+``views`` module, which in turn contains a :term:`view` function ``my_view``
+that returns a HTML body when the root URL is invoked:
+
+   .. literalinclude:: MyProject/myproject/views.py
+      :linenos:
+      :language: python
+
+Then the following example functional test (shown below) demonstrates invoking
+the :term:`view` shown above:
+
+   .. literalinclude:: MyProject/myproject/tests.py
+      :linenos:
+      :pyobject: FunctionalTests
+      :language: python
+
+When this test is run, each test method creates a "real" :term:`WSGI`
+application using the ``main`` function in your ``myproject.__init__`` module,
+using :term:`WebTest` to wrap that WSGI application.  It assigns the result to
+``self.testapp``.  In the test named ``test_root``. The ``TestApp``'s ``get``
+method is used to invoke the root URL.  Finally, an assertion is made that the
+returned HTML contains the text ``MyProject``.
 
 See the :term:`WebTest` documentation for further information about the
 methods available to a :class:`webtest.app.TestApp` instance.