Skip to content
This repository
branch: 1.3-branch
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 158 lines (121 sloc) 5.946 kb

Application Configuration

System Message: ERROR/3 (<string>, line 1)

Unknown directive type "index".

.. index::
   single: 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 :app:`Pyramid` to call the code that makes up your application.

System Message: ERROR/3 (<string>, line 9); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 9); backlink

Unknown interpreted text role "app".

There are two ways to configure a :app:`Pyramid` application: :term:`imperative configuration` and :term:`declarative configuration`. Both are described below.

System Message: ERROR/3 (<string>, line 20); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 20); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 20); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 24)

Unknown directive type "index".

.. index::
   single: imperative configuration

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:

System Message: ERROR/3 (<string>, line 32); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 36)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   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!')

   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()

We won't talk much about what this application does yet. Just note that the "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.

System Message: ERROR/3 (<string>, line 53); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 60)

Unknown directive type "index".

.. index::
   single: view_config
   single: configuration decoration
   single: code scanning

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:

System Message: ERROR/3 (<string>, line 70); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 70); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 79)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   from pyramid.response import Response
   from pyramid.view import view_config

   @view_config(name='hello', request_method='GET')
   def hello(request):
       return Response('Hello')

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`.

System Message: ERROR/3 (<string>, line 89); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 89); backlink

Unknown interpreted text role "term".

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.

System Message: ERROR/3 (<string>, line 95); backlink

Unknown interpreted text role "class".

System Message: ERROR/3 (<string>, line 95); backlink

Unknown interpreted text role "term".

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:

System Message: ERROR/3 (<string>, line 99); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 99); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 99); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 99); backlink

Unknown interpreted text role "meth".

Starting A Scan

System Message: ERROR/3 (<string>, line 106)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   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()
   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()

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.

System Message: ERROR/3 (<string>, line 126); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 126); backlink

Unknown interpreted text role "class".

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.

System Message: ERROR/3 (<string>, line 133); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 133); backlink

Unknown interpreted text role "term".

The combination of :term:`configuration decoration` and the invocation of a :term:`scan` is collectively known as :term:`declarative configuration`.

System Message: ERROR/3 (<string>, line 138); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 138); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 138); backlink

Unknown interpreted text role "term".

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:

System Message: ERROR/3 (<string>, line 141); backlink

Unknown interpreted text role "class".

System Message: ERROR/3 (<string>, line 141); backlink

Unknown interpreted text role "meth".

System Message: ERROR/3 (<string>, line 146)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   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.

System Message: ERROR/3 (<string>, line 154); backlink

Unknown interpreted text role "app".
Something went wrong with that request. Please try again.