adjust wiki2 tutorial for pyramid

1 files changed, 79 insertions, 0 deletions

diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
new file mode 100644
index 000000000..18d8363ad
--- /dev/null
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -0,0 +1,79 @@
+===============
+Defining Models
+===============
+
+The first change we'll make to our stock paster-generated application
+will be to define a :term:`model` constructor representing a wiki
+page.  We'll do this inside our ``models.py`` file.
+
+The source code for this tutorial stage can be browsed at
+`http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/models/
+<http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/models/>`_.
+
+Making Edits to ``models.py``
+-----------------------------
+
+.. note::
+
+  There is nothing automagically special about the filename
+  ``models.py``.  A project may have many models throughout its
+  codebase in arbitrarily-named files.  Files implementing models
+  often have ``model`` in their filenames (or they may live in a
+  Python subpackage of your application package named ``models``) ,
+  but this is only by convention.
+
+The first thing we want to do is remove the stock ``Model`` class from
+the generated ``models.py`` file.  The ``Model`` class is only a
+sample and we're not going to use it.
+
+Then, we'll add a ``Page`` class.  Because this is a SQLAlchemy
+application, this class should inherit from an instance of
+:class:`sqlalchemy.ext.declarative.declarative_base`.  Declarative
+SQLAlchemy models are easier to use than directly-mapped ones.  The
+code generated by our ``routesalchemy`` paster template does not use
+declarative SQLAlchemy syntax, so we'll need to change various things
+to begin to use declarative syntax.
+
+Our ``Page`` class will have a class level attribute ``__tablename__``
+which equals the string ``pages``.  This means that SQLAlchemy will
+store our wiki data in a SQL table named ``pages``.  Our Page class
+will also have class-level attributes named ``id``, ``pagename`` and
+``data`` (all instances of :class:`sqlalchemy.Column`).  These will
+map to columns in the ``pages`` table.  The ``id`` attribute will be
+the primary key in the table.  The ``name`` attribute will be a text
+attribute, each value of which needs to be unique within the column.
+The ``data`` attribute is a text attribute that will hold the body of
+each page.
+
+We'll also remove our ``populate`` function.  We'll inline the
+populate step into ``initialize_sql``, changing our ``initialize_sql``
+function to add a FrontPage object to our database at startup time.
+We're also going to use slightly different binding syntax.  It will
+will otherwise largely be the same as the ``initialize_sql`` in the
+paster-generated ``models.py``.
+
+Our DBSession assignment stays the same as the original generated
+``models.py``.
+
+Looking at the Result of Our Edits to ``models.py``
+---------------------------------------------------
+
+The result of all of our edits to ``models.py`` will end up looking
+something like this:
+
+.. literalinclude:: src/models/tutorial/models.py
+   :linenos:
+   :language: python
+
+Viewing the Application in a Browser
+------------------------------------
+
+We can't.  At this point, our system is in a "non-runnable" state;
+we'll need to change view-related files in the next chapter to be able
+to start the application successfully.  If you try to start the
+application, you'll wind up with a Python traceback on your console
+that ends with this exception:
+
+.. code-block:: text
+
+   ImportError: cannot import name MyModel