diff options
Diffstat (limited to 'docs/tutorials/wiki2/basiclayout.rst')
| -rw-r--r-- | docs/tutorials/wiki2/basiclayout.rst | 155 |
1 files changed, 69 insertions, 86 deletions
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 63175138c..bd5a04ef5 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -11,53 +11,82 @@ The source code for this tutorial stage can be browsed at `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/basiclayout/ <http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/basiclayout/>`_. -``__init__.py`` ---------------- +App Startup with ``__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. +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. We use ``__init__.py`` both as a package marker and to contain +configuration code. -Configuration With ``configure.zcml`` --------------------------------------- - -:mod:`pyramid` 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: +When you run the application using the ``paster`` command using the +``development.ini`` generated config file, the application configuration +points at an Setuptools *entry point* described as ``egg:tutorial#app``. In +our application, because the application's ``setup.py`` file says so, this +entry point happens to be the ``app`` function within the file named +``__init__.py``: - .. literalinclude:: src/basiclayout/tutorial/configure.zcml + .. literalinclude:: src/basiclayout/tutorial/__init__.py :linenos: - :language: xml - -#. *Line 1*. The root ``<configure>`` element. - -#. *Lines 3-4*. Boilerplate, the comment explains. - -#. *Lines 6-11*. Register a ``<route>`` :term:`route configuration` - that will be used when the URL is ``/``. Since this ``<route>`` - has an empty ``pattern`` 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 - ``pyramid_routesalchemy`` template) that is given a ``request`` - object and which returns a response or a dictionary. You will use - mostly ``<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 - ``.views.my_view`` view returns a dictionary, a :term:`renderer` + :language: py + +#. *Lines 1-4*. Imports to support later code. + +#. *Lines 12-14*. Get the database configuration string from the + ``development.ini`` file's ``[app:sqlalchemy]`` section. This will be a + URI (something like ``sqlite://``). + +#. *Line 15*. Get the database echo setting from ``development.ini`` + file's ``[app:sqlalchemy]`` section. This will either be ``true`` + or ``false``. If ``true``, the application will print SQL to the + console as it is generated and run by SQLAlchemy. By default, it + is false. + +#. Line *16*. We initialize our SQL database using SQLAlchemy, passing + it the db string and a variant of the db_echo value. + +#. *Line 17*. 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 18*. We call :meth:`pyramid.configuration.Configurator.begin` which + tells the configuration machinery we are starting configuration. + +#. *Line 19*. We call + :meth:`pyramid.configuration.Configurator.add_static_view` with the + arguments ``static`` (the name), and ``tutorial:templates/static``. 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 + ``templates/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 20-21*. Register a :term:`route configuration` via the + :meth:`pyramid.configuration.Configurator.add_route` method that will be + used when the URL is ``/``. Since this route has an ``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.configuration.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. -#. *Lines 13-16*. Register a ``<static>`` directive that will match - any URL that starts with ``/static/``. This will serve up static - resources for us, in this case, at - ``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. +#. *Line 22*. We call :meth:`pyramid.configuration.Configurator.end` which + tells the configuration machinery we are ending configuration. -#. *Line 18*. The closing ``</configure>`` tag. +#. *Line 23*. We use the + :meth:`pyramid.configuration.Configurator.make_wsgi_app` method to return + a :term:`WSGI` application. Content Models with ``models.py`` --------------------------------- @@ -100,49 +129,3 @@ Here is the source for ``models.py``: object. It also calls the ``populate`` function, to do initial database population. -App Startup with ``run.py`` ---------------------------- - -When you run the application using the ``paster`` command using the -``tutorial.ini`` generated config file, the application configuration -points at an Setuptools *entry point* described as -``egg:tutorial#app``. In our application, because the application's -``setup.py`` file says so, this entry point happens to be the ``app`` -function within the file named ``run.py``: - - .. literalinclude:: src/basiclayout/tutorial/run.py - :linenos: - :language: py - -#. *Lines 1-3*. Imports to support later code. - -#. *Line 12*. Obtain the ``configure_zcml`` setting from a value in - the ``tutorial.ini`` file's ``[app:sqlalchemy]`` section. If it - doesn't exist in the configuration file, default to - ``configure.zcml``. - -#. *Lines 13-15*. Get the database configuration string from the - ``tutorial.ini`` file's ``[app:sqlalchemy]`` section. This will be a URI - (something like ``sqlite://``). - -#. *Line 16*. Get the database echo settingf rom ``tutorial.ini`` - file's ``[app:sqlalchemy]`` section. This will either be ``true`` - or ``false``. If ``true``, the application will print SQL to the - console as it is generated and run by SQLAlchemy. By default, it - is false. - -#. Line *17*. We initialize our SQL database using SQLAlchemy, passing - it the db string and a variant of the db_echo value. - -#. *Line 18*. 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. - -#. *Lines 19-22*. We then load a ZCML file to do application - configuration, and use the - :meth:`pyramid.configuration.Configurator.make_wsgi_app` method - to return a :term:`WSGI` application. - |