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

40 files changed, 275 insertions, 67 deletions

diff --git a/docs/tutorials/wiki2/src/authorization/README.txt b/docs/tutorials/wiki2/src/authorization/README.txt
index 6f851e9b7..141851285 100644
--- a/docs/tutorials/wiki2/src/authorization/README.txt
+++ b/docs/tutorials/wiki2/src/authorization/README.txt
@@ -1 +1,14 @@
 tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $venv/bin/python setup.py develop
+
+- $venv/bin/initialize_tutorial_db development.ini
+
+- $venv/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/authorization/development.ini b/docs/tutorials/wiki2/src/authorization/development.ini
index eb2f878c5..a9d53b296 100644
--- a/docs/tutorials/wiki2/src/authorization/development.ini
+++ b/docs/tutorials/wiki2/src/authorization/development.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -12,12 +17,23 @@ pyramid.includes =
 
 sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -53,5 +69,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/authorization/setup.py b/docs/tutorials/wiki2/src/authorization/setup.py
index 2fd051927..36668dd33 100644
--- a/docs/tutorials/wiki2/src/authorization/setup.py
+++ b/docs/tutorials/wiki2/src/authorization/setup.py
@@ -13,17 +13,17 @@ requires = [
     'pyramid_tm',
     'pyramid_debugtoolbar',
     'zope.sqlalchemy',
-    'docutils',
     'waitress',
+    'docutils',
     ]
 
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -35,8 +35,8 @@ setup(name='tutorial',
       include_package_data=True,
       zip_safe=False,
       test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
index 76071173a..d08e55bf9 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py
@@ -11,6 +11,7 @@ from .models import (
     Base,
     )
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
@@ -33,4 +34,3 @@ def main(global_config, **settings):
     config.add_route('edit_page', '/{pagename}/edit_page')
     config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models.py b/docs/tutorials/wiki2/src/authorization/tutorial/models.py
index c3bdcbea5..91e5a0019 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/models.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/models.py
@@ -21,6 +21,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
+
 class Page(Base):
     """ The SQLAlchemy declarative model class for a Page object. """
     __tablename__ = 'pages'
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
index 03188e8ad..092e359ce 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py
@@ -15,12 +15,14 @@ from ..models import (
     Base,
     )
 
+
 def usage(argv):
     cmd = os.path.basename(argv[0])
     print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
+          '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
+
 def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/tests.py b/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
index 31d2dc6d5..5dcee127b 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/tests.py
@@ -1,5 +1,6 @@
 import unittest
 import transaction
+
 from pyramid import testing
 
 def _initTestingDB():
diff --git a/docs/tutorials/wiki2/src/basiclayout/README.txt b/docs/tutorials/wiki2/src/basiclayout/README.txt
index 6f851e9b7..141851285 100644
--- a/docs/tutorials/wiki2/src/basiclayout/README.txt
+++ b/docs/tutorials/wiki2/src/basiclayout/README.txt
@@ -1 +1,14 @@
 tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $venv/bin/python setup.py develop
+
+- $venv/bin/initialize_tutorial_db development.ini
+
+- $venv/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/basiclayout/development.ini b/docs/tutorials/wiki2/src/basiclayout/development.ini
index eb2f878c5..a9d53b296 100644
--- a/docs/tutorials/wiki2/src/basiclayout/development.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/development.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -12,12 +17,23 @@ pyramid.includes =
 
 sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -53,5 +69,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/basiclayout/production.ini b/docs/tutorials/wiki2/src/basiclayout/production.ini
index 4684d2f7a..fa94c1b3e 100644
--- a/docs/tutorials/wiki2/src/basiclayout/production.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/production.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -16,7 +21,10 @@ use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -52,5 +60,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/basiclayout/setup.py b/docs/tutorials/wiki2/src/basiclayout/setup.py
index 050de7299..a09bf756a 100644
--- a/docs/tutorials/wiki2/src/basiclayout/setup.py
+++ b/docs/tutorials/wiki2/src/basiclayout/setup.py
@@ -19,10 +19,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -34,12 +34,11 @@ setup(name='tutorial',
       include_package_data=True,
       zip_safe=False,
       test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
       initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
-
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
index e39f619ed..aac7c5e69 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
@@ -6,6 +6,7 @@ from .models import (
     Base,
     )
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
@@ -17,4 +18,3 @@ def main(global_config, **settings):
     config.add_route('home', '/')
     config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py
index b6ac15429..aeeb9df64 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py
@@ -16,6 +16,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
+
 class MyModel(Base):
     __tablename__ = 'models'
     id = Column(Integer, primary_key=True)
@@ -25,4 +26,3 @@ class MyModel(Base):
     def __init__(self, name, value):
         self.name = name
         self.value = value
-
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py
index 0e828465f..66feb3008 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/scripts/initializedb.py
@@ -15,12 +15,14 @@ from ..models import (
     Base,
     )
 
+
 def usage(argv):
     cmd = os.path.basename(argv[0])
     print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
+          '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
+
 def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt
index fbfa9870b..15ea6614f 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt
@@ -70,7 +70,7 @@
     </div>
   </div>
   <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2011, Agendaless Consulting.</div>
+    <div class="footer">&copy; Copyright 2008-2012, Agendaless Consulting.</div>
   </div>
 </body>
 </html>
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
index 653d061e4..57a775e0a 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/tests.py
@@ -5,6 +5,7 @@ from pyramid import testing
 
 from .models import DBSession
 
+
 class TestMyView(unittest.TestCase):
     def setUp(self):
         self.config = testing.setUp()
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
index 3e6abf2c2..4cfcae4af 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py
@@ -1,11 +1,35 @@
+from pyramid.response import Response
 from pyramid.view import view_config
 
+from sqlalchemy.exc import DBAPIError
+
 from .models import (
     DBSession,
     MyModel,
     )
 
+
 @view_config(route_name='home', renderer='templates/mytemplate.pt')
 def my_view(request):
-    one = DBSession.query(MyModel).filter(MyModel.name=='one').first()
-    return {'one':one, 'project':'tutorial'}
+    try:
+        one = DBSession.query(MyModel).filter(MyModel.name == 'one').first()
+    except DBAPIError:
+        return Response(conn_err_msg, content_type='text/plain', status_int=500)
+    return {'one': one, 'project': 'tutorial'}
+
+conn_err_msg = """\
+Pyramid is having a problem using your SQL database.  The problem
+might be caused by one of the following things:
+
+1.  You may need to run the "initialize_tutorial_db" script
+    to initialize your database tables.  Check your virtual 
+    environment's "bin" directory for this script and try to run it.
+
+2.  Your database server may not be running.  Check that the
+    database server referred to by the "sqlalchemy.url" setting in
+    your "development.ini" file is running.
+
+After you fix the problem, please restart the Pyramid application to
+try it again.
+"""
+
diff --git a/docs/tutorials/wiki2/src/models/README.txt b/docs/tutorials/wiki2/src/models/README.txt
index 6f851e9b7..141851285 100644
--- a/docs/tutorials/wiki2/src/models/README.txt
+++ b/docs/tutorials/wiki2/src/models/README.txt
@@ -1 +1,14 @@
 tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $venv/bin/python setup.py develop
+
+- $venv/bin/initialize_tutorial_db development.ini
+
+- $venv/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/models/development.ini b/docs/tutorials/wiki2/src/models/development.ini
index eb2f878c5..a9d53b296 100644
--- a/docs/tutorials/wiki2/src/models/development.ini
+++ b/docs/tutorials/wiki2/src/models/development.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -12,12 +17,23 @@ pyramid.includes =
 
 sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -53,5 +69,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/models/setup.py b/docs/tutorials/wiki2/src/models/setup.py
index 050de7299..a09bf756a 100644
--- a/docs/tutorials/wiki2/src/models/setup.py
+++ b/docs/tutorials/wiki2/src/models/setup.py
@@ -19,10 +19,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -34,12 +34,11 @@ setup(name='tutorial',
       include_package_data=True,
       zip_safe=False,
       test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
       initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
-
diff --git a/docs/tutorials/wiki2/src/models/tutorial/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
index e39f619ed..aac7c5e69 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/__init__.py
@@ -6,6 +6,7 @@ from .models import (
     Base,
     )
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
@@ -17,4 +18,3 @@ def main(global_config, **settings):
     config.add_route('home', '/')
     config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/models/tutorial/models.py b/docs/tutorials/wiki2/src/models/tutorial/models.py
index 499396c5b..9a078d757 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/models.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/models.py
@@ -16,6 +16,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
+
 class Page(Base):
     """ The SQLAlchemy declarative model class for a Page object. """
     __tablename__ = 'pages'
@@ -26,4 +27,3 @@ class Page(Base):
     def __init__(self, name, data):
         self.name = name
         self.data = data
-
diff --git a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
index 03188e8ad..092e359ce 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py
@@ -15,12 +15,14 @@ from ..models import (
     Base,
     )
 
+
 def usage(argv):
     cmd = os.path.basename(argv[0])
     print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
+          '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
+
 def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
diff --git a/docs/tutorials/wiki2/src/models/tutorial/tests.py b/docs/tutorials/wiki2/src/models/tutorial/tests.py
index 653d061e4..57a775e0a 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/tests.py
@@ -5,6 +5,7 @@ from pyramid import testing
 
 from .models import DBSession
 
+
 class TestMyView(unittest.TestCase):
     def setUp(self):
         self.config = testing.setUp()
diff --git a/docs/tutorials/wiki2/src/models/tutorial/views.py b/docs/tutorials/wiki2/src/models/tutorial/views.py
index 3e6abf2c2..4cfcae4af 100644
--- a/docs/tutorials/wiki2/src/models/tutorial/views.py
+++ b/docs/tutorials/wiki2/src/models/tutorial/views.py
@@ -1,11 +1,35 @@
+from pyramid.response import Response
 from pyramid.view import view_config
 
+from sqlalchemy.exc import DBAPIError
+
 from .models import (
     DBSession,
     MyModel,
     )
 
+
 @view_config(route_name='home', renderer='templates/mytemplate.pt')
 def my_view(request):
-    one = DBSession.query(MyModel).filter(MyModel.name=='one').first()
-    return {'one':one, 'project':'tutorial'}
+    try:
+        one = DBSession.query(MyModel).filter(MyModel.name == 'one').first()
+    except DBAPIError:
+        return Response(conn_err_msg, content_type='text/plain', status_int=500)
+    return {'one': one, 'project': 'tutorial'}
+
+conn_err_msg = """\
+Pyramid is having a problem using your SQL database.  The problem
+might be caused by one of the following things:
+
+1.  You may need to run the "initialize_tutorial_db" script
+    to initialize your database tables.  Check your virtual 
+    environment's "bin" directory for this script and try to run it.
+
+2.  Your database server may not be running.  Check that the
+    database server referred to by the "sqlalchemy.url" setting in
+    your "development.ini" file is running.
+
+After you fix the problem, please restart the Pyramid application to
+try it again.
+"""
+
diff --git a/docs/tutorials/wiki2/src/tests/README.txt b/docs/tutorials/wiki2/src/tests/README.txt
index 6f851e9b7..141851285 100644
--- a/docs/tutorials/wiki2/src/tests/README.txt
+++ b/docs/tutorials/wiki2/src/tests/README.txt
@@ -1 +1,14 @@
 tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $venv/bin/python setup.py develop
+
+- $venv/bin/initialize_tutorial_db development.ini
+
+- $venv/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/tests/development.ini b/docs/tutorials/wiki2/src/tests/development.ini
index eb2f878c5..a9d53b296 100644
--- a/docs/tutorials/wiki2/src/tests/development.ini
+++ b/docs/tutorials/wiki2/src/tests/development.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -12,12 +17,23 @@ pyramid.includes =
 
 sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -53,5 +69,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/tests/setup.py b/docs/tutorials/wiki2/src/tests/setup.py
index 0f58d8a18..3c2961fcc 100644
--- a/docs/tutorials/wiki2/src/tests/setup.py
+++ b/docs/tutorials/wiki2/src/tests/setup.py
@@ -21,10 +21,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -36,8 +36,8 @@ setup(name='tutorial',
       include_package_data=True,
       zip_safe=False,
       test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/__init__.py b/docs/tutorials/wiki2/src/tests/tutorial/__init__.py
index 76071173a..d08e55bf9 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/__init__.py
@@ -11,6 +11,7 @@ from .models import (
     Base,
     )
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
@@ -33,4 +34,3 @@ def main(global_config, **settings):
     config.add_route('edit_page', '/{pagename}/edit_page')
     config.scan()
     return config.make_wsgi_app()
-
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models.py b/docs/tutorials/wiki2/src/tests/tutorial/models.py
index c3bdcbea5..91e5a0019 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/models.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/models.py
@@ -21,6 +21,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
+
 class Page(Base):
     """ The SQLAlchemy declarative model class for a Page object. """
     __tablename__ = 'pages'
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
index 03188e8ad..092e359ce 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py
@@ -15,12 +15,14 @@ from ..models import (
     Base,
     )
 
+
 def usage(argv):
     cmd = os.path.basename(argv[0])
     print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
+          '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
+
 def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests.py b/docs/tutorials/wiki2/src/tests/tutorial/tests.py
index 659862a09..3e96d0a82 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/tests.py
@@ -1,7 +1,9 @@
 import unittest
 import transaction
+
 from pyramid import testing
 
+
 def _initTestingDB():
     from sqlalchemy import create_engine
     from tutorial.models import (
@@ -17,6 +19,7 @@ def _initTestingDB():
         DBSession.add(model)
     return DBSession
 
+
 def _registerRoutes(config):
     config.add_route('view_page', '{pagename}')
     config.add_route('edit_page', '{pagename}/edit_page')
@@ -43,6 +46,7 @@ class PageModelTests(unittest.TestCase):
         self.assertEqual(instance.name, 'SomeName')
         self.assertEqual(instance.data, 'some data')
 
+
 class ViewWikiTests(unittest.TestCase):
     def setUp(self):
         self.config = testing.setUp()
@@ -60,6 +64,7 @@ class ViewWikiTests(unittest.TestCase):
         response = self._callFUT(request)
         self.assertEqual(response.location, 'http://example.com/FrontPage')
 
+
 class ViewPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
@@ -93,6 +98,7 @@ class ViewPageTests(unittest.TestCase):
         self.assertEqual(info['edit_url'],
             'http://example.com/IDoExist/edit_page')
 
+
 class AddPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
@@ -125,6 +131,7 @@ class AddPageTests(unittest.TestCase):
         page = self.session.query(Page).filter_by(name='AnotherPage').one()
         self.assertEqual(page.data, 'Hello yo!')
 
+
 class EditPageTests(unittest.TestCase):
     def setUp(self):
         self.session = _initTestingDB()
@@ -162,6 +169,7 @@ class EditPageTests(unittest.TestCase):
         self.assertEqual(response.location, 'http://example.com/abc')
         self.assertEqual(page.data, 'Hello yo!')
 
+
 class FunctionalTests(unittest.TestCase):
 
     viewer_login = '/login?login=viewer&password=viewer' \
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/views.py b/docs/tutorials/wiki2/src/tests/tutorial/views.py
index 42ac0eb7f..0d085b0e2 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/views.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/views.py
@@ -37,14 +37,13 @@ def view_wiki(request):
              permission='view')
 def view_page(request):
     pagename = request.matchdict['pagename']
-    session = DBSession()
-    page = session.query(Page).filter_by(name=pagename).first()
+    page = DBSession.query(Page).filter_by(name=pagename).first()
     if page is None:
         return HTTPNotFound('No such page')
 
     def check(match):
         word = match.group(1)
-        exists = session.query(Page).filter_by(name=word).all()
+        exists = DBSession.query(Page).filter_by(name=word).all()
         if exists:
             view_url = request.route_url('view_page', pagename=word)
             return '<a href="%s">%s</a>' % (view_url, word)
@@ -63,10 +62,9 @@ def view_page(request):
 def add_page(request):
     pagename = request.matchdict['pagename']
     if 'form.submitted' in request.params:
-        session = DBSession()
         body = request.params['body']
         page = Page(pagename, body)
-        session.add(page)
+        DBSession.add(page)
         return HTTPFound(location = request.route_url('view_page',
                                                       pagename=pagename))
     save_url = request.route_url('add_page', pagename=pagename)
@@ -78,11 +76,10 @@ def add_page(request):
              permission='edit')
 def edit_page(request):
     pagename = request.matchdict['pagename']
-    session = DBSession()
-    page = session.query(Page).filter_by(name=pagename).one()
+    page = DBSession.query(Page).filter_by(name=pagename).one()
     if 'form.submitted' in request.params:
         page.data = request.params['body']
-        session.add(page)
+        DBSession.add(page)
         return HTTPFound(location = request.route_url('view_page',
                                                       pagename=pagename))
     return dict(
diff --git a/docs/tutorials/wiki2/src/views/README.txt b/docs/tutorials/wiki2/src/views/README.txt
index 6f851e9b7..141851285 100644
--- a/docs/tutorials/wiki2/src/views/README.txt
+++ b/docs/tutorials/wiki2/src/views/README.txt
@@ -1 +1,14 @@
 tutorial README
+==================
+
+Getting Started
+---------------
+
+- cd <directory containing this file>
+
+- $venv/bin/python setup.py develop
+
+- $venv/bin/initialize_tutorial_db development.ini
+
+- $venv/bin/pserve development.ini
+
diff --git a/docs/tutorials/wiki2/src/views/development.ini b/docs/tutorials/wiki2/src/views/development.ini
index eb2f878c5..a9d53b296 100644
--- a/docs/tutorials/wiki2/src/views/development.ini
+++ b/docs/tutorials/wiki2/src/views/development.ini
@@ -1,3 +1,8 @@
+###
+# app configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html
+###
+
 [app:main]
 use = egg:tutorial
 
@@ -12,12 +17,23 @@ pyramid.includes =
 
 sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
+# By default, the toolbar only appears for clients from IP addresses
+# '127.0.0.1' and '::1'.
+# debugtoolbar.hosts = 127.0.0.1 ::1
+
+###
+# wsgi server configuration
+###
+
 [server:main]
 use = egg:waitress#main
 host = 0.0.0.0
 port = 6543
 
-# Begin logging configuration
+###
+# logging configuration
+# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html
+###
 
 [loggers]
 keys = root, tutorial, sqlalchemy
@@ -53,5 +69,3 @@ formatter = generic
 
 [formatter_generic]
 format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
-
-# End logging configuration
diff --git a/docs/tutorials/wiki2/src/views/setup.py b/docs/tutorials/wiki2/src/views/setup.py
index 34b578e21..36668dd33 100644
--- a/docs/tutorials/wiki2/src/views/setup.py
+++ b/docs/tutorials/wiki2/src/views/setup.py
@@ -20,10 +20,10 @@ requires = [
 setup(name='tutorial',
       version='0.0',
       description='tutorial',
-      long_description=README + '\n\n' +  CHANGES,
+      long_description=README + '\n\n' + CHANGES,
       classifiers=[
         "Programming Language :: Python",
-        "Framework :: Pylons",
+        "Framework :: Pyramid",
         "Topic :: Internet :: WWW/HTTP",
         "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
         ],
@@ -35,12 +35,11 @@ setup(name='tutorial',
       include_package_data=True,
       zip_safe=False,
       test_suite='tutorial',
-      install_requires = requires,
-      entry_points = """\
+      install_requires=requires,
+      entry_points="""\
       [paste.app_factory]
       main = tutorial:main
       [console_scripts]
       initialize_tutorial_db = tutorial.scripts.initializedb:main
       """,
       )
-
diff --git a/docs/tutorials/wiki2/src/views/tutorial/__init__.py b/docs/tutorials/wiki2/src/views/tutorial/__init__.py
index 810e92f75..c95bfdbf8 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/__init__.py
@@ -6,6 +6,7 @@ from .models import (
     Base,
     )
 
+
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
diff --git a/docs/tutorials/wiki2/src/views/tutorial/models.py b/docs/tutorials/wiki2/src/views/tutorial/models.py
index 499396c5b..9a078d757 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/models.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/models.py
@@ -16,6 +16,7 @@ from zope.sqlalchemy import ZopeTransactionExtension
 DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
 Base = declarative_base()
 
+
 class Page(Base):
     """ The SQLAlchemy declarative model class for a Page object. """
     __tablename__ = 'pages'
@@ -26,4 +27,3 @@ class Page(Base):
     def __init__(self, name, data):
         self.name = name
         self.data = data
-
diff --git a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
index 03188e8ad..092e359ce 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py
@@ -15,12 +15,14 @@ from ..models import (
     Base,
     )
 
+
 def usage(argv):
     cmd = os.path.basename(argv[0])
     print('usage: %s <config_uri>\n'
-          '(example: "%s development.ini")' % (cmd, cmd)) 
+          '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
+
 def main(argv=sys.argv):
     if len(argv) != 2:
         usage(argv)
diff --git a/docs/tutorials/wiki2/src/views/tutorial/tests.py b/docs/tutorials/wiki2/src/views/tutorial/tests.py
index 31d2dc6d5..5dcee127b 100644
--- a/docs/tutorials/wiki2/src/views/tutorial/tests.py
+++ b/docs/tutorials/wiki2/src/views/tutorial/tests.py
@@ -1,5 +1,6 @@
 import unittest
 import transaction
+
 from pyramid import testing
 
 def _initTestingDB():