diff options
Diffstat (limited to 'docs/tutorials/wiki2/basiclayout.rst')
| -rw-r--r-- | docs/tutorials/wiki2/basiclayout.rst | 200 |
1 files changed, 133 insertions, 67 deletions
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 17dcfc48f..c73009eb0 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -23,58 +23,93 @@ The generated ``development.ini`` file is read by ``paster`` which looks for the application module in the ``use`` variable of the ``app:tutorial`` section. The *entry point* is defined in the Setuptools configuration of this module, specifically in the ``setup.py`` file. For this tutorial, the *entry -point* is defined as ``tutorial:main`` and points to the following ``main`` -function: +point* is defined as ``tutorial:main`` and points to a function named ``main``. + +First we need some imports to support later code: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :end-before: main + :linenos: + :language: py + +Next we define the main function and create a SQLAlchemy database +engine from the ``sqlalchemy.`` prefixed settings in the ``development.ini` +`file's ``[app:tutorial]`` section. This will be a URI (something like +``sqlite://``): .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 6-9 :linenos: :language: py -#. *Lines 1-4*. Imports to support later code. - -#. *Line 9*. Create a SQLAlchemy database engine from the ``sqlalchemy.`` - prefixed settings in the ``development.ini`` file's ``[app:tutorial]`` - section. This will be a URI (something like ``sqlite://``). - -#. *Line 10*. We initialize our SQL database using SQLAlchemy, passing - it the engine - -#. *Line 11*. We construct a :term:`Configurator`. ``settings`` is - passed as a keyword argument with the dictionary values passed by - PasteDeploy as the ``settings`` argument. This will be a - dictionary of settings parsed by PasteDeploy, which contains - deployment-related values such as ``reload_templates``, - ``db_string``, etc. - -#. *Line 12*. We call - :meth:`pyramid.config.Configurator.add_static_view` with the - arguments ``static`` (the name), and ``tutorial:static`` (the path). This - registers a static resource view which will match any URL that starts with - ``/static/``. This will serve up static resources for us from within the - ``static`` directory of our ``tutorial`` package, in this case, - via ``http://localhost:6543/static/`` and below. With this declaration, - we're saying that any URL that starts with ``/static`` should go to the - static view; any remainder of its path (e.g. the ``/foo`` in - ``/static/foo``) will be used to compose a path to a static file resource, - such as a CSS file. - -#. *Lines 13-14*. Register a :term:`route configuration` via the - :meth:`pyramid.config.Configurator.add_route` method that will be - used when the URL is ``/``. Since this route has a ``pattern`` equalling - ``/`` it is the "default" route. The argument named ``view`` with the - value ``tutorial.views.my_view`` is the dotted name to a *function* we - write (generated by the ``pyramid_routesalchemy`` template) that is given - a ``request`` object and which returns a response or a dictionary. You - will use :meth:`pyramid.config.Configurator.add_route` statements - in a :term:`URL dispatch` based application to map URLs to code. This - route also names a ``view_renderer``, which is a template which lives in - the ``templates`` subdirectory of the package. When the - ``tutorial.views.my_view`` view returns a dictionary, a :term:`renderer` - will use this template to create a response. - -#. *Line 15*. We use the - :meth:`pyramid.config.Configurator.make_wsgi_app` method to return - a :term:`WSGI` application. +We then initialize our SQL database using SQLAlchemy, passing +it the engine: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 10 + :language: py + +The next step is to construct a :term:`Configurator`: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 11 + :language: py + +``settings`` is passed as a keyword argument with the dictionary values +passed by PasteDeploy as the ``settings`` argument. This will be a +dictionary of settings parsed by PasteDeploy, which contains +deployment-related values such as ``reload_templates``, +``db_string``, etc. + +We now can call :meth:`pyramid.config.Configurator.add_static_view` with the +arguments ``static`` (the name), and ``tutorial:static`` (the path): + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 12 + :language: py + +This registers a static resource view which will match any URL that starts with +``/static/``. This will serve up static resources for us from within the +``static`` directory of our ``tutorial`` package, in this case, +via ``http://localhost:6543/static/`` and below. With this declaration, +we're saying that any URL that starts with ``/static`` should go to the +static view; any remainder of its path (e.g. the ``/foo`` in +``/static/foo``) will be used to compose a path to a static file resource, +such as a CSS file. + +Using the configurator we can also register a :term:`route configuration` +via the :meth:`pyramid.config.Configurator.add_route` method that will be +used when the URL is ``/``: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 13-14 + :language: py + +Since this route has a ``pattern`` equalling +``/`` it is the "default" route. The argument named ``view`` with the +value ``tutorial.views.my_view`` is the dotted name to a *function* we +write (generated by the ``pyramid_routesalchemy`` template) that is given +a ``request`` object and which returns a response or a dictionary. + +You will use :meth:`pyramid.config.Configurator.add_route` statements +in a :term:`URL dispatch` based application to map URLs to code. This +route also names a ``view_renderer``, which is a template which lives in +the ``templates`` subdirectory of the package. When the +``tutorial.views.my_view`` view returns a dictionary, a :term:`renderer` +will use this template to create a response. + +Fimnally, we use the :meth:`pyramid.config.Configurator.make_wsgi_app` +method to return a :term:`WSGI` application: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 15 + :language: py + +Our final __init__.py file will look like this: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :linenos: + :language: py Content Models with ``models.py`` --------------------------------- @@ -85,34 +120,65 @@ SQLAlchemy is an "object relational mapper" (an ORM). The ``models.py`` file is where the ``pyramid_routesalchemy`` Paster template put the classes that implement our models. -Here is the source for ``models.py``: +Let's take a look. First, we need some imports to support later code. .. literalinclude:: src/basiclayout/tutorial/models.py + :end-before: DBSession :linenos: :language: py -#. *Lines 1-13*. Imports to support later code. +Next we set up a SQLAlchemy "DBSession" object: + + .. literalinclude:: src/basiclayout/tutorial/models.py + :lines: 15-16 + :linenos: + :language: py -#. *Line 15*. We set up a SQLAlchemy "DBSession" object here. We - specify that we'd like to use the "ZopeTransactionExtension". This - extension is an extension which allows us to use a *transaction - manager* instead of controlling commits and aborts to database - operations by hand. +We also need to create a declarative ``Base`` object to use as a +base class for our model: -#. *Line 16*. We create a declarative ``Base`` object to use as a - base class for our model. + .. literalinclude:: src/basiclayout/tutorial/models.py + :lines: 17 + :language: py + +To give a simple example of a model class, we define one named ``MyModel``: + + .. literalinclude:: src/basiclayout/tutorial/models.py + :pyobject: MyModel + :linenos: + :language: py -#. *Lines 18-26*. A model class named ``MyModel``. It has an - ``__init__`` that takes a two arguments (``name``, and ``value``). - It stores these values as ``self.name`` and ``self.value`` within - the ``__init__`` function itself. The ``MyModel`` class also has a - ``__tablename__`` attribute. This informs SQLAlchemy which table - to use to store the data representing instances of this class. +Our sample model has an ``__init__`` that takes a two arguments +(``name``, and ``value``). +It stores these values as ``self.name`` and ``self.value`` within +the ``__init__`` function itself. The ``MyModel`` class also has a +``__tablename__`` attribute. This informs SQLAlchemy which table +to use to store the data representing instances of this class. -#. *Lines 28-33*. A function named ``populate`` which adds a single - model instance into our SQL storage and commits a transaction. +Next we define a function named ``populate`` which adds a single +model instance into our SQL storage and commits a transaction: -#. *Lines 35-42*. A function named ``initialize_sql`` which receives a SQL - database engine and binds it to our SQLAlchemy DBSession object. It also - calls the ``populate`` function, to do initial database population. + .. literalinclude:: src/basiclayout/tutorial/models.py + :pyobject: populate + :linenos: + :language: py + +The function doesn't do a lot in this case, but it's there to illustrate +how an application requiring many objects to be set up could work. + +Lastly we have a function named ``initialize_sql`` which receives a SQL +database engine and binds it to our SQLAlchemy DBSession object. It also +calls the ``populate`` function, to do initial database population. This +is the initialization function that is called from __init__.py above. + + .. literalinclude:: src/basiclayout/tutorial/models.py + :pyobject: initialize_sql + :linenos: + :language: py + +Here is the complete source for ``models.py``: + + .. literalinclude:: src/basiclayout/tutorial/models.py + :linenos: + :language: py |