diff options
Diffstat (limited to 'docs/narr/configuration.rst')
| -rw-r--r-- | docs/narr/configuration.rst | 75 |
1 files changed, 36 insertions, 39 deletions
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 6360dc574..597d48b09 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -6,22 +6,20 @@ Application Configuration ========================= -Each deployment of an application written using :app:`Pyramid` implies a -specific *configuration* of the framework itself. For example, an -application which serves up MP3 files for your listening enjoyment might plug -code into the framework that manages song files, while an application that -manages corporate data might plug in code that manages accounting -information. The way in which code is plugged in to :app:`Pyramid` for a -specific application is referred to as "configuration". - -Most people understand "configuration" as coarse settings that inform the -high-level operation of a specific application deployment. For instance, -it's easy to think of the values implied by a ``.ini`` file parsed at -application startup time as "configuration". :app:`Pyramid` extends this -pattern to application development, using the term "configuration" to express -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. +Most people already understand "configuration" as settings that influence the +operation of an application. For instance, it's easy to think of the values +in a ``.ini`` file parsed at application startup time as "configuration". +However, if you're reasonably open-minded, it's easy to think of *code* as +configuration too. Since Pyramid, like most other web application platforms, +is a *framework*, it calls into code that you write (as opposed to a +*library*, which is code that exists purely for you to call). The act of +plugging application code that you've written into :app:`Pyramid` is also +referred to within this documentation as "configuration"; you are configuring +:app:`Pyramid` to call the code that makes up your 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 +29,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 +63,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 +132,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 +145,10 @@ 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. +Summary +------- +There are two ways to configure a :app:`Pyramid` application: declaratively +and imperatively. You can choose the mode you're most comfortable with; both +are completely equivalent. Examples in this documentation will use both +modes interchangeably. |