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

19 files changed, 102 insertions, 53 deletions

diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 16023c821..25ccf6838 100644
--- a/CONTRIBUTORS.txt
+++ b/CONTRIBUTORS.txt
@@ -274,3 +274,7 @@ Contributors
 - Zack Brunson, 2016/06/02
 
 - Marco Martinez, 2016/06/02
+
+- Cris Ewing, 2016/06/03
+
+- Jean-Christophe Bohin, 2016/06/13
\ No newline at end of file
diff --git a/README.rst b/README.rst
index dec7e03d0..35c335d9c 100644
--- a/README.rst
+++ b/README.rst
@@ -17,11 +17,28 @@ Pyramid
         :target: https://webchat.freenode.net/?channels=pyramid
         :alt: IRC Freenode
 
-Pyramid is a small, fast, down-to-earth, open source Python web framework. It
-makes real-world web application development and deployment more fun, more
-predictable, and more productive.
+`Pyramid <https://trypyramid.com/>`_ is a small, fast, down-to-earth, open
+source Python web framework. It makes real-world web application development
+and deployment more fun, more predictable, and more productive.
 
-Pyramid is produced by the `Pylons Project <http://pylonsproject.org/>`_.
+.. code-block:: python
+
+   from wsgiref.simple_server import make_server
+   from pyramid.config import Configurator
+   from pyramid.response import Response
+
+   def hello_world(request):
+       return Response('Hello %(name)s!' % request.matchdict)
+
+   if __name__ == '__main__':
+       config = Configurator()
+       config.add_route('hello', '/hello/{name}')
+       config.add_view(hello_world, route_name='hello')
+       app = config.make_wsgi_app()
+       server = make_server('0.0.0.0', 8080, app)
+       server.serve_forever()
+
+Pyramid is a project of the `Pylons Project <http://www.pylonsproject.org/>`_.
 
 Support and Documentation
 -------------------------
@@ -46,6 +63,6 @@ Pyramid is offered under the BSD-derived `Repoze Public License
 Authors
 -------
 
-Pyramid is made available by `Agendaless Consulting <http://agendaless.com>`_
-and a team of contributors.
-
+Pyramid is made available by `Agendaless Consulting <https://agendaless.com>`_
+and a team of `contributors
+<https://github.com/Pylons/pyramid/graphs/contributors>`_.
diff --git a/contributing.md b/contributing.md
index ae201d370..b5f17ae06 100644
--- a/contributing.md
+++ b/contributing.md
@@ -56,11 +56,15 @@ System](http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/install.ht
 
          git clone git@github.com:<username>/pyramid.git
 
-3.  Add a git remote "upstream" for the cloned fork.
+3.  Change directories into the cloned repository
+
+         cd pyramid
+
+4.  Add a git remote "upstream" for the cloned fork.
 
          git remote add upstream git@github.com:Pylons/pyramid.git
 
-4.  Set an environment variable as instructed in the
+5.  Create a virtual environment and set an environment variable as instructed in the
     [prerequisites](https://github.com/Pylons/pyramid/blob/master/HACKING.txt#L55-L58).
 
          # Mac and Linux
@@ -69,36 +73,34 @@ System](http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/install.ht
          # Windows
          set VENV=c:\hack-on-pyramid\env
 
-5.  Try to build the docs in your workspace.
+6.  Install `tox` into your virtual environment.
 
-         # Mac and Linux
-         $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build
+         $ $VENV/bin/pip install tox
 
-         # Windows
-         c:\> make clean html SPHINXBUILD=%VENV%\bin\sphinx-build
+7.  Try to build the docs in your workspace.
+
+         $ $VENV/bin/tox -e docs
 
-     If successful, then you can make changes to the documentation. You can
-     load the built documentation in the `/_build/html/` directory in a web
-     browser.
+     When the build finishes, you'll find HTML documentation rendered in
+     `.tox/docs/html`. An `epub` version will be in `.tox/docs/epub`. And the
+     result of the tests that are run on the documentation will be in
+     `.tox/docs/doctest`.
 
-6.  From this point forward, follow the typical [git
+8.  From this point forward, follow the typical [git
     workflow](https://help.github.com/articles/what-is-a-good-git-workflow/).
-    Start by pulling from the upstream to get the most current changes.
+    *Always* start by pulling from the upstream to get the most current changes.
 
          git pull upstream master
 
-7.  Make a branch, make changes to the docs, and rebuild them as indicated in
-    step 5.  To speed up the build process, you can omit `clean` from the above
-    command to rebuild only those pages that depend on the files you have
-    changed.
+9.  Make a branch, make changes to the docs, and rebuild them as indicated above.
 
-8.  Once you are satisfied with your changes and the documentation builds
-    successfully without errors or warnings, then git commit and push them to
-    your "origin" repository on GitHub.
+10.  Once you are satisfied with your changes and the documentation builds
+     successfully without errors or warnings, then git commit and push them to
+     your "origin" repository on GitHub.
 
          git commit -m "commit message"
          git push -u origin --all # first time only, subsequent can be just 'git push'.
 
-9.  Create a [pull request](https://help.github.com/articles/using-pull-requests/).
+11.  Create a [pull request](https://help.github.com/articles/using-pull-requests/).
 
-10.  Repeat the process starting from Step 6.
+12.  Repeat the process starting from Step 8.
diff --git a/docs/designdefense.rst b/docs/designdefense.rst
index f42582e47..5f65671bb 100644
--- a/docs/designdefense.rst
+++ b/docs/designdefense.rst
@@ -1009,7 +1009,7 @@ Microframeworks have smaller Hello World programs
 Self-described "microframeworks" exist. `Bottle
 <http://bottlepy.org/docs/dev/index.html>`_ and `Flask
 <http://flask.pocoo.org/>`_ are two that are becoming popular. `Bobo
-<http://bobo.digicool.com/en/latest/>`_ doesn't describe itself as a
+<https://bobo.readthedocs.io/en/latest/>`_ doesn't describe itself as a
 microframework, but its intended user base is much the same. Many others exist.
 We've even (only as a teaching tool, not as any sort of official project)
 `created one using Pyramid <http://static.repoze.org/casts/videotags.html>`_.
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 7cbea113c..77e7fd707 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -290,6 +290,14 @@ properties of the instance.
        def __init__(self, owner):
            self.owner = owner
 
+.. warning::
+
+   Writing ``__acl__`` as properties is discouraged because an
+   ``AttributeError`` occurring in ``fget`` or ``fset`` will be silently
+   dismissed (this is consistent with Python ``getattr`` and ``hasattr``
+   behaviors). For dynamic ACLs, simply use callables, as documented above.
+
+
 .. index::
    single: ACE
    single: access control entry
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 2472ace31..7d37c04df 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -557,7 +557,7 @@ Here is an example of a corresponding ``mypackage.views`` module:
 
    @view_config(route_name='idea')
    def idea_view(request):
-       return Response(request.matchdict['id'])
+       return Response(request.matchdict['idea'])
    
    @view_config(route_name='user')
    def user_view(request):
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index b170e5d98..dde91b495 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -1,3 +1,4 @@
+
 .. _quick_tour:
 
 =====================
@@ -70,6 +71,7 @@ step. Here's a tiny application in Pyramid:
 
 .. literalinclude:: quick_tour/hello_world/app.py
     :linenos:
+    :language: python
 
 This simple example is easy to run. Save this as ``app.py`` and run it:
 
@@ -120,6 +122,7 @@ library for request and response handling. In our example above, Pyramid hands
 Let's see some features of requests and responses in action:
 
 .. literalinclude:: quick_tour/requests/app.py
+    :language: python
     :pyobject: hello_world
 
 In this Pyramid view, we get the URL being visited from ``request.url``. Also
@@ -159,6 +162,7 @@ Let's move the views out to their own ``views.py`` module and change the
 First our revised ``app.py``:
 
 .. literalinclude:: quick_tour/views/app.py
+    :language: python
     :linenos:
 
 We added some more routes, but we also removed the view code. Our views and
@@ -169,6 +173,7 @@ We now have a ``views.py`` module that is focused on handling requests and
 responses:
 
 .. literalinclude:: quick_tour/views/views.py
+    :language: python
     :linenos:
 
 We have four views, each leading to the other. If you start at
@@ -214,6 +219,7 @@ What if we want part of the URL to be available as data in my view? We can use
 this route declaration, for example:
 
 .. literalinclude:: quick_tour/routing/app.py
+    :language: python
     :linenos:
     :lines: 6
     :lineno-start: 6
@@ -222,6 +228,7 @@ With this, URLs such as ``/howdy/amy/smith`` will assign ``amy`` to ``first``
 and ``smith`` to ``last``. We can then use this data in our view:
 
 .. literalinclude:: quick_tour/routing/views.py
+    :language: python
     :linenos:
     :lines: 5-8
     :lineno-start: 5
@@ -260,6 +267,7 @@ With the package installed, we can include the template bindings into our
 configuration in ``app.py``:
 
 .. literalinclude:: quick_tour/templating/app.py
+    :language: python
     :linenos:
     :lines: 6-8
     :lineno-start: 6
@@ -268,6 +276,7 @@ configuration in ``app.py``:
 Now lets change our ``views.py`` file:
 
 .. literalinclude:: quick_tour/templating/views.py
+    :language: python
     :linenos:
     :emphasize-lines: 4,6
 
@@ -304,6 +313,7 @@ With the package installed, we can include the template bindings into our
 configuration:
 
 .. literalinclude:: quick_tour/jinja2/app.py
+    :language: python
     :linenos:
     :lines: 6-8
     :lineno-start: 6
@@ -312,6 +322,7 @@ configuration:
 The only change in our view is to point the renderer at the ``.jinja2`` file:
 
 .. literalinclude:: quick_tour/jinja2/views.py
+    :language: python
     :linenos:
     :lines: 4-6
     :lineno-start: 4
@@ -339,9 +350,10 @@ Static assets
 Of course the Web is more than just markup. You need static assets: CSS, JS,
 and images. Let's point our web app at a directory from which Pyramid will
 serve some static assets. First let's make another call to the
-:term:`configurator`:
+:term:`configurator` in ``app.py``:
 
 .. literalinclude:: quick_tour/static_assets/app.py
+    :language: python
     :linenos:
     :lines: 6-8
     :lineno-start: 6
@@ -359,7 +371,7 @@ Next make a directory named ``static``, and place ``app.css`` inside:
 All we need to do now is point to it in the ``<head>`` of our Jinja2 template,
 ``hello_world.jinja2``:
 
-.. literalinclude:: quick_tour/static_assets/hello_world.jinja2
+.. literalinclude:: quick_tour/static_assets/hello_world_static.jinja2
     :language: jinja
     :linenos:
     :lines: 4-6
@@ -371,16 +383,16 @@ the site is later moved under ``/somesite/static/``? Or perhaps a web developer
 changes the arrangement on disk? Pyramid provides a helper to allow flexibility
 on URL generation:
 
-.. literalinclude:: quick_tour/static_assets/hello_world_static.jinja2
+.. literalinclude:: quick_tour/static_assets/hello_world.jinja2
     :language: jinja
     :linenos:
     :lines: 4-6
     :lineno-start: 4
     :emphasize-lines: 2
 
-By using ``request.static_url`` to generate the full URL to the static
-assets, you both ensure you stay in sync with the configuration and
-gain refactoring flexibility later.
+By using ``request.static_url`` to generate the full URL to the static assets,
+you ensure that you stay in sync with the configuration and gain refactoring
+flexibility later.
 
 .. seealso:: See also:
     :ref:`Quick Tutorial Static Assets <qtut_static_assets>`,
@@ -396,6 +408,7 @@ to update the UI in the browser by requesting server data as JSON. Pyramid
 supports this with a JSON renderer:
 
 .. literalinclude:: quick_tour/json/views.py
+    :language: python
     :linenos:
     :lines: 9-
     :lineno-start: 9
@@ -408,6 +421,7 @@ We also need to add a route to ``app.py`` so that our app will know how to
 respond to a request for ``hello.json``.
 
 .. literalinclude:: quick_tour/json/app.py
+    :language: python
     :linenos:
     :lines: 6-8
     :lineno-start: 6
@@ -437,6 +451,7 @@ The following shows a "Hello World" example with three operations: view a form,
 save a change, or press the delete button in our ``views.py``:
 
 .. literalinclude:: quick_tour/view_classes/views.py
+    :language: python
     :linenos:
     :lines: 7-
     :lineno-start: 7
@@ -728,6 +743,7 @@ Our unit test passed, although its coverage is incomplete. What did our test
 look like?
 
 .. literalinclude:: quick_tour/package/hello_world/tests.py
+    :language: python
     :linenos:
 
 Pyramid supplies helpers for test writing, which we use in the test setup and
@@ -881,6 +897,7 @@ SQLAlchemy uses "models" for this mapping. The scaffold generated a sample
 model:
 
 .. literalinclude:: quick_tour/sqla_demo/sqla_demo/models/mymodel.py
+    :language: python
     :start-after: Start Sphinx Include
     :end-before: End Sphinx Include
 
@@ -888,6 +905,7 @@ View code, which mediates the logic between web requests and the rest of the
 system, can then easily get at the data thanks to SQLAlchemy:
 
 .. literalinclude:: quick_tour/sqla_demo/sqla_demo/views/default.py
+    :language: python
     :start-after: Start Sphinx Include
     :end-before: End Sphinx Include
 
diff --git a/docs/quick_tour/json/hello_world.jinja2 b/docs/quick_tour/json/hello_world.jinja2
index 4fb9be074..a55865231 100644
--- a/docs/quick_tour/json/hello_world.jinja2
+++ b/docs/quick_tour/json/hello_world.jinja2
@@ -2,7 +2,7 @@
 <html lang="en">
 <head>
     <title>Hello World</title>
-    <link rel="stylesheet" href="{{ request.static_url('static/app.css') }}"/>
+    <link rel="stylesheet" href="{{ request.static_url('__main__:static/app.css') }}"/>
 </head>
 <body>
 <h1>Hello {{ name }}!</h1>
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/models/__init__.py b/docs/quick_tour/sqla_demo/sqla_demo/models/__init__.py
index 6ffc10a78..76e0fd26b 100644
--- a/docs/quick_tour/sqla_demo/sqla_demo/models/__init__.py
+++ b/docs/quick_tour/sqla_demo/sqla_demo/models/__init__.py
@@ -1,7 +1,7 @@
 from sqlalchemy.orm import configure_mappers
 # import all models classes here for sqlalchemy mappers
 # to pick up
-from .mymodel import MyModel # flake8: noqa
+from .mymodel import MyModel  # noqa
 
 # run configure mappers to ensure we avoid any race conditions
 configure_mappers()
diff --git a/docs/quick_tour/static_assets/hello_world.jinja2 b/docs/quick_tour/static_assets/hello_world.jinja2
index 0fb2ce296..a55865231 100644
--- a/docs/quick_tour/static_assets/hello_world.jinja2
+++ b/docs/quick_tour/static_assets/hello_world.jinja2
@@ -2,7 +2,7 @@
 <html lang="en">
 <head>
     <title>Hello World</title>
-    <link rel="stylesheet" href="/static/app.css"/>
+    <link rel="stylesheet" href="{{ request.static_url('__main__:static/app.css') }}"/>
 </head>
 <body>
 <h1>Hello {{ name }}!</h1>
diff --git a/docs/quick_tour/static_assets/hello_world_static.jinja2 b/docs/quick_tour/static_assets/hello_world_static.jinja2
index 4fb9be074..0fb2ce296 100644
--- a/docs/quick_tour/static_assets/hello_world_static.jinja2
+++ b/docs/quick_tour/static_assets/hello_world_static.jinja2
@@ -2,7 +2,7 @@
 <html lang="en">
 <head>
     <title>Hello World</title>
-    <link rel="stylesheet" href="{{ request.static_url('static/app.css') }}"/>
+    <link rel="stylesheet" href="/static/app.css"/>
 </head>
 <body>
 <h1>Hello {{ name }}!</h1>
diff --git a/docs/tutorials/wiki2/src/authentication/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/authentication/tutorial/models/__init__.py
index a8871f6f5..8147052ad 100644
--- a/docs/tutorials/wiki2/src/authentication/tutorial/models/__init__.py
+++ b/docs/tutorials/wiki2/src/authentication/tutorial/models/__init__.py
@@ -5,8 +5,8 @@ import zope.sqlalchemy
 
 # import or define all models here to ensure they are attached to the
 # Base.metadata prior to any initialization routines
-from .page import Page # flake8: noqa
-from .user import User # flake8: noqa
+from .page import Page  # noqa
+from .user import User  # noqa
 
 # run configure_mappers after defining all of the models to ensure
 # all relationships can be setup
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/authorization/tutorial/models/__init__.py
index a8871f6f5..8147052ad 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/models/__init__.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models/__init__.py
@@ -5,8 +5,8 @@ import zope.sqlalchemy
 
 # import or define all models here to ensure they are attached to the
 # Base.metadata prior to any initialization routines
-from .page import Page # flake8: noqa
-from .user import User # flake8: noqa
+from .page import Page  # noqa
+from .user import User  # noqa
 
 # run configure_mappers after defining all of the models to ensure
 # all relationships can be setup
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py
index 48a957ecb..3fc82cfba 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/models/__init__.py
@@ -5,7 +5,7 @@ import zope.sqlalchemy
 
 # import or define all models here to ensure they are attached to the
 # Base.metadata prior to any initialization routines
-from .mymodel import MyModel # flake8: noqa
+from .mymodel import MyModel  # noqa
 
 # run configure_mappers after defining all of the models to ensure
 # all relationships can be setup
diff --git a/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py
index 48a957ecb..3fc82cfba 100644
--- a/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py
+++ b/docs/tutorials/wiki2/src/installation/tutorial/models/__init__.py
@@ -5,7 +5,7 @@ import zope.sqlalchemy
 
 # import or define all models here to ensure they are attached to the
 # Base.metadata prior to any initialization routines
-from .mymodel import MyModel # flake8: noqa
+from .mymodel import MyModel  # noqa
 
 # run configure_mappers after defining all of the models to ensure
 # all relationships can be setup
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py
index a8871f6f5..8147052ad 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/models/__init__.py
@@ -5,8 +5,8 @@ import zope.sqlalchemy
 
 # import or define all models here to ensure they are attached to the
 # Base.metadata prior to any initialization routines
-from .page import Page # flake8: noqa
-from .user import User # flake8: noqa
+from .page import Page  # noqa
+from .user import User  # noqa
 
 # run configure_mappers after defining all of the models to ensure
 # all relationships can be setup
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/tests/tutorial/models/__init__.py
index a8871f6f5..8147052ad 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/models/__init__.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models/__init__.py
@@ -5,8 +5,8 @@ import zope.sqlalchemy
 
 # import or define all models here to ensure they are attached to the
 # Base.metadata prior to any initialization routines
-from .page import Page # flake8: noqa
-from .user import User # flake8: noqa
+from .page import Page  # noqa
+from .user import User  # noqa
 
 # run configure_mappers after defining all of the models to ensure
 # all relationships can be setup
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models/__init__.py b/docs/tutorials/wiki2/src/views/tutorial/models/__init__.py
index a8871f6f5..8147052ad 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/models/__init__.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/models/__init__.py
@@ -5,8 +5,8 @@ import zope.sqlalchemy
 
 # import or define all models here to ensure they are attached to the
 # Base.metadata prior to any initialization routines
-from .page import Page # flake8: noqa
-from .user import User # flake8: noqa
+from .page import Page  # noqa
+from .user import User  # noqa
 
 # run configure_mappers after defining all of the models to ensure
 # all relationships can be setup
diff --git a/pyramid/scaffolds/alchemy/+package+/models/__init__.py_tmpl b/pyramid/scaffolds/alchemy/+package+/models/__init__.py_tmpl
index 26b50aaf6..f626d1ef0 100644
--- a/pyramid/scaffolds/alchemy/+package+/models/__init__.py_tmpl
+++ b/pyramid/scaffolds/alchemy/+package+/models/__init__.py_tmpl
@@ -5,7 +5,7 @@ import zope.sqlalchemy
 
 # import or define all models here to ensure they are attached to the
 # Base.metadata prior to any initialization routines
-from .mymodel import MyModel # flake8: noqa
+from .mymodel import MyModel  # noqa
 
 # run configure_mappers after defining all of the models to ensure
 # all relationships can be setup