From 875ded31e7fdd0c85d1c91458248581b9dd729d7 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sat, 30 Jul 2011 01:50:24 -0600 Subject: Updated all of the docs to reflect the new pyramid.* settings prefix. --- docs/tutorials/wiki2/basiclayout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 6151e0e25..0fd64fde4 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -57,7 +57,7 @@ The next step is to construct a :term:`Configurator`: ``settings`` is passed to the Configurator as a keyword argument with the dictionary values passed by PasteDeploy as the ``**settings`` argument. This will be a dictionary of settings parsed from the ``.ini`` file, which -contains deployment-related values such as ``reload_templates``, +contains deployment-related values such as ``pyramid.reload_templates``, ``db_string``, etc. We now can call :meth:`pyramid.config.Configurator.add_static_view` with the -- cgit v1.2.3 From 3d338ea5737b7c113b17120b40684e2694cf3fa9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 22 Aug 2011 02:16:55 -0400 Subject: - Use [app:main] instead of a pipeline in all scaffolds and tutorials and narrative docs. - Break out awkward description of PasteDeploy entry points from project chapter into its own Paste chapter. --- docs/tutorials/wiki2/basiclayout.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 0fd64fde4..2d25ace00 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -19,10 +19,11 @@ package. We use ``__init__.py`` both as a package marker and to contain configuration code. The generated ``development.ini`` file is read by ``paster`` which looks for -the application module in the ``use`` variable of the ``app:tutorial`` +the application module in the ``use`` variable of the ``app:main`` 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 a function named ``main``. +point* is defined as ``tutorial:main`` and points to a function named +``main``. First we need some imports to support later code: @@ -33,7 +34,7 @@ First we need some imports to support later code: 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 +``[app:main]`` section. This will be a URI (something like ``sqlite://``): .. literalinclude:: src/basiclayout/tutorial/__init__.py -- cgit v1.2.3 From cfb2b5596b8ef366aeef3bce5b61eafc7a2f175d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 6 Oct 2011 03:05:29 -0400 Subject: remove all reference to the paster command-line utility --- docs/tutorials/wiki2/basiclayout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 2d25ace00..8dc886373 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -18,7 +18,7 @@ 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. -The generated ``development.ini`` file is read by ``paster`` which looks for +The generated ``development.ini`` file is read by ``pserve`` which looks for the application module in the ``use`` variable of the ``app:main`` section. The *entry point* is defined in the Setuptools configuration of this module, specifically in the ``setup.py`` file. For this tutorial, the *entry -- cgit v1.2.3 From 8092b61b4704bc3a374f5c15e6e626612d9eb504 Mon Sep 17 00:00:00 2001 From: Chris Shenton Date: Mon, 7 Nov 2011 17:57:57 -0800 Subject: Remove 'pyramid_' from scaffolding name used for pcreate now. --- docs/tutorials/wiki2/basiclayout.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 8dc886373..acd2f04f3 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -2,7 +2,7 @@ Basic Layout ============ -The starter files generated by the ``pyramid_routesalchemy`` scaffold are +The starter files generated by the ``routesalchemy`` scaffold are basic, but they provide a good orientation for the high-level patterns common to most :term:`url dispatch` -based :app:`Pyramid` projects. @@ -98,7 +98,7 @@ register views for the routes, mapping your patterns to code: The first positional ``add_view`` argument ``tutorial.views.my_view`` is the dotted name to a *function* we write (generated by the -``pyramid_routesalchemy`` scaffold) that is given a ``request`` object and +``routesalchemy`` scaffold) that is given a ``request`` object and which returns a response or a dictionary. This view also names a ``renderer``, which is a template which lives in the ``templates`` subdirectory of the package. When the ``tutorial.views.my_view`` view @@ -124,7 +124,7 @@ 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 ``pyramid_routesalchemy`` scaffold +``models.py`` file is where the ``routesalchemy`` scaffold put the classes that implement our models. Let's take a look. First, we need some imports to support later code. -- cgit v1.2.3 From 818f8cab1dff781bbacf94cbabb4bec3825e081e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 12 Nov 2011 20:41:29 -0500 Subject: - The ``alchemy`` scaffold has been removed. - The ``routesalchemy`` scaffold has been renamed ``alchemy``. --- docs/tutorials/wiki2/basiclayout.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index acd2f04f3..db8ab1fbe 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -2,7 +2,7 @@ Basic Layout ============ -The starter files generated by the ``routesalchemy`` scaffold are +The starter files generated by the ``alchemy`` scaffold are basic, but they provide a good orientation for the high-level patterns common to most :term:`url dispatch` -based :app:`Pyramid` projects. @@ -98,7 +98,7 @@ register views for the routes, mapping your patterns to code: The first positional ``add_view`` argument ``tutorial.views.my_view`` is the dotted name to a *function* we write (generated by the -``routesalchemy`` scaffold) that is given a ``request`` object and +``alchemy`` scaffold) that is given a ``request`` object and which returns a response or a dictionary. This view also names a ``renderer``, which is a template which lives in the ``templates`` subdirectory of the package. When the ``tutorial.views.my_view`` view @@ -124,7 +124,7 @@ 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 ``routesalchemy`` scaffold +``models.py`` file is where the ``alchemy`` scaffold put the classes that implement our models. Let's take a look. First, we need some imports to support later code. -- cgit v1.2.3 From 6772a25160b0c996ae6e7baa012199b606407db4 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 26 Nov 2011 14:56:29 -0500 Subject: output warning to use populate command to console after alchemy scaffold rendering; emit logging statements when populate is run --- docs/tutorials/wiki2/basiclayout.rst | 159 ++++++++++++++++++++++------------- 1 file changed, 100 insertions(+), 59 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index db8ab1fbe..dc5664c5b 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -2,82 +2,96 @@ Basic Layout ============ -The starter files generated by the ``alchemy`` scaffold are -basic, but they provide a good orientation for the high-level patterns common -to most :term:`url dispatch` -based :app:`Pyramid` projects. +The starter files generated by the ``alchemy`` scaffold are very basic, but +they provide a good orientation for the high-level patterns common to most +:term:`url dispatch` -based :app:`Pyramid` projects. The source code for this tutorial stage can be browsed at `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/basiclayout/ `_. -App Startup with ``__init__.py`` --------------------------------- +Application Configuration 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. We use ``__init__.py`` both as a package marker and to contain -configuration code. +package. We use ``__init__.py`` both as a marker indicating the directory +it's contained within is a package, and to contain configuration code. Our +``__init__.py`` file will look like this: -The generated ``development.ini`` file is read by ``pserve`` which looks for -the application module in the ``use`` variable of the ``app:main`` -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 a function named -``main``. + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :linenos: + :language: py -First we need some imports to support later code: +Let's go over this piece-by-piece. 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:main]`` section. This will be a URI (something like -``sqlite://``): +``__init__.py`` defines a function named ``main``. Here is the entirety of +the ``main`` function we've defined in our ``__init__.py``: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :pyobject: main + :linenos: + :language: py + +When you invoke the ``pserve development.ini`` command, the ``main`` function +above is executed. It accepts some settings and returns a :term:`WSGI` +application. You can read :ref:`startup_chapter` for details about *how* +this function is found and called when you run ``pserve``, but for purposes +of brevity, we'll elide the details here. + +The main function first creates a SQLAlchemy database engine using +``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the +``development.ini`` file's ``[app:main]`` section. This will be a URI +(something like ``sqlite://``): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 6-9 + :lines: 9 :linenos: :language: py -We then initialize our SQL database using SQLAlchemy, passing -it the engine: +``main`` then initializes 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`: +The next step of ``main`` is to construct a :term:`Configurator` object: .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 11 :language: py ``settings`` is passed to the Configurator as a keyword argument with the -dictionary values passed by PasteDeploy as the ``**settings`` argument. This -will be a dictionary of settings parsed from the ``.ini`` file, which -contains deployment-related values such as ``pyramid.reload_templates``, +dictionary values passed as the ``**settings`` argument. This will be a +dictionary of settings parsed from the ``.ini`` file, which contains +deployment-related values such as ``pyramid.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): +``'main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with +two arguments: ``static`` (the name), and ``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. +This registers a static resource view which will match any URL that starts +with the prefix ``/static`` (by virtue of the first argument to add_static +view). 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 (by virtue of the second argument +to add_static_view). 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` +Using the configurator ``main`` also registers a :term:`route configuration` via the :meth:`pyramid.config.Configurator.add_route` method that will be used when the URL is ``/``: @@ -88,44 +102,71 @@ used when the URL is ``/``: Since this route has a ``pattern`` equalling ``/`` it is the route that will be matched when the URL ``/`` is visted, e.g. ``http://localhost:6543/``. -Mapping the ``home`` route to code is done by registering a view. You will -use :meth:`pyramid.config.Configurator.add_view` in :term:`URL dispatch` to -register views for the routes, mapping your patterns to code: +``main`` next calls the ``scan`` method of the configurator, which will +recursively scan our ``tutorial`` package, looking for ``@view_config`` (and +other special) decorators. When it finds a ``@view_config`` decorator, a +view configuration will be registered, which will allow one of our +application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 14-15 + :lines: 14 :language: py -The first positional ``add_view`` argument ``tutorial.views.my_view`` is the -dotted name to a *function* we write (generated by the -``alchemy`` scaffold) that is given a ``request`` object and -which returns a response or a dictionary. This view also names a -``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. - -Finally, we use the :meth:`pyramid.config.Configurator.make_wsgi_app` -method to return a :term:`WSGI` application: +Finally, ``main`` is finished configuring things, so it uses the +:meth:`pyramid.config.Configurator.make_wsgi_app` method to return a +:term:`WSGI` application: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 16 + :lines: 15 :language: py -Our final ``__init__.py`` file will look like this: +View Declarations via ``views.py`` +---------------------------------- - .. literalinclude:: src/basiclayout/tutorial/__init__.py +Mapping a :term:`route` to code that will be executed when that route's +pattern matches is done by registering a :term:`view configuration`. Our +application uses the :meth:`pyramid.view.view_config` decorator to map view +callables to each route, thereby mapping URL patterns to code. + +Here is the code in the ``views.py`` file within our package: + + .. literalinclude:: src/basiclayout/tutorial/views.py :linenos: :language: py +The important part to point out here is the ``@view_config`` decorator. In +fact, ``@view_config`` is so important that we're going to ignore the rest of +the code in the module at this point just to explain it. The +``@view_config`` decorator associates the function it decorates with a +:term:`view configuration`. The view configuration names a ``route_name`` +(``home``), and names a ``renderer``, which is a template which lives in the +``templates`` subdirectory of the package. + +As the result of this view configuration, when the pattern associated with +the view named ``home`` is matched during a request, the function named +``my_view`` will be executed. The the function named ``my_view`` returns a +dictionary; the renderer will use the ``templates/mytemplate.pt`` template to +create a response based on the values in the dictionary. + +Note that the decorated function named ``my_view`` accepts a single argument +named ``request``. This is the standard call signature for a Pyramid +:term:`view callable`. + +Remember in our ``__init__.py`` when we executed the +:meth:`pyramid.config.Configurator.scan` method, e.g. ``config.scan()``? The +purpose of calling the scan method was to find and process this +``@view_config`` decorator in order to create a view configuration within our +application. Without being processed by ``scan``, the decorator effectively +does nothing. ``@view_config`` is inert without being detected via a +:term:`scan`. + 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 ``alchemy`` scaffold -put the classes that implement our models. +In a SQLAlchemy-based application, a *model* object is an object composed by +querying the SQL database. SQLAlchemy is an "object relational mapper" (an +ORM). The ``models.py`` file is where the ``alchemy`` scaffold put the +classes that implement our models. Let's take a look. First, we need some imports to support later code. -- cgit v1.2.3 From 5edd54f05b05330fa6e899a1bb1650cc7a2df33c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 27 Nov 2011 04:08:20 -0500 Subject: - The SQLAlchemy Wiki tutorial has been updated. It now uses ``@view_config`` decorators and an explicit database population script. Closes #359. --- docs/tutorials/wiki2/basiclayout.rst | 58 +++++++++++++----------------------- 1 file changed, 20 insertions(+), 38 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index dc5664c5b..77658970d 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -128,19 +128,20 @@ pattern matches is done by registering a :term:`view configuration`. Our application uses the :meth:`pyramid.view.view_config` decorator to map view callables to each route, thereby mapping URL patterns to code. -Here is the code in the ``views.py`` file within our package: +Here is the entirety of code in the ``views.py`` file within our package: .. literalinclude:: src/basiclayout/tutorial/views.py :linenos: :language: py -The important part to point out here is the ``@view_config`` decorator. In -fact, ``@view_config`` is so important that we're going to ignore the rest of -the code in the module at this point just to explain it. The -``@view_config`` decorator associates the function it decorates with a -:term:`view configuration`. The view configuration names a ``route_name`` -(``home``), and names a ``renderer``, which is a template which lives in the -``templates`` subdirectory of the package. +The important part to point out here is the ``@view_config`` decorator which +sits atop the ``my_view`` function. In fact, ``@view_config`` is so +important that we're going to ignore the rest of the code in the module at +this point just to explain it. The ``@view_config`` decorator associates the +function it decorates with a :term:`view configuration`. The view +configuration names a ``route_name`` (``home``), and names a ``renderer``, +which is a template which lives in the ``templates`` subdirectory of the +package. As the result of this view configuration, when the pattern associated with the view named ``home`` is matched during a request, the function named @@ -164,9 +165,14 @@ Content Models with ``models.py`` --------------------------------- In a SQLAlchemy-based application, a *model* object is an object composed by -querying the SQL database. SQLAlchemy is an "object relational mapper" (an -ORM). The ``models.py`` file is where the ``alchemy`` scaffold put the -classes that implement our models. +querying the SQL database. The ``models.py`` file is where the ``alchemy`` +scaffold put the classes that implement our models. + +Here is the complete source for ``models.py``: + + .. literalinclude:: src/basiclayout/tutorial/models.py + :linenos: + :language: py Let's take a look. First, we need some imports to support later code. @@ -178,7 +184,7 @@ Let's take a look. First, we need some imports to support later code. Next we set up a SQLAlchemy "DBSession" object: .. literalinclude:: src/basiclayout/tutorial/models.py - :lines: 15-16 + :lines: 16 :linenos: :language: py @@ -202,30 +208,6 @@ 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. -Next we define a function named ``populate`` which adds a single -model instance into our SQL storage and commits a transaction: - - .. 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 +That's about all there is to it to models, views, and initialization code in +our stock application. -- cgit v1.2.3 From 8794d59fea64095bdaf15968051c6d62efca79dc Mon Sep 17 00:00:00 2001 From: Mathieu Larose Date: Wed, 4 Jan 2012 15:03:58 -0500 Subject: Removed repetition of the word "the" in the Wiki Tutorial. --- docs/tutorials/wiki2/basiclayout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 77658970d..e4200ae0f 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -145,7 +145,7 @@ package. As the result of this view configuration, when the pattern associated with the view named ``home`` is matched during a request, the function named -``my_view`` will be executed. The the function named ``my_view`` returns a +``my_view`` will be executed. The function named ``my_view`` returns a dictionary; the renderer will use the ``templates/mytemplate.pt`` template to create a response based on the values in the dictionary. -- cgit v1.2.3 From e2919c4916c9dba5c6bfce14035b2a4a5333c0fd Mon Sep 17 00:00:00 2001 From: Audrey Roy Date: Mon, 12 Mar 2012 15:57:45 -0700 Subject: More concise views.py section. --- docs/tutorials/wiki2/basiclayout.rst | 37 ++++++++++++++++-------------------- 1 file changed, 16 insertions(+), 21 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index e4200ae0f..29e272081 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -41,9 +41,7 @@ the ``main`` function we've defined in our ``__init__.py``: When you invoke the ``pserve development.ini`` command, the ``main`` function above is executed. It accepts some settings and returns a :term:`WSGI` -application. You can read :ref:`startup_chapter` for details about *how* -this function is found and called when you run ``pserve``, but for purposes -of brevity, we'll elide the details here. +application. (See :ref:`startup_chapter` for more about ``pserve``.) The main function first creates a SQLAlchemy database engine using ``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the @@ -134,24 +132,21 @@ Here is the entirety of code in the ``views.py`` file within our package: :linenos: :language: py -The important part to point out here is the ``@view_config`` decorator which -sits atop the ``my_view`` function. In fact, ``@view_config`` is so -important that we're going to ignore the rest of the code in the module at -this point just to explain it. The ``@view_config`` decorator associates the -function it decorates with a :term:`view configuration`. The view -configuration names a ``route_name`` (``home``), and names a ``renderer``, -which is a template which lives in the ``templates`` subdirectory of the -package. - -As the result of this view configuration, when the pattern associated with -the view named ``home`` is matched during a request, the function named -``my_view`` will be executed. The function named ``my_view`` returns a -dictionary; the renderer will use the ``templates/mytemplate.pt`` template to -create a response based on the values in the dictionary. - -Note that the decorated function named ``my_view`` accepts a single argument -named ``request``. This is the standard call signature for a Pyramid -:term:`view callable`. +The important part here is that the ``@view_config`` decorator associates the +function it decorates (``my_view``) with a :term:`view configuration`, +consisting of: + + * a ``route_name`` (``home``) + * a ``renderer``, which is a template from the ``templates`` subdirectory + of the package. + +When the pattern associated with the ``home`` view is matched during a request, +``my_view()`` will be executed. ``my_view()`` returns a dictionary; the +renderer will use the ``templates/mytemplate.pt`` template to create a response +based on the values in the dictionary. + +Note that ``my_view()`` accepts a single argument named ``request``. This is +the standard call signature for a Pyramid :term:`view callable`. Remember in our ``__init__.py`` when we executed the :meth:`pyramid.config.Configurator.scan` method, e.g. ``config.scan()``? The -- cgit v1.2.3 From 197808638a50dc085efc7511e24c043274e35663 Mon Sep 17 00:00:00 2001 From: Audrey Roy Date: Mon, 12 Mar 2012 17:02:46 -0700 Subject: Clarified which files to open/edit. Highlighted the lines to be edited in models.py. --- docs/tutorials/wiki2/basiclayout.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 29e272081..888ae0bf3 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -16,8 +16,10 @@ Application Configuration 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. We use ``__init__.py`` both as a marker indicating the directory -it's contained within is a package, and to contain configuration code. Our -``__init__.py`` file will look like this: +it's contained within is a package, and to contain configuration code. + +Open the ``tutorial/tutorial/__init__.py`` file. It should already contain +the following: .. literalinclude:: src/basiclayout/tutorial/__init__.py :linenos: -- cgit v1.2.3 From d0f5c6885d584493c451d776867d44585c89ec02 Mon Sep 17 00:00:00 2001 From: Audrey Roy Date: Mon, 12 Mar 2012 17:21:08 -0700 Subject: More clarification, telling the user to open specified files. --- docs/tutorials/wiki2/basiclayout.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 888ae0bf3..0fca0edf9 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -18,7 +18,7 @@ an ``__init__.py`` file. Even if empty, this marks a directory as a Python package. We use ``__init__.py`` both as a marker indicating the directory it's contained within is a package, and to contain configuration code. -Open the ``tutorial/tutorial/__init__.py`` file. It should already contain +Open ``tutorial/tutorial/__init__.py``. It should already contain the following: .. literalinclude:: src/basiclayout/tutorial/__init__.py @@ -128,7 +128,7 @@ pattern matches is done by registering a :term:`view configuration`. Our application uses the :meth:`pyramid.view.view_config` decorator to map view callables to each route, thereby mapping URL patterns to code. -Here is the entirety of code in the ``views.py`` file within our package: +Open ``tutorial/tutorial/views.py``. It should already contain the following: .. literalinclude:: src/basiclayout/tutorial/views.py :linenos: @@ -165,13 +165,13 @@ In a SQLAlchemy-based application, a *model* object is an object composed by querying the SQL database. The ``models.py`` file is where the ``alchemy`` scaffold put the classes that implement our models. -Here is the complete source for ``models.py``: +Open ``tutorial/tutorial/models.py``. It should already contain the following: .. literalinclude:: src/basiclayout/tutorial/models.py :linenos: :language: py -Let's take a look. First, we need some imports to support later code. +Let's examine this in detail. First, we need some imports to support later code: .. literalinclude:: src/basiclayout/tutorial/models.py :end-before: DBSession -- cgit v1.2.3 From 692fd6816616ed5b3cb9ef3c0f2c6eff2276da93 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 17 Mar 2012 00:05:06 -0400 Subject: master->1.3-branch --- docs/tutorials/wiki2/basiclayout.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 0fca0edf9..39321a88e 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -7,8 +7,8 @@ they provide a good orientation for the high-level patterns common to most :term:`url dispatch` -based :app:`Pyramid` projects. 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/1.3-branch/docs/tutorials/wiki2/src/basiclayout/ +`_. Application Configuration with ``__init__.py`` ---------------------------------------------- -- cgit v1.2.3 From b3e608bac815a7d3fc639d78ec38edc5f97df859 Mon Sep 17 00:00:00 2001 From: Doug Latornell Date: Sat, 17 Mar 2012 09:27:13 -0700 Subject: Improve text of SQLAlchemy wiki tutorial. A mixture of typo fixes and wording improvements. --- docs/tutorials/wiki2/basiclayout.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 0fca0edf9..a5e900e4c 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -74,7 +74,7 @@ dictionary of settings parsed from the ``.ini`` file, which contains deployment-related values such as ``pyramid.reload_templates``, ``db_string``, etc. -``'main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with +``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py @@ -123,10 +123,11 @@ Finally, ``main`` is finished configuring things, so it uses the View Declarations via ``views.py`` ---------------------------------- -Mapping a :term:`route` to code that will be executed when that route's -pattern matches is done by registering a :term:`view configuration`. Our -application uses the :meth:`pyramid.view.view_config` decorator to map view -callables to each route, thereby mapping URL patterns to code. +Mapping a :term:`route` to code that will be executed when a match for +the route's pattern occurs is done by registering a :term:`view +configuration`. Our application uses the +:meth:`pyramid.view.view_config` decorator to map view callables to +each route, thereby mapping URL patterns to code. Open ``tutorial/tutorial/views.py``. It should already contain the following: @@ -151,7 +152,7 @@ Note that ``my_view()`` accepts a single argument named ``request``. This is the standard call signature for a Pyramid :term:`view callable`. Remember in our ``__init__.py`` when we executed the -:meth:`pyramid.config.Configurator.scan` method, e.g. ``config.scan()``? The +:meth:`pyramid.config.Configurator.scan` method, i.e. ``config.scan()``? The purpose of calling the scan method was to find and process this ``@view_config`` decorator in order to create a view configuration within our application. Without being processed by ``scan``, the decorator effectively @@ -199,7 +200,7 @@ To give a simple example of a model class, we define one named ``MyModel``: :linenos: :language: py -Our sample model has an ``__init__`` that takes a two arguments (``name``, +Our example 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 -- cgit v1.2.3 From a7a639fe5b875f4e94e4c788fb93711315df62ae Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 17 Mar 2012 14:07:21 -0400 Subject: explain zopetransaction extension --- docs/tutorials/wiki2/basiclayout.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 6715b2bd7..9661fcd6e 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -186,6 +186,15 @@ Next we set up a SQLAlchemy "DBSession" object: :linenos: :language: py +``scoped_session`` and ``sessionmaker`` are standard SQLAlchemy helpers. +``scoped_session`` allows us to access our database connection globally. +``sessionmaker`` creates a database session object. We pass to +``sessionmaker`` the ``extension=ZopeTransactionExtension()`` extension +option in order to allow the system to automatically manage datbase +transactions. With ``ZopeTransactionExtension`` activated, our application +will automatically issue a transaction commit after every request unless an +exception is raised, in which case the transaction will be aborted. + We also need to create a declarative ``Base`` object to use as a base class for our model: -- cgit v1.2.3 From 0070533a553c93b102f17e2013355b7b7e388cd1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 17 Mar 2012 14:08:55 -0400 Subject: explain base a bit --- docs/tutorials/wiki2/basiclayout.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 9661fcd6e..5f4ea671c 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -202,6 +202,9 @@ base class for our model: :lines: 17 :language: py +Our model classes will inherit from this ``Base`` class so they can be +associated with our particular database connection. + To give a simple example of a model class, we define one named ``MyModel``: .. literalinclude:: src/basiclayout/tutorial/models.py -- cgit v1.2.3 From 0f372cd870caf36dfea59319df2ca26a92a74dc9 Mon Sep 17 00:00:00 2001 From: Daniel Haaker Date: Sat, 4 Aug 2012 21:54:22 +0200 Subject: fix two minor typos in docs --- docs/tutorials/wiki2/basiclayout.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 5f4ea671c..b3184c4fc 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -100,7 +100,7 @@ used when the URL is ``/``: :language: py Since this route has a ``pattern`` equalling ``/`` it is the route that will -be matched when the URL ``/`` is visted, e.g. ``http://localhost:6543/``. +be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``. ``main`` next calls the ``scan`` method of the configurator, which will recursively scan our ``tutorial`` package, looking for ``@view_config`` (and @@ -190,7 +190,7 @@ Next we set up a SQLAlchemy "DBSession" object: ``scoped_session`` allows us to access our database connection globally. ``sessionmaker`` creates a database session object. We pass to ``sessionmaker`` the ``extension=ZopeTransactionExtension()`` extension -option in order to allow the system to automatically manage datbase +option in order to allow the system to automatically manage database transactions. With ``ZopeTransactionExtension`` activated, our application will automatically issue a transaction commit after every request unless an exception is raised, in which case the transaction will be aborted. -- cgit v1.2.3 From 098599b497fb6cd7c9372ceb795e9e8a416d573e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 22 Sep 2012 10:04:14 -0400 Subject: - Add ``Base.metadata.bind = engine`` to alchemy template, so that tables defined imperatively will work. - update wiki2 SQLA tutorial with the changes required after inserting ``Base.metadata.bind = engine`` into the alchemy scaffold. --- docs/tutorials/wiki2/basiclayout.rst | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index b3184c4fc..dbd130c36 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -51,21 +51,33 @@ The main function first creates a SQLAlchemy database engine using (something like ``sqlite://``): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 9 + :lines: 12 :linenos: :language: py -``main`` then initializes our SQL database using SQLAlchemy, passing it the +``main`` then initializes our SQLAlchemy session object, passing it the engine: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 10 + :lines: 13 + :language: py + +``main`` subsequently initializes our SQLAlchemy declarative Base object, +assigning the engine we created to the ``bind`` attribute of it's +``metadata`` object. This allows table definitions done imperatively +(instead of declaratively, via a class statement) to work. We won't use any +such tables in our application, but if you add one later, long after you've +forgotten about this tutorial, you won't be left scratching your head when it +doesn't work. + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 14 :language: py The next step of ``main`` is to construct a :term:`Configurator` object: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 11 + :lines: 15 :language: py ``settings`` is passed to the Configurator as a keyword argument with the @@ -78,7 +90,7 @@ deployment-related values such as ``pyramid.reload_templates``, two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 12 + :lines: 16 :language: py This registers a static resource view which will match any URL that starts @@ -96,7 +108,7 @@ 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 + :lines: 17 :language: py Since this route has a ``pattern`` equalling ``/`` it is the route that will @@ -109,7 +121,7 @@ view configuration will be registered, which will allow one of our application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 14 + :lines: 18 :language: py Finally, ``main`` is finished configuring things, so it uses the @@ -117,7 +129,7 @@ Finally, ``main`` is finished configuring things, so it uses the :term:`WSGI` application: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 15 + :lines: 19 :language: py View Declarations via ``views.py`` -- cgit v1.2.3 From 5fbaf7be1b82247e21fa7d3b98d76e7d92ac522c Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Tue, 20 Nov 2012 19:46:10 -0600 Subject: Sync views.py on SQL wiki tutorial with the scaffold - Explain the added lines in the Basic Layout chapter. - The user is told to remove the added lines in the Defining Views chapter, there was no need to fix any emphasized lines. - Sync the file in the other sections even if it is not shown, for consistency. --- docs/tutorials/wiki2/basiclayout.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index dbd130c36..4f73dc914 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -171,6 +171,12 @@ application. Without being processed by ``scan``, the decorator effectively does nothing. ``@view_config`` is inert without being detected via a :term:`scan`. +The sample ``my_view()`` created by the scaffold uses a ``try:`` and ``except:`` +clause, to detect if there is a problem accessing the project database and +provide an alternate error response. That response will include the text +shown at the end of the file, which will be displayed in the browser to +inform the user about possible actions to take to solve the problem. + Content Models with ``models.py`` --------------------------------- -- cgit v1.2.3 From b9b2ee39c251dd68a12e717e1f6d9d02a29efe9a Mon Sep 17 00:00:00 2001 From: Marc Abramowitz Date: Fri, 30 Nov 2012 09:27:09 -0800 Subject: A bunch of minor tweaks to the wiki2 tutorial in docs/tutorials/wiki2 --- docs/tutorials/wiki2/basiclayout.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 4f73dc914..ed98da183 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -45,7 +45,7 @@ When you invoke the ``pserve development.ini`` command, the ``main`` function above is executed. It accepts some settings and returns a :term:`WSGI` application. (See :ref:`startup_chapter` for more about ``pserve``.) -The main function first creates a SQLAlchemy database engine using +The main function first creates a :term:`SQLAlchemy` database engine using ``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the ``development.ini`` file's ``[app:main]`` section. This will be a URI (something like ``sqlite://``): @@ -62,7 +62,7 @@ engine: :lines: 13 :language: py -``main`` subsequently initializes our SQLAlchemy declarative Base object, +``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object, assigning the engine we created to the ``bind`` attribute of it's ``metadata`` object. This allows table definitions done imperatively (instead of declaratively, via a class statement) to work. We won't use any @@ -94,9 +94,9 @@ two arguments: ``static`` (the name), and ``static`` (the path): :language: py This registers a static resource view which will match any URL that starts -with the prefix ``/static`` (by virtue of the first argument to add_static -view). This will serve up static resources for us from within the ``static`` -directory of our ``tutorial`` package, in this case, via +with the prefix ``/static`` (by virtue of the first argument to +``add_static_view``). 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 (by virtue of the second argument to add_static_view). With this declaration, we're saying that any URL that starts with ``/static`` should go to the static view; any remainder of its @@ -114,8 +114,9 @@ used when the URL is ``/``: Since this route has a ``pattern`` equalling ``/`` it is the route that will be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``. -``main`` next calls the ``scan`` method of the configurator, which will -recursively scan our ``tutorial`` package, looking for ``@view_config`` (and +``main`` next calls the ``scan`` method of the configurator +(:meth:`pyramid.config.Configurator.scan`), which will recursively scan our +``tutorial`` package, looking for ``@view_config`` (and other special) decorators. When it finds a ``@view_config`` decorator, a view configuration will be registered, which will allow one of our application URLs to be mapped to some code. @@ -197,7 +198,7 @@ Let's examine this in detail. First, we need some imports to support later code: :linenos: :language: py -Next we set up a SQLAlchemy "DBSession" object: +Next we set up a SQLAlchemy ``DBSession`` object: .. literalinclude:: src/basiclayout/tutorial/models.py :lines: 16 @@ -230,8 +231,9 @@ To give a simple example of a model class, we define one named ``MyModel``: :linenos: :language: py -Our example model has an ``__init__`` that takes a two arguments (``name``, -and ``value``). It stores these values as ``self.name`` and ``self.value`` +Our example model has an ``__init__`` method 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. -- cgit v1.2.3 From e90fa43a8051dfc8799596e17b72fd3d3def6516 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Sat, 1 Dec 2012 19:43:02 -0600 Subject: Sync __init__.py in SQL wiki tutorial - Update lines and emphasized-lines - No line numbers if only a single line --- docs/tutorials/wiki2/basiclayout.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 4f73dc914..7b9c44bb1 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -51,15 +51,14 @@ The main function first creates a SQLAlchemy database engine using (something like ``sqlite://``): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 12 - :linenos: + :lines: 13 :language: py ``main`` then initializes our SQLAlchemy session object, passing it the engine: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 13 + :lines: 14 :language: py ``main`` subsequently initializes our SQLAlchemy declarative Base object, @@ -71,13 +70,13 @@ forgotten about this tutorial, you won't be left scratching your head when it doesn't work. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 14 + :lines: 15 :language: py The next step of ``main`` is to construct a :term:`Configurator` object: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 15 + :lines: 16 :language: py ``settings`` is passed to the Configurator as a keyword argument with the @@ -90,7 +89,7 @@ deployment-related values such as ``pyramid.reload_templates``, two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 16 + :lines: 17 :language: py This registers a static resource view which will match any URL that starts @@ -108,7 +107,7 @@ via the :meth:`pyramid.config.Configurator.add_route` method that will be used when the URL is ``/``: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 17 + :lines: 18 :language: py Since this route has a ``pattern`` equalling ``/`` it is the route that will @@ -121,7 +120,7 @@ view configuration will be registered, which will allow one of our application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 18 + :lines: 19 :language: py Finally, ``main`` is finished configuring things, so it uses the @@ -129,7 +128,7 @@ Finally, ``main`` is finished configuring things, so it uses the :term:`WSGI` application: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 19 + :lines: 20 :language: py View Declarations via ``views.py`` -- cgit v1.2.3 From 479178179df2e3554d81d8c42d7ff46b75901c62 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Sat, 1 Dec 2012 22:30:50 -0600 Subject: Sync models.py in SQL wiki tutorial - Update lines and emphasized-lines - No line numbers if only a single line --- docs/tutorials/wiki2/basiclayout.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 7b9c44bb1..934bfb52a 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -200,7 +200,6 @@ Next we set up a SQLAlchemy "DBSession" object: .. literalinclude:: src/basiclayout/tutorial/models.py :lines: 16 - :linenos: :language: py ``scoped_session`` and ``sessionmaker`` are standard SQLAlchemy helpers. -- cgit v1.2.3 From f65e191ed7da0ff97638879cf854c0b1cb505aaa Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 2 Jan 2013 23:09:40 +0200 Subject: typos --- docs/tutorials/wiki2/basiclayout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 763deaa32..e8874784c 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -97,7 +97,7 @@ with the prefix ``/static`` (by virtue of the first argument to ``add_static_view``). 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 (by virtue of the second argument -to add_static_view). With this declaration, we're saying that any URL that +to ``add_static_view``). 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. -- cgit v1.2.3 From 445eb8708fa48209947377f6de609799dd843ad6 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 20 Jan 2013 17:10:40 +0200 Subject: point to the sources of the wiki tutorials in just one location; fix #763 * This avoids having to update the link multiple times. * Also, mention their location, in case user has Pyramid checkout. --- docs/tutorials/wiki2/basiclayout.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index e8874784c..68be4ee7c 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -6,9 +6,6 @@ The starter files generated by the ``alchemy`` scaffold are very basic, but they provide a good orientation for the high-level patterns common to most :term:`url dispatch` -based :app:`Pyramid` projects. -The source code for this tutorial stage can be browsed at -`http://github.com/Pylons/pyramid/tree/1.3-branch/docs/tutorials/wiki2/src/basiclayout/ -`_. Application Configuration with ``__init__.py`` ---------------------------------------------- -- cgit v1.2.3 From 286a9ecab57621d0e1af1ba70986ef083149137a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 17 Mar 2013 12:22:35 +0200 Subject: grammar --- docs/tutorials/wiki2/basiclayout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 68be4ee7c..86fe97956 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -226,7 +226,7 @@ To give a simple example of a model class, we define one named ``MyModel``: :linenos: :language: py -Our example model has an ``__init__`` method that takes a two arguments +Our example model has an ``__init__`` method that takes 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 -- cgit v1.2.3 From f1c29f104a14dea0be612ca0aa8ecd49e165fafa Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Thu, 21 Mar 2013 18:24:31 +0200 Subject: add hyperlinks for SQLAlchemy --- docs/tutorials/wiki2/basiclayout.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 86fe97956..eb2445864 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -43,9 +43,9 @@ above is executed. It accepts some settings and returns a :term:`WSGI` application. (See :ref:`startup_chapter` for more about ``pserve``.) The main function first creates a :term:`SQLAlchemy` database engine using -``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the -``development.ini`` file's ``[app:main]`` section. This will be a URI -(something like ``sqlite://``): +:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed +settings in the ``development.ini`` file's ``[app:main]`` section. +This will be a URI (something like ``sqlite://``): .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 13 -- cgit v1.2.3 From 203fe8b2a92c18151894f0656b7846cef8ec4e51 Mon Sep 17 00:00:00 2001 From: Patrick Canfield Date: Mon, 18 Mar 2013 12:00:43 -0700 Subject: Update basiclayout.rst, more deductive concept ordering, singular form of terms --- docs/tutorials/wiki2/basiclayout.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index eb2445864..109d368b8 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -132,11 +132,11 @@ Finally, ``main`` is finished configuring things, so it uses the View Declarations via ``views.py`` ---------------------------------- -Mapping a :term:`route` to code that will be executed when a match for -the route's pattern occurs is done by registering a :term:`view -configuration`. Our application uses the -:meth:`pyramid.view.view_config` decorator to map view callables to -each route, thereby mapping URL patterns to code. +Arguably, the main function of a web framework is mapping each URL +patterns, see :term:`route`, to code, see :term:`view callable`, that is +executed when the requested URL matches the corresponding :term:`route`. Our +application uses the :meth:`pyramid.view.view_config` decorator to perform +this mapping. Open ``tutorial/tutorial/views.py``. It should already contain the following: -- cgit v1.2.3 From b1611cf0d24e2947ebfb58071ff7c695a1d824cc Mon Sep 17 00:00:00 2001 From: Patrick Canfield Date: Mon, 18 Mar 2013 13:05:41 -0700 Subject: Update definingviews.rst explain matchdict more explicitly, concisely --- docs/tutorials/wiki2/basiclayout.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 109d368b8..6d6287126 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -228,11 +228,10 @@ To give a simple example of a model class, we define one named ``MyModel``: Our example model has an ``__init__`` method that takes 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. +``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. -That's about all there is to it to models, views, and initialization code in +That's about all there is to it with models, views, and initialization code in our stock application. -- cgit v1.2.3 From e7b21013bab17d5eccdc60f6125cc898996021cf Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 23 Mar 2013 03:12:42 -0400 Subject: change some slightly awkward wording --- docs/tutorials/wiki2/basiclayout.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 6d6287126..0193afab4 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -132,11 +132,10 @@ Finally, ``main`` is finished configuring things, so it uses the View Declarations via ``views.py`` ---------------------------------- -Arguably, the main function of a web framework is mapping each URL -patterns, see :term:`route`, to code, see :term:`view callable`, that is -executed when the requested URL matches the corresponding :term:`route`. Our -application uses the :meth:`pyramid.view.view_config` decorator to perform -this mapping. +The main function of a web framework is mapping each URL pattern to code (a +:term:`view callable`) that is executed when the requested URL matches the +corresponding :term:`route`. Our application uses the +:meth:`pyramid.view.view_config` decorator to perform this mapping. Open ``tutorial/tutorial/views.py``. It should already contain the following: @@ -228,10 +227,10 @@ To give a simple example of a model class, we define one named ``MyModel``: Our example model has an ``__init__`` method that takes 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. - -That's about all there is to it with models, views, and initialization code in -our stock application. +``self.value`` on the instance created by 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. +That's about all there is to it regarding models, views, and initialization +code in our stock application. -- cgit v1.2.3 From 404b28ba2efb02d93777a3e01fd602c96af8c077 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 6 Sep 2013 00:02:46 -0500 Subject: update the code in the wiki and wiki2 tutorials to use pyramid_chameleon --- docs/tutorials/wiki2/basiclayout.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 0193afab4..c8e6723b3 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -82,11 +82,18 @@ dictionary of settings parsed from the ``.ini`` file, which contains deployment-related values such as ``pyramid.reload_templates``, ``db_string``, etc. +Next, include :term:`Chameleon` templating bindings so that we can use +renderers with the ``.pt`` extension within our project. + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 17 + :language: py + ``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 17 + :lines: 18 :language: py This registers a static resource view which will match any URL that starts @@ -104,7 +111,7 @@ via the :meth:`pyramid.config.Configurator.add_route` method that will be used when the URL is ``/``: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 18 + :lines: 19 :language: py Since this route has a ``pattern`` equalling ``/`` it is the route that will @@ -118,7 +125,7 @@ view configuration will be registered, which will allow one of our application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 19 + :lines: 20 :language: py Finally, ``main`` is finished configuring things, so it uses the @@ -126,7 +133,7 @@ Finally, ``main`` is finished configuring things, so it uses the :term:`WSGI` application: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 20 + :lines: 21 :language: py View Declarations via ``views.py`` -- cgit v1.2.3 From db51d27579d5177c415643707abf3108dc209923 Mon Sep 17 00:00:00 2001 From: "sergey.volobuev" Date: Fri, 29 Mar 2013 07:45:13 +1000 Subject: changed the explanation of the (now missing) __init__ method --- docs/tutorials/wiki2/basiclayout.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 0193afab4..4b78b30d1 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -225,10 +225,11 @@ To give a simple example of a model class, we define one named ``MyModel``: :linenos: :language: py -Our example model has an ``__init__`` method that takes two arguments -(``name``, and ``value``). It stores these values as ``self.name`` and -``self.value`` on the instance created by the ``__init__`` function itself. -The ``MyModel`` class also has a ``__tablename__`` attribute. This informs +Our example model does not require an ``__init__`` method because SQLAlchemy +supplies for us a default constructor if one is not already present, +which accepts keyword arguments of the same name as that of the mapped attributes. + +The ``MyModel`` class has a ``__tablename__`` attribute. This informs SQLAlchemy which table to use to store the data representing instances of this class. -- cgit v1.2.3 From ca51e11d86f9b4cb24f35e28fa3ab801fc6a49ec Mon Sep 17 00:00:00 2001 From: Bert JW Regeer Date: Fri, 6 Sep 2013 19:07:22 -0600 Subject: Add small note showing example usage of MyModel --- docs/tutorials/wiki2/basiclayout.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 4b78b30d1..1f3d630c7 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -229,6 +229,12 @@ Our example model does not require an ``__init__`` method because SQLAlchemy supplies for us a default constructor if one is not already present, which accepts keyword arguments of the same name as that of the mapped attributes. +.. note:: Example usage of MyModel: + + .. code-block:: python + + johnny = MyModel(name="John Doe", value=10) + The ``MyModel`` class has a ``__tablename__`` attribute. This informs SQLAlchemy which table to use to store the data representing instances of this class. -- cgit v1.2.3 From ee9676a8691dd18b88d3247fd8c1306c5aaa1543 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 24 May 2015 19:15:22 -0700 Subject: - make templates html5 compliant - punctuation, grammar, spelling - fix linenos references - update outputs --- docs/tutorials/wiki2/basiclayout.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 05781c044..90157aa9e 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -4,7 +4,7 @@ Basic Layout The starter files generated by the ``alchemy`` scaffold are very basic, but they provide a good orientation for the high-level patterns common to most -:term:`url dispatch` -based :app:`Pyramid` projects. +:term:`URL dispatch`-based :app:`Pyramid` projects. Application Configuration with ``__init__.py`` @@ -12,7 +12,7 @@ Application Configuration 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. We use ``__init__.py`` both as a marker indicating the directory +package. We use ``__init__.py``, both as a marker indicating the directory it's contained within is a package, and to contain configuration code. Open ``tutorial/tutorial/__init__.py``. It should already contain @@ -114,7 +114,7 @@ used when the URL is ``/``: :lines: 19 :language: py -Since this route has a ``pattern`` equalling ``/`` it is the route that will +Since this route has a ``pattern`` equaling ``/`` it is the route that will be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``. ``main`` next calls the ``scan`` method of the configurator @@ -167,7 +167,7 @@ Note that ``my_view()`` accepts a single argument named ``request``. This is the standard call signature for a Pyramid :term:`view callable`. Remember in our ``__init__.py`` when we executed the -:meth:`pyramid.config.Configurator.scan` method, i.e. ``config.scan()``? The +:meth:`pyramid.config.Configurator.scan` method ``config.scan()``? The purpose of calling the scan method was to find and process this ``@view_config`` decorator in order to create a view configuration within our application. Without being processed by ``scan``, the decorator effectively @@ -175,7 +175,7 @@ does nothing. ``@view_config`` is inert without being detected via a :term:`scan`. The sample ``my_view()`` created by the scaffold uses a ``try:`` and ``except:`` -clause, to detect if there is a problem accessing the project database and +clause to detect if there is a problem accessing the project database and provide an alternate error response. That response will include the text shown at the end of the file, which will be displayed in the browser to inform the user about possible actions to take to solve the problem. -- cgit v1.2.3 From 34a913dd693695ade475000bfe61eb6e828a1dc8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 25 May 2015 14:55:00 -0700 Subject: grammar, caps, minor tweaks --- docs/tutorials/wiki2/basiclayout.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 90157aa9e..623882516 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -7,13 +7,14 @@ they provide a good orientation for the high-level patterns common to most :term:`URL dispatch`-based :app:`Pyramid` projects. -Application Configuration with ``__init__.py`` +Application configuration 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. We use ``__init__.py``, both as a marker indicating the directory -it's contained within is a package, and to contain configuration code. +package. We use ``__init__.py`` both as a marker, indicating the directory +in which it's contained is a package, and to contain application configuration +code. Open ``tutorial/tutorial/__init__.py``. It should already contain the following: @@ -136,7 +137,7 @@ Finally, ``main`` is finished configuring things, so it uses the :lines: 21 :language: py -View Declarations via ``views.py`` +View declarations via ``views.py`` ---------------------------------- The main function of a web framework is mapping each URL pattern to code (a -- cgit v1.2.3 From 91dee884e9e4831e73a5d0a5c6a00e1e0f1397d9 Mon Sep 17 00:00:00 2001 From: nharringtonwasatch Date: Thu, 1 Oct 2015 13:52:12 -0400 Subject: wiki2 documentation precisely matches the scaffolding output --- docs/tutorials/wiki2/basiclayout.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 623882516..08132e8cd 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -247,5 +247,8 @@ The ``MyModel`` class has a ``__tablename__`` attribute. This informs SQLAlchemy which table to use to store the data representing instances of this class. +The Index import and the Index object creation is not required for this +tutorial, and will be removed in the next step. + That's about all there is to it regarding models, views, and initialization code in our stock application. -- cgit v1.2.3 From 301d7e7b7f9477e3d6dc5185707ebdd5b27c0b06 Mon Sep 17 00:00:00 2001 From: Bert JW Regeer Date: Tue, 6 Oct 2015 19:52:05 -0600 Subject: Include the right line number from the .py file This was including a blank line. This mistake was caught when attempting to build a PDF file using latexpdf due to LaTeX not allowing certain sections to be blank. --- docs/tutorials/wiki2/basiclayout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 08132e8cd..80ae4b34e 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -204,7 +204,7 @@ Let's examine this in detail. First, we need some imports to support later code: Next we set up a SQLAlchemy ``DBSession`` object: .. literalinclude:: src/basiclayout/tutorial/models.py - :lines: 16 + :lines: 17 :language: py ``scoped_session`` and ``sessionmaker`` are standard SQLAlchemy helpers. -- cgit v1.2.3 From bf564d134846b16271f6c9c1742fc1fd86de71ec Mon Sep 17 00:00:00 2001 From: Naoko Reeves Date: Thu, 5 Nov 2015 13:40:23 -0700 Subject: literalinclude line number was off for Base object --- docs/tutorials/wiki2/basiclayout.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 80ae4b34e..695d7f15b 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -220,7 +220,7 @@ We also need to create a declarative ``Base`` object to use as a base class for our model: .. literalinclude:: src/basiclayout/tutorial/models.py - :lines: 17 + :lines: 18 :language: py Our model classes will inherit from this ``Base`` class so they can be -- cgit v1.2.3 From fea87a5cbb4edbfef204283c23d5b0d8fb5220f8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 11 Nov 2015 18:34:44 -0800 Subject: - update basiclayout/tutorial/__init__.py - update section "Application configuration with ``__init__.py``" - move WIP to "Content Models with ``models.py``", wrapped by Sphinx comments --- docs/tutorials/wiki2/basiclayout.rst | 98 ++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 43 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 80ae4b34e..8a1dbf3f8 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -12,12 +12,12 @@ Application configuration 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. We use ``__init__.py`` both as a marker, indicating the directory -in which it's contained is a package, and to contain application configuration +package. We use ``__init__.py`` both as a marker, indicating the directory in +which it's contained is a package, and to contain application configuration code. -Open ``tutorial/tutorial/__init__.py``. It should already contain -the following: +Open ``tutorial/tutorial/__init__.py``. It should already contain the +following: .. literalinclude:: src/basiclayout/tutorial/__init__.py :linenos: @@ -43,58 +43,37 @@ When you invoke the ``pserve development.ini`` command, the ``main`` function above is executed. It accepts some settings and returns a :term:`WSGI` application. (See :ref:`startup_chapter` for more about ``pserve``.) -The main function first creates a :term:`SQLAlchemy` database engine using -:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed -settings in the ``development.ini`` file's ``[app:main]`` section. -This will be a URI (something like ``sqlite://``): - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 13 - :language: py - -``main`` then initializes our SQLAlchemy session object, passing it the -engine: - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 14 - :language: py - -``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object, -assigning the engine we created to the ``bind`` attribute of it's -``metadata`` object. This allows table definitions done imperatively -(instead of declaratively, via a class statement) to work. We won't use any -such tables in our application, but if you add one later, long after you've -forgotten about this tutorial, you won't be left scratching your head when it -doesn't work. - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 15 - :language: py - The next step of ``main`` is to construct a :term:`Configurator` object: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 16 + :lines: 7 :language: py ``settings`` is passed to the Configurator as a keyword argument with the dictionary values passed as the ``**settings`` argument. This will be a dictionary of settings parsed from the ``.ini`` file, which contains deployment-related values such as ``pyramid.reload_templates``, -``db_string``, etc. +``sqlalchemy.url``, and so on. -Next, include :term:`Chameleon` templating bindings so that we can use -renderers with the ``.pt`` extension within our project. +Next include :term:`Jinja2` templating bindings so that we can use renderers +with the ``.jinja2`` extension within our project. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 17 + :lines: 8 + :language: py + +Next include the module ``meta`` from the package ``models`` using a dotted +Python path. + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 9 :language: py ``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 18 + :lines: 10 :language: py This registers a static resource view which will match any URL that starts @@ -112,11 +91,11 @@ via the :meth:`pyramid.config.Configurator.add_route` method that will be used when the URL is ``/``: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 19 + :lines: 11 :language: py -Since this route has a ``pattern`` equaling ``/`` it is the route that will -be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``. +Since this route has a ``pattern`` equaling ``/``, it is the route that will +be matched when the URL ``/`` is visited, e.g., ``http://localhost:6543/``. ``main`` next calls the ``scan`` method of the configurator (:meth:`pyramid.config.Configurator.scan`), which will recursively scan our @@ -126,10 +105,10 @@ view configuration will be registered, which will allow one of our application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 20 + :lines: 12 :language: py -Finally, ``main`` is finished configuring things, so it uses the +Finally ``main`` is finished configuring things, so it uses the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application: @@ -184,6 +163,39 @@ inform the user about possible actions to take to solve the problem. Content Models with ``models.py`` --------------------------------- +.. START moved from Application configuration with ``__init__.py``. This + section is a WIP, and needs to be updated using the new models package. + +The main function first creates a :term:`SQLAlchemy` database engine using +:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed +settings in the ``development.ini`` file's ``[app:main]`` section. +This will be a URI (something like ``sqlite://``): + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 13 + :language: py + +``main`` then initializes our SQLAlchemy session object, passing it the +engine: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 14 + :language: py + +``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object, +assigning the engine we created to the ``bind`` attribute of it's +``metadata`` object. This allows table definitions done imperatively +(instead of declaratively, via a class statement) to work. We won't use any +such tables in our application, but if you add one later, long after you've +forgotten about this tutorial, you won't be left scratching your head when it +doesn't work. + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 15 + :language: py + +.. END moved from Application configuration with ``__init__.py`` + In a SQLAlchemy-based application, a *model* object is an object composed by querying the SQL database. The ``models.py`` file is where the ``alchemy`` scaffold put the classes that implement our models. -- cgit v1.2.3 From 049e670aef9ea5611561546fd5c0e2dd6152b9b7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 11 Nov 2015 21:09:15 -0800 Subject: Revert "update wiki2/src/basiclayout/tutorial" --- docs/tutorials/wiki2/basiclayout.rst | 98 ++++++++++++++++-------------------- 1 file changed, 43 insertions(+), 55 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 72b2bc26b..695d7f15b 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -12,12 +12,12 @@ Application configuration 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. We use ``__init__.py`` both as a marker, indicating the directory in -which it's contained is a package, and to contain application configuration +package. We use ``__init__.py`` both as a marker, indicating the directory +in which it's contained is a package, and to contain application configuration code. -Open ``tutorial/tutorial/__init__.py``. It should already contain the -following: +Open ``tutorial/tutorial/__init__.py``. It should already contain +the following: .. literalinclude:: src/basiclayout/tutorial/__init__.py :linenos: @@ -43,37 +43,58 @@ When you invoke the ``pserve development.ini`` command, the ``main`` function above is executed. It accepts some settings and returns a :term:`WSGI` application. (See :ref:`startup_chapter` for more about ``pserve``.) +The main function first creates a :term:`SQLAlchemy` database engine using +:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed +settings in the ``development.ini`` file's ``[app:main]`` section. +This will be a URI (something like ``sqlite://``): + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 13 + :language: py + +``main`` then initializes our SQLAlchemy session object, passing it the +engine: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 14 + :language: py + +``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object, +assigning the engine we created to the ``bind`` attribute of it's +``metadata`` object. This allows table definitions done imperatively +(instead of declaratively, via a class statement) to work. We won't use any +such tables in our application, but if you add one later, long after you've +forgotten about this tutorial, you won't be left scratching your head when it +doesn't work. + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 15 + :language: py + The next step of ``main`` is to construct a :term:`Configurator` object: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 7 + :lines: 16 :language: py ``settings`` is passed to the Configurator as a keyword argument with the dictionary values passed as the ``**settings`` argument. This will be a dictionary of settings parsed from the ``.ini`` file, which contains deployment-related values such as ``pyramid.reload_templates``, -``sqlalchemy.url``, and so on. - -Next include :term:`Jinja2` templating bindings so that we can use renderers -with the ``.jinja2`` extension within our project. - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 8 - :language: py +``db_string``, etc. -Next include the module ``meta`` from the package ``models`` using a dotted -Python path. +Next, include :term:`Chameleon` templating bindings so that we can use +renderers with the ``.pt`` extension within our project. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 9 + :lines: 17 :language: py ``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 10 + :lines: 18 :language: py This registers a static resource view which will match any URL that starts @@ -91,11 +112,11 @@ via the :meth:`pyramid.config.Configurator.add_route` method that will be used when the URL is ``/``: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 11 + :lines: 19 :language: py -Since this route has a ``pattern`` equaling ``/``, it is the route that will -be matched when the URL ``/`` is visited, e.g., ``http://localhost:6543/``. +Since this route has a ``pattern`` equaling ``/`` it is the route that will +be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``. ``main`` next calls the ``scan`` method of the configurator (:meth:`pyramid.config.Configurator.scan`), which will recursively scan our @@ -105,10 +126,10 @@ view configuration will be registered, which will allow one of our application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 12 + :lines: 20 :language: py -Finally ``main`` is finished configuring things, so it uses the +Finally, ``main`` is finished configuring things, so it uses the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application: @@ -163,39 +184,6 @@ inform the user about possible actions to take to solve the problem. Content Models with ``models.py`` --------------------------------- -.. START moved from Application configuration with ``__init__.py``. This - section is a WIP, and needs to be updated using the new models package. - -The main function first creates a :term:`SQLAlchemy` database engine using -:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed -settings in the ``development.ini`` file's ``[app:main]`` section. -This will be a URI (something like ``sqlite://``): - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 13 - :language: py - -``main`` then initializes our SQLAlchemy session object, passing it the -engine: - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 14 - :language: py - -``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object, -assigning the engine we created to the ``bind`` attribute of it's -``metadata`` object. This allows table definitions done imperatively -(instead of declaratively, via a class statement) to work. We won't use any -such tables in our application, but if you add one later, long after you've -forgotten about this tutorial, you won't be left scratching your head when it -doesn't work. - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 15 - :language: py - -.. END moved from Application configuration with ``__init__.py`` - In a SQLAlchemy-based application, a *model* object is an object composed by querying the SQL database. The ``models.py`` file is where the ``alchemy`` scaffold put the classes that implement our models. -- cgit v1.2.3 From 392cc17f5091d51a8e1b8908f8600c0b821ebd7f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 11 Nov 2015 21:58:03 -0800 Subject: basiclayout/tutorial - views - use package instead of single file - add tests.py from scaffold - update basiclayout.rst with views section --- docs/tutorials/wiki2/basiclayout.rst | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 8a1dbf3f8..cdcf0fa5f 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -116,17 +116,19 @@ Finally ``main`` is finished configuring things, so it uses the :lines: 21 :language: py -View declarations via ``views.py`` ----------------------------------- + +View declarations via the ``views`` package +------------------------------------------- The main function of a web framework is mapping each URL pattern to code (a :term:`view callable`) that is executed when the requested URL matches the corresponding :term:`route`. Our application uses the :meth:`pyramid.view.view_config` decorator to perform this mapping. -Open ``tutorial/tutorial/views.py``. It should already contain the following: +Open ``tutorial/tutorial/views/default.py`` in the ``views`` package. It +should already contain the following: - .. literalinclude:: src/basiclayout/tutorial/views.py + .. literalinclude:: src/basiclayout/tutorial/views/default.py :linenos: :language: py @@ -135,13 +137,13 @@ function it decorates (``my_view``) with a :term:`view configuration`, consisting of: * a ``route_name`` (``home``) - * a ``renderer``, which is a template from the ``templates`` subdirectory - of the package. + * a ``renderer``, which is a template from the ``templates`` subdirectory of + the package. When the pattern associated with the ``home`` view is matched during a request, -``my_view()`` will be executed. ``my_view()`` returns a dictionary; the -renderer will use the ``templates/mytemplate.pt`` template to create a response -based on the values in the dictionary. +``my_view()`` will be executed. ``my_view()`` returns a dictionary; the +renderer will use the ``templates/mytemplate.jinja2`` template to create a +response based on the values in the dictionary. Note that ``my_view()`` accepts a single argument named ``request``. This is the standard call signature for a Pyramid :term:`view callable`. @@ -154,13 +156,13 @@ application. Without being processed by ``scan``, the decorator effectively does nothing. ``@view_config`` is inert without being detected via a :term:`scan`. -The sample ``my_view()`` created by the scaffold uses a ``try:`` and ``except:`` -clause to detect if there is a problem accessing the project database and -provide an alternate error response. That response will include the text -shown at the end of the file, which will be displayed in the browser to -inform the user about possible actions to take to solve the problem. +The sample ``my_view()`` created by the scaffold uses a ``try:`` and +``except:`` clause to detect if there is a problem accessing the project +database and provide an alternate error response. That response will include +the text shown at the end of the file, which will be displayed in the browser +to inform the user about possible actions to take to solve the problem. -Content Models with ``models.py`` +Content models with ``models.py`` --------------------------------- .. START moved from Application configuration with ``__init__.py``. This -- cgit v1.2.3 From 0409cf178d4c0fa9a0d3b0858ab2294935b23609 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 12 Nov 2015 00:40:02 -0800 Subject: basiclayout/tutorial - models, scripts, static, templates - use package instead of single file - add tests.py from scaffold - update basiclayout.rst with models section --- docs/tutorials/wiki2/basiclayout.rst | 117 ++++++++++++++++++----------------- 1 file changed, 61 insertions(+), 56 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index cdcf0fa5f..5d9b62eea 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -113,7 +113,7 @@ Finally ``main`` is finished configuring things, so it uses the :term:`WSGI` application: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 21 + :lines: 13 :language: py @@ -162,94 +162,99 @@ database and provide an alternate error response. That response will include the text shown at the end of the file, which will be displayed in the browser to inform the user about possible actions to take to solve the problem. -Content models with ``models.py`` ---------------------------------- +Content models with the ``models`` package +------------------------------------------ -.. START moved from Application configuration with ``__init__.py``. This - section is a WIP, and needs to be updated using the new models package. +In a SQLAlchemy-based application, a *model* object is an object composed by +querying the SQL database. The ``models`` package is where the ``alchemy`` +scaffold put the classes that implement our models. -The main function first creates a :term:`SQLAlchemy` database engine using -:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed -settings in the ``development.ini`` file's ``[app:main]`` section. -This will be a URI (something like ``sqlite://``): +First, open ``tutorial/tutorial/models/__init__.py``, which should already +contain the following: - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 13 + .. literalinclude:: src/basiclayout/tutorial/models/__init__.py + :linenos: :language: py -``main`` then initializes our SQLAlchemy session object, passing it the -engine: +Our ``__init__.py`` will perform some imports to support later code, then calls +the function :func:`sqlalchemy.orm.configure_mappers`. - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 14 +Next open ``tutorial/tutorial/models/meta.py``, which should already contain +the following: + + .. literalinclude:: src/basiclayout/tutorial/models/meta.py + :linenos: :language: py -``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object, -assigning the engine we created to the ``bind`` attribute of it's -``metadata`` object. This allows table definitions done imperatively -(instead of declaratively, via a class statement) to work. We won't use any -such tables in our application, but if you add one later, long after you've -forgotten about this tutorial, you won't be left scratching your head when it -doesn't work. +``meta.py`` contains imports that are used to support later code. We create a +dictionary ``NAMING_CONVENTION`` as well. - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 15 + .. literalinclude:: src/basiclayout/tutorial/models/meta.py + :end-before: metadata + :linenos: :language: py -.. END moved from Application configuration with ``__init__.py`` +Next we create a ``metadata`` object from the class +:class:`sqlalchemy.schema.MetaData`, using ``NAMING_CONVENTION`` as the value +for the ``naming_convention`` argument. We also need to create a declarative +``Base`` object to use as a base class for our model. Then our model classes +will inherit from the ``Base`` class so they can be associated with our +particular database connection. -In a SQLAlchemy-based application, a *model* object is an object composed by -querying the SQL database. The ``models.py`` file is where the ``alchemy`` -scaffold put the classes that implement our models. + .. literalinclude:: src/basiclayout/tutorial/models/meta.py + :lines: 15-16 + :lineno-start: 15 + :linenos: + :language: py -Open ``tutorial/tutorial/models.py``. It should already contain the following: +Next we define several functions, the first of which is ``includeme``, which +configures various database settings by calling subsequently defined functions. - .. literalinclude:: src/basiclayout/tutorial/models.py + .. literalinclude:: src/basiclayout/tutorial/models/meta.py + :pyobject: includeme :linenos: :language: py -Let's examine this in detail. First, we need some imports to support later code: +The function ``get_session`` registers a database session with a transaction +manager, and returns a ``dbsession`` object. With the transaction manager, our +application will automatically issue a transaction commit after every request +unless an exception is raised, in which case the transaction will be aborted. - .. literalinclude:: src/basiclayout/tutorial/models.py - :end-before: DBSession + .. literalinclude:: src/basiclayout/tutorial/models/meta.py + :pyobject: get_session :linenos: :language: py -Next we set up a SQLAlchemy ``DBSession`` object: +The ``get_engine`` function creates an :term:`SQLAlchemy` database engine using +:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.``-prefixed +settings in the ``development.ini`` file's ``[app:main]`` section, which is a +URI, something like ``sqlite://``. - .. literalinclude:: src/basiclayout/tutorial/models.py - :lines: 17 + .. literalinclude:: src/basiclayout/tutorial/models/meta.py + :pyobject: get_engine + :linenos: :language: py -``scoped_session`` and ``sessionmaker`` are standard SQLAlchemy helpers. -``scoped_session`` allows us to access our database connection globally. -``sessionmaker`` creates a database session object. We pass to -``sessionmaker`` the ``extension=ZopeTransactionExtension()`` extension -option in order to allow the system to automatically manage database -transactions. With ``ZopeTransactionExtension`` activated, our application -will automatically issue a transaction commit after every request unless an -exception is raised, in which case the transaction will be aborted. - -We also need to create a declarative ``Base`` object to use as a -base class for our model: +The function ``get_dbmaker`` accepts an :term:`SQLAlchemy` database engine, +and creates a database session object ``dbmaker`` from the :term:`SQLAlchemy` +class :class:`sqlalchemy.orm.session.sessionmaker`, which is then used for +creating a session with the database engine. - .. literalinclude:: src/basiclayout/tutorial/models.py - :lines: 17 + .. literalinclude:: src/basiclayout/tutorial/models/meta.py + :pyobject: get_dbmaker + :linenos: :language: py -Our model classes will inherit from this ``Base`` class so they can be -associated with our particular database connection. - -To give a simple example of a model class, we define one named ``MyModel``: +To give a simple example of a model class, we define one named ``MyModel``: - .. literalinclude:: src/basiclayout/tutorial/models.py + .. literalinclude:: src/basiclayout/tutorial/models/mymodel.py :pyobject: MyModel :linenos: :language: py Our example model does not require an ``__init__`` method because SQLAlchemy -supplies for us a default constructor if one is not already present, -which accepts keyword arguments of the same name as that of the mapped attributes. +supplies for us a default constructor if one is not already present, which +accepts keyword arguments of the same name as that of the mapped attributes. .. note:: Example usage of MyModel: -- cgit v1.2.3 From 1b994c6b87449a9542dcf5f0daf44023dbff31ff Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 12 Nov 2015 01:04:18 -0800 Subject: basiclayout/tutorial poke in attempt to resolve merge conflict on GitHub --- docs/tutorials/wiki2/basiclayout.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 5d9b62eea..c293f3170 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -162,6 +162,7 @@ database and provide an alternate error response. That response will include the text shown at the end of the file, which will be displayed in the browser to inform the user about possible actions to take to solve the problem. + Content models with the ``models`` package ------------------------------------------ -- cgit v1.2.3 From 414b67b45bab156b9738105e180908c4eee8600a Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 12 Nov 2015 12:56:27 -0600 Subject: Restore progress after backing changes out of master. This reverts commit 049e670aef9ea5611561546fd5c0e2dd6152b9b7. --- docs/tutorials/wiki2/basiclayout.rst | 98 ++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 43 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 649c11e85..abe9e4202 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -12,12 +12,12 @@ Application configuration 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. We use ``__init__.py`` both as a marker, indicating the directory -in which it's contained is a package, and to contain application configuration +package. We use ``__init__.py`` both as a marker, indicating the directory in +which it's contained is a package, and to contain application configuration code. -Open ``tutorial/tutorial/__init__.py``. It should already contain -the following: +Open ``tutorial/tutorial/__init__.py``. It should already contain the +following: .. literalinclude:: src/basiclayout/tutorial/__init__.py :linenos: @@ -43,58 +43,37 @@ When you invoke the ``pserve development.ini`` command, the ``main`` function above is executed. It accepts some settings and returns a :term:`WSGI` application. (See :ref:`startup_chapter` for more about ``pserve``.) -The main function first creates a :term:`SQLAlchemy` database engine using -:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed -settings in the ``development.ini`` file's ``[app:main]`` section. -This will be a URI (something like ``sqlite://``): - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 13 - :language: py - -``main`` then initializes our SQLAlchemy session object, passing it the -engine: - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 14 - :language: py - -``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object, -assigning the engine we created to the ``bind`` attribute of it's -``metadata`` object. This allows table definitions done imperatively -(instead of declaratively, via a class statement) to work. We won't use any -such tables in our application, but if you add one later, long after you've -forgotten about this tutorial, you won't be left scratching your head when it -doesn't work. - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 15 - :language: py - The next step of ``main`` is to construct a :term:`Configurator` object: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 16 + :lines: 7 :language: py ``settings`` is passed to the Configurator as a keyword argument with the dictionary values passed as the ``**settings`` argument. This will be a dictionary of settings parsed from the ``.ini`` file, which contains deployment-related values such as ``pyramid.reload_templates``, -``db_string``, etc. +``sqlalchemy.url``, and so on. -Next, include :term:`Chameleon` templating bindings so that we can use -renderers with the ``.pt`` extension within our project. +Next include :term:`Jinja2` templating bindings so that we can use renderers +with the ``.jinja2`` extension within our project. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 17 + :lines: 8 + :language: py + +Next include the module ``meta`` from the package ``models`` using a dotted +Python path. + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 9 :language: py ``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 18 + :lines: 10 :language: py This registers a static resource view which will match any URL that starts @@ -112,11 +91,11 @@ via the :meth:`pyramid.config.Configurator.add_route` method that will be used when the URL is ``/``: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 19 + :lines: 11 :language: py -Since this route has a ``pattern`` equaling ``/`` it is the route that will -be matched when the URL ``/`` is visited, e.g. ``http://localhost:6543/``. +Since this route has a ``pattern`` equaling ``/``, it is the route that will +be matched when the URL ``/`` is visited, e.g., ``http://localhost:6543/``. ``main`` next calls the ``scan`` method of the configurator (:meth:`pyramid.config.Configurator.scan`), which will recursively scan our @@ -126,10 +105,10 @@ view configuration will be registered, which will allow one of our application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 20 + :lines: 12 :language: py -Finally, ``main`` is finished configuring things, so it uses the +Finally ``main`` is finished configuring things, so it uses the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application: @@ -187,6 +166,39 @@ to inform the user about possible actions to take to solve the problem. Content models with the ``models`` package ------------------------------------------ +.. START moved from Application configuration with ``__init__.py``. This + section is a WIP, and needs to be updated using the new models package. + +The main function first creates a :term:`SQLAlchemy` database engine using +:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed +settings in the ``development.ini`` file's ``[app:main]`` section. +This will be a URI (something like ``sqlite://``): + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 13 + :language: py + +``main`` then initializes our SQLAlchemy session object, passing it the +engine: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 14 + :language: py + +``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object, +assigning the engine we created to the ``bind`` attribute of it's +``metadata`` object. This allows table definitions done imperatively +(instead of declaratively, via a class statement) to work. We won't use any +such tables in our application, but if you add one later, long after you've +forgotten about this tutorial, you won't be left scratching your head when it +doesn't work. + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 15 + :language: py + +.. END moved from Application configuration with ``__init__.py`` + In a SQLAlchemy-based application, a *model* object is an object composed by querying the SQL database. The ``models`` package is where the ``alchemy`` scaffold put the classes that implement our models. -- cgit v1.2.3 From 3525fa106fe2ca4b4bed93e28f72b13e3fa943b3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 13 Nov 2015 03:54:14 -0800 Subject: correct line numbers in and remove obsolete WIP block wiki2/basiclayout.rst --- docs/tutorials/wiki2/basiclayout.rst | 45 ++++++++++-------------------------- 1 file changed, 12 insertions(+), 33 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index abe9e4202..1ba7d3958 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -36,6 +36,7 @@ the ``main`` function we've defined in our ``__init__.py``: .. literalinclude:: src/basiclayout/tutorial/__init__.py :pyobject: main + :lineno-start: 4 :linenos: :language: py @@ -47,6 +48,7 @@ The next step of ``main`` is to construct a :term:`Configurator` object: .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 7 + :lineno-start: 7 :language: py ``settings`` is passed to the Configurator as a keyword argument with the @@ -60,6 +62,7 @@ with the ``.jinja2`` extension within our project. .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 8 + :lineno-start: 8 :language: py Next include the module ``meta`` from the package ``models`` using a dotted @@ -67,6 +70,7 @@ Python path. .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 9 + :lineno-start: 9 :language: py ``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with @@ -74,6 +78,7 @@ two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 10 + :lineno-start: 10 :language: py This registers a static resource view which will match any URL that starts @@ -92,6 +97,7 @@ used when the URL is ``/``: .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 11 + :lineno-start: 11 :language: py Since this route has a ``pattern`` equaling ``/``, it is the route that will @@ -106,6 +112,7 @@ application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 12 + :lineno-start: 12 :language: py Finally ``main`` is finished configuring things, so it uses the @@ -114,6 +121,7 @@ Finally ``main`` is finished configuring things, so it uses the .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 13 + :lineno-start: 13 :language: py @@ -166,39 +174,6 @@ to inform the user about possible actions to take to solve the problem. Content models with the ``models`` package ------------------------------------------ -.. START moved from Application configuration with ``__init__.py``. This - section is a WIP, and needs to be updated using the new models package. - -The main function first creates a :term:`SQLAlchemy` database engine using -:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed -settings in the ``development.ini`` file's ``[app:main]`` section. -This will be a URI (something like ``sqlite://``): - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 13 - :language: py - -``main`` then initializes our SQLAlchemy session object, passing it the -engine: - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 14 - :language: py - -``main`` subsequently initializes our SQLAlchemy declarative ``Base`` object, -assigning the engine we created to the ``bind`` attribute of it's -``metadata`` object. This allows table definitions done imperatively -(instead of declaratively, via a class statement) to work. We won't use any -such tables in our application, but if you add one later, long after you've -forgotten about this tutorial, you won't be left scratching your head when it -doesn't work. - - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 15 - :language: py - -.. END moved from Application configuration with ``__init__.py`` - In a SQLAlchemy-based application, a *model* object is an object composed by querying the SQL database. The ``models`` package is where the ``alchemy`` scaffold put the classes that implement our models. @@ -246,6 +221,7 @@ configures various database settings by calling subsequently defined functions. .. literalinclude:: src/basiclayout/tutorial/models/meta.py :pyobject: includeme + :lineno-start: 19 :linenos: :language: py @@ -256,6 +232,7 @@ unless an exception is raised, in which case the transaction will be aborted. .. literalinclude:: src/basiclayout/tutorial/models/meta.py :pyobject: get_session + :lineno-start: 32 :linenos: :language: py @@ -266,6 +243,7 @@ URI, something like ``sqlite://``. .. literalinclude:: src/basiclayout/tutorial/models/meta.py :pyobject: get_engine + :lineno-start: 39 :linenos: :language: py @@ -276,6 +254,7 @@ creating a session with the database engine. .. literalinclude:: src/basiclayout/tutorial/models/meta.py :pyobject: get_dbmaker + :lineno-start: 43 :linenos: :language: py -- cgit v1.2.3 From 2f6864759d66b8a9cea845d8e6b628b5bede5336 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 14 Nov 2015 03:15:59 -0800 Subject: minor changes to narrative flow --- docs/tutorials/wiki2/basiclayout.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 1ba7d3958..1426e55a5 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -44,7 +44,7 @@ When you invoke the ``pserve development.ini`` command, the ``main`` function above is executed. It accepts some settings and returns a :term:`WSGI` application. (See :ref:`startup_chapter` for more about ``pserve``.) -The next step of ``main`` is to construct a :term:`Configurator` object: +Next in ``main``, construct a :term:`Configurator` object: .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 7 @@ -279,8 +279,8 @@ The ``MyModel`` class has a ``__tablename__`` attribute. This informs SQLAlchemy which table to use to store the data representing instances of this class. -The Index import and the Index object creation is not required for this -tutorial, and will be removed in the next step. - That's about all there is to it regarding models, views, and initialization code in our stock application. + +The Index import and the Index object creation is not required for this +tutorial, and will be removed in the next step. -- cgit v1.2.3 From 86d90fb8c22a50e68077542d8f3f0f488e72a5d8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 2 Dec 2015 04:38:58 -0800 Subject: - adjust linenos for NAMING_CONVENTION comment --- docs/tutorials/wiki2/basiclayout.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 1426e55a5..e3d0a0a3c 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -211,8 +211,8 @@ will inherit from the ``Base`` class so they can be associated with our particular database connection. .. literalinclude:: src/basiclayout/tutorial/models/meta.py - :lines: 15-16 - :lineno-start: 15 + :lines: 18-19 + :lineno-start: 18 :linenos: :language: py @@ -221,7 +221,7 @@ configures various database settings by calling subsequently defined functions. .. literalinclude:: src/basiclayout/tutorial/models/meta.py :pyobject: includeme - :lineno-start: 19 + :lineno-start: 22 :linenos: :language: py @@ -232,7 +232,7 @@ unless an exception is raised, in which case the transaction will be aborted. .. literalinclude:: src/basiclayout/tutorial/models/meta.py :pyobject: get_session - :lineno-start: 32 + :lineno-start: 35 :linenos: :language: py @@ -243,7 +243,7 @@ URI, something like ``sqlite://``. .. literalinclude:: src/basiclayout/tutorial/models/meta.py :pyobject: get_engine - :lineno-start: 39 + :lineno-start: 42 :linenos: :language: py @@ -254,7 +254,7 @@ creating a session with the database engine. .. literalinclude:: src/basiclayout/tutorial/models/meta.py :pyobject: get_dbmaker - :lineno-start: 43 + :lineno-start: 46 :linenos: :language: py -- cgit v1.2.3 From 8ec0b01ef0de3d7859e081652ef752d9af612fc5 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 5 Feb 2016 00:04:23 -0600 Subject: unindent literalincludes --- docs/tutorials/wiki2/basiclayout.rst | 166 +++++++++++++++++------------------ 1 file changed, 83 insertions(+), 83 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index e3d0a0a3c..d55ce807f 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -19,25 +19,25 @@ code. Open ``tutorial/tutorial/__init__.py``. It should already contain the following: - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :linenos: + :language: py Let's go over this piece-by-piece. First, we need some imports to support later code: - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :end-before: main - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :end-before: main + :linenos: + :language: py ``__init__.py`` defines a function named ``main``. Here is the entirety of the ``main`` function we've defined in our ``__init__.py``: - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :pyobject: main - :lineno-start: 4 - :linenos: +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :pyobject: main + :lineno-start: 4 + :linenos: :language: py When you invoke the ``pserve development.ini`` command, the ``main`` function @@ -46,10 +46,10 @@ application. (See :ref:`startup_chapter` for more about ``pserve``.) Next in ``main``, construct a :term:`Configurator` object: - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 7 - :lineno-start: 7 - :language: py +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 7 + :lineno-start: 7 + :language: py ``settings`` is passed to the Configurator as a keyword argument with the dictionary values passed as the ``**settings`` argument. This will be a @@ -60,26 +60,26 @@ deployment-related values such as ``pyramid.reload_templates``, Next include :term:`Jinja2` templating bindings so that we can use renderers with the ``.jinja2`` extension within our project. - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 8 - :lineno-start: 8 - :language: py +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 8 + :lineno-start: 8 + :language: py Next include the module ``meta`` from the package ``models`` using a dotted Python path. - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 9 - :lineno-start: 9 - :language: py +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 9 + :lineno-start: 9 + :language: py ``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with two arguments: ``static`` (the name), and ``static`` (the path): - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 10 - :lineno-start: 10 - :language: py +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 10 + :lineno-start: 10 + :language: py This registers a static resource view which will match any URL that starts with the prefix ``/static`` (by virtue of the first argument to @@ -95,10 +95,10 @@ Using the configurator ``main`` also registers 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: 11 - :lineno-start: 11 - :language: py +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 11 + :lineno-start: 11 + :language: py Since this route has a ``pattern`` equaling ``/``, it is the route that will be matched when the URL ``/`` is visited, e.g., ``http://localhost:6543/``. @@ -110,19 +110,19 @@ other special) decorators. When it finds a ``@view_config`` decorator, a view configuration will be registered, which will allow one of our application URLs to be mapped to some code. - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 12 - :lineno-start: 12 - :language: py +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 12 + :lineno-start: 12 + :language: py Finally ``main`` is finished configuring things, so it uses the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application: - .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 13 - :lineno-start: 13 - :language: py +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 13 + :lineno-start: 13 + :language: py View declarations via the ``views`` package @@ -136,9 +136,9 @@ corresponding :term:`route`. Our application uses the Open ``tutorial/tutorial/views/default.py`` in the ``views`` package. It should already contain the following: - .. literalinclude:: src/basiclayout/tutorial/views/default.py - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/views/default.py + :linenos: + :language: py The important part here is that the ``@view_config`` decorator associates the function it decorates (``my_view``) with a :term:`view configuration`, @@ -181,9 +181,9 @@ scaffold put the classes that implement our models. First, open ``tutorial/tutorial/models/__init__.py``, which should already contain the following: - .. literalinclude:: src/basiclayout/tutorial/models/__init__.py - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/models/__init__.py + :linenos: + :language: py Our ``__init__.py`` will perform some imports to support later code, then calls the function :func:`sqlalchemy.orm.configure_mappers`. @@ -191,17 +191,17 @@ the function :func:`sqlalchemy.orm.configure_mappers`. Next open ``tutorial/tutorial/models/meta.py``, which should already contain the following: - .. literalinclude:: src/basiclayout/tutorial/models/meta.py - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/models/meta.py + :linenos: + :language: py ``meta.py`` contains imports that are used to support later code. We create a dictionary ``NAMING_CONVENTION`` as well. - .. literalinclude:: src/basiclayout/tutorial/models/meta.py - :end-before: metadata - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/models/meta.py + :end-before: metadata + :linenos: + :language: py Next we create a ``metadata`` object from the class :class:`sqlalchemy.schema.MetaData`, using ``NAMING_CONVENTION`` as the value @@ -210,60 +210,60 @@ for the ``naming_convention`` argument. We also need to create a declarative will inherit from the ``Base`` class so they can be associated with our particular database connection. - .. literalinclude:: src/basiclayout/tutorial/models/meta.py - :lines: 18-19 - :lineno-start: 18 - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/models/meta.py + :lines: 18-19 + :lineno-start: 18 + :linenos: + :language: py Next we define several functions, the first of which is ``includeme``, which configures various database settings by calling subsequently defined functions. - .. literalinclude:: src/basiclayout/tutorial/models/meta.py - :pyobject: includeme - :lineno-start: 22 - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/models/meta.py + :pyobject: includeme + :lineno-start: 22 + :linenos: + :language: py The function ``get_session`` registers a database session with a transaction manager, and returns a ``dbsession`` object. With the transaction manager, our application will automatically issue a transaction commit after every request unless an exception is raised, in which case the transaction will be aborted. - .. literalinclude:: src/basiclayout/tutorial/models/meta.py - :pyobject: get_session - :lineno-start: 35 - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/models/meta.py + :pyobject: get_session + :lineno-start: 35 + :linenos: + :language: py The ``get_engine`` function creates an :term:`SQLAlchemy` database engine using :func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.``-prefixed settings in the ``development.ini`` file's ``[app:main]`` section, which is a URI, something like ``sqlite://``. - .. literalinclude:: src/basiclayout/tutorial/models/meta.py - :pyobject: get_engine - :lineno-start: 42 - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/models/meta.py + :pyobject: get_engine + :lineno-start: 42 + :linenos: + :language: py The function ``get_dbmaker`` accepts an :term:`SQLAlchemy` database engine, and creates a database session object ``dbmaker`` from the :term:`SQLAlchemy` class :class:`sqlalchemy.orm.session.sessionmaker`, which is then used for creating a session with the database engine. - .. literalinclude:: src/basiclayout/tutorial/models/meta.py - :pyobject: get_dbmaker - :lineno-start: 46 - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/models/meta.py + :pyobject: get_dbmaker + :lineno-start: 46 + :linenos: + :language: py To give a simple example of a model class, we define one named ``MyModel``: - .. literalinclude:: src/basiclayout/tutorial/models/mymodel.py - :pyobject: MyModel - :linenos: - :language: py +.. literalinclude:: src/basiclayout/tutorial/models/mymodel.py + :pyobject: MyModel + :linenos: + :language: py Our example model does not require an ``__init__`` method because SQLAlchemy supplies for us a default constructor if one is not already present, which @@ -282,5 +282,5 @@ class. That's about all there is to it regarding models, views, and initialization code in our stock application. -The Index import and the Index object creation is not required for this -tutorial, and will be removed in the next step. +The ``Index`` import and the ``Index`` object creation is not required for +this tutorial, and will be removed in the next step. -- cgit v1.2.3 From 7b89a7e435b9edb4da6976e9185ae425717d4085 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 5 Feb 2016 01:00:49 -0600 Subject: update basiclayout prose --- docs/tutorials/wiki2/basiclayout.rst | 168 ++++++++++++++++++++--------------- 1 file changed, 98 insertions(+), 70 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index d55ce807f..976f12e90 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -29,6 +29,7 @@ later code: .. literalinclude:: src/basiclayout/tutorial/__init__.py :end-before: main :linenos: + :lineno-match: :language: py ``__init__.py`` defines a function named ``main``. Here is the entirety of @@ -36,9 +37,9 @@ the ``main`` function we've defined in our ``__init__.py``: .. literalinclude:: src/basiclayout/tutorial/__init__.py :pyobject: main - :lineno-start: 4 :linenos: - :language: py + :lineno-match: + :language: py When you invoke the ``pserve development.ini`` command, the ``main`` function above is executed. It accepts some settings and returns a :term:`WSGI` @@ -48,7 +49,7 @@ Next in ``main``, construct a :term:`Configurator` object: .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 7 - :lineno-start: 7 + :lineno-match: :language: py ``settings`` is passed to the Configurator as a keyword argument with the @@ -62,15 +63,15 @@ with the ``.jinja2`` extension within our project. .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 8 - :lineno-start: 8 + :lineno-match: :language: py -Next include the module ``meta`` from the package ``models`` using a dotted -Python path. +Next include the the package ``models`` using a dotted Python path. The +exact setup of the models will be covered later. .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 9 - :lineno-start: 9 + :lineno-match: :language: py ``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with @@ -78,7 +79,7 @@ two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 10 - :lineno-start: 10 + :lineno-match: :language: py This registers a static resource view which will match any URL that starts @@ -97,7 +98,7 @@ used when the URL is ``/``: .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 11 - :lineno-start: 11 + :lineno-match: :language: py Since this route has a ``pattern`` equaling ``/``, it is the route that will @@ -112,7 +113,7 @@ application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 12 - :lineno-start: 12 + :lineno-match: :language: py Finally ``main`` is finished configuring things, so it uses the @@ -178,25 +179,16 @@ In a SQLAlchemy-based application, a *model* object is an object composed by querying the SQL database. The ``models`` package is where the ``alchemy`` scaffold put the classes that implement our models. -First, open ``tutorial/tutorial/models/__init__.py``, which should already -contain the following: - -.. literalinclude:: src/basiclayout/tutorial/models/__init__.py - :linenos: - :language: py - -Our ``__init__.py`` will perform some imports to support later code, then calls -the function :func:`sqlalchemy.orm.configure_mappers`. - -Next open ``tutorial/tutorial/models/meta.py``, which should already contain +First, open ``tutorial/tutorial/models/meta.py``, which should already contain the following: .. literalinclude:: src/basiclayout/tutorial/models/meta.py :linenos: :language: py -``meta.py`` contains imports that are used to support later code. We create a -dictionary ``NAMING_CONVENTION`` as well. +``meta.py`` contains imports and support code for defining the models. We +create a dictionary ``NAMING_CONVENTION`` as well for consistent naming of +support objects like indices and constraints. .. literalinclude:: src/basiclayout/tutorial/models/meta.py :end-before: metadata @@ -205,82 +197,118 @@ dictionary ``NAMING_CONVENTION`` as well. Next we create a ``metadata`` object from the class :class:`sqlalchemy.schema.MetaData`, using ``NAMING_CONVENTION`` as the value -for the ``naming_convention`` argument. We also need to create a declarative -``Base`` object to use as a base class for our model. Then our model classes -will inherit from the ``Base`` class so they can be associated with our -particular database connection. +for the ``naming_convention`` argument. + +A ``MetaData`` object represents the table and other schema definitions for +a single database. We also need to create a declarative ``Base`` object to use +as a base class for our models. Our models will inherit from this ``Base`` +which will attach the tables to the ``metadata`` we created and define our +application's database schema. .. literalinclude:: src/basiclayout/tutorial/models/meta.py - :lines: 18-19 - :lineno-start: 18 + :lines: 15-16 + :lineno-match: :linenos: :language: py -Next we define several functions, the first of which is ``includeme``, which -configures various database settings by calling subsequently defined functions. +We've defined the ``models`` as a packge to make it straightforward to +define models separately in different modules. To give a simple example of a +model class, we define one named ``MyModel`` in a ``mymodel.py``: -.. literalinclude:: src/basiclayout/tutorial/models/meta.py - :pyobject: includeme - :lineno-start: 22 +.. literalinclude:: src/basiclayout/tutorial/models/mymodel.py + :pyobject: MyModel :linenos: :language: py -The function ``get_session`` registers a database session with a transaction -manager, and returns a ``dbsession`` object. With the transaction manager, our -application will automatically issue a transaction commit after every request -unless an exception is raised, in which case the transaction will be aborted. +Our example model does not require an ``__init__`` method because SQLAlchemy +supplies for us a default constructor if one is not already present, which +accepts keyword arguments of the same name as that of the mapped attributes. -.. literalinclude:: src/basiclayout/tutorial/models/meta.py - :pyobject: get_session - :lineno-start: 35 +.. note:: Example usage of MyModel: + + .. code-block:: python + + johnny = MyModel(name="John Doe", value=10) + +The ``MyModel`` class has a ``__tablename__`` attribute. This informs +SQLAlchemy which table to use to store the data representing instances of this +class. + +Finally, open ``tutorial/tutorial/models/__init__.py``, which should already +contain the following: + +.. literalinclude:: src/basiclayout/tutorial/models/__init__.py :linenos: :language: py -The ``get_engine`` function creates an :term:`SQLAlchemy` database engine using -:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.``-prefixed -settings in the ``development.ini`` file's ``[app:main]`` section, which is a -URI, something like ``sqlite://``. +Our ``models/__init__.py`` module defines the primary API we will use for +configuring the database connections within our application and it contains +several functions we will cover below. + +As we mentioned above, the purpose of the ``models.meta.metadata`` object is +to describe the schema of the database and this is done by defining models +that inherit from the ``Base`` attached to that ``metadata`` object. In +Python, code is only executed if it is imported and so to attach the +``models`` table, defined in ``mymodel.py`` to the ``metadata`` we must +import it. If we skip this step then later when we run ``metadata.create_all`` +the table will not be created because the ``metadata`` does not know about it! +Another important reason to import all of the models is that when +defining relationships between models they must all exist in order for +SQLAlchemy to find and build those internal mappings. This is why after +importing all the models we explicitly execute the function +:func:`sqlalchemy.orm.configure_mappers`, once we are sure all the models have +been defined and before we start creating connections. + +Next we define several functions for connecting to our database. The first +and lowest level is the ``get_engine`` function which creates an +:term:`SQLAlchemy` database engine using :func:`sqlalchemy.engine_from_config` +from the ``sqlalchemy.``-prefixed settings in the ``development.ini`` +file's ``[app:main]`` section, which is a URI (something like ``sqlite://``). -.. literalinclude:: src/basiclayout/tutorial/models/meta.py +.. literalinclude:: src/basiclayout/tutorial/models/__init__.py :pyobject: get_engine - :lineno-start: 42 + :lineno-match: :linenos: :language: py -The function ``get_dbmaker`` accepts an :term:`SQLAlchemy` database engine, -and creates a database session object ``dbmaker`` from the :term:`SQLAlchemy` +The function ``get_session_factory`` accepts an :term:`SQLAlchemy` database +engine, and creates a ``session_factory`` from the :term:`SQLAlchemy` class :class:`sqlalchemy.orm.session.sessionmaker`, which is then used for -creating a session with the database engine. +creating sessions bound to the database engine. -.. literalinclude:: src/basiclayout/tutorial/models/meta.py - :pyobject: get_dbmaker - :lineno-start: 46 +.. literalinclude:: src/basiclayout/tutorial/models/__init__.py + :pyobject: get_session_factory + :lineno-match: :linenos: :language: py -To give a simple example of a model class, we define one named ``MyModel``: +The function ``get_tm_session`` registers a database session with a transaction +manager, and returns a ``dbsession`` object. With the transaction manager, our +application will automatically issue a transaction commit after every request +unless an exception is raised, in which case the transaction will be aborted. -.. literalinclude:: src/basiclayout/tutorial/models/mymodel.py - :pyobject: MyModel +.. literalinclude:: src/basiclayout/tutorial/models/__init__.py + :pyobject: get_tm_session + :lineno-match: :linenos: :language: py -Our example model does not require an ``__init__`` method because SQLAlchemy -supplies for us a default constructor if one is not already present, which -accepts keyword arguments of the same name as that of the mapped attributes. - -.. note:: Example usage of MyModel: - - .. code-block:: python - - johnny = MyModel(name="John Doe", value=10) +Finally, we define an ``includeme`` function, which is a hook for use with +:meth:`pyramid.config.Configurator.include` to activate code in a Pyramid +application addon. It is the code that is executed above when we ran +``config.include('.models')`` in our application's ``main`` function. This +function will take the settings from the application, create an engine +and define a ``request.dbsession`` property which we can use to do work +on behalf of an incoming request to our application. -The ``MyModel`` class has a ``__tablename__`` attribute. This informs -SQLAlchemy which table to use to store the data representing instances of this -class. +.. literalinclude:: src/basiclayout/tutorial/models/__init__.py + :pyobject: includeme + :lineno-match: + :linenos: + :language: py That's about all there is to it regarding models, views, and initialization code in our stock application. -The ``Index`` import and the ``Index`` object creation is not required for -this tutorial, and will be removed in the next step. +The ``Index`` import and the ``Index`` object creation in ``mymodel.py`` is +not required for this tutorial, and will be removed in the next step. -- cgit v1.2.3 From 21d69fd97b66401264746bb7dad1e8d4bd2491b9 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 5 Feb 2016 01:09:11 -0600 Subject: link to create_all sqla method --- docs/tutorials/wiki2/basiclayout.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 976f12e90..6d1ff73a0 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -250,8 +250,10 @@ to describe the schema of the database and this is done by defining models that inherit from the ``Base`` attached to that ``metadata`` object. In Python, code is only executed if it is imported and so to attach the ``models`` table, defined in ``mymodel.py`` to the ``metadata`` we must -import it. If we skip this step then later when we run ``metadata.create_all`` -the table will not be created because the ``metadata`` does not know about it! +import it. If we skip this step then later when we run +:meth:`sqlalchemy.schema.MetaData.create_all` the table will not be created +because the ``metadata`` does not know about it! + Another important reason to import all of the models is that when defining relationships between models they must all exist in order for SQLAlchemy to find and build those internal mappings. This is why after -- cgit v1.2.3 From ab68f1f89a0a1602078bf1a99741d0635ce06dd0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 5 Feb 2016 01:28:18 -0800 Subject: minor grammar and punctuation tweaks, break up run-on sentences. --- docs/tutorials/wiki2/basiclayout.rst | 50 ++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 25 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 6d1ff73a0..3533bb455 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -201,8 +201,8 @@ for the ``naming_convention`` argument. A ``MetaData`` object represents the table and other schema definitions for a single database. We also need to create a declarative ``Base`` object to use -as a base class for our models. Our models will inherit from this ``Base`` -which will attach the tables to the ``metadata`` we created and define our +as a base class for our models. Our models will inherit from this ``Base``, +which will attach the tables to the ``metadata`` we created, and define our application's database schema. .. literalinclude:: src/basiclayout/tutorial/models/meta.py @@ -242,30 +242,30 @@ contain the following: :language: py Our ``models/__init__.py`` module defines the primary API we will use for -configuring the database connections within our application and it contains +configuring the database connections within our application, and it contains several functions we will cover below. As we mentioned above, the purpose of the ``models.meta.metadata`` object is -to describe the schema of the database and this is done by defining models -that inherit from the ``Base`` attached to that ``metadata`` object. In -Python, code is only executed if it is imported and so to attach the -``models`` table, defined in ``mymodel.py`` to the ``metadata`` we must -import it. If we skip this step then later when we run -:meth:`sqlalchemy.schema.MetaData.create_all` the table will not be created +to describe the schema of the database. This is done by defining models that +inherit from the ``Base`` attached to that ``metadata`` object. In Python, code +is only executed if it is imported, and so to attach the ``models`` table +defined in ``mymodel.py`` to the ``metadata``, we must import it. If we skip +this step, then later, when we run +:meth:`sqlalchemy.schema.MetaData.create_all`, the table will not be created because the ``metadata`` does not know about it! -Another important reason to import all of the models is that when -defining relationships between models they must all exist in order for -SQLAlchemy to find and build those internal mappings. This is why after -importing all the models we explicitly execute the function +Another important reason to import all of the models is that, when defining +relationships between models, they must all exist in order for SQLAlchemy to +find and build those internal mappings. This is why, after importing all the +models, we explicitly execute the function :func:`sqlalchemy.orm.configure_mappers`, once we are sure all the models have been defined and before we start creating connections. -Next we define several functions for connecting to our database. The first -and lowest level is the ``get_engine`` function which creates an -:term:`SQLAlchemy` database engine using :func:`sqlalchemy.engine_from_config` -from the ``sqlalchemy.``-prefixed settings in the ``development.ini`` -file's ``[app:main]`` section, which is a URI (something like ``sqlite://``). +Next we define several functions for connecting to our database. The first and +lowest level is the ``get_engine`` function. This creates an :term:`SQLAlchemy` +database engine using :func:`sqlalchemy.engine_from_config` from the +``sqlalchemy.``-prefixed settings in the ``development.ini`` file's +``[app:main]`` section. This setting is a URI (something like ``sqlite://``). .. literalinclude:: src/basiclayout/tutorial/models/__init__.py :pyobject: get_engine @@ -274,9 +274,9 @@ file's ``[app:main]`` section, which is a URI (something like ``sqlite://``). :language: py The function ``get_session_factory`` accepts an :term:`SQLAlchemy` database -engine, and creates a ``session_factory`` from the :term:`SQLAlchemy` -class :class:`sqlalchemy.orm.session.sessionmaker`, which is then used for -creating sessions bound to the database engine. +engine, and creates a ``session_factory`` from the :term:`SQLAlchemy` class +:class:`sqlalchemy.orm.session.sessionmaker`. This ``session_factory`` is then +used for creating sessions bound to the database engine. .. literalinclude:: src/basiclayout/tutorial/models/__init__.py :pyobject: get_session_factory @@ -286,7 +286,7 @@ creating sessions bound to the database engine. The function ``get_tm_session`` registers a database session with a transaction manager, and returns a ``dbsession`` object. With the transaction manager, our -application will automatically issue a transaction commit after every request +application will automatically issue a transaction commit after every request, unless an exception is raised, in which case the transaction will be aborted. .. literalinclude:: src/basiclayout/tutorial/models/__init__.py @@ -297,10 +297,10 @@ unless an exception is raised, in which case the transaction will be aborted. Finally, we define an ``includeme`` function, which is a hook for use with :meth:`pyramid.config.Configurator.include` to activate code in a Pyramid -application addon. It is the code that is executed above when we ran +application add-on. It is the code that is executed above when we ran ``config.include('.models')`` in our application's ``main`` function. This -function will take the settings from the application, create an engine -and define a ``request.dbsession`` property which we can use to do work +function will take the settings from the application, create an engine, +and define a ``request.dbsession`` property, which we can use to do work on behalf of an incoming request to our application. .. literalinclude:: src/basiclayout/tutorial/models/__init__.py -- cgit v1.2.3 From d1cb34643e086ac74965455b486ce0058764324f Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sun, 7 Feb 2016 13:57:51 -0600 Subject: assume the user is in the tutorial folder this is already assumed inside of installation where commands are run relative to setup.py --- docs/tutorials/wiki2/basiclayout.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 6d1ff73a0..eb315d2cb 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -16,7 +16,7 @@ package. We use ``__init__.py`` both as a marker, indicating the directory in which it's contained is a package, and to contain application configuration code. -Open ``tutorial/tutorial/__init__.py``. It should already contain the +Open ``tutorial/__init__.py``. It should already contain the following: .. literalinclude:: src/basiclayout/tutorial/__init__.py @@ -134,7 +134,7 @@ The main function of a web framework is mapping each URL pattern to code (a corresponding :term:`route`. Our application uses the :meth:`pyramid.view.view_config` decorator to perform this mapping. -Open ``tutorial/tutorial/views/default.py`` in the ``views`` package. It +Open ``tutorial/views/default.py`` in the ``views`` package. It should already contain the following: .. literalinclude:: src/basiclayout/tutorial/views/default.py @@ -179,7 +179,7 @@ In a SQLAlchemy-based application, a *model* object is an object composed by querying the SQL database. The ``models`` package is where the ``alchemy`` scaffold put the classes that implement our models. -First, open ``tutorial/tutorial/models/meta.py``, which should already contain +First, open ``tutorial/models/meta.py``, which should already contain the following: .. literalinclude:: src/basiclayout/tutorial/models/meta.py @@ -234,7 +234,7 @@ The ``MyModel`` class has a ``__tablename__`` attribute. This informs SQLAlchemy which table to use to store the data representing instances of this class. -Finally, open ``tutorial/tutorial/models/__init__.py``, which should already +Finally, open ``tutorial/models/__init__.py``, which should already contain the following: .. literalinclude:: src/basiclayout/tutorial/models/__init__.py -- cgit v1.2.3 From da5ebc28c38ea32ad99389b5bc23e2f847af8047 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Sun, 14 Feb 2016 17:40:03 -0600 Subject: split routes into a separate module --- docs/tutorials/wiki2/basiclayout.rst | 64 ++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 25 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 485d38047..1ae51eb93 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -74,35 +74,19 @@ exact setup of the models will be covered later. :lineno-match: :language: py -``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with -two arguments: ``static`` (the name), and ``static`` (the path): +Next include the ``routes`` module using a dotted Python path. This module +will be explained in the next section. .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 10 :lineno-match: :language: py -This registers a static resource view which will match any URL that starts -with the prefix ``/static`` (by virtue of the first argument to -``add_static_view``). 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 (by virtue of the second argument -to ``add_static_view``). 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 ``main`` also registers 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: 11 - :lineno-match: - :language: py +.. note:: -Since this route has a ``pattern`` equaling ``/``, it is the route that will -be matched when the URL ``/`` is visited, e.g., ``http://localhost:6543/``. + Pyramid's :meth:`pyramid.config.Configurator.include` method is the + primary mechanism for extending the configurator and breaking your code + into feature-focused modules. ``main`` next calls the ``scan`` method of the configurator (:meth:`pyramid.config.Configurator.scan`), which will recursively scan our @@ -112,7 +96,7 @@ view configuration will be registered, which will allow one of our application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 12 + :lines: 11 :lineno-match: :language: py @@ -121,11 +105,41 @@ Finally ``main`` is finished configuring things, so it uses the :term:`WSGI` application: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 13 - :lineno-start: 13 + :lines: 12 + :lineno-match: :language: py +Route declarations +------------------ + +Open the ``tutorials/routes.py`` file. It should already contain the +following: + +.. literalinclude:: src/basiclayout/tutorial/routes.py + :linenos: + :language: py + +First, on line 2, call :meth:`pyramid.config.Configurator.add_static_view` +with two arguments: ``static`` (the name), and ``static`` (the path). + +This registers a static resource view which will match any URL that starts +with the prefix ``/static`` (by virtue of the first argument to +``add_static_view``). 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 (by virtue of the second argument +to ``add_static_view``). 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. + +Second, on line 3, the module registers 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`` equaling +``/``, it is the route that will be matched when the URL ``/`` is visited, +e.g., ``http://localhost:6543/``. + + View declarations via the ``views`` package ------------------------------------------- -- cgit v1.2.3 From 4f87e545ed9596b9be5ca5958e80be55dba28a87 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 22 Feb 2016 00:58:03 -0800 Subject: update basiclayout - minor grammar and syntax - insert complete mymodel.py code --- docs/tutorials/wiki2/basiclayout.rst | 126 ++++++++++++++++++----------------- 1 file changed, 66 insertions(+), 60 deletions(-) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 1ae51eb93..1310e0969 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -16,15 +16,14 @@ package. We use ``__init__.py`` both as a marker, indicating the directory in which it's contained is a package, and to contain application configuration code. -Open ``tutorial/__init__.py``. It should already contain the -following: +Open ``tutorial/__init__.py``. It should already contain the following: .. literalinclude:: src/basiclayout/tutorial/__init__.py :linenos: :language: py -Let's go over this piece-by-piece. First, we need some imports to support -later code: +Let's go over this piece-by-piece. First we need some imports to support later +code: .. literalinclude:: src/basiclayout/tutorial/__init__.py :end-before: main @@ -52,10 +51,10 @@ Next in ``main``, construct a :term:`Configurator` object: :lineno-match: :language: py -``settings`` is passed to the Configurator as a keyword argument with the -dictionary values passed as the ``**settings`` argument. This will be a +``settings`` is passed to the ``Configurator`` as a keyword argument with the +dictionary values passed as the ``**settings`` argument. This will be a dictionary of settings parsed from the ``.ini`` file, which contains -deployment-related values such as ``pyramid.reload_templates``, +deployment-related values, such as ``pyramid.reload_templates``, ``sqlalchemy.url``, and so on. Next include :term:`Jinja2` templating bindings so that we can use renderers @@ -66,16 +65,16 @@ with the ``.jinja2`` extension within our project. :lineno-match: :language: py -Next include the the package ``models`` using a dotted Python path. The -exact setup of the models will be covered later. +Next include the the package ``models`` using a dotted Python path. The exact +setup of the models will be covered later. .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 9 :lineno-match: :language: py -Next include the ``routes`` module using a dotted Python path. This module -will be explained in the next section. +Next include the ``routes`` module using a dotted Python path. This module will +be explained in the next section. .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 10 @@ -84,16 +83,16 @@ will be explained in the next section. .. note:: - Pyramid's :meth:`pyramid.config.Configurator.include` method is the - primary mechanism for extending the configurator and breaking your code - into feature-focused modules. + Pyramid's :meth:`pyramid.config.Configurator.include` method is the primary + mechanism for extending the configurator and breaking your code into + feature-focused modules. ``main`` next calls the ``scan`` method of the configurator (:meth:`pyramid.config.Configurator.scan`), which will recursively scan our -``tutorial`` package, looking for ``@view_config`` (and -other special) decorators. When it finds a ``@view_config`` decorator, a -view configuration will be registered, which will allow one of our -application URLs to be mapped to some code. +``tutorial`` package, looking for ``@view_config`` and other special +decorators. When it finds a ``@view_config`` decorator, a view configuration +will be registered, allowing one of our application URLs to be mapped to some +code. .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 11 @@ -113,31 +112,31 @@ Finally ``main`` is finished configuring things, so it uses the Route declarations ------------------ -Open the ``tutorials/routes.py`` file. It should already contain the -following: +Open the ``tutorials/routes.py`` file. It should already contain the following: .. literalinclude:: src/basiclayout/tutorial/routes.py :linenos: :language: py -First, on line 2, call :meth:`pyramid.config.Configurator.add_static_view` -with two arguments: ``static`` (the name), and ``static`` (the path). +On line 2, we call :meth:`pyramid.config.Configurator.add_static_view` with +three arguments: ``static`` (the name), ``static`` (the path), and +``cache_max_age`` (a keyword argument). This registers a static resource view which will match any URL that starts with the prefix ``/static`` (by virtue of the first argument to -``add_static_view``). This will serve up static resources for us from within -the ``static`` directory of our ``tutorial`` package, in this case, via +``add_static_view``). 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 (by virtue of the second argument to ``add_static_view``). 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 +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. -Second, on line 3, the module registers 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`` equaling -``/``, it is the route that will be matched when the URL ``/`` is visited, -e.g., ``http://localhost:6543/``. +On line 3, the module registers 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`` equaling ``/``, it is the +route that will be matched when the URL ``/`` is visited, e.g., +``http://localhost:6543/``. View declarations via the ``views`` package @@ -148,15 +147,15 @@ The main function of a web framework is mapping each URL pattern to code (a corresponding :term:`route`. Our application uses the :meth:`pyramid.view.view_config` decorator to perform this mapping. -Open ``tutorial/views/default.py`` in the ``views`` package. It -should already contain the following: +Open ``tutorial/views/default.py`` in the ``views`` package. It should already +contain the following: .. literalinclude:: src/basiclayout/tutorial/views/default.py :linenos: :language: py The important part here is that the ``@view_config`` decorator associates the -function it decorates (``my_view``) with a :term:`view configuration`, +function it decorates (``my_view``) with a :term:`view configuration`, consisting of: * a ``route_name`` (``home``) @@ -172,12 +171,11 @@ Note that ``my_view()`` accepts a single argument named ``request``. This is the standard call signature for a Pyramid :term:`view callable`. Remember in our ``__init__.py`` when we executed the -:meth:`pyramid.config.Configurator.scan` method ``config.scan()``? The -purpose of calling the scan method was to find and process this -``@view_config`` decorator in order to create a view configuration within our -application. Without being processed by ``scan``, the decorator effectively -does nothing. ``@view_config`` is inert without being detected via a -:term:`scan`. +:meth:`pyramid.config.Configurator.scan` method ``config.scan()``? The purpose +of calling the scan method was to find and process this ``@view_config`` +decorator in order to create a view configuration within our application. +Without being processed by ``scan``, the decorator effectively does nothing. +``@view_config`` is inert without being detected via a :term:`scan`. The sample ``my_view()`` created by the scaffold uses a ``try:`` and ``except:`` clause to detect if there is a problem accessing the project @@ -189,12 +187,12 @@ to inform the user about possible actions to take to solve the problem. Content models with the ``models`` package ------------------------------------------ -In a SQLAlchemy-based application, a *model* object is an object composed by +In an SQLAlchemy-based application, a *model* object is an object composed by querying the SQL database. The ``models`` package is where the ``alchemy`` scaffold put the classes that implement our models. -First, open ``tutorial/models/meta.py``, which should already contain -the following: +First, open ``tutorial/models/meta.py``, which should already contain the +following: .. literalinclude:: src/basiclayout/tutorial/models/meta.py :linenos: @@ -213,10 +211,10 @@ Next we create a ``metadata`` object from the class :class:`sqlalchemy.schema.MetaData`, using ``NAMING_CONVENTION`` as the value for the ``naming_convention`` argument. -A ``MetaData`` object represents the table and other schema definitions for -a single database. We also need to create a declarative ``Base`` object to use -as a base class for our models. Our models will inherit from this ``Base``, -which will attach the tables to the ``metadata`` we created, and define our +A ``MetaData`` object represents the table and other schema definitions for a +single database. We also need to create a declarative ``Base`` object to use as +a base class for our models. Our models will inherit from this ``Base``, which +will attach the tables to the ``metadata`` we created, and define our application's database schema. .. literalinclude:: src/basiclayout/tutorial/models/meta.py @@ -225,17 +223,25 @@ application's database schema. :linenos: :language: py -We've defined the ``models`` as a packge to make it straightforward to -define models separately in different modules. To give a simple example of a -model class, we define one named ``MyModel`` in a ``mymodel.py``: +Next open ``tutorial/models/mymodel.py``, which should already contain the +following: + +.. literalinclude:: src/basiclayout/tutorial/models/mymodel.py + :linenos: + :language: py + +Notice we've defined the ``models`` as a package to make it straightforward for +defining models in separate modules. To give a simple example of a model class, +we have defined one named ``MyModel`` in ``mymodel.py``: .. literalinclude:: src/basiclayout/tutorial/models/mymodel.py :pyobject: MyModel + :lineno-match: :linenos: :language: py Our example model does not require an ``__init__`` method because SQLAlchemy -supplies for us a default constructor if one is not already present, which +supplies for us a default constructor, if one is not already present, which accepts keyword arguments of the same name as that of the mapped attributes. .. note:: Example usage of MyModel: @@ -259,14 +265,14 @@ Our ``models/__init__.py`` module defines the primary API we will use for configuring the database connections within our application, and it contains several functions we will cover below. -As we mentioned above, the purpose of the ``models.meta.metadata`` object is -to describe the schema of the database. This is done by defining models that -inherit from the ``Base`` attached to that ``metadata`` object. In Python, code -is only executed if it is imported, and so to attach the ``models`` table -defined in ``mymodel.py`` to the ``metadata``, we must import it. If we skip -this step, then later, when we run +As we mentioned above, the purpose of the ``models.meta.metadata`` object is to +describe the schema of the database. This is done by defining models that +inherit from the ``Base`` object attached to that ``metadata`` object. In +Python, code is only executed if it is imported, and so to attach the +``models`` table defined in ``mymodel.py`` to the ``metadata``, we must import +it. If we skip this step, then later, when we run :meth:`sqlalchemy.schema.MetaData.create_all`, the table will not be created -because the ``metadata`` does not know about it! +because the ``metadata`` object does not know about it! Another important reason to import all of the models is that, when defining relationships between models, they must all exist in order for SQLAlchemy to @@ -313,9 +319,9 @@ Finally, we define an ``includeme`` function, which is a hook for use with :meth:`pyramid.config.Configurator.include` to activate code in a Pyramid application add-on. It is the code that is executed above when we ran ``config.include('.models')`` in our application's ``main`` function. This -function will take the settings from the application, create an engine, -and define a ``request.dbsession`` property, which we can use to do work -on behalf of an incoming request to our application. +function will take the settings from the application, create an engine, and +define a ``request.dbsession`` property, which we can use to do work on behalf +of an incoming request to our application. .. literalinclude:: src/basiclayout/tutorial/models/__init__.py :pyobject: includeme -- cgit v1.2.3 From 640d7779b69f49ab11d7e276a7548684524bc215 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 9 Apr 2016 13:36:11 -0700 Subject: - add intersphinx targets --- docs/tutorials/wiki2/basiclayout.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/tutorials/wiki2/basiclayout.rst') diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 1310e0969..ce67bb9e3 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -1,3 +1,5 @@ +.. _wiki2_basic_layout: + ============ Basic Layout ============ -- cgit v1.2.3