From 4e1199fdb3219ed7ed3635f8ed96fb0cff18abe1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 11 Jul 2011 04:35:53 -0400 Subject: simplify --- docs/narr/configuration.rst | 44 ++++++++++++++++++++------------------------ 1 file changed, 20 insertions(+), 24 deletions(-) (limited to 'docs/narr/configuration.rst') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 6360dc574..4c2870562 100644 --- a/docs/narr/configuration.rst +++ b/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. - -- cgit v1.2.3 From 7c48ff7bde21fda813ce74a7691c89bedd2b54cc Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 11 Jul 2011 23:58:57 -0400 Subject: simplify --- docs/narr/configuration.rst | 25 +++++++++---------------- 1 file changed, 9 insertions(+), 16 deletions(-) (limited to 'docs/narr/configuration.rst') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 4c2870562..3ecb4b06a 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -6,22 +6,15 @@ 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. +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". However, :app:`Pyramid` also uses the word "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. There are two ways to configure a :app:`Pyramid` application: :term:`imperative configuration` and :term:`declarative configuration`. Both -- cgit v1.2.3 From be9bbff6440750e56a73f534bc09511ef5d2b8b4 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 07:31:33 -0400 Subject: use less awkward language --- docs/narr/configuration.rst | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) (limited to 'docs/narr/configuration.rst') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 3ecb4b06a..dacf09f18 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -6,15 +6,16 @@ Application Configuration ========================= -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". However, :app:`Pyramid` also uses the word "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 your 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 @@ -144,3 +145,10 @@ In the example above, the scanner translates the arguments to config.add_view(hello) +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. -- cgit v1.2.3 From 87a689d71191a175ee20e52701a9e802548f91a6 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 07:32:01 -0400 Subject: typo --- docs/narr/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/configuration.rst') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index dacf09f18..597d48b09 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -12,7 +12,7 @@ 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 your to call). The act of +*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. -- cgit v1.2.3