diff options
Diffstat (limited to 'docs/narr/configuration.rst')
| -rw-r--r-- | docs/narr/configuration.rst | 172 |
1 files changed, 90 insertions, 82 deletions
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index f7a69d613..80bfa159c 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -3,23 +3,26 @@ .. _configuration_narr: -Application Configuration +Application Configuration ========================= 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 +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. +.. seealso:: + For information on ``.ini`` files for Pyramid applications see the + :ref:`startup_chapter` chapter. + +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 @@ -29,33 +32,34 @@ are described below. Imperative Configuration ------------------------ -"Imperative configuration" just means configuration done by Python -statements, one after the next. 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: + :linenos: - from wsgiref.simple_server import make_server - from pyramid.config import Configurator - from pyramid.response import Response + from wsgiref.simple_server import make_server + from pyramid.config import Configurator + from pyramid.response import Response - def hello_world(request): - return Response('Hello world!') + def hello_world(request): + return Response('Hello world!') - if __name__ == '__main__': - config = Configurator() - config.add_view(hello_world) - app = config.make_wsgi_app() - server = make_server('0.0.0.0', 8080, app) - server.serve_forever() + if __name__ == '__main__': + with Configurator() as config: + config.add_route('hello', '/') + config.add_view(hello_world) + app = config.make_wsgi_app() + server = make_server('0.0.0.0', 6543, app) + server.serve_forever() We won't talk much about what this application does yet. Just note that the -"configuration' statements take place underneath the ``if __name__ == +configuration statements take place underneath the ``if __name__ == '__main__':`` stanza in the form of method calls on a :term:`Configurator` -object (e.g. ``config.add_view(...)``). These statements take place one -after the other, and are executed in order, so the full power of Python, -including conditionals, can be employed in this mode of configuration. +object (e.g., ``config.add_view(...)``). These statements take place one after +the other, and are executed in order, so the full power of Python, including +conditionals, can be employed in this mode of configuration. .. index:: single: view_config @@ -68,70 +72,73 @@ Declarative Configuration ------------------------- 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: +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: + :linenos: + :emphasize-lines: 2-4 - from pyramid.response import Response - from pyramid.view import view_config + from pyramid.response import Response + from pyramid.view import view_config - @view_config(name='hello', request_method='GET') - def hello(request): - return Response('Hello') + @view_config(route_name='hello', request_method='GET') + def hello_world(request): + return Response('Hello World!') -The mere existence of configuration decoration doesn't cause any -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 mere existence of configuration decoration doesn't cause any 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`. 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. +example above adds an attribute to the ``hello_world`` function, making it available +for a :term:`scan` to find it later. -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: +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: .. code-block:: python - :linenos: + :linenos: + :emphasize-lines: 15 + + from wsgiref.simple_server import make_server + from pyramid.config import Configurator + from pyramid.response import Response + from pyramid.view import view_config + - from wsgiref.simple_server import make_server - from pyramid.config import Configurator - from pyramid.response import Response - from pyramid.view import view_config + @view_config(route_name='hello', request_method='GET') + def hello_world(request): + return Response('Hello World!') - @view_config() - def hello(request): - return Response('Hello') - if __name__ == '__main__': - from pyramid.config import Configurator - config = Configurator() - config.scan() - app = config.make_wsgi_app() - server = make_server('0.0.0.0', 8080, app) - server.serve_forever() + if __name__ == '__main__': + with Configurator() as config: + config.add_route('hello', '/') + config.scan() + app = config.make_wsgi_app() + server = make_server('0.0.0.0', 6543, app) + server.serve_forever() 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 +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 your -behalf: these calls replace the need to add imperative configuration -statements that don't live near the code being configured. +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. The combination of :term:`configuration decoration` and the invocation of a :term:`scan` is collectively known as :term:`declarative configuration`. @@ -142,12 +149,13 @@ In the example above, the scanner translates the arguments to .. code-block:: python - config.add_view(hello) + config.add_view(hello_world, route_name='hello', + request_method='GET') 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. +There are two ways to configure a :app:`Pyramid` application: declaratively and +imperatively. You can choose the mode with which you're most comfortable; both +are completely equivalent. Examples in this documentation will use both modes +interchangeably. |