Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 132 lines (104 sloc) 6.074 kb
e267005 @mcdonc adjust wiki2 tutorial for pyramid
mcdonc authored
1 ============
2 Basic Layout
3 ============
4
5 The starter files generated by the ``pyramid_routesalchemy`` template
6 are basic, but they provide a good orientation for the high-level
7 patterns common to most :term:`url dispatch` -based :mod:`pyramid`
8 projects.
9
10 The source code for this tutorial stage can be browsed at
11 `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/basiclayout/
12 <http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/basiclayout/>`_.
13
b2adfe7 @mcdonc - The SQL Wiki tutorial was updated to take into account changes to the
mcdonc authored
14 App Startup with ``__init__.py``
15 --------------------------------
e267005 @mcdonc adjust wiki2 tutorial for pyramid
mcdonc authored
16
b2adfe7 @mcdonc - The SQL Wiki tutorial was updated to take into account changes to the
mcdonc authored
17 A directory on disk can be turned into a Python :term:`package` by containing
18 an ``__init__.py`` file. Even if empty, this marks a directory as a Python
19 package. We use ``__init__.py`` both as a package marker and to contain
20 configuration code.
e267005 @mcdonc adjust wiki2 tutorial for pyramid
mcdonc authored
21
b2adfe7 @mcdonc - The SQL Wiki tutorial was updated to take into account changes to the
mcdonc authored
22 When you run the application using the ``paster`` command using the
23 ``development.ini`` generated config file, the application configuration
24 points at an Setuptools *entry point* described as ``egg:tutorial#app``. In
25 our application, because the application's ``setup.py`` file says so, this
26 entry point happens to be the ``app`` function within the file named
27 ``__init__.py``:
e267005 @mcdonc adjust wiki2 tutorial for pyramid
mcdonc authored
28
b2adfe7 @mcdonc - The SQL Wiki tutorial was updated to take into account changes to the
mcdonc authored
29 .. literalinclude:: src/basiclayout/tutorial/__init__.py
e267005 @mcdonc adjust wiki2 tutorial for pyramid
mcdonc authored
30 :linenos:
b2adfe7 @mcdonc - The SQL Wiki tutorial was updated to take into account changes to the
mcdonc authored
31 :language: py
32
33 #. *Lines 1-4*. Imports to support later code.
34
35 #. *Lines 12-14*. Get the database configuration string from the
36 ``development.ini`` file's ``[app:sqlalchemy]`` section. This will be a
37 URI (something like ``sqlite://``).
38
39 #. *Line 15*. Get the database echo setting from ``development.ini``
40 file's ``[app:sqlalchemy]`` section. This will either be ``true``
41 or ``false``. If ``true``, the application will print SQL to the
42 console as it is generated and run by SQLAlchemy. By default, it
43 is false.
44
45 #. Line *16*. We initialize our SQL database using SQLAlchemy, passing
46 it the db string and a variant of the db_echo value.
47
48 #. *Line 17*. We construct a :term:`Configurator`. ``settings`` is
49 passed as a keyword argument with the dictionary values passed by
50 PasteDeploy as the ``settings`` argument. This will be a
51 dictionary of settings parsed by PasteDeploy, which contains
52 deployment-related values such as ``reload_templates``,
53 ``db_string``, etc.
54
55 #. *Line 18*. We call :meth:`pyramid.configuration.Configurator.begin` which
56 tells the configuration machinery we are starting configuration.
57
58 #. *Line 19*. We call
59 :meth:`pyramid.configuration.Configurator.add_static_view` with the
60 arguments ``static`` (the name), and ``tutorial:templates/static``. This
61 registers a static resource view which will match any URL that starts with
62 ``/static/``. This will serve up static resources for us from within the
63 ``templates/static`` directory of our ``tutorial`` package, in this case,
64 via ``http://localhost:6543/static/`` and below. With this declaration,
65 we're saying that any URL that starts with ``/static`` should go to the
66 static view; any remainder of its path (e.g. the ``/foo`` in
67 ``/static/foo``) will be used to compose a path to a static file resource,
68 such as a CSS file.
69
70 #. *Lines 20-21*. Register a :term:`route configuration` via the
71 :meth:`pyramid.configuration.Configurator.add_route` method that will be
72 used when the URL is ``/``. Since this route has an ``pattern`` equalling
73 ``/`` it is the "default" route. The argument named ``view`` with the
74 value ``tutorial.views.my_view`` is the dotted name to a *function* we
75 write (generated by the ``pyramid_routesalchemy`` template) that is given
76 a ``request`` object and which returns a response or a dictionary. You
77 will use :meth:`pyramid.configuration.Configurator.add_route` statements
78 in a :term:`URL dispatch` based application to map URLs to code. This
79 route also names a ``view_renderer``, which is a template which lives in
80 the ``templates`` subdirectory of the package. When the
81 ``tutorial.views.my_view`` view returns a dictionary, a :term:`renderer`
e267005 @mcdonc adjust wiki2 tutorial for pyramid
mcdonc authored
82 will use this template to create a response.
83
b2adfe7 @mcdonc - The SQL Wiki tutorial was updated to take into account changes to the
mcdonc authored
84 #. *Line 22*. We call :meth:`pyramid.configuration.Configurator.end` which
85 tells the configuration machinery we are ending configuration.
e267005 @mcdonc adjust wiki2 tutorial for pyramid
mcdonc authored
86
b2adfe7 @mcdonc - The SQL Wiki tutorial was updated to take into account changes to the
mcdonc authored
87 #. *Line 23*. We use the
88 :meth:`pyramid.configuration.Configurator.make_wsgi_app` method to return
89 a :term:`WSGI` application.
e267005 @mcdonc adjust wiki2 tutorial for pyramid
mcdonc authored
90
91 Content Models with ``models.py``
92 ---------------------------------
93
94 In a SQLAlchemy-based application, a *model* object is an object
95 composed by querying the SQL database which backs an application.
96 SQLAlchemy is an "object relational mapper" (an ORM). The
97 ``models.py`` file is where the ``pyramid_routesalchemy`` Paster
98 template put the classes that implement our models.
99
100 Here is the source for ``models.py``:
101
102 .. literalinclude:: src/basiclayout/tutorial/models.py
103 :linenos:
104 :language: py
105
106 #. *Lines 1-14*. Imports to support later code.
107
108 #. *Line 16*. We set up a SQLAlchemy "DBSession" object here. We
109 specify that we'd like to use the "ZopeTransactionExtension". This
110 extension is an extension which allows us to use a *transaction
111 manager* instead of controlling commits and aborts to database
112 operations by hand.
113
114 #. *Line 17*. We create a declarative ``Base`` object to use as a
115 base class for our model.
116
117 #. *Lines 19-27*. A model class named ``MyModel``. It has an
118 ``__init__`` that takes a two arguments (``name``, and ``value``).
119 It stores these values as ``self.name`` and ``self.value`` within
120 the ``__init__`` function itself. The ``MyModel`` class also has a
121 ``__tablename__`` attribute. This informs SQLAlchemy which table
122 to use to store the data representing instances of this class.
123
124 #. *Lines 29-34*. A function named ``populate`` which adds a single
125 model instance into our SQL storage and commits a transaction.
126
127 #. *Lines 36-44*. A function named ``initialize_sql`` which sets up
128 an actual SQL database and binds it to our SQLAlchemy DBSession
129 object. It also calls the ``populate`` function, to do initial
130 database population.
131
Something went wrong with that request. Please try again.