From fec0f0614c69dc7382fba367f8269479e2682058 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 25 Oct 2010 18:47:29 -0400 Subject: convert narrative docs to Pyramid --- docs/narr/configuration.rst | 74 ++++++++++++++++++++++----------------------- 1 file changed, 37 insertions(+), 37 deletions(-) (limited to 'docs/narr/configuration.rst') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index a3336e735..fe55705bb 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -6,12 +6,12 @@ Application Configuration ========================= -Each deployment of an application written using :mod:`repoze.bfg` +Each deployment of an application written using :mod:`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. :mod:`repoze.bfg` refers to the way +manages accounting information. :mod:`pyramid` refers to the way in which code is plugged in to it for a specific application as "configuration". @@ -19,15 +19,15 @@ 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". -:mod:`repoze.bfg` extends this pattern to application development, +:mod:`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 :mod:`repoze.bfg` framework, you are "configuring" -:mod:`repoze.bfg` for the purpose of creating a particular application +code into the :mod:`pyramid` framework, you are "configuring" +:mod:`pyramid` for the purpose of creating a particular application deployment. There are two different mechanisms you may use to configure -:mod:`repoze.bfg` to create an application: *imperative* configuration +:mod:`pyramid` to create an application: *imperative* configuration and *declarative* configuration. We'll examine both modes in the sections which follow. @@ -46,7 +46,7 @@ control to the framework; it's "imperative" because you express the configuration directly in Python code, and you have the full power of Python at your disposal as you issue configuration statements. -Here's one of the simplest :mod:`repoze.bfg` applications, configured +Here's one of the simplest :mod:`pyramid` applications, configured imperatively: .. code-block:: python @@ -54,7 +54,7 @@ imperatively: from webob import Response from paste.httpserver import serve - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator def hello_world(request): return Response('Hello world!') @@ -84,13 +84,13 @@ of configuration. Declarative Configuration ------------------------- -A :mod:`repoze.bfg` application can be alternately be configured +A :mod:`pyramid` application can be alternately be configured "declaratively", if so desired. Declarative configuration relies on *declarations* made external to the code in a configuration file format named :term:`ZCML` (Zope Configuration Markup Language), an XML dialect. -A :mod:`repoze.bfg` application configured declaratively requires not +A :mod:`pyramid` application configured declaratively requires not one, but two files: a Python file and a :term:`ZCML` file. In a file named ``helloworld.py``: @@ -100,7 +100,7 @@ In a file named ``helloworld.py``: from webob import Response from paste.httpserver import serve - from repoze.bfg.configuration import Configurator + from pyramid.configuration import Configurator def hello_world(request): return Response('Hello world!') @@ -119,9 +119,9 @@ previously created ``helloworld.py``: .. code-block:: xml :linenos: - + - + + - + `` declaration tag performs the same function as the ``add_view`` method that was employed within :ref:`imperative_configuration`. In fact, the ```` tag is effectively a "macro" which calls the -:meth:`repoze.bfg.configuration.Configurator.add_view` method on your +:meth:`pyramid.configuration.Configurator.add_view` method on your behalf. -The ```` tag is an example of a :mod:`repoze.bfg` declaration +The ```` tag is an example of a :mod:`pyramid` declaration tag. Other such tags include ```` and ````. Each of these tags is effectively a "macro" which calls methods of a -:class:`repoze.bfg.configuration.Configurator` object on your behalf. +:class:`pyramid.configuration.Configurator` object on your behalf. Essentially, using a :term:`ZCML` file and loading it from the filesystem allows us to put our configuration statements within this @@ -234,9 +234,9 @@ start. For example, the following ZCML file has two conflicting .. code-block:: xml :linenos: - + - + - + @@ -366,7 +366,7 @@ 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:`repoze.bfg.view.bfg_view` decorator can be +example, the :class:`pyramid.view.bfg_view` decorator can be attached to a function or instance method. Once scanning is invoked, and :term:`configuration decoration` is @@ -375,8 +375,8 @@ found by the scanner, a set of calls are made to a the intent of the configuration decoration. In the example above, this is best represented as the scanner -translating the arguments to :class:`repoze.bfg.view.bfg_view` into a -call to the :meth:`repoze.bfg.configuration.Configurator.add_view` +translating the arguments to :class:`pyramid.view.bfg_view` into a +call to the :meth:`pyramid.configuration.Configurator.add_view` method, effectively: .. ignore-next-block @@ -391,9 +391,9 @@ A combination of imperative configuration, declarative configuration via ZCML and scanning can be used to configure any application. They are not mutually exclusive. -The :mod:`repoze.bfg` authors often recommend using mostly declarative +The :mod:`pyramid` authors often recommend using mostly declarative configuration, because it's the more traditional form of configuration -used in :mod:`repoze.bfg` applications, it can be overridden and +used in :mod:`pyramid` applications, it can be overridden and extended by third party deployers, and there are more examples for it "in the wild". -- cgit v1.2.3