1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
============
Basic Layout
============
The starter files generated by the ``bfg_routesalchemy`` template are
basic, but they provide a good orientation for the high-level patterns
common to most :term:`url dispatch` -based :mod:`repoze.bfg` projects.
``__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.
Configuration With ``configure.zcml``
--------------------------------------
:mod:`repoze.bfg` uses a configuration markup language syntactically
the same as Zope's implementation of :term:`ZCML`, but using a
different default XML namespace. Our sample ZCML file looks like the
following:
.. literalinclude:: src/basiclayout/tutorial/configure.zcml
:linenos:
:language: xml
#. *Line 1*. The root ``<configure>`` element, in a ``bfg``
namespace.
#. *Line 3*. Boilerplate, the comment explains.
#. *Lines 6-7*. Register a :term:`subscriber` that tears down the
SQLAlchemy connection after a request is finished.
#. *Lines 9-12*. Register a ``<route>`` that will be used when the
URL is ``/``. Since this ``<route>`` has an empty ``path``
attribute, it is the "default" route. The attribute named ``view``
with the value ``.views.my_view`` is the dotted name to a
*function* we write (generated by the ``bfg_routesalchemy``
template) that is given a ``request`` object and which returns a
response. You will use mostly ``<route>`` statements in a
:term:`URL dispatch` based application to map URLs to code.
#. *Lines 14-17*. Register a ``<route>`` that will match with a path
that starts with ``/static/``. This points at a bit of code
(``.views.static_view``) that will serve up static resources for
us, in this case, at ``http://localhost:6543/static/`` and below.
The ``*subpath`` token captures the remainder of the path and sets
the request :term:`subpath` to a derivation of the remainder of the
path, which is relied on by the view it mentions. With this view
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.
Content Models with ``models.py``
---------------------------------
In a SQLAlchemy-based application, a *model* object is an object
composed by querying the SQL database which backs an application.
SQLAlchemy is an "object relational mapper" (an ORM). The
``models.py`` file is where the ``bfg_routesalchemy`` Paster template
put the classes that implement our models.
Here is the source for ``models.py``:
.. literalinclude:: src/basiclayout/tutorial/models.py
:linenos:
:language: py
#. *Lines 1-16*. Imports to support later code.
#. *Line 18*. 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.
#. *Line 20*. Set up a SQLAlchemy metadata object.
#. *Lines 22-24*. A model class named ``Model``. It has an
``__init__`` that takes a single argument (``name``). It stores a
single attribute named ``name``.
#. *Lines 26-31*. A SQLAlchemy ``Table`` declaration named
``models_table`` which we'll use later to map onto our ``Model``
class.
#. *Line 33*. We map our ``models_table`` table to our Models class
here. This makes an association between the ``Model`` class and
the ``models`` table in the database, as far as SQLAlchemy is
concerned.
#. *Lines 35-40*. A function named ``populate`` which adds a single
model instance into our SQL storage and commits a transaction.
#. *Lines 42-50*. A function named ``initialize_sql`` which sets up
an actual SQL database and binds it to our SQLAlchemy DBSession
object. It also calls the ``populate`` function, to do initial
database population.
App Startup with ``run.py``
---------------------------
How does a :mod:`repoze.bfg` application start up? When you run under
``paster`` using the ``tutorial.ini`` generated config file, the
application area points at an entry point. Our entry point happens to
be in ``run.py`` and its ``app`` function:
.. literalinclude:: src/basiclayout/tutorial/run.py
:linenos:
:language: py
#. *Lines 1-5*. Imports to support later code.
#. *Lines 7-11*. We define a ``Cleanup`` class which has a
``__del__`` method (the method called at Python object
destruction), which calls a function.
#. *Lines 13-15*. An event :term:`subscriber` which adds a
``Cleanup`` instance to the WSGI environment as
``tutorial.sasession``. As a result of registering this event
subscriber, when the WSGI environment is cleaned up, our database
connection will be removed.
#. *Lines 17-24*. Get the database configuration string from the
``tutorial.ini`` file's ``[app:sql]`` section. This will be a URI
(something like ``sqlite://``).
#. Line *25*. We initialize our SQL database using SQLAlchemy, passing
it the db string.
#. Line *26*. We use the ``repoze.bfg.router.make_app`` to return a
:term:`WSGI` application. The ``make_app`` function's first
parameter is the "root factory", which is used by the
:mod:`repoze.bfg` :term:`traversal` mechanism. Since this is a URL
dispatch application, the root factory is ``None``. The second
argument is the *package* representing our application, and the
third argument, ``options`` is passed as a keyword argument. It
contains a dictionary of options parsed by PasteDeploy.
|
