Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 207 lines (162 sloc) 9.771 kb
e53e134 @mcdonc rename bfgwiki to wiki
mcdonc authored
1 ============
2 Basic Layout
3 ============
4
7584643 @jayd3e It was decided that pyramid would undergo a terminology change.
jayd3e authored
5 The starter files generated by the ``pyramid_zodb`` scaffold are basic, but
b743bb4 @mcdonc tutorial accuracy and wording improvements
mcdonc authored
6 they provide a good orientation for the high-level patterns common to most
7 :term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` based) projects.
e53e134 @mcdonc rename bfgwiki to wiki
mcdonc authored
8
9 The source code for this tutorial stage can be browsed via
f4ed956 @mcdonc use the right branch for github urls
mcdonc authored
10 `http://github.com/Pylons/pyramid/tree/1.1-branch/docs/tutorials/wiki/src/basiclayout/
11 <http://github.com/Pylons/pyramid/tree/1.1-branch/docs/tutorials/wiki/src/basiclayout/>`_.
e53e134 @mcdonc rename bfgwiki to wiki
mcdonc authored
12
b3b7132 @mcdonc - The ZODB Wiki tutorial was updated to take into account changes to the
mcdonc authored
13 App Startup with ``__init__.py``
14 --------------------------------
e53e134 @mcdonc rename bfgwiki to wiki
mcdonc authored
15
b3b7132 @mcdonc - The ZODB Wiki tutorial was updated to take into account changes to the
mcdonc authored
16 A directory on disk can be turned into a Python :term:`package` by containing
17 an ``__init__.py`` file. Even if empty, this marks a directory as a Python
18 package. Our application uses ``__init__.py`` as both a package marker, as
19 well as to contain application configuration code.
20
21 When you run the application using the ``paster`` command using the
22 ``development.ini`` generated config file, the application configuration
291995f @cmbeelby Corrected a/an usage and also clarified "deployment" to mean to a produc...
cmbeelby authored
23 points at a Setuptools *entry point* described as ``egg:tutorial``. In our
2a5ae03 @mcdonc - The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead,...
mcdonc authored
24 application, because the application's ``setup.py`` file says so, this entry
25 point happens to be the ``main`` function within the file named
b3b7132 @mcdonc - The ZODB Wiki tutorial was updated to take into account changes to the
mcdonc authored
26 ``__init__.py``:
27
28 .. literalinclude:: src/basiclayout/tutorial/__init__.py
29 :linenos:
30 :language: py
31
c44c409 @mcdonc fix wiki tutorial based on changes to zodb paster template
mcdonc authored
32 #. *Lines 1-3*. Perform some dependency imports.
b3b7132 @mcdonc - The ZODB Wiki tutorial was updated to take into account changes to the
mcdonc authored
33
c44c409 @mcdonc fix wiki tutorial based on changes to zodb paster template
mcdonc authored
34 #. *Line 8*. Get the ZODB configuration from the ``development.ini``
b3b7132 @mcdonc - The ZODB Wiki tutorial was updated to take into account changes to the
mcdonc authored
35 file's ``[app:main]`` section represented by the ``settings``
36 dictionary passed to our ``app`` function. This will be a URI
37 (something like ``file:///path/to/Data.fs``).
38
c44c409 @mcdonc fix wiki tutorial based on changes to zodb paster template
mcdonc authored
39 #. *Line 12*. We create a "finder" object using the
b3b7132 @mcdonc - The ZODB Wiki tutorial was updated to take into account changes to the
mcdonc authored
40 ``PersistentApplicationFinder`` helper class, passing it the ZODB
41 URI and the "appmaker" we've imported from ``models.py``.
42
c44c409 @mcdonc fix wiki tutorial based on changes to zodb paster template
mcdonc authored
43 #. *Lines 13 - 14*. We create a :term:`root factory` which uses the
b3b7132 @mcdonc - The ZODB Wiki tutorial was updated to take into account changes to the
mcdonc authored
44 finder to return a ZODB root object.
45
c44c409 @mcdonc fix wiki tutorial based on changes to zodb paster template
mcdonc authored
46 #. *Line 15*. We construct a :term:`Configurator` with a :term:`root
b3b7132 @mcdonc - The ZODB Wiki tutorial was updated to take into account changes to the
mcdonc authored
47 factory` and the settings keywords parsed by PasteDeploy. The root
48 factory is named ``get_root``.
49
2a5ae03 @mcdonc - The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead,...
mcdonc authored
50 #. *Line 16*. Register a 'static view' which answers requests which start
51 with with URL path ``/static`` using the
52 :meth:`pyramid.config.Configurator.add_static_view method`. This
53 statement registers a view that will serve up static assets, such as CSS
54 and image files, for us, in this case, at
55 ``http://localhost:6543/static/`` and below. The first argument is the
56 "name" ``static``, which indicates that the URL path prefix of the view
57 will be ``/static``. the The second argument of this tag is the "path",
58 which is an :term:`asset specification`, so it finds the resources it
59 should serve within the ``static`` directory inside the ``tutorial``
60 package.
61
62 #. *Line 17*. Perform a :term:`scan`. A scan will find :term:`configuration
63 decoration`, such as view configuration decorators
64 (e.g. ``@view_config``) in the source code of the ``tutorial`` package and
65 will take actions based on these decorators. The argument to
66 :meth:`~pyramid.config.Configurator.scan` is the package name to scan,
67 which is ``tutorial``.
68
69 #. *Line 18*. Use the
d7f2590 @mcdonc fix docs: pyramid.configuration -> pyramid.config
mcdonc authored
70 :meth:`pyramid.config.Configurator.make_wsgi_app` method
b3b7132 @mcdonc - The ZODB Wiki tutorial was updated to take into account changes to the
mcdonc authored
71 to return a :term:`WSGI` application.
e53e134 @mcdonc rename bfgwiki to wiki
mcdonc authored
72
2a5ae03 @mcdonc - The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead,...
mcdonc authored
73 Resources and Models with ``models.py``
74 ---------------------------------------
e53e134 @mcdonc rename bfgwiki to wiki
mcdonc authored
75
a5ffd62 @mcdonc model->resource; make docs render without warnings
mcdonc authored
76 :app:`Pyramid` uses the word :term:`resource` to describe objects arranged
77 hierarchically in a :term:`resource tree`. This tree is consulted by
78 :term:`traversal` to map URLs to code. In this application, the resource
79 tree represents the site structure, but it *also* represents the
b743bb4 @mcdonc tutorial accuracy and wording improvements
mcdonc authored
80 :term:`domain model` of the application, because each resource is a node
a5ffd62 @mcdonc model->resource; make docs render without warnings
mcdonc authored
81 stored persistently in a :term:`ZODB` database. The ``models.py`` file is
7584643 @jayd3e It was decided that pyramid would undergo a terminology change.
jayd3e authored
82 where the ``pyramid_zodb`` scaffold put the classes that implement our
b743bb4 @mcdonc tutorial accuracy and wording improvements
mcdonc authored
83 resource objects, each of which happens also to be a domain model object.
e53e134 @mcdonc rename bfgwiki to wiki
mcdonc authored
84
85 Here is the source for ``models.py``:
86
87 .. literalinclude:: src/basiclayout/tutorial/models.py
88 :linenos:
89 :language: py
90
2a5ae03 @mcdonc - The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead,...
mcdonc authored
91 #. *Lines 3-4*. The ``MyModel`` :term:`resource` class is implemented here.
92 Instances of this class will be capable of being persisted in :term:`ZODB`
93 because the class inherits from the
94 :class:`persistent.mapping.PersistentMapping` class. The ``__parent__``
95 and ``__name__`` are important parts of the :term:`traversal` protocol.
96 By default, have these as ``None`` indicating that this is the
97 :term:`root` object.
e53e134 @mcdonc rename bfgwiki to wiki
mcdonc authored
98
99 #. *Lines 6-12*. ``appmaker`` is used to return the *application
100 root* object. It is called on *every request* to the
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`pyra...
mcdonc authored
101 :app:`Pyramid` application. It also performs bootstrapping by
e53e134 @mcdonc rename bfgwiki to wiki
mcdonc authored
102 *creating* an application root (inside the ZODB root object) if one
103 does not already exist.
104
105 We do so by first seeing if the database has the persistent
106 application root. If not, we make an instance, store it, and
107 commit the transaction. We then return the application root
108 object.
109
2a5ae03 @mcdonc - The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead,...
mcdonc authored
110 Views With ``views.py``
111 -----------------------
112
7584643 @jayd3e It was decided that pyramid would undergo a terminology change.
jayd3e authored
113 Our scaffold generated a default ``views.py`` on our behalf. It
2a5ae03 @mcdonc - The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead,...
mcdonc authored
114 contains a single view, which is used to render the page shown when you visit
115 the URL ``http://localhost:6543/``.
116
117 Here is the source for ``views.py``:
118
119 .. literalinclude:: src/basiclayout/tutorial/views.py
120 :linenos:
121 :language: py
122
123 Let's try to understand the components in this module:
124
125 #. *Lines 1-2*. Perform some dependency imports.
126
127 #. *Line 4*. Use the :func:`pyramid.view.view_config` :term:`configuration
128 decoration` to perform a :term:`view configuration` registration. This
129 view configuration registration will be activated when the application is
130 started. It will be activated by virtue of it being found as the result
131 of a :term:`scan` (when Line 17 of ``__init__.py`` is run).
132
133 The ``@view_config`` decorator accepts a number of keyword arguments. We
134 use two keyword arguments here: ``context`` and ``renderer``.
135
136 The ``context`` argument signifies that the decorated view callable should
137 only be run when :term:`traversal` finds the ``tutorial.models.MyModel``
138 :term:`resource` to be the :term:`context` of a request. In English, this
139 means that when the URL ``/`` is visited, because ``MyModel`` is the root
140 model, this view callable will be invoked.
141
142 The ``renderer`` argument names an :term:`asset specification` of
143 ``tutorial:templates/mytemplate.pt``. This asset specification points at
144 a :term:`Chameleon` template which lives in the ``mytemplate.pt`` file
145 within the ``templates`` directory of the ``tutorial`` package. And
146 indeed if you look in the ``templates`` directory of this package, you'll
147 see a ``mytemplate.pt`` template file, which renders the default home page
148 of the generated project.
149
150 Since this call to ``@view_config`` doesn't pass a ``name`` argument, the
151 ``my_view`` function which it decorates represents the "default" view
152 callable used when the context is of the type ``MyModel``.
153
154 #. *Lines 5-6*. We define a :term:`view callable` named ``my_view``, which
155 we decorated in the step above. This view callable is a *function* we
7584643 @jayd3e It was decided that pyramid would undergo a terminology change.
jayd3e authored
156 write generated by the ``pyramid_zodb`` scaffold that is given a
2a5ae03 @mcdonc - The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead,...
mcdonc authored
157 ``request`` and which returns a dictionary. The ``mytemplate.pt``
158 :term:`renderer` named by the asset specification in the step above will
159 convert this dictionary to a :term:`response` on our behalf.
160
161 The function returns the dictionary ``{'project':'tutorial'}``. This
162 dictionary is used by the template named by the ``mytemplate.pt`` asset
163 specification to fill in certain values on the page.
164
165 The WSGI Pipeline in ``development.ini``
166 ----------------------------------------
167
168 The ``development.ini`` (in the tutorial :term:`project` directory, as
169 opposed to the tutorial :term:`package` directory) looks like this:
170
171 .. literalinclude:: src/views/development.ini
172 :language: ini
173
174
175 Note the existence of a ``[pipeline:main]`` section which specifies our WSGI
176 pipeline. This "pipeline" will be served up as our WSGI application. As far
177 as the WSGI server is concerned the pipeline *is* our application. Simpler
178 configurations don't use a pipeline: instead they expose a single WSGI
179 application as "main". Our setup is more complicated, so we use a pipeline
180 composed of :term:`middleware`.
181
182 The ``egg:WebError#evalerror`` middleware is at the "top" of the pipeline.
183 This is middleware which displays debuggable errors in the browser while
291995f @cmbeelby Corrected a/an usage and also clarified "deployment" to mean to a produc...
cmbeelby authored
184 you're developing (not recommended for a production system).
2a5ae03 @mcdonc - The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead,...
mcdonc authored
185
186 The ``egg:repoze.zodbconn#closer`` middleware is in the middle of the
187 pipeline. This is a piece of middleware which closes the ZODB connection
188 opened by the ``PersistentApplicationFinder`` at the end of the request.
189
9afa52f @mcdonc - Added ``egg:repoze.retry#retry`` middleware to the WSGI pipeline in ZO...
mcdonc authored
190 The ``egg:repoze.retry#retry`` middleware catches ``ConflictError``
191 exceptions from ZODB and retries the request up to three times (ZODB is an
192 optimistic concurrency database that relies on application-level transaction
193 retries when a conflict occurs).
194
607d756 @mcdonc - The ``pyramid_zodb``, ``pyramid_routesalchemy`` and ``pyramid_alchemy`...
mcdonc authored
195 The ``tm`` middleware is the last piece of middleware in the pipeline. This
196 commits a transaction near the end of the request unless there's an exception
197 raised or the HTTP response code is an error code. The ``tm`` refers to the
198 ``[filter:tm]`` section beneath the pipeline declaration, which configures
199 the transaction manager.
2a5ae03 @mcdonc - The ``pyramid_zodb`` Paster template no longer employs ZCML. Instead,...
mcdonc authored
200
201 The final line in the ``[pipeline:main]`` section is ``tutorial``, which
202 refers to the ``[app:tutorial]`` section above it. The ``[app:tutorial]``
203 section is the section which actually defines our application settings. The
204 values within this section are passed as ``**settings`` to the ``main``
205 function we defined in ``__init__.py`` when the server is started via
206 ``paster serve``.
Something went wrong with that request. Please try again.