From 29d6b3b030b0a0a60415dd3fe7e39c7c9b28b189 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 18:00:45 -0800 Subject: Clean up application configuration in __init__.py --- docs/tutorials/wiki/basiclayout.rst | 105 ++++++++++++++++++------------------ 1 file changed, 53 insertions(+), 52 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 49ee6902e..f2c6dbb37 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -4,80 +4,81 @@ Basic Layout ============ -The starter files generated by selecting the ``zodb`` backend in the -cookiecutter are very basic, but they provide a good orientation for the -high-level patterns common to most :term:`traversal`-based (and -:term:`ZODB`-based) :app:`Pyramid` projects. +The starter files generated by the cookiecutter are very basic, but they provide a good orientation for the high-level patterns common to most :term:`traversal`-based (and :term:`ZODB`-based) :app:`Pyramid` projects. 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 -code. +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 is contained is a package, and to contain application configuration code. -When you run the application using the ``pserve`` command using the -``development.ini`` generated configuration file, the application -configuration points at a :term:`Setuptools` :term:`entry point` described as -``egg:tutorial``. In our application, because the application's ``setup.py`` -file says so, this entry point happens to be the ``main`` function within the -file named ``__init__.py``. +When you run the application using the ``pserve`` command using the ``development.ini`` generated configuration file, the application configuration points at a :term:`Setuptools` :term:`entry point` described as ``egg:tutorial``. +In our application, because the application's ``setup.py`` file says so, this entry point happens to be the ``main`` function within the file named ``__init__.py``. -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 + :linenos: + :language: py + +#. *Lines 1-3*. + Perform some dependency imports. + +#. *Lines 6-8*. + Define a :term:`root factory` for our Pyramid application. + +#. *Line 11*. + ``__init__.py`` defines a function named ``main``. -#. *Lines 1-3*. Perform some dependency imports. +#. *Line 14*. + Construct a :term:`Configurator` as a :term:`context manager` with the ``settings`` keyword parsed by :term:`PasteDeploy`. See :term:`Deployment settings`. -#. *Lines 6-8*. Define a :term:`root factory` for our Pyramid application. +#. *Line 15*. + Use an explicit transaction manager for apps so that they do not implicitly create new transactions when touching the manager outside of the ``pyramid_tm`` lifecycle. -#. *Line 11*. ``__init__.py`` defines a function named ``main``. +#. *Line 16*. + Include support for ``pyramid_tm``, allowing Pyramid requests to join the active transaction as provided by the `transaction `_ package. -#. *Line 14*. Use an explicit transaction manager for apps so that they do not implicitly create new transactions when touching the manager outside of the ``pyramid_tm`` lifecycle. +#. *Line 17*. + Include support for ``pyramid_retry`` to retry a request when transient exceptions occur. -#. *Line 15*. Construct a :term:`Configurator` as a :term:`context manager` with the settings keyword parsed by :term:`PasteDeploy`. +#. *Line 18*. + Include support for ``pyramid_zodbconn``, providing integration between :term:`ZODB` and a Pyramid application. -#. *Line 16*. Include support for the :term:`Chameleon` template rendering - bindings, allowing us to use the ``.pt`` templates. +#. *Line 19*. + Set a root factory using our function named ``root_factory``. -#. *Line 17*. Include support for ``pyramid_tm``, allowing Pyramid requests to join the active transaction as provided by the `transaction `_ package. +#. *Line 20*. + Include support for the :term:`Chameleon` template rendering bindings, allowing us to use the ``.pt`` templates. -#. *Line 18*. Include support for ``pyramid_retry`` to retry a request when transient exceptions occur. +#. *Line 21*. + Include routes from the ``.routes`` module. + This registers a "static view" using the :meth:`pyramid.config.Configurator.add_static_view` method. + This view answers requests whose URL path starts with ``/static``. + This statement registers a view that will serve up static assets, such as CSS and image files. + In this case the URL will answer requests at ``http://localhost:6543/static/`` and below. -#. *Line 19*. Include support for ``pyramid_zodbconn``, providing integration between :term:`ZODB` and a Pyramid application. + The first argument is the "name" ``static``, which indicates that the URL path prefix of the view will be ``/static``. -#. *Line 20*. Set a root factory using our function named ``root_factory``. + The second argument of this method is the "path". + It is a relative :term:`asset specification`. + It finds the resources it should serve within the ``static`` directory inside the ``tutorial`` package. + Alternatively the cookiecutter could have used an *absolute* asset specification as the path (``tutorial:static``). -#. *Line 21*. Register a "static view", which answers requests whose URL - paths start with ``/static``, using the - :meth:`pyramid.config.Configurator.add_static_view` method. This - statement registers a view that will serve up static assets, such as CSS - and image files, for us, in this case, at - ``http://localhost:6543/static/`` and below. The first argument is the - "name" ``static``, which indicates that the URL path prefix of the view - will be ``/static``. The second argument of this tag is the "path", - which is a relative :term:`asset specification`, so it finds the resources - it should serve within the ``static`` directory inside the ``tutorial`` - package. Alternatively the cookiecutter could have used an *absolute* asset - specification as the path (``tutorial:static``). + The third argument is an optional ``cache_max_age`` which specifies the number of seconds the static asset will be HTTP-cached. -#. *Line 22*. Perform a :term:`scan`. A scan will find :term:`configuration - decoration`, such as view configuration decorators (e.g., ``@view_config``) - in the source code of the ``tutorial`` package and will take actions based - on these decorators. We don't pass any arguments to - :meth:`~pyramid.config.Configurator.scan`, which implies that the scan - should take place in the current package (in this case, ``tutorial``). - The cookiecutter could have equivalently said ``config.scan('tutorial')``, but - it chose to omit the package name argument. +#. *Line 22*. + Perform a :term:`scan`. + A scan will find :term:`configuration decoration`, such as view configuration decorators (e.g., ``@view_config``) in the source code of the ``tutorial`` package. + It will take actions based on these decorators. + We don't pass any arguments to :meth:`~pyramid.config.Configurator.scan`, which implies that the scan should take place in the current package (in this case, ``tutorial``). + The cookiecutter could have equivalently said ``config.scan('tutorial')``, but it chose to omit the package name argument. -#. *Line 23*. Use the - :meth:`pyramid.config.Configurator.make_wsgi_app` method - to return a :term:`WSGI` application. +#. *Line 23*. + Use the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application. Resources and models with ``models.py`` --------------------------------------- -- cgit v1.2.3 From 9c1091c692c7c05ae9d6c1b8f9a8f83720ed8401 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 18:01:15 -0800 Subject: Clean up models, now in a package --- docs/tutorials/wiki/basiclayout.rst | 53 +++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 29 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index f2c6dbb37..83225c6e1 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -80,42 +80,37 @@ It should already contain the following: #. *Line 23*. Use the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application. -Resources and models with ``models.py`` ---------------------------------------- - -:app:`Pyramid` uses the word :term:`resource` to describe objects arranged -hierarchically in a :term:`resource tree`. This tree is consulted by -:term:`traversal` to map URLs to code. In this application, the resource -tree represents the site structure, but it *also* represents the -:term:`domain model` of the application, because each resource is a node -stored persistently in a :term:`ZODB` database. The ``models.py`` file is -where the ``zodb`` cookiecutter put the classes that implement our -resource objects, each of which also happens to be a domain model object. + +Resources and models with ``models`` package +-------------------------------------------- + +:app:`Pyramid` uses the word :term:`resource` to describe objects arranged hierarchically in a :term:`resource tree`. +This tree is consulted by :term:`traversal` to map URLs to code. +In this application, the resource tree represents the site structure, but it *also* represents the :term:`domain model` of the application. +Each resource is a node stored persistently in a :term:`ZODB` database. +The ``models.py`` file is where the ``zodb`` cookiecutter put the classes that implement our resource objects, each of which also happens to be a domain model object. Here is the source for ``models.py``: -.. literalinclude:: src/basiclayout/tutorial/models.py +.. literalinclude:: src/basiclayout/tutorial/models/__init__.py :linenos: :language: python -#. *Lines 4-5*. The ``MyModel`` :term:`resource` class is implemented here. - Instances of this class are capable of being persisted in :term:`ZODB` - because the class inherits from the - :class:`persistent.mapping.PersistentMapping` class. The ``__parent__`` - and ``__name__`` are important parts of the :term:`traversal` protocol. - By default, set these to ``None`` to indicate that this is the - :term:`root` object. - -#. *Lines 8-12*. ``appmaker`` is used to return the *application - root* object. It is called on *every request* to the - :app:`Pyramid` application. It also performs bootstrapping by - *creating* an application root (inside the ZODB root object) if one - does not already exist. It is used by the ``root_factory`` we've defined - in our ``__init__.py``. +#. *Lines 4-5*. + The ``MyModel`` :term:`resource` class is implemented here. + Instances of this class are capable of being persisted in :term:`ZODB` because the class inherits from the :class:`persistent.mapping.PersistentMapping` class. + The ``__parent__`` and ``__name__`` are important parts of the :term:`traversal` protocol. + By default, set these to ``None`` to indicate that this is the :term:`root` object. + +#. *Lines 8-12*. + ``appmaker`` is used to return the *application root* object. + It is called on *every request* to the :app:`Pyramid` application. + It also performs bootstrapping by *creating* an application root (inside the ZODB root object) if one does not already exist. + It is used by the ``root_factory`` we've defined in our ``__init__.py``. - Bootstrapping is done by first seeing if the database has the persistent - application root. If not, we make an instance, store it, and commit the - transaction. We then return the application root object. + Bootstrapping is done by first seeing if the database has the persistent application root. + If not, we make an instance, store it, and commit the transaction. + We then return the application root object. Views With ``views.py`` ----------------------- -- cgit v1.2.3 From b770c31e5713b33f7d77e22a6dc1ddb530d00b9c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 18:01:25 -0800 Subject: Clean up views, now in a package --- docs/tutorials/wiki/basiclayout.rst | 96 +++++++++++++++++-------------------- 1 file changed, 45 insertions(+), 51 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 83225c6e1..a1a1da286 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -112,63 +112,57 @@ Here is the source for ``models.py``: If not, we make an instance, store it, and commit the transaction. We then return the application root object. -Views With ``views.py`` ------------------------ -Our cookiecutter generated a default ``views.py`` on our behalf. It -contains a single view, which is used to render the page shown when you visit -the URL ``http://localhost:6543/``. +View declarations via the ``views`` package +------------------------------------------- -Here is the source for ``views.py``: +Our cookiecutter generated a default ``views`` package on our behalf. +It contains a two views. +which is used to render the page shown when you visit the URL ``http://localhost:6543/``. -.. literalinclude:: src/basiclayout/tutorial/views.py - :linenos: - :language: python +Open ``tutorial/views/default.py`` in the ``views`` package. +It should already contain the following: + +.. literalinclude:: src/basiclayout/tutorial/views/default.py + :linenos: + :language: python Let's try to understand the components in this module: -#. *Lines 1-2*. Perform some dependency imports. - -#. *Line 5*. Use the :func:`pyramid.view.view_config` :term:`configuration - decoration` to perform a :term:`view configuration` registration. This - view configuration registration will be activated when the application is - started. It will be activated by virtue of it being found as the result - of a :term:`scan` (when Line 14 of ``__init__.py`` is run). - - The ``@view_config`` decorator accepts a number of keyword arguments. We - use two keyword arguments here: ``context`` and ``renderer``. - - The ``context`` argument signifies that the decorated view callable should - only be run when :term:`traversal` finds the ``tutorial.models.MyModel`` - :term:`resource` to be the :term:`context` of a request. In English, this - means that when the URL ``/`` is visited, because ``MyModel`` is the root - model, this view callable will be invoked. - - The ``renderer`` argument names an :term:`asset specification` of - ``templates/mytemplate.pt``. This asset specification points at a - :term:`Chameleon` template which lives in the ``mytemplate.pt`` file - within the ``templates`` directory of the ``tutorial`` package. And - indeed if you look in the ``templates`` directory of this package, you'll - see a ``mytemplate.pt`` template file, which renders the default home page - of the generated project. This asset specification is *relative* (to the - view.py's current package). Alternatively we could have used the - absolute asset specification ``tutorial:templates/mytemplate.pt``, but - chose to use the relative version. - - Since this call to ``@view_config`` doesn't pass a ``name`` argument, the - ``my_view`` function which it decorates represents the "default" view - callable used when the context is of the type ``MyModel``. - -#. *Lines 6-7*. We define a :term:`view callable` named ``my_view``, which - we decorated in the step above. This view callable is a *function* we - write generated by the ``zodb`` cookiecutter that is given a - ``request`` and which returns a dictionary. The ``mytemplate.pt`` - :term:`renderer` named by the asset specification in the step above will - convert this dictionary to a :term:`response` on our behalf. - - The function returns the dictionary ``{'project':'tutorial'}``. This - dictionary is used by the template named by the ``mytemplate.pt`` asset - specification to fill in certain values on the page. +#. *Lines 1-3*. + Perform some dependency imports. + +#. *Line 6*. + Use the :func:`pyramid.view.view_config` :term:`configuration decoration` to perform a :term:`view configuration` registration. + This view configuration registration will be activated when the application is started. + Remember in our application's ``__init__.py`` when we executed the :meth:`pyramid.config.Configurator.scan` method ``config.scan()``? + By calling the scan method, Pyramid's configurator will find and process this ``@view_config`` decorator, and 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 ``@view_config`` decorator accepts a number of keyword arguments. + We use two keyword arguments here: ``context`` and ``renderer``. + + The ``context`` argument signifies that the decorated view callable ``my_view`` should only be run when :term:`traversal` finds the ``tutorial.models.MyModel`` :term:`resource` as the :term:`context` of a request. + In English this means that when the URL ``/`` is visited, and because ``MyModel`` is the root model, this view callable will be invoked. + + The ``renderer`` argument names an :term:`asset specification` of ``templates/mytemplate.pt``. + This asset specification points at a :term:`Chameleon` template which lives in the ``mytemplate.pt`` file within the ``templates`` directory of the ``tutorial`` package. + And indeed if you look in the ``templates`` directory of this package, you will see a ``mytemplate.pt`` template file + This template renders the default home page of the generated project. + This asset specification is *relative* to the ``views`` package. + Alternatively we could have used the absolute asset specification ``tutorial:templates/mytemplate.pt``. + + Since this call to ``@view_config`` doesn't pass a ``name`` argument, the ``my_view`` function which it decorates represents the "default" view callable used when the context is of the type ``MyModel``. + +#. *Lines 7-8*. + A :term:`view callable` named ``my_view`` is defined, which is decorated in the step above. + This view callable is a *function* generated by the cookiecutter. + It is given a single argument, ``request``. + This is the standard call signature for a Pyramid :term:`view callable`. + The function returns the dictionary ``{'project': 'myproj'}``. + This dictionary is used by the template named by the ``mytemplate.pt`` asset specification to fill in certain values on the page. + Configuration in ``development.ini`` ------------------------------------ -- cgit v1.2.3 From a4b1059b4c92f8b25486159cc650a8a94cd62772 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 18:33:46 -0800 Subject: Rewrite application configuration to mirror the URL-dispatch + SQLAlchemy wiki style --- docs/tutorials/wiki/basiclayout.rst | 160 +++++++++++++++++++++++++++--------- 1 file changed, 120 insertions(+), 40 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index a1a1da286..33e0b4ff3 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -24,62 +24,132 @@ It should already contain the following: :linenos: :language: py -#. *Lines 1-3*. - Perform some dependency imports. +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: root_factory + :lineno-match: + :language: py + +Define a :term:`root factory` for our Pyramid application. +It establishes a connection to ZODB database. +It returns an ``appmaker``, which we will describe in the next section :ref:`wiki-resources-and-models`. + +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :pyobject: root_factory + :lineno-match: + :language: py + +``__init__.py`` defines a function named ``main``. +Here is the entirety of the ``main`` function that we have defined in our ``__init__.py``: + +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :pyobject: main + :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` application. +See :ref:`startup_chapter` for more about ``pserve``. + +Next in ``main``, construct a :term:`Configurator` object using a context manager. +See also :term:`Deployment settings`. + +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 14 + :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 dictionary of settings parsed from the ``.ini`` file, which contains +deployment-related values, such as ``pyramid.reload_templates``, ``zodbconn.uri``, and so on. + +Next use an explicit transaction manager for our application. +This prevents new transactions from being implicitly created when touching the manager outside of the ``pyramid_tm`` lifecycle. + +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 15 + :lineno-match: + :language: py + +Next include support for ``pyramid_tm``, allowing Pyramid requests to join the active transaction as provided by the `transaction `_ package. + +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 16 + :lineno-match: + :language: py + +Next include support for ``pyramid_retry`` to retry a request when transient exceptions occur. -#. *Lines 6-8*. - Define a :term:`root factory` for our Pyramid application. +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 17 + :lineno-match: + :language: py -#. *Line 11*. - ``__init__.py`` defines a function named ``main``. +Next include support for ``pyramid_zodbconn``, providing integration between :term:`ZODB` and a Pyramid application. + +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 18 + :lineno-match: + :language: py -#. *Line 14*. - Construct a :term:`Configurator` as a :term:`context manager` with the ``settings`` keyword parsed by :term:`PasteDeploy`. See :term:`Deployment settings`. +Next set a root factory using our function named ``root_factory``. + +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 19 + :lineno-match: + :language: py + +Next include support for the :term:`Chameleon` template rendering bindings, allowing us to use the ``.pt`` templates. + +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 20 + :lineno-match: + :language: py -#. *Line 15*. - Use an explicit transaction manager for apps so that they do not implicitly create new transactions when touching the manager outside of the ``pyramid_tm`` lifecycle. +Next include routes from the ``.routes`` module. -#. *Line 16*. - Include support for ``pyramid_tm``, allowing Pyramid requests to join the active transaction as provided by the `transaction `_ package. +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 21 + :lineno-match: + :language: py -#. *Line 17*. - Include support for ``pyramid_retry`` to retry a request when transient exceptions occur. +This registers a "static view" using the :meth:`pyramid.config.Configurator.add_static_view` method. +This view answers requests whose URL path starts with ``/static``. +This statement registers a view that will serve up static assets, such as CSS and image files. +In this case the URL will answer requests at ``http://localhost:6543/static/`` and below. -#. *Line 18*. - Include support for ``pyramid_zodbconn``, providing integration between :term:`ZODB` and a Pyramid application. +The first argument is the "name" ``static``, which indicates that the URL path prefix of the view will be ``/static``. -#. *Line 19*. - Set a root factory using our function named ``root_factory``. +The second argument of this method is the "path". +It is a relative :term:`asset specification`. +It finds the resources it should serve within the ``static`` directory inside the ``tutorial`` package. +Alternatively the cookiecutter could have used an *absolute* asset specification as the path (``tutorial:static``). -#. *Line 20*. - Include support for the :term:`Chameleon` template rendering bindings, allowing us to use the ``.pt`` templates. +The third argument is an optional ``cache_max_age`` which specifies the number of seconds the static asset will be HTTP-cached. -#. *Line 21*. - Include routes from the ``.routes`` module. - This registers a "static view" using the :meth:`pyramid.config.Configurator.add_static_view` method. - This view answers requests whose URL path starts with ``/static``. - This statement registers a view that will serve up static assets, such as CSS and image files. - In this case the URL will answer requests at ``http://localhost:6543/static/`` and below. +Next perform a :term:`scan`. - The first argument is the "name" ``static``, which indicates that the URL path prefix of the view will be ``/static``. +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 22 + :lineno-match: + :language: py - The second argument of this method is the "path". - It is a relative :term:`asset specification`. - It finds the resources it should serve within the ``static`` directory inside the ``tutorial`` package. - Alternatively the cookiecutter could have used an *absolute* asset specification as the path (``tutorial:static``). +A scan will find :term:`configuration decoration`, such as view configuration decorators (e.g., ``@view_config``) in the source code of the ``tutorial`` package. +It will take actions based on these decorators. +We don't pass any arguments to :meth:`~pyramid.config.Configurator.scan`, which implies that the scan should take place in the current package (in this case, ``tutorial``). +The cookiecutter could have equivalently said ``config.scan('tutorial')``, but it chose to omit the package name argument. - The third argument is an optional ``cache_max_age`` which specifies the number of seconds the static asset will be HTTP-cached. +Finally use the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application. -#. *Line 22*. - Perform a :term:`scan`. - A scan will find :term:`configuration decoration`, such as view configuration decorators (e.g., ``@view_config``) in the source code of the ``tutorial`` package. - It will take actions based on these decorators. - We don't pass any arguments to :meth:`~pyramid.config.Configurator.scan`, which implies that the scan should take place in the current package (in this case, ``tutorial``). - The cookiecutter could have equivalently said ``config.scan('tutorial')``, but it chose to omit the package name argument. +.. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 23 + :lineno-match: + :language: py -#. *Line 23*. - Use the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application. +.. _wiki-resources-and-models: Resources and models with ``models`` package -------------------------------------------- @@ -163,6 +233,16 @@ Let's try to understand the components in this module: The function returns the dictionary ``{'project': 'myproj'}``. This dictionary is used by the template named by the ``mytemplate.pt`` asset specification to fill in certain values on the page. +Now let us open the ``notfound.py`` module, and describe its function. + +.. literalinclude:: src/basiclayout/tutorial/views/notfound.py + :linenos: + :language: python + +Without repeating ourselves, we will point out the differences between this view and the previous. + +#. + Configuration in ``development.ini`` ------------------------------------ -- cgit v1.2.3 From dd2aefc04435b65d67163c432409b4f76685b93a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 18:36:31 -0800 Subject: Clean up grammar in models section --- docs/tutorials/wiki/basiclayout.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 33e0b4ff3..7e6e86143 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -170,16 +170,16 @@ Here is the source for ``models.py``: The ``MyModel`` :term:`resource` class is implemented here. Instances of this class are capable of being persisted in :term:`ZODB` because the class inherits from the :class:`persistent.mapping.PersistentMapping` class. The ``__parent__`` and ``__name__`` are important parts of the :term:`traversal` protocol. - By default, set these to ``None`` to indicate that this is the :term:`root` object. + By default, these are set to ``None`` to indicate that this is the :term:`root` object. #. *Lines 8-12*. ``appmaker`` is used to return the *application root* object. It is called on *every request* to the :app:`Pyramid` application. It also performs bootstrapping by *creating* an application root (inside the ZODB root object) if one does not already exist. - It is used by the ``root_factory`` we've defined in our ``__init__.py``. + It is used by the ``root_factory`` we have defined in our ``__init__.py``. Bootstrapping is done by first seeing if the database has the persistent application root. - If not, we make an instance, store it, and commit the transaction. + If not, then we make an instance, store it, and commit the transaction. We then return the application root object. -- cgit v1.2.3 From 28f659844f0f3520a8bedf4d318970b039bf9734 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 18:42:18 -0800 Subject: Remove redundancy in appmaker narrative --- docs/tutorials/wiki/basiclayout.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 7e6e86143..39e15bb58 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -174,12 +174,12 @@ Here is the source for ``models.py``: #. *Lines 8-12*. ``appmaker`` is used to return the *application root* object. - It is called on *every request* to the :app:`Pyramid` application. + It is called on *every request* to the :app:`Pyramid` application by virtue of the ``root_factory`` defined in our ``__init__.py``. It also performs bootstrapping by *creating* an application root (inside the ZODB root object) if one does not already exist. - It is used by the ``root_factory`` we have defined in our ``__init__.py``. - + Bootstrapping is done by first seeing if the database has the persistent application root. If not, then we make an instance, store it, and commit the transaction. + We then return the application root object. -- cgit v1.2.3 From 4ccf01a091485463bfae1129ed858546b6a93da6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 18:54:09 -0800 Subject: Add notfound_view function description and 404.pt template. --- docs/tutorials/wiki/basiclayout.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 39e15bb58..3f84f12c3 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -188,8 +188,8 @@ View declarations via the ``views`` package Our cookiecutter generated a default ``views`` package on our behalf. It contains a two views. -which is used to render the page shown when you visit the URL ``http://localhost:6543/``. +The first view is used to render the page shown when you visit the URL ``http://localhost:6543/``. Open ``tutorial/views/default.py`` in the ``views`` package. It should already contain the following: @@ -233,7 +233,7 @@ Let's try to understand the components in this module: The function returns the dictionary ``{'project': 'myproj'}``. This dictionary is used by the template named by the ``mytemplate.pt`` asset specification to fill in certain values on the page. -Now let us open the ``notfound.py`` module, and describe its function. +Let us open ``tutorial/views/default.py`` in the ``views`` package to look at the second view. .. literalinclude:: src/basiclayout/tutorial/views/notfound.py :linenos: @@ -241,7 +241,16 @@ Now let us open the ``notfound.py`` module, and describe its function. Without repeating ourselves, we will point out the differences between this view and the previous. -#. +#. *Line 4*. + The ``notfound_view`` function is decorated with ``@notfound_view_config``. + This decorator registers a :term:`Not Found View` using :meth:`pyramid.config.Configurator.add_notfound_view`. + + The ``renderer`` argument names an :term:`asset specification` of ``templates/404.pt``. + +#. *Lines 5-7*. + A :term:`view callable` named ``notfound_view`` is defined, which is decorated in the step above. + It sets the HTTP response status code to ``404``. + The function returns an empty dictionary to the template ``404.pt``, which accepts no parameters anyway. Configuration in ``development.ini`` -- cgit v1.2.3 From d42b654b1dda5e0e80c25c2cb8b8836ad538d60c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 23 Nov 2018 18:57:26 -0800 Subject: Clean up configuration for development.ini --- docs/tutorials/wiki/basiclayout.rst | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 3f84f12c3..ab9b7df5c 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -256,15 +256,11 @@ Without repeating ourselves, we will point out the differences between this view Configuration in ``development.ini`` ------------------------------------ -The ``development.ini`` (in the ``tutorial`` :term:`project` directory, as -opposed to the ``tutorial`` :term:`package` directory) looks like this: +The ``development.ini`` (in the ``tutorial`` :term:`project` directory, as opposed to the ``tutorial`` :term:`package` directory) looks like this: .. literalinclude:: src/basiclayout/development.ini :language: ini -Note the existence of a ``[app:main]`` section which specifies our WSGI -application. Our ZODB database settings are specified as the -``zodbconn.uri`` setting within this section. This value, and the other -values within this section, are passed as ``**settings`` to the ``main`` -function we defined in ``__init__.py`` when the server is started via -``pserve``. +Note the existence of a ``[app:main]`` section which specifies our WSGI application. +Our ZODB database settings are specified as the ``zodbconn.uri`` setting within this section. +When the server is started via ``pserve``, the values within this section are passed as ``**settings`` to the ``main`` function defined in ``__init__.py``. -- cgit v1.2.3 From c2092ff372f49efb73a923d97d641b0561594b3f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 25 Nov 2018 23:37:10 -0800 Subject: Align line numbers with code - See https://github.com/Pylons/pyramid-cookiecutter-starter/pull/66 --- docs/tutorials/wiki/basiclayout.rst | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) (limited to 'docs/tutorials/wiki/basiclayout.rst') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index ab9b7df5c..52d3f4670 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -65,53 +65,45 @@ See also :term:`Deployment settings`. This will be a dictionary of settings parsed from the ``.ini`` file, which contains deployment-related values, such as ``pyramid.reload_templates``, ``zodbconn.uri``, and so on. -Next use an explicit transaction manager for our application. -This prevents new transactions from being implicitly created when touching the manager outside of the ``pyramid_tm`` lifecycle. - -.. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 15 - :lineno-match: - :language: py - Next include support for ``pyramid_tm``, allowing Pyramid requests to join the active transaction as provided by the `transaction `_ package. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 16 + :lines: 15 :lineno-match: :language: py Next include support for ``pyramid_retry`` to retry a request when transient exceptions occur. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 17 + :lines: 16 :lineno-match: :language: py Next include support for ``pyramid_zodbconn``, providing integration between :term:`ZODB` and a Pyramid application. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 18 + :lines: 17 :lineno-match: :language: py Next set a root factory using our function named ``root_factory``. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 19 + :lines: 18 :lineno-match: :language: py Next include support for the :term:`Chameleon` template rendering bindings, allowing us to use the ``.pt`` templates. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 20 + :lines: 19 :lineno-match: :language: py Next include routes from the ``.routes`` module. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 21 + :lines: 20 :lineno-match: :language: py @@ -132,7 +124,7 @@ The third argument is an optional ``cache_max_age`` which specifies the number o Next perform a :term:`scan`. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 22 + :lines: 21 :lineno-match: :language: py @@ -144,7 +136,7 @@ The cookiecutter could have equivalently said ``config.scan('tutorial')``, but i Finally use the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 23 + :lines: 22 :lineno-match: :language: py -- cgit v1.2.3