Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

simplify

  • Loading branch information...
commit 4e1199fdb3219ed7ed3635f8ed96fb0cff18abe1 1 parent e81ad8c
@mcdonc mcdonc authored
Showing with 23 additions and 26 deletions.
  1. +3 −2 docs/glossary.rst
  2. +20 −24 docs/narr/configuration.rst
View
5 docs/glossary.rst
@@ -592,8 +592,9 @@ Glossary
declaration` required by your application.
declarative configuration
- The configuration mode in which you use :term:`ZCML` to make a set of
- :term:`configuration declaration` statements. See :term:`pyramid_zcml`.
+ The configuration mode in which you use the combination of
+ :term:`configuration decorator` decorations and a :term:`scan` to
+ configure your Pyramid application.
Not Found view
An :term:`exception view` invoked by :app:`Pyramid` when the
View
44 docs/narr/configuration.rst
@@ -23,6 +23,10 @@ standardized ways that code gets plugged into a deployment of the framework
itself. When you plug code into the :app:`Pyramid` framework, you are
"configuring" :app:`Pyramid` to create a particular application.
+There are two ways to configure a :app:`Pyramid` application:
+:term:`imperative configuration` and :term:`declarative configuration`. Both
+are described below.
+
.. index::
single: imperative configuration
@@ -31,8 +35,9 @@ itself. When you plug code into the :app:`Pyramid` framework, you are
Imperative Configuration
------------------------
-Here's one of the simplest :app:`Pyramid` applications, configured
-imperatively:
+"Imperative configuration" just means configuration done by Python
+statements, one after the next. Here's one of the simplest :app:`Pyramid`
+applications, configured imperatively:
.. code-block:: python
:linenos:
@@ -64,19 +69,17 @@ including conditionals, can be employed in this mode of configuration.
.. _decorations_and_code_scanning:
-Configuration Decorations and Code Scanning
--------------------------------------------
+Declarative Configuration
+-------------------------
-A different mode of configuration gives more *locality of reference* to a
-:term:`configuration declaration`. It's sometimes painful to have all
-configuration done in imperative code, because often the code for a single
-application may live in many files. If the configuration is centralized in
-one place, you'll need to have at least two files open at once to see the
-"big picture": the file that represents the configuration, and the file that
-contains the implementation objects referenced by the configuration. To
-avoid this, :app:`Pyramid` allows you to insert :term:`configuration
-decoration` statements very close to code that is referred to by the
-declaration itself. For example:
+It's sometimes painful to have all configuration done by imperative code,
+because often the code for a single application may live in many files. If
+the configuration is centralized in one place, you'll need to have at least
+two files open at once to see the "big picture": the file that represents the
+configuration, and the file that contains the implementation objects
+referenced by the configuration. To avoid this, :app:`Pyramid` allows you to
+insert :term:`configuration decoration` statements very close to code that is
+referred to by the declaration itself. For example:
.. code-block:: python
:linenos:
@@ -135,6 +138,9 @@ the scanner, a set of calls are made to a :term:`Configurator` on your
behalf: these calls replace the need to add imperative configuration
statements that don't live near the code being configured.
+The combination of :term:`configuration decoration` and the invocation of a
+:term:`scan` is collectively known as :term:`declarative configuration`.
+
In the example above, the scanner translates the arguments to
:class:`~pyramid.view.view_config` into a call to the
:meth:`pyramid.config.Configurator.add_view` method, effectively:
@@ -145,13 +151,3 @@ In the example above, the scanner translates the arguments to
config.add_view(hello)
-Declarative Configuration
--------------------------
-
-A third mode of configuration can be employed when you create a
-:app:`Pyramid` application named *declarative configuration*. This mode uses
-an XML language known as :term:`ZCML` to represent configuration statements
-rather than Python. ZCML is not built-in to Pyramid, but almost everything
-that can be configured imperatively can also be configured via ZCML if you
-install the :term:`pyramid_zcml` package.
-
Please sign in to comment.
Something went wrong with that request. Please try again.