Merge pull request #2108 from stevepiercy/feature/alchemy-scaffold-update

update wiki2/src/basiclayout/tutorial

46 files changed, 606 insertions, 696 deletions

diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 2ef07af75..0c79b9a41 100644
--- a/CONTRIBUTORS.txt
+++ b/CONTRIBUTORS.txt
@@ -247,6 +247,8 @@ Contributors
 
 - Donald Stufft, 2015/03/15
 
+- Randy Topliffe, 2015/04/14
+
 - Karen Dalton, 2015/06/01
 
 - Igor Stroh, 2015/06/10
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index be5be2e36..87c6f1e1c 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -818,14 +818,14 @@ The ORM eases the mapping of database structures into a programming
 language. SQLAlchemy uses "models" for this mapping. The scaffold
 generated a sample model:
 
-.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models.py
+.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models/mymodel.py
     :start-after: Start Sphinx Include
     :end-before: End Sphinx Include
 
 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.py
+.. literalinclude:: quick_tour/sqla_demo/sqla_demo/views/default.py                    
     :start-after: Start Sphinx Include
     :end-before: End Sphinx Include
 
diff --git a/docs/quick_tour/sqla_demo/development.ini b/docs/quick_tour/sqla_demo/development.ini
index 174468abf..0db0950a0 100644
--- a/docs/quick_tour/sqla_demo/development.ini
+++ b/docs/quick_tour/sqla_demo/development.ini
@@ -27,7 +27,7 @@ sqlalchemy.url = sqlite:///%(here)s/sqla_demo.sqlite
 
 [server:main]
 use = egg:waitress#main
-host = 0.0.0.0
+host = 127.0.0.1
 port = 6543
 
 ###
@@ -68,4 +68,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/quick_tour/sqla_demo/production.ini b/docs/quick_tour/sqla_demo/production.ini
index dc0ba304f..38f3b6318 100644
--- a/docs/quick_tour/sqla_demo/production.ini
+++ b/docs/quick_tour/sqla_demo/production.ini
@@ -59,4 +59,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/quick_tour/sqla_demo/setup.py b/docs/quick_tour/sqla_demo/setup.py
index ac2eed035..312a97c06 100644
--- a/docs/quick_tour/sqla_demo/setup.py
+++ b/docs/quick_tour/sqla_demo/setup.py
@@ -3,15 +3,18 @@ import os
 from setuptools import setup, find_packages
 
 here = os.path.abspath(os.path.dirname(__file__))
-README = open(os.path.join(here, 'README.txt')).read()
-CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+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 = [
     'pyramid',
+    'pyramid_jinja2',
+    'pyramid_debugtoolbar',
+    'pyramid_tm',
     'SQLAlchemy',
     'transaction',
-    'pyramid_tm',
-    'pyramid_debugtoolbar',
     'zope.sqlalchemy',
     'waitress',
     ]
diff --git a/docs/quick_tour/sqla_demo/sqla_demo.sqlite b/docs/quick_tour/sqla_demo/sqla_demo.sqlite
deleted file mode 100644
index fa6adb104..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo.sqlite
+++ /dev/null
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/__init__.py b/docs/quick_tour/sqla_demo/sqla_demo/__init__.py
index aac7c5e69..7994bbfa8 100644
--- a/docs/quick_tour/sqla_demo/sqla_demo/__init__.py
+++ b/docs/quick_tour/sqla_demo/sqla_demo/__init__.py
@@ -1,19 +1,12 @@
 from pyramid.config import Configurator
-from sqlalchemy import engine_from_config
-
-from .models import (
-    DBSession,
-    Base,
-    )
 
 
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
-    engine = engine_from_config(settings, 'sqlalchemy.')
-    DBSession.configure(bind=engine)
-    Base.metadata.bind = engine
     config = Configurator(settings=settings)
+    config.include('pyramid_jinja2')
+    config.include('.models.meta')
     config.add_static_view('static', 'static', cache_max_age=3600)
     config.add_route('home', '/')
     config.scan()
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/models.py b/docs/quick_tour/sqla_demo/sqla_demo/models.py
deleted file mode 100644
index 3dfb40e58..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo/models.py
+++ /dev/null
@@ -1,29 +0,0 @@
-from sqlalchemy import (
-    Column,
-    Integer,
-    Text,
-    )
-
-from sqlalchemy.ext.declarative import declarative_base
-
-from sqlalchemy.orm import (
-    scoped_session,
-    sessionmaker,
-    )
-
-from zope.sqlalchemy import ZopeTransactionExtension
-
-DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension()))
-Base = declarative_base()
-
-# Start Sphinx Include
-class MyModel(Base):
-    __tablename__ = 'models'
-    id = Column(Integer, primary_key=True)
-    name = Column(Text, unique=True)
-    value = Column(Integer)
-
-    def __init__(self, name, value):
-        self.name = name
-        self.value = value
-    # End Sphinx Include
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/models/__init__.py b/docs/quick_tour/sqla_demo/sqla_demo/models/__init__.py
new file mode 100644
index 000000000..6ffc10a78
--- /dev/null
+++ b/docs/quick_tour/sqla_demo/sqla_demo/models/__init__.py
@@ -0,0 +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
+
+# run configure mappers to ensure we avoid any race conditions
+configure_mappers()
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/models/meta.py b/docs/quick_tour/sqla_demo/sqla_demo/models/meta.py
new file mode 100644
index 000000000..b72b45f9f
--- /dev/null
+++ b/docs/quick_tour/sqla_demo/sqla_demo/models/meta.py
@@ -0,0 +1,46 @@
+from sqlalchemy import engine_from_config
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.schema import MetaData
+import zope.sqlalchemy
+
+NAMING_CONVENTION = {
+    "ix": 'ix_%(column_0_label)s',
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s"
+}
+
+metadata = MetaData(naming_convention=NAMING_CONVENTION)
+Base = declarative_base(metadata=metadata)
+
+
+def includeme(config):
+    settings = config.get_settings()
+    dbmaker = get_dbmaker(get_engine(settings))
+
+    config.add_request_method(
+        lambda r: get_session(r.tm, dbmaker),
+        'dbsession',
+        reify=True
+    )
+
+    config.include('pyramid_tm')
+
+
+def get_session(transaction_manager, dbmaker):
+    dbsession = dbmaker()
+    zope.sqlalchemy.register(dbsession,
+                             transaction_manager=transaction_manager)
+    return dbsession
+
+
+def get_engine(settings, prefix='sqlalchemy.'):
+    return engine_from_config(settings, prefix)
+
+
+def get_dbmaker(engine):
+    dbmaker = sessionmaker()
+    dbmaker.configure(bind=engine)
+    return dbmaker
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/models/mymodel.py b/docs/quick_tour/sqla_demo/sqla_demo/models/mymodel.py
new file mode 100644
index 000000000..eb645bfe6
--- /dev/null
+++ b/docs/quick_tour/sqla_demo/sqla_demo/models/mymodel.py
@@ -0,0 +1,19 @@
+from .meta import Base
+from sqlalchemy import (
+    Column,
+    Index,
+    Integer,
+    Text,
+)
+
+
+# Start Sphinx Include
+class MyModel(Base):
+    __tablename__ = 'models'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text)
+    value = Column(Integer)
+    # End Sphinx Include
+
+
+Index('my_index', MyModel.name, unique=True, mysql_length=255)
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/scripts/initializedb.py b/docs/quick_tour/sqla_demo/sqla_demo/scripts/initializedb.py
index 66feb3008..f0d09729e 100644
--- a/docs/quick_tour/sqla_demo/sqla_demo/scripts/initializedb.py
+++ b/docs/quick_tour/sqla_demo/sqla_demo/scripts/initializedb.py
@@ -2,36 +2,44 @@ import os
 import sys
 import transaction
 
-from sqlalchemy import engine_from_config
-
 from pyramid.paster import (
     get_appsettings,
     setup_logging,
     )
 
-from ..models import (
-    DBSession,
-    MyModel,
+from pyramid.scripts.common import parse_vars
+
+from ..models.meta import (
     Base,
+    get_session,
+    get_engine,
+    get_dbmaker,
     )
+from ..models.mymodel import MyModel
 
 
 def usage(argv):
     cmd = os.path.basename(argv[0])
-    print('usage: %s <config_uri>\n'
+    print('usage: %s <config_uri> [var=value]\n'
           '(example: "%s development.ini")' % (cmd, cmd))
     sys.exit(1)
 
 
 def main(argv=sys.argv):
-    if len(argv) != 2:
+    if len(argv) < 2:
         usage(argv)
     config_uri = argv[1]
+    options = parse_vars(argv[2:])
     setup_logging(config_uri)
-    settings = get_appsettings(config_uri)
-    engine = engine_from_config(settings, 'sqlalchemy.')
-    DBSession.configure(bind=engine)
+    settings = get_appsettings(config_uri, options=options)
+
+    engine = get_engine(settings)
+    dbmaker = get_dbmaker(engine)
+
+    dbsession = get_session(transaction.manager, dbmaker)
+
     Base.metadata.create_all(engine)
+
     with transaction.manager:
         model = MyModel(name='one', value=1)
-        DBSession.add(model)
+        dbsession.add(model)
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/favicon.ico b/docs/quick_tour/sqla_demo/sqla_demo/static/favicon.ico
deleted file mode 100644
index 71f837c9e..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo/static/favicon.ico
+++ /dev/null
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/footerbg.png b/docs/quick_tour/sqla_demo/sqla_demo/static/footerbg.png
deleted file mode 100644
index 1fbc873da..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo/static/footerbg.png
+++ /dev/null
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/headerbg.png b/docs/quick_tour/sqla_demo/sqla_demo/static/headerbg.png
deleted file mode 100644
index 0596f2020..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo/static/headerbg.png
+++ /dev/null
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/ie6.css b/docs/quick_tour/sqla_demo/sqla_demo/static/ie6.css
deleted file mode 100644
index b7c8493d8..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo/static/ie6.css
+++ /dev/null
@@ -1,8 +0,0 @@
-* html img,
-* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none",
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')",
-this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''),
-this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')",
-this.runtimeStyle.backgroundImage = "none")),this.pngSet=true)
-);}
-#wrap{display:table;height:100%}
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/middlebg.png b/docs/quick_tour/sqla_demo/sqla_demo/static/middlebg.png
deleted file mode 100644
index 2369cfb7d..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo/static/middlebg.png
+++ /dev/null
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/pylons.css b/docs/quick_tour/sqla_demo/sqla_demo/static/pylons.css
deleted file mode 100644
index 4b1c017cd..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo/static/pylons.css
+++ /dev/null
@@ -1,372 +0,0 @@
-html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, font, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td
-{
-  margin: 0;
-  padding: 0;
-  border: 0;
-  outline: 0;
-  font-size: 100%; /* 16px */
-  vertical-align: baseline;
-  background: transparent;
-}
-
-body
-{
-  line-height: 1;
-}
-
-ol, ul
-{
-  list-style: none;
-}
-
-blockquote, q
-{
-  quotes: none;
-}
-
-blockquote:before, blockquote:after, q:before, q:after
-{
-  content: '';
-  content: none;
-}
-
-:focus
-{
-  outline: 0;
-}
-
-ins
-{
-  text-decoration: none;
-}
-
-del
-{
-  text-decoration: line-through;
-}
-
-table
-{
-  border-collapse: collapse;
-  border-spacing: 0;
-}
-
-sub
-{
-  vertical-align: sub;
-  font-size: smaller;
-  line-height: normal;
-}
-
-sup
-{
-  vertical-align: super;
-  font-size: smaller;
-  line-height: normal;
-}
-
-ul, menu, dir
-{
-  display: block;
-  list-style-type: disc;
-  margin: 1em 0;
-  padding-left: 40px;
-}
-
-ol
-{
-  display: block;
-  list-style-type: decimal-leading-zero;
-  margin: 1em 0;
-  padding-left: 40px;
-}
-
-li
-{
-  display: list-item;
-}
-
-ul ul, ul ol, ul dir, ul menu, ul dl, ol ul, ol ol, ol dir, ol menu, ol dl, dir ul, dir ol, dir dir, dir menu, dir dl, menu ul, menu ol, menu dir, menu menu, menu dl, dl ul, dl ol, dl dir, dl menu, dl dl
-{
-  margin-top: 0;
-  margin-bottom: 0;
-}
-
-ol ul, ul ul, menu ul, dir ul, ol menu, ul menu, menu menu, dir menu, ol dir, ul dir, menu dir, dir dir
-{
-  list-style-type: circle;
-}
-
-ol ol ul, ol ul ul, ol menu ul, ol dir ul, ol ol menu, ol ul menu, ol menu menu, ol dir menu, ol ol dir, ol ul dir, ol menu dir, ol dir dir, ul ol ul, ul ul ul, ul menu ul, ul dir ul, ul ol menu, ul ul menu, ul menu menu, ul dir menu, ul ol dir, ul ul dir, ul menu dir, ul dir dir, menu ol ul, menu ul ul, menu menu ul, menu dir ul, menu ol menu, menu ul menu, menu menu menu, menu dir menu, menu ol dir, menu ul dir, menu menu dir, menu dir dir, dir ol ul, dir ul ul, dir menu ul, dir dir ul, dir ol menu, dir ul menu, dir menu menu, dir dir menu, dir ol dir, dir ul dir, dir menu dir, dir dir dir
-{
-  list-style-type: square;
-}
-
-.hidden
-{
-  display: none;
-}
-
-p
-{
-  line-height: 1.5em;
-}
-
-h1
-{
-  font-size: 1.75em;
-  line-height: 1.7em;
-  font-family: helvetica, verdana;
-}
-
-h2
-{
-  font-size: 1.5em;
-  line-height: 1.7em;
-  font-family: helvetica, verdana;
-}
-
-h3
-{
-  font-size: 1.25em;
-  line-height: 1.7em;
-  font-family: helvetica, verdana;
-}
-
-h4
-{
-  font-size: 1em;
-  line-height: 1.7em;
-  font-family: helvetica, verdana;
-}
-
-html, body
-{
-  width: 100%;
-  height: 100%;
-}
-
-body
-{
-  margin: 0;
-  padding: 0;
-  background-color: #fff;
-  position: relative;
-  font: 16px/24px NobileRegular, "Lucida Grande", Lucida, Verdana, sans-serif;
-}
-
-a
-{
-  color: #1b61d6;
-  text-decoration: none;
-}
-
-a:hover
-{
-  color: #e88f00;
-  text-decoration: underline;
-}
-
-body h1, body h2, body h3, body h4, body h5, body h6
-{
-  font-family: NeutonRegular, "Lucida Grande", Lucida, Verdana, sans-serif;
-  font-weight: 400;
-  color: #373839;
-  font-style: normal;
-}
-
-#wrap
-{
-  min-height: 100%;
-}
-
-#header, #footer
-{
-  width: 100%;
-  color: #fff;
-  height: 40px;
-  position: absolute;
-  text-align: center;
-  line-height: 40px;
-  overflow: hidden;
-  font-size: 12px;
-  vertical-align: middle;
-}
-
-#header
-{
-  background: #000;
-  top: 0;
-  font-size: 14px;
-}
-
-#footer
-{
-  bottom: 0;
-  background: #000 url(footerbg.png) repeat-x 0 top;
-  position: relative;
-  margin-top: -40px;
-  clear: both;
-}
-
-.header, .footer
-{
-  width: 750px;
-  margin-right: auto;
-  margin-left: auto;
-}
-
-.wrapper
-{
-  width: 100%;
-}
-
-#top, #top-small, #bottom
-{
-  width: 100%;
-}
-
-#top
-{
-  color: #000;
-  height: 230px;
-  background: #fff url(headerbg.png) repeat-x 0 top;
-  position: relative;
-}
-
-#top-small
-{
-  color: #000;
-  height: 60px;
-  background: #fff url(headerbg.png) repeat-x 0 top;
-  position: relative;
-}
-
-#bottom
-{
-  color: #222;
-  background-color: #fff;
-}
-
-.top, .top-small, .middle, .bottom
-{
-  width: 750px;
-  margin-right: auto;
-  margin-left: auto;
-}
-
-.top
-{
-  padding-top: 40px;
-}
-
-.top-small
-{
-  padding-top: 10px;
-}
-
-#middle
-{
-  width: 100%;
-  height: 100px;
-  background: url(middlebg.png) repeat-x;
-  border-top: 2px solid #fff;
-  border-bottom: 2px solid #b2b2b2;
-}
-
-.app-welcome
-{
-  margin-top: 25px;
-}
-
-.app-name
-{
-  color: #000;
-  font-weight: 700;
-}
-
-.bottom
-{
-  padding-top: 50px;
-}
-
-#left
-{
-  width: 350px;
-  float: left;
-  padding-right: 25px;
-}
-
-#right
-{
-  width: 350px;
-  float: right;
-  padding-left: 25px;
-}
-
-.align-left
-{
-  text-align: left;
-}
-
-.align-right
-{
-  text-align: right;
-}
-
-.align-center
-{
-  text-align: center;
-}
-
-ul.links
-{
-  margin: 0;
-  padding: 0;
-}
-
-ul.links li
-{
-  list-style-type: none;
-  font-size: 14px;
-}
-
-form
-{
-  border-style: none;
-}
-
-fieldset
-{
-  border-style: none;
-}
-
-input
-{
-  color: #222;
-  border: 1px solid #ccc;
-  font-family: sans-serif;
-  font-size: 12px;
-  line-height: 16px;
-}
-
-input[type=text], input[type=password]
-{
-  width: 205px;
-}
-
-input[type=submit]
-{
-  background-color: #ddd;
-  font-weight: 700;
-}
-
-/*Opera Fix*/
-body:before
-{
-  content: "";
-  height: 100%;
-  float: left;
-  width: 0;
-  margin-top: -32767px;
-}
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid-16x16.png b/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid-16x16.png
new file mode 100644
index 000000000..979203112
--- /dev/null
+++ b/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid-16x16.png
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid-small.png b/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid-small.png
deleted file mode 100644
index a5bc0ade7..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid-small.png
+++ /dev/null
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid.png b/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid.png
index 347e05549..4ab837be9 100644
--- a/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid.png
+++ b/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid.png
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/theme.css b/docs/quick_tour/sqla_demo/sqla_demo/static/theme.css
new file mode 100644
index 000000000..0f4b1a4d4
--- /dev/null
+++ b/docs/quick_tour/sqla_demo/sqla_demo/static/theme.css
@@ -0,0 +1,154 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);
+body {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+  color: #ffffff;
+  background: #bc2131;
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+  font-weight: 300;
+}
+p {
+  font-weight: 300;
+}
+.font-normal {
+  font-weight: 400;
+}
+.font-semi-bold {
+  font-weight: 600;
+}
+.font-bold {
+  font-weight: 700;
+}
+.starter-template {
+  margin-top: 250px;
+}
+.starter-template .content {
+  margin-left: 10px;
+}
+.starter-template .content h1 {
+  margin-top: 10px;
+  font-size: 60px;
+}
+.starter-template .content h1 .smaller {
+  font-size: 40px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead {
+  font-size: 25px;
+  color: #f2b7bd;
+}
+.starter-template .content .lead .font-normal {
+  color: #ffffff;
+}
+.starter-template .links {
+  float: right;
+  right: 0;
+  margin-top: 125px;
+}
+.starter-template .links ul {
+  display: block;
+  padding: 0;
+  margin: 0;
+}
+.starter-template .links ul li {
+  list-style: none;
+  display: inline;
+  margin: 0 10px;
+}
+.starter-template .links ul li:first-child {
+  margin-left: 0;
+}
+.starter-template .links ul li:last-child {
+  margin-right: 0;
+}
+.starter-template .links ul li.current-version {
+  color: #f2b7bd;
+  font-weight: 400;
+}
+.starter-template .links ul li a, a {
+  color: #f2b7bd;
+  text-decoration: underline;
+}
+.starter-template .links ul li a:hover, a:hover {
+  color: #ffffff;
+  text-decoration: underline;
+}
+.starter-template .links ul li .icon-muted {
+  color: #eb8b95;
+  margin-right: 5px;
+}
+.starter-template .links ul li:hover .icon-muted {
+  color: #ffffff;
+}
+.starter-template .copyright {
+  margin-top: 10px;
+  font-size: 0.9em;
+  color: #f2b7bd;
+  text-transform: lowercase;
+  float: right;
+  right: 0;
+}
+@media (max-width: 1199px) {
+  .starter-template .content h1 {
+    font-size: 45px;
+  }
+  .starter-template .content h1 .smaller {
+    font-size: 30px;
+  }
+  .starter-template .content .lead {
+    font-size: 20px;
+  }
+}
+@media (max-width: 991px) {
+  .starter-template {
+    margin-top: 0;
+  }
+  .starter-template .logo {
+    margin: 40px auto;
+  }
+  .starter-template .content {
+    margin-left: 0;
+    text-align: center;
+  }
+  .starter-template .content h1 {
+    margin-bottom: 20px;
+  }
+  .starter-template .links {
+    float: none;
+    text-align: center;
+    margin-top: 60px;
+  }
+  .starter-template .copyright {
+    float: none;
+    text-align: center;
+  }
+}
+@media (max-width: 767px) {
+  .starter-template .content h1 .smaller {
+    font-size: 25px;
+    display: block;
+  }
+  .starter-template .content .lead {
+    font-size: 16px;
+  }
+  .starter-template .links {
+    margin-top: 40px;
+  }
+  .starter-template .links ul li {
+    display: block;
+    margin: 0;
+  }
+  .starter-template .links ul li .icon-muted {
+    display: none;
+  }
+  .starter-template .copyright {
+    margin-top: 20px;
+  }
+}
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/theme.min.css b/docs/quick_tour/sqla_demo/sqla_demo/static/theme.min.css
new file mode 100644
index 000000000..0d25de5b6
--- /dev/null
+++ b/docs/quick_tour/sqla_demo/sqla_demo/static/theme.min.css
@@ -0,0 +1 @@
+@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);body{font-family:"Open Sans","Helvetica Neue",Helvetica,Arial,sans-serif;font-weight:300;color:#fff;background:#bc2131}h1,h2,h3,h4,h5,h6{font-family:"Open Sans","Helvetica Neue",Helvetica,Arial,sans-serif;font-weight:300}p{font-weight:300}.font-normal{font-weight:400}.font-semi-bold{font-weight:600}.font-bold{font-weight:700}.starter-template{margin-top:250px}.starter-template .content{margin-left:10px}.starter-template .content h1{margin-top:10px;font-size:60px}.starter-template .content h1 .smaller{font-size:40px;color:#f2b7bd}.starter-template .content .lead{font-size:25px;color:#f2b7bd}.starter-template .content .lead .font-normal{color:#fff}.starter-template .links{float:right;right:0;margin-top:125px}.starter-template .links ul{display:block;padding:0;margin:0}.starter-template .links ul li{list-style:none;display:inline;margin:0 10px}.starter-template .links ul li:first-child{margin-left:0}.starter-template .links ul li:last-child{margin-right:0}.starter-template .links ul li.current-version{color:#f2b7bd;font-weight:400}.starter-template .links ul li a,a{color:#f2b7bd;text-decoration:underline}.starter-template .links ul li a:hover,a:hover{color:#fff;text-decoration:underline}.starter-template .links ul li .icon-muted{color:#eb8b95;margin-right:5px}.starter-template .links ul li:hover .icon-muted{color:#fff}.starter-template .copyright{margin-top:10px;font-size:.9em;color:#f2b7bd;text-transform:lowercase;float:right;right:0}@media (max-width:1199px){.starter-template .content h1{font-size:45px}.starter-template .content h1 .smaller{font-size:30px}.starter-template .content .lead{font-size:20px}}@media (max-width:991px){.starter-template{margin-top:0}.starter-template .logo{margin:40px auto}.starter-template .content{margin-left:0;text-align:center}.starter-template .content h1{margin-bottom:20px}.starter-template .links{float:none;text-align:center;margin-top:60px}.starter-template .copyright{float:none;text-align:center}}@media (max-width:767px){.starter-template .content h1 .smaller{font-size:25px;display:block}.starter-template .content .lead{font-size:16px}.starter-template .links{margin-top:40px}.starter-template .links ul li{display:block;margin:0}.starter-template .links ul li .icon-muted{display:none}.starter-template .copyright{margin-top:20px}}
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/transparent.gif b/docs/quick_tour/sqla_demo/sqla_demo/static/transparent.gif
deleted file mode 100644
index 0341802e5..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo/static/transparent.gif
+++ /dev/null
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/templates/layout.jinja2 b/docs/quick_tour/sqla_demo/sqla_demo/templates/layout.jinja2
new file mode 100644
index 000000000..76a098122
--- /dev/null
+++ b/docs/quick_tour/sqla_demo/sqla_demo/templates/layout.jinja2
@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html lang="{{request.locale_name}}">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="description" content="pyramid web application">
+    <meta name="author" content="Pylons Project">
+    <link rel="shortcut icon" href="{{request.static_url('sqla_demo:static/pyramid-16x16.png')}}">
+
+    <title>Alchemy Scaffold for The Pyramid Web Framework</title>
+
+    <!-- Bootstrap core CSS -->
+    <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
+
+    <!-- Custom styles for this scaffold -->
+    <link href="{{request.static_url('sqla_demo:static/theme.css')}}" rel="stylesheet">
+
+    <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
+    <!--[if lt IE 9]>
+      <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+      <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
+    <![endif]-->
+  </head>
+
+  <body>
+
+    <div class="starter-template">
+      <div class="container">
+        <div class="row">
+          <div class="col-md-2">
+            <img class="logo img-responsive" src="{{request.static_url('sqla_demo:static/pyramid.png')}}" alt="pyramid web framework">
+          </div>
+          <div class="col-md-10">
+            {% block content %}
+                <p>No content</p>
+            {% endblock content %}
+          </div>
+        </div>
+        <div class="row">
+          <div class="links">
+            <ul>
+              <li class="current-version">Generated by v1.7.dev0</li>
+              <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.7-branch/">Docs</a></li>
+              <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li>
+              <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li>
+              <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li>
+            </ul>
+          </div>
+        </div>
+        <div class="row">
+          <div class="copyright">
+            Copyright &copy; Pylons Project
+          </div>
+        </div>
+      </div>
+    </div>
+
+
+    <!-- Bootstrap core JavaScript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script>
+    <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script>
+  </body>
+</html>
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/templates/mytemplate.jinja2 b/docs/quick_tour/sqla_demo/sqla_demo/templates/mytemplate.jinja2
new file mode 100644
index 000000000..bb622bf5a
--- /dev/null
+++ b/docs/quick_tour/sqla_demo/sqla_demo/templates/mytemplate.jinja2
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Alchemy scaffold</span></h1>
+  <p class="lead">Welcome to <span class="font-normal">{{project}}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework 1.7.dev0</span>.</p>
+</div>
+{% endblock content %}
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/templates/mytemplate.pt b/docs/quick_tour/sqla_demo/sqla_demo/templates/mytemplate.pt
deleted file mode 100644
index 321c0f5fb..000000000
--- a/docs/quick_tour/sqla_demo/sqla_demo/templates/mytemplate.pt
+++ /dev/null
@@ -1,76 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
-<head>
-  <title>The Pyramid Web Framework</title>
-  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
-  <meta name="keywords" content="python web application" />
-  <meta name="description" content="pyramid web application" />
-  <link rel="shortcut icon" href="${request.static_url('sqla_demo:static/favicon.ico')}" />
-  <link rel="stylesheet" href="${request.static_url('sqla_demo:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" />
-  <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/nobile/stylesheet.css" media="screen" />
-  <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/neuton/stylesheet.css" media="screen" />
-  <!--[if lte IE 6]>
-  <link rel="stylesheet" href="${request.static_url('sqla_demo:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" />
-  <![endif]-->
-</head>
-<body>
-  <div id="wrap">
-    <div id="top">
-      <div class="top align-center">
-        <div><img src="${request.static_url('sqla_demo:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div>
-      </div>
-    </div>
-    <div id="middle">
-      <div class="middle align-center">
-        <p class="app-welcome">
-          Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web framework.
-        </p>
-      </div>
-    </div>
-    <div id="bottom">
-      <div class="bottom">
-        <div id="left" class="align-right">
-          <h2>Search documentation</h2>
-          <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/search.html">
-                <input type="text" id="q" name="q" value="" />
-                <input type="submit" id="x" value="Go" />
-            </form>
-        </div>
-        <div id="right" class="align-left">
-          <h2>Pyramid links</h2>
-          <ul class="links">
-            <li>
-              <a href="http://pylonsproject.org">Pylons Website</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#narrative-documentation">Narrative Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#reference-material">API Documentation</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#tutorials">Tutorials</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#detailed-change-history">Change History</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#sample-applications">Sample Applications</a>
-            </li>
-            <li>
-              <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#support-and-development">Support and Development</a>
-            </li>
-            <li>
-              <a href="irc://irc.freenode.net#pyramid">IRC Channel</a>
-            </li>
-            </ul>
-        </div>
-      </div>
-    </div>
-  </div>
-  <div id="footer">
-    <div class="footer">&copy; Copyright 2008-2012, Agendaless Consulting.</div>
-  </div>
-</body>
-</html>
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/tests.py b/docs/quick_tour/sqla_demo/sqla_demo/tests.py
index 6fef6d695..b6b6fdf4d 100644
--- a/docs/quick_tour/sqla_demo/sqla_demo/tests.py
+++ b/docs/quick_tour/sqla_demo/sqla_demo/tests.py
@@ -3,31 +3,63 @@ import transaction
 
 from pyramid import testing
 
-from .models import DBSession
 
+def dummy_request(dbsession):
+    return testing.DummyRequest(dbsession=dbsession)
 
-class TestMyView(unittest.TestCase):
+
+class BaseTest(unittest.TestCase):
     def setUp(self):
-        self.config = testing.setUp()
-        from sqlalchemy import create_engine
-        engine = create_engine('sqlite://')
-        from .models import (
-            Base,
-            MyModel,
+        self.config = testing.setUp(settings={
+            'sqlalchemy.url': 'sqlite:///:memory:'
+        })
+        self.config.include('.models.meta')
+        settings = self.config.get_settings()
+
+        from .models.meta import (
+            get_session,
+            get_engine,
+            get_dbmaker,
             )
-        DBSession.configure(bind=engine)
-        Base.metadata.create_all(engine)
-        with transaction.manager:
-            model = MyModel(name='one', value=55)
-            DBSession.add(model)
+
+        self.engine = get_engine(settings)
+        dbmaker = get_dbmaker(self.engine)
+
+        self.session = get_session(transaction.manager, dbmaker)
+
+    def init_database(self):
+        from .models.meta import Base
+        Base.metadata.create_all(self.engine)
 
     def tearDown(self):
-        DBSession.remove()
+        from .models.meta import Base
+
         testing.tearDown()
+        transaction.abort()
+        Base.metadata.create_all(self.engine)
+
+
+class TestMyViewSuccessCondition(BaseTest):
 
-    def test_it(self):
-        from .views import my_view
-        request = testing.DummyRequest()
-        info = my_view(request)
+    def setUp(self):
+        super(TestMyViewSuccessCondition, self).setUp()
+        self.init_database()
+
+        from .models.mymodel import MyModel
+
+        model = MyModel(name='one', value=55)
+        self.session.add(model)
+
+    def test_passing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
         self.assertEqual(info['one'].name, 'one')
         self.assertEqual(info['project'], 'sqla_demo')
+
+
+class TestMyViewFailureCondition(BaseTest):
+
+    def test_failing_view(self):
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info.status_int, 500)
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/views/__init__.py b/docs/quick_tour/sqla_demo/sqla_demo/views/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/docs/quick_tour/sqla_demo/sqla_demo/views/__init__.py
diff --git a/docs/quick_tour/sqla_demo/sqla_demo/views.py b/docs/quick_tour/sqla_demo/sqla_demo/views/default.py
index 768a7e42e..e5e70cf9d 100644
--- a/docs/quick_tour/sqla_demo/sqla_demo/views.py
+++ b/docs/quick_tour/sqla_demo/sqla_demo/views/default.py
@@ -3,28 +3,27 @@ from pyramid.view import view_config
 
 from sqlalchemy.exc import DBAPIError
 
-from .models import (
-    DBSession,
-    MyModel,
-    )
+from ..models.mymodel import MyModel
 
 
-@view_config(route_name='home', renderer='templates/mytemplate.pt')
+@view_config(route_name='home', renderer='../templates/mytemplate.jinja2')
 def my_view(request):
     try:
+        query = request.dbsession.query(MyModel)
         # Start Sphinx Include
-        one = DBSession.query(MyModel).filter(MyModel.name == 'one').first()
+        one = query.filter(MyModel.name == 'one').first()
         # End Sphinx Include
     except DBAPIError:
-        return Response(conn_err_msg, content_type='text/plain', status_int=500)
+        return Response(db_err_msg, content_type='text/plain', status_int=500)
     return {'one': one, 'project': 'sqla_demo'}
 
-conn_err_msg = """\
+
+db_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_sqla_demo_db" script
-    to initialize your database tables.  Check your virtual 
+    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
@@ -34,4 +33,3 @@ might be caused by one of the following things:
 After you fix the problem, please restart the Pyramid application to
 try it again.
 """
-
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index 695d7f15b..72b2bc26b 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -12,12 +12,12 @@ Application configuration with ``__init__.py``
 
 A directory on disk can be turned into a Python :term:`package` by containing
 an ``__init__.py`` file.  Even if empty, this marks a directory as a Python
-package.  We use ``__init__.py`` both as a marker, indicating the directory
-in which it's contained is a package, and to contain application configuration
+package.  We use ``__init__.py`` both as a marker, indicating the directory in
+which it's contained is a package, and to contain application configuration
 code.
 
-Open ``tutorial/tutorial/__init__.py``.  It should already contain
-the following:
+Open ``tutorial/tutorial/__init__.py``.  It should already contain the
+following:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
       :linenos:
@@ -43,58 +43,37 @@ When you invoke the ``pserve development.ini`` command, the ``main`` function
 above is executed.  It accepts some settings and returns a :term:`WSGI`
 application.  (See :ref:`startup_chapter` for more about ``pserve``.)
 
-The main function first creates a :term:`SQLAlchemy` database engine using
-:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed
-settings in the ``development.ini`` file's ``[app:main]`` section.
-This will be a URI (something like ``sqlite://``):
-
-   .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 13
-      :language: py
-
-``main`` then initializes our SQLAlchemy session object, passing it the
-engine:
-
-   .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 14
-      :language: py
-
-``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object,
-assigning the engine we created to the ``bind`` attribute of it's
-``metadata`` object.  This allows table definitions done imperatively
-(instead of declaratively, via a class statement) to work.  We won't use any
-such tables in our application, but if you add one later, long after you've
-forgotten about this tutorial, you won't be left scratching your head when it
-doesn't work.
-
-   .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 15
-      :language: py
-
 The next step of ``main`` is to construct a :term:`Configurator` object:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 16
+      :lines: 7
       :language: py
 
 ``settings`` is passed to the Configurator as a keyword argument with the
 dictionary values passed as the ``**settings`` argument.  This will be a
 dictionary of settings parsed from the ``.ini`` file, which contains
 deployment-related values such as ``pyramid.reload_templates``,
-``db_string``, etc.
+``sqlalchemy.url``, and so on.
 
-Next, include :term:`Chameleon` templating bindings so that we can use
-renderers with the ``.pt`` extension within our project.
+Next include :term:`Jinja2` templating bindings so that we can use renderers
+with the ``.jinja2`` extension within our project.
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 17
+      :lines: 8
+      :language: py
+
+Next include the module ``meta`` from the package ``models`` using a dotted
+Python path.
+
+   .. literalinclude:: src/basiclayout/tutorial/__init__.py
+      :lines: 9
       :language: py
 
 ``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with
 two arguments: ``static`` (the name), and ``static`` (the path):
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 18
+      :lines: 10
       :language: py
 
 This registers a static resource view which will match any URL that starts
@@ -112,11 +91,11 @@ via the :meth:`pyramid.config.Configurator.add_route` method that will be
 used when the URL is ``/``:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 19
+      :lines: 11
       :language: py
 
-Since this route has a ``pattern`` equaling ``/`` it is the route that will
-be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``.
+Since this route has a ``pattern`` equaling ``/``, it is the route that will
+be matched when the URL ``/`` is visited, e.g., ``http://localhost:6543/``.
 
 ``main`` next calls the ``scan`` method of the configurator
 (:meth:`pyramid.config.Configurator.scan`), which will recursively scan our
@@ -126,10 +105,10 @@ view configuration will be registered, which will allow one of our
 application URLs to be mapped to some code.
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
-      :lines: 20
+      :lines: 12
       :language: py
 
-Finally, ``main`` is finished configuring things, so it uses the
+Finally ``main`` is finished configuring things, so it uses the
 :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a
 :term:`WSGI` application:
 
@@ -184,6 +163,39 @@ inform the user about possible actions to take to solve the problem.
 Content Models with ``models.py``
 ---------------------------------
 
+.. START moved from Application configuration with ``__init__.py``. This
+  section is a WIP, and needs to be updated using the new models package.
+
+The main function first creates a :term:`SQLAlchemy` database engine using
+:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed
+settings in the ``development.ini`` file's ``[app:main]`` section.
+This will be a URI (something like ``sqlite://``):
+
+   .. literalinclude:: src/basiclayout/tutorial/__init__.py
+      :lines: 13
+      :language: py
+
+``main`` then initializes our SQLAlchemy session object, passing it the
+engine:
+
+   .. literalinclude:: src/basiclayout/tutorial/__init__.py
+      :lines: 14
+      :language: py
+
+``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object,
+assigning the engine we created to the ``bind`` attribute of it's
+``metadata`` object.  This allows table definitions done imperatively
+(instead of declaratively, via a class statement) to work.  We won't use any
+such tables in our application, but if you add one later, long after you've
+forgotten about this tutorial, you won't be left scratching your head when it
+doesn't work.
+
+   .. literalinclude:: src/basiclayout/tutorial/__init__.py
+      :lines: 15
+      :language: py
+
+.. END moved from Application configuration with ``__init__.py``
+
 In a SQLAlchemy-based application, a *model* object is an object composed by
 querying the SQL database. The ``models.py`` file is where the ``alchemy``
 scaffold put the classes that implement our models.
diff --git a/docs/tutorials/wiki2/src/basiclayout/development.ini b/docs/tutorials/wiki2/src/basiclayout/development.ini
index a9d53b296..99c4ff0fe 100644
--- a/docs/tutorials/wiki2/src/basiclayout/development.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/development.ini
@@ -27,7 +27,7 @@ sqlalchemy.url = sqlite:///%(here)s/tutorial.sqlite
 
 [server:main]
 use = egg:waitress#main
-host = 0.0.0.0
+host = 127.0.0.1
 port = 6543
 
 ###
@@ -68,4 +68,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/basiclayout/production.ini b/docs/tutorials/wiki2/src/basiclayout/production.ini
index fa94c1b3e..97acfbd7d 100644
--- a/docs/tutorials/wiki2/src/basiclayout/production.ini
+++ b/docs/tutorials/wiki2/src/basiclayout/production.ini
@@ -59,4 +59,4 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s
+format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s
diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
index 867049e4f..7994bbfa8 100644
--- a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
+++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py
@@ -1,20 +1,12 @@
 from pyramid.config import Configurator
-from sqlalchemy import engine_from_config
-
-from .models import (
-    DBSession,
-    Base,
-    )
 
 
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
-    engine = engine_from_config(settings, 'sqlalchemy.')
-    DBSession.configure(bind=engine)
-    Base.metadata.bind = engine
     config = Configurator(settings=settings)
-    config.include('pyramid_chameleon')
+    config.include('pyramid_jinja2')
+    config.include('.models.meta')
     config.add_static_view('static', 'static', cache_max_age=3600)
     config.add_route('home', '/')
     config.scan()
diff --git a/pyramid/scaffolds/alchemy/+package+/__init__.py b/pyramid/scaffolds/alchemy/+package+/__init__.py
index 867049e4f..7994bbfa8 100644
--- a/pyramid/scaffolds/alchemy/+package+/__init__.py
+++ b/pyramid/scaffolds/alchemy/+package+/__init__.py
@@ -1,20 +1,12 @@
 from pyramid.config import Configurator
-from sqlalchemy import engine_from_config
-
-from .models import (
-    DBSession,
-    Base,
-    )
 
 
 def main(global_config, **settings):
     """ This function returns a Pyramid WSGI application.
     """
-    engine = engine_from_config(settings, 'sqlalchemy.')
-    DBSession.configure(bind=engine)
-    Base.metadata.bind = engine
     config = Configurator(settings=settings)
-    config.include('pyramid_chameleon')
+    config.include('pyramid_jinja2')
+    config.include('.models.meta')
     config.add_static_view('static', 'static', cache_max_age=3600)
     config.add_route('home', '/')
     config.scan()
diff --git a/pyramid/scaffolds/alchemy/+package+/models.py b/pyramid/scaffolds/alchemy/+package+/models.py
deleted file mode 100644
index a0d3e7b71..000000000
--- a/pyramid/scaffolds/alchemy/+package+/models.py
+++ /dev/null
@@ -1,27 +0,0 @@
-from sqlalchemy import (
-    Column,
-    Index,
-    Integer,
-    Text,
-    )
-
-from sqlalchemy.ext.declarative import declarative_base
-
-from sqlalchemy.orm import (
-    scoped_session,
-    sessionmaker,
-    )
-
-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)
-    name = Column(Text)
-    value = Column(Integer)
-
-Index('my_index', MyModel.name, unique=True, mysql_length=255)
diff --git a/pyramid/scaffolds/alchemy/+package+/models/__init__.py b/pyramid/scaffolds/alchemy/+package+/models/__init__.py
new file mode 100644
index 000000000..6ffc10a78
--- /dev/null
+++ b/pyramid/scaffolds/alchemy/+package+/models/__init__.py
@@ -0,0 +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
+
+# run configure mappers to ensure we avoid any race conditions
+configure_mappers()
diff --git a/pyramid/scaffolds/alchemy/+package+/models/meta.py b/pyramid/scaffolds/alchemy/+package+/models/meta.py
new file mode 100644
index 000000000..b72b45f9f
--- /dev/null
+++ b/pyramid/scaffolds/alchemy/+package+/models/meta.py
@@ -0,0 +1,46 @@
+from sqlalchemy import engine_from_config
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.schema import MetaData
+import zope.sqlalchemy
+
+NAMING_CONVENTION = {
+    "ix": 'ix_%(column_0_label)s',
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s"
+}
+
+metadata = MetaData(naming_convention=NAMING_CONVENTION)
+Base = declarative_base(metadata=metadata)
+
+
+def includeme(config):
+    settings = config.get_settings()
+    dbmaker = get_dbmaker(get_engine(settings))
+
+    config.add_request_method(
+        lambda r: get_session(r.tm, dbmaker),
+        'dbsession',
+        reify=True
+    )
+
+    config.include('pyramid_tm')
+
+
+def get_session(transaction_manager, dbmaker):
+    dbsession = dbmaker()
+    zope.sqlalchemy.register(dbsession,
+                             transaction_manager=transaction_manager)
+    return dbsession
+
+
+def get_engine(settings, prefix='sqlalchemy.'):
+    return engine_from_config(settings, prefix)
+
+
+def get_dbmaker(engine):
+    dbmaker = sessionmaker()
+    dbmaker.configure(bind=engine)
+    return dbmaker
diff --git a/pyramid/scaffolds/alchemy/+package+/models/mymodel.py b/pyramid/scaffolds/alchemy/+package+/models/mymodel.py
new file mode 100644
index 000000000..5a2b5890c
--- /dev/null
+++ b/pyramid/scaffolds/alchemy/+package+/models/mymodel.py
@@ -0,0 +1,17 @@
+from .meta import Base
+from sqlalchemy import (
+    Column,
+    Index,
+    Integer,
+    Text,
+)
+
+
+class MyModel(Base):
+    __tablename__ = 'models'
+    id = Column(Integer, primary_key=True)
+    name = Column(Text)
+    value = Column(Integer)
+
+
+Index('my_index', MyModel.name, unique=True, mysql_length=255)
diff --git a/pyramid/scaffolds/alchemy/+package+/scripts/initializedb.py b/pyramid/scaffolds/alchemy/+package+/scripts/initializedb.py
index 7dfdece15..f0d09729e 100644
--- a/pyramid/scaffolds/alchemy/+package+/scripts/initializedb.py
+++ b/pyramid/scaffolds/alchemy/+package+/scripts/initializedb.py
@@ -2,8 +2,6 @@ import os
 import sys
 import transaction
 
-from sqlalchemy import engine_from_config
-
 from pyramid.paster import (
     get_appsettings,
     setup_logging,
@@ -11,11 +9,13 @@ from pyramid.paster import (
 
 from pyramid.scripts.common import parse_vars
 
-from ..models import (
-    DBSession,
-    MyModel,
+from ..models.meta import (
     Base,
+    get_session,
+    get_engine,
+    get_dbmaker,
     )
+from ..models.mymodel import MyModel
 
 
 def usage(argv):
@@ -32,9 +32,14 @@ def main(argv=sys.argv):
     options = parse_vars(argv[2:])
     setup_logging(config_uri)
     settings = get_appsettings(config_uri, options=options)
-    engine = engine_from_config(settings, 'sqlalchemy.')
-    DBSession.configure(bind=engine)
+
+    engine = get_engine(settings)
+    dbmaker = get_dbmaker(engine)
+
+    dbsession = get_session(transaction.manager, dbmaker)
+
     Base.metadata.create_all(engine)
+
     with transaction.manager:
         model = MyModel(name='one', value=1)
-        DBSession.add(model)
+        dbsession.add(model)
diff --git a/pyramid/scaffolds/alchemy/+package+/templates/mytemplate.pt_tmpl b/pyramid/scaffolds/alchemy/+package+/templates/layout.jinja2_tmpl
index 3f1d23d47..51e382654 100644
--- a/pyramid/scaffolds/alchemy/+package+/templates/mytemplate.pt_tmpl
+++ b/pyramid/scaffolds/alchemy/+package+/templates/layout.jinja2_tmpl
@@ -1,12 +1,12 @@
 <!DOCTYPE html>
-<html lang="${request.locale_name}">
+<html lang="\{\{request.locale_name\}\}">
   <head>
     <meta charset="utf-8">
     <meta http-equiv="X-UA-Compatible" content="IE=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="description" content="pyramid web application">
     <meta name="author" content="Pylons Project">
-    <link rel="shortcut icon" href="${request.static_url('{{package}}:static/pyramid-16x16.png')}">
+    <link rel="shortcut icon" href="\{\{request.static_url('{{package}}:static/pyramid-16x16.png')\}\}">
 
     <title>Alchemy Scaffold for The Pyramid Web Framework</title>
 
@@ -14,7 +14,7 @@
     <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet">
 
     <!-- Custom styles for this scaffold -->
-    <link href="${request.static_url('{{package}}:static/theme.css')}" rel="stylesheet">
+    <link href="\{\{request.static_url('{{package}}:static/theme.css')\}\}" rel="stylesheet">
 
     <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
     <!--[if lt IE 9]>
@@ -29,13 +29,12 @@
       <div class="container">
         <div class="row">
           <div class="col-md-2">
-            <img class="logo img-responsive" src="${request.static_url('{{package}}:static/pyramid.png')}" alt="pyramid web framework">
+            <img class="logo img-responsive" src="\{\{request.static_url('{{package}}:static/pyramid.png')\}\}" alt="pyramid web framework">
           </div>
           <div class="col-md-10">
-            <div class="content">
-              <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Alchemy scaffold</span></h1>
-              <p class="lead">Welcome to <span class="font-normal">${project}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework {{pyramid_version}}</span>.</p>
-            </div>
+            {% block content %}
+                <p>No content</p>
+            {% endblock content %}
           </div>
         </div>
         <div class="row">
diff --git a/pyramid/scaffolds/alchemy/+package+/templates/mytemplate.jinja2_tmpl b/pyramid/scaffolds/alchemy/+package+/templates/mytemplate.jinja2_tmpl
new file mode 100644
index 000000000..01fe5b8e3
--- /dev/null
+++ b/pyramid/scaffolds/alchemy/+package+/templates/mytemplate.jinja2_tmpl
@@ -0,0 +1,8 @@
+{% extends "layout.jinja2" %}
+
+{% block content %}
+<div class="content">
+  <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Alchemy scaffold</span></h1>
+  <p class="lead">Welcome to <span class="font-normal">\{\{project\}\}</span>, an&nbsp;application generated&nbsp;by<br>the <span class="font-normal">Pyramid Web Framework {{pyramid_version}}</span>.</p>
+</div>
+{% endblock content %}
diff --git a/pyramid/scaffolds/alchemy/+package+/tests.py_tmpl b/pyramid/scaffolds/alchemy/+package+/tests.py_tmpl
index e6425eb91..074c7a773 100644
--- a/pyramid/scaffolds/alchemy/+package+/tests.py_tmpl
+++ b/pyramid/scaffolds/alchemy/+package+/tests.py_tmpl
@@ -3,53 +3,63 @@ import transaction
 
 from pyramid import testing
 
-from .models import DBSession
 
+def dummy_request(dbsession):
+    return testing.DummyRequest(dbsession=dbsession)
 
-class TestMyViewSuccessCondition(unittest.TestCase):
+
+class BaseTest(unittest.TestCase):
     def setUp(self):
-        self.config = testing.setUp()
-        from sqlalchemy import create_engine
-        engine = create_engine('sqlite://')
-        from .models import (
-            Base,
-            MyModel,
+        self.config = testing.setUp(settings={
+            'sqlalchemy.url': 'sqlite:///:memory:'
+        })
+        self.config.include('.models.meta')
+        settings = self.config.get_settings()
+
+        from .models.meta import (
+            get_session,
+            get_engine,
+            get_dbmaker,
             )
-        DBSession.configure(bind=engine)
-        Base.metadata.create_all(engine)
-        with transaction.manager:
-            model = MyModel(name='one', value=55)
-            DBSession.add(model)
+
+        self.engine = get_engine(settings)
+        dbmaker = get_dbmaker(self.engine)
+
+        self.session = get_session(transaction.manager, dbmaker)
+
+    def init_database(self):
+        from .models.meta import Base
+        Base.metadata.create_all(self.engine)
 
     def tearDown(self):
-        DBSession.remove()
+        from .models.meta import Base
+
         testing.tearDown()
+        transaction.abort()
+        Base.metadata.create_all(self.engine)
+
+
+class TestMyViewSuccessCondition(BaseTest):
+
+    def setUp(self):
+        super(TestMyViewSuccessCondition, self).setUp()
+        self.init_database()
+
+        from .models.mymodel import MyModel
+
+        model = MyModel(name='one', value=55)
+        self.session.add(model)
 
     def test_passing_view(self):
-        from .views import my_view
-        request = testing.DummyRequest()
-        info = my_view(request)
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
         self.assertEqual(info['one'].name, 'one')
         self.assertEqual(info['project'], '{{project}}')
 
 
-class TestMyViewFailureCondition(unittest.TestCase):
-    def setUp(self):
-        self.config = testing.setUp()
-        from sqlalchemy import create_engine
-        engine = create_engine('sqlite://')
-        from .models import (
-            Base,
-            MyModel,
-            )
-        DBSession.configure(bind=engine)
-
-    def tearDown(self):
-        DBSession.remove()
-        testing.tearDown()
+class TestMyViewFailureCondition(BaseTest):
 
     def test_failing_view(self):
-        from .views import my_view
-        request = testing.DummyRequest()
-        info = my_view(request)
-        self.assertEqual(info.status_int, 500)
\ No newline at end of file
+        from .views.default import my_view
+        info = my_view(dummy_request(self.session))
+        self.assertEqual(info.status_int, 500)
diff --git a/pyramid/scaffolds/alchemy/+package+/views/__init__.py b/pyramid/scaffolds/alchemy/+package+/views/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/pyramid/scaffolds/alchemy/+package+/views/__init__.py
diff --git a/pyramid/scaffolds/alchemy/+package+/views.py_tmpl b/pyramid/scaffolds/alchemy/+package+/views/default.py_tmpl
index 292bce579..43fb33e05 100644
--- a/pyramid/scaffolds/alchemy/+package+/views.py_tmpl
+++ b/pyramid/scaffolds/alchemy/+package+/views/default.py_tmpl
@@ -3,22 +3,20 @@ from pyramid.view import view_config
 
 from sqlalchemy.exc import DBAPIError
 
-from .models import (
-    DBSession,
-    MyModel,
-    )
+from ..models.mymodel import MyModel
 
 
-@view_config(route_name='home', renderer='templates/mytemplate.pt')
+@view_config(route_name='home', renderer='../templates/mytemplate.jinja2')
 def my_view(request):
     try:
-        one = DBSession.query(MyModel).filter(MyModel.name == 'one').first()
+        query = request.dbsession.query(MyModel)
+        one = query.filter(MyModel.name == 'one').first()
     except DBAPIError:
-        return Response(conn_err_msg, content_type='text/plain', status_int=500)
+        return Response(db_err_msg, content_type='text/plain', status_int=500)
     return {'one': one, 'project': '{{project}}'}
 
 
-conn_err_msg = """\
+db_err_msg = """\
 Pyramid is having a problem using your SQL database.  The problem
 might be caused by one of the following things:
 
@@ -33,4 +31,3 @@ might be caused by one of the following things:
 After you fix the problem, please restart the Pyramid application to
 try it again.
 """
-
diff --git a/pyramid/scaffolds/alchemy/setup.py_tmpl b/pyramid/scaffolds/alchemy/setup.py_tmpl
index 9496b9948..af193a73d 100644
--- a/pyramid/scaffolds/alchemy/setup.py_tmpl
+++ b/pyramid/scaffolds/alchemy/setup.py_tmpl
@@ -10,7 +10,7 @@ with open(os.path.join(here, 'CHANGES.txt')) as f:
 
 requires = [
     'pyramid',
-    'pyramid_chameleon',
+    'pyramid_jinja2',
     'pyramid_debugtoolbar',
     'pyramid_tm',
     'SQLAlchemy',