diff options
| -rw-r--r-- | docs/narr/configuration.rst | 82 |
1 files changed, 41 insertions, 41 deletions
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index 85e755c4a..394603946 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -8,11 +8,11 @@ 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 MP3s for user consumption might plug code into -the framework that manages songs, 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". +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, @@ -67,14 +67,16 @@ including conditionals, can be employed in this mode of configuration. Configuration Decorations and Code Scanning ------------------------------------------- -An alternate mode of configuration lends more *locality of reference* to a +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 you may need to have 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: +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: .. code-block:: python :linenos: @@ -87,20 +89,19 @@ referred to by the declaration itself. For example: return Response('Hello') The mere existence of configuration decoration doesn't cause any -configuration registration to be made. Before it hasany effect on the +configuration registration to be performed. Before it has any effect on the configuration of a :app:`Pyramid` application, a configuration decoration within application code must be found through a process known as a :term:`scan`. -The :class:`pyramid.view.view_config` decorator above adds an -attribute to the ``hello`` function, making it available for a -:term:`scan` to find it later. +For example, the :class:`pyramid.view.view_config` decorator in the code +example above adds an attribute to the ``hello`` function, making it +available for a :term:`scan` to find it later. -:app:`Pyramid` is willing to :term:`scan` a module or a package and -its subpackages for decorations when the -:meth:`pyramid.config.Configurator.scan` method is invoked: -scanning implies searching for configuration declarations in a package -and its subpackages. For example: +A :term:`scan` of a :term:`module` or a :term:`package` and its subpackages +for decorations happens when the :meth:`pyramid.config.Configurator.scan` +method is invoked: scanning implies searching for configuration declarations +in a package and its subpackages. For example: .. topic:: Starting A Scan @@ -122,22 +123,21 @@ and its subpackages. For example: app = config.make_wsgi_app() serve(app, host='0.0.0.0') -The scanning machinery imports each module and subpackage in a package -or module recursively, looking for special attributes attached to -objects defined within a module. These special attributes are -typically attached to code via the use of a :term:`decorator`. For -example, the :class:`pyramid.view.view_config` decorator can be -attached to a function or instance method. +The scanning machinery imports each module and subpackage in a package or +module recursively, looking for special attributes attached to objects +defined within a module. These special attributes are typically attached to +code via the use of a :term:`decorator`. For example, the +:class:`pyramid.view.view_config` decorator can be attached to a function or +instance method. -Once scanning is invoked, and :term:`configuration decoration` is -found by the scanner, a set of calls are made to a -:term:`Configurator` on behalf of the developer: these calls represent -the intent of the configuration decoration. +Once scanning is invoked, and :term:`configuration decoration` is found by +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. -In the example above, this is best represented as the scanner -translating the arguments to :class:`pyramid.view.view_config` into a -call to the :meth:`pyramid.config.Configurator.add_view` -method, effectively: +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: .. ignore-next-block .. code-block:: python @@ -150,10 +150,10 @@ Declarative Configuration A third mode of configuration can be employed when you create a :app:`Pyramid` application named *declarative configuration*. This mode uses -:term:`ZCML` to represent configuration statements rather than Python. ZCML -is often used when application extensibility is important. Most of the -examples in the narrative portion of this documentation concentrate on -imperative configuration rather than ZCML, but almost everything that can be -configured imperatively can also be configured via ZCML. See -:ref:`declarative_chapter` for more information about ZCML. +an XML language known as :term:`ZCML` to represent configuration statements +rather than Python. ZCML is often used when application extensibility is +important. Most of the examples in the narrative portion of this +documentation concentrate on imperative configuration rather than ZCML, but +almost everything that can be configured imperatively can also be configured +via ZCML. See :ref:`declarative_chapter` for more information about ZCML. |