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') 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