.. _configuration_narr: Creating Your First :mod:`repoze.bfg` Application ================================================= The majority of the logic in any web application is completely application-specific. For example, the body of a web page served by one web application might be a representation of the contents of an accounting ledger, while the content of of a web page served by another might be a listing of songs. These applications obviously might not service the same set of customers. However, both the ledger-serving and song-serving applications can be written using :mod:`repoze.bfg`, because :mod:`repoze.bfg` is a very general *framework* which can be used to create all kinds of web applications. .. sidebar:: Frameworks vs. Libraries A *framework* differs from a *library* in one very important way: library code is always *called* by code that you write, while a framework always *calls* code that you write. Using a set of libraries to create an application is often initially easier than using a framework to create an application, because the developer can choose to cede control to library code he has not authored selectively, making the resulting application easier to understand for the original developer. When using a framework, the developer is typically required to cede a greater portion of control to code he has not authored: code that resides in the framework itself. You needn't use a framework at all to create a web application using Python. A rich set of libraries exists for the platform which you can snap together to effectively create your own framework. In practice, however, using an existing framework to create an application is often more practical than rolling your own via a set of libraries if the framework provides a set of facilities and assumptions that fit your application domain's requirements. :mod:`repoze.bfg` is a framework that fits a large set of assumptions in the domain of web application creation. As a framework, the primary job of :mod:`repoze.bfg` is to make it easier for a developer to create an arbitrary web application. From the perspective of the authors of :mod:`repoze.bfg`, each deployment of an application written using :mod:`repoze.bfg` implies a specific *configuration* of the framework itself. For example, a song-serving application might plug code into the framework that manages songs, while the ledger- serving application might plug code that manages accounting information. :mod:`repoze.bfg` refers to the way in which code is plugged in to it for a specific deployment as "configuration". Most people understand "configuration" as coarse knobs 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 which is parsed at application startup time as "configuration". :mod:`repoze.bfg` extends this pattern all the way out to application development, using the term "configuration" to express standardized methods the framework makes available to developers which can be used to plug code into a deployment of the framework itself. When you plug code into the :mod:`repoze.bfg` framework, you are indeed "configuring" :mod:`repoze.bfg` for the purpose of creating a particular application deployment. .. admonition:: Tip If the term "configuration" as used in this guide just doesn't seem to "click" in your brain, maybe because you just can't bring yourself to consider "configuration" anything except the modification of a configuration file containing higher-level knobs than those exposed by :mod:`repoze.bfg`, it may help to mentally substitute the term "configuration" with "wiring" or "plumbing" as you read the chapter. There are a number of different mechanisms you may use to configure :mod:`repoze.bfg` to create an application: *imperative* configuration and *declarative* configuration. We'll examine both modes in the sections which follow. .. warning:: If you are using Python 2.4 (as opposed to Python 2.5 or 2.6), you will need to install the ``wsgiref`` package for the examples in this chapter to work. Use ``easy_install wsgiref`` to get it installed. .. _helloworld_imperative: Hello World, Configured Imperatively ------------------------------------ Experienced Python programmers may find the "imperative" configuration mechanism fits the way they already do things. This is the configuration mode in which developers cede the least amount of control to the framework. Because of this, it is also the easiest configuration mode to understand. Here's one of the simplest :mod:`repoze.bfg` applications, configured imperatively: .. code-block:: python :linenos: from webob import Response from wsgiref import simple_server from repoze.bfg.configuration import Configurator def hello_world(request): return Response('Hello world!') def goodbye_world(request): return Response('Goodbye world!') if __name__ == '__main__': config = Configurator() config.add_view(hello_world) config.add_view(goodbye_world, name='goodbye') app = config.make_wsgi_app() simple_server.make_server('', 8080, app).serve_forever() When this code is inserted into a Python script named ``helloworld.py`` and executed by a Python interpreter which has the :mod:`repoze.bfg` software installed, this code starts an HTTP server on port 8080. When visited by a user agent on the root URL (``/``), the server will simply serve up the text "Hello world!" with the HTTP response values ``200 OK`` as a response code and a ``Content-Type`` header value of ``text/plain``. But for reasons we'll better understand shortly, when visited by a user agent on the URL ``/goodbye``, the server will serve up "Goodbye world!". Let's examine this program piece-by-piece. Imports ~~~~~~~ The above script defines the following set of imports: .. code-block:: python :linenos: from webob import Response from wsgiref import simple_server from repoze.bfg.configuration import Configurator :mod:`repoze.bfg` uses the :term:`WebOb` library as the basis for its :term:`request` and :term:`response` objects. The script uses the ``webob.Response`` class later in the script to create a :term:`response` object. Like many other Python web frameworks, :mod:`repoze.bfg` uses the :term:`WSGI` protocol as a basis between an application and a web server. The ``wsgiref.simple_server`` server is used in this example as a WSGI server, purely for convenience. :mod:`repoze.bfg` applications can be served via any WSGI server. The script also imports the ``Configurator`` class from the ``repoze.bfg.configuration`` module. This class is used to configure :mod:`repoze.bfg` for a particular application. An instance of this class provides methods which help configure various parts of :mod:`repoze.bfg` for a given application deployment. View Declaration ~~~~~~~~~~~~~~~~ The above script, beneath its set of imports, defines two functions: one named ``hello_world`` and one named ``goodbye_world``. .. code-block:: python :linenos: def hello_world(request): return Response('Hello world!') def goodbye_world(request): return Response('Goodbye world!') Both functions accepts a single argument (``request``), and each returns an instance of the ``webob.Response`` class. In the ``hello_world`` function, the string ``'Hello world!'`` is passed to the ``Response`` constructor as the *body* of the response. In the ``goodbye_world`` function, the string ``'Goodbye world!'`` is passed. Each of these functions is known as a :term:`view callable`. View callables in a "real" :mod:`repoze.bfg` application are often functions which accept a request and return a response. A view callable can be represented via another type of object, like a class or an instance, but for our purposes here, a function serves us well. A view callable is called with a :term:`request` object, which is a representation of an HTTP request sent by a remote user agent. A view callable is required to return a :term:`response` object because a response object has all the information necessary to formulate an actual HTTP response; this object is then converted to text and sent back to the requesting user agent. The ``hello_world`` view callable defined by the script does nothing but return a response with the body ``Hello world!``; the ``goodbye_world`` view callable returns a response with the body ``Goodbye world!``. .. _helloworld_imperative_appconfig: Application Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~ In the above script, the following code, representing the *configuration* of an application which uses the previously defined imports and function definitions is placed within the confines of an ``if`` statement: .. code-block:: python :linenos: if __name__ == '__main__': config = Configurator() config.add_view(hello_world) config.add_view(goodbye_world, name='goodbye') app = config.make_wsgi_app() simple_server.make_server('', 8080, app).serve_forever() Let's break this down this piece-by-piece: .. code-block:: python :linenos: if __name__ == '__main__': config = Configurator() The ``if __name__ == '__main__':`` line above represents a Python idiom: the code inside this if clause is not invoked unless the script is run directly from the command line via, for example, ``python helloworld.py`` where the file named ``helloworld.py`` contains the entire script body. ``helloworld.py`` in this case is a Python *module*. Using the ``if`` clause is necessary (or at least "best practice") because code in any Python module may be imported by another Python module. By using this idiom, the script is indicating that it does not want the code within the ``if`` statement to execute if this module is imported; the code within the ``if`` block should only be run during a direct script execution. The ``config = Configurator()`` line above creates an instance of the ``repoze.bfg.configuration.Configurator`` class. The resulting ``config`` object represents an API which the script uses to configure this particular :mod:`repoze.bfg` application. .. note:: An instance of the ``Configurator`` class is a *wrapper* object which mutates an :term:`application registry` as its methods are called. An application registry represents the configuration state of a :mod:`repoze.bfg` application. The ``Configurator`` is not itself an :term:`application registry`, it is a mechanism used to configure an application registry. The underlying application registry object being configured by a ``Configurator`` is available as its ``registry`` attribute. .. code-block:: python :linenos: config.add_view(hello_world) config.add_view(goodbye_world, name='goodbye') Each of these lines calls the ``add_view`` method of the ``Configurator`` API. The ``add_view`` method of a configurator registers a :term:`view configuration` within the :term:`application registry`. A :term:`view configuration` represents a :term:`view callable` which must be invoked when a set of circumstances related to the :term:`request` is true. This "set of circumstances" is provided as one or more keyword arguments to the ``add_view`` method, otherwise known as :term:`predicate` arguments. The line ``config.add_view(hello_world)`` registers the ``hello_world`` function as a view callble. The ``add_view`` method of a Configurator must be called with a view callable object as its first argument, so the first argument passed is ``hello_world`` function we'd like to use as a :term:`view callable`. However, this line calls ``add_view`` with no additional :term:`predicate` arguments, meaning that we'd like :mod:`repoze.bfg` to invoke the ``hello_world`` view callable for *any* request if another more specific view configuration (one with more specific predicate arguments) doesn't match it more closely. Since our ``hello_world`` view callable returns a Response instance with a body of ``Hello world!``` in the configuration implied by this script, a user agent to a server running this application will receive the greeting ``Hello world!`` when any URL is invoked, unless :mod:`repoze.bfg` finds a more specific view configuration in its application registry for a given request. The line ``config.add_view(goodbye_world, name='goodbye')`` registers the ``hello_world`` function as a view callble. The line calls ``add_view`` with the view callable as the first required positional argument, and a :term:`predicate` keyword argument ``name`` with the value ``'goodbye'``. This :term:`view configuration` implies that a request with a :term:`view name` of ``goodbye`` should cause the ``goodbye_world`` view callable to be invoked. For the purposes of this discussion, the :term:`view name` can be considered the first non-empty path segment in the URL: in particular, this view configuration will match when the URL is ``/goodbye``. .. sidebar:: View Dispatching and Ordering If you've been running the code in this tutorial, you've actually unknowingly now configured :mod:`repoze.bfg` to serve an application that relies on :term:`traversal`. When :term:`traversal` is used, :mod:`repoze.bfg` chooses the most specific view callable based *only* on view :term:`predicate` applicability. This is unlike :term:`URL dispatch`, another dispatch mode of :mod:`repoze.bfg` (and other frameworks, like :term:`Pylons` and :term:`Django`) which first uses an ordered routing lookup to resolve the request to a view callable by running it through a relatively-ordered series of URL path matches. We're not really concerned about the finer details of :term:`URL dispatch` right now. It's just useful to use for demonstrative purposes: the ordering of calls to ``Configurator.add_view`` is never very important. We can register ``goodbye_world`` first and ``hello_world`` second; :mod:`repoze.bfg` will still give us the most specific callable when a request is dispatched to it. Since our ``goodbye_world`` view callable returns a Response instance with a body of ``Goodbye world!`` in the configuration implied by this script, a visit by a user agent to the URL that contains the path info ``/goodbye`` of the a server running this application will receive the greeting ``Goodbye world!`` unless :mod:`repoze.bfg` finds a more specific view configuration in its application registry for a given request. Each invocation of the ``add_view`` method implies a :term:`view configuration` registration. Each :term:`predicate` provided as a keyword argument to the ``add_view`` method narrows the set of circumstances which would cause the view configuration's callable to be invoked. In general, a greater number of predicates supplied along with a view configuration will more strictly limit the applicability of its associated view callable. When :mod:`repoze.bfg` processes a request, however, the view callable with the *most specific* view configuration (the view configuration that matches the largest number of predicates) is always invoked. Earlier we explained that the server would return ``Hello world!`` if you visited the *root* (``/``) URL. However, actually, because the view configuration registration for the ``hello_world`` view callable has no :term:`predicate` arguments, the ``hello_world`` view callable is applicable for *any request*. For example, if you visit the URL with the path info ``/buz``, you will see ``Hello world!``. The only time you *won't* see ``Hello world!`` is when you visit a URL with the path info that ends in ``/goodbye``. This is because we've also registered a *more specific* view configuration for this circumstance: the ``goodbye_world`` view callable has a ``name`` predicate of ``goodbye``, meaning that it is a better match for requests that have the :term:`view name` ``goodbye`` than the more general ``hello_world`` view configuration registration. Because :mod:`repoze.bfg` uses the most specific view configuration for any request, the ``goodbye_world`` view callable will be used when the URL contains path information that ends with ``/goodbye``. WGSI Application Creation ~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python :linenos: app = config.make_wsgi_app() After configuring views, the script creates a WSGI *application* via the ``config.make_wsgi_app`` method. A call to ``make_wsgi_app`` implies that all "configuration" is finished (meaning all method calls to the configurator which set up views, and various other configuration settings have been performed). The ``make_wsgi_app`` method returns a :term:`WSGI` application object that can be used by any WSGI server to present an application to a requestor. The :mod:`repoze.bfg` application object, in particular, is an instance of the ``repoze.bfg.router.Router`` class. It has a reference to the :term:`application registry` which resulted from method calls to the configurator used to configure it. The Router consults the registry to obey the policy choices made by a single application. These policy choices were informed by method calls to the ``Configurator`` made earlier; in our case, the only policy choices made were implied by two calls to the ``add_view`` method, telling our application that it should effectively serve up the ``hello_world`` view callable to any user agent when it visits the root URL, and the ``goodbye_world`` view callable to any user agent when it visits the URL with the path info ``/goodbye``. WSGI Application Serving ~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python :linenos: simple_server.make_server('', 8080, app).serve_forever() Finally, we actually serve the application to requestors by starting up a WSGI server. We happen to use the ``wsgiref.simple_server`` WSGI server implementation, telling it to serve the application on TCP port 8080, and we pass it the ``app`` object (an instance of ``repoze.bfg.router.Router``) as the application we wish to serve. We then call the ``serve_forever`` method of the result to ``simple_server.make_server``, causing the server to start listening on the TCP port. It will serve requests forever, or at least until we stop it by killing the process which runs it. Conclusion ~~~~~~~~~~ Our hello world application is one of the simplest possible :mod:`repoze.bfg` applications, configured "imperatively". We can see a good deal of what's going on "under the hood" when we configure a :mod:`repoze.bfg` application imperatively. However, another mode of configuration exists named *declarative* configuration. Hello World, Configured Declaratively ------------------------------------- :mod:`repoze.bfg` can be configured for the same "hello world" application "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. Declarative configuration mode is the configuration mode in which developers cede the most amount of control to the framework itself. Because application developers cede more control to the framework, it is also harder to understand than purely imperative configuration. However, using declarative configuration has a number of benefits, the primary benefit being that applications configured declaratively can be *overridden* and *extended* by third parties without requiring the third party to change application code. .. note:: See :ref:`extending_chapter` for a discussion of extending and overriding :mod:`repoze.bfg` applications. Unlike the simplest :mod:`repoze.bfg` application configured imperatively, the simplest :mod:`repoze.bfg` application, configured declaratively requires not one, but two files: a Python file and a :term:`ZCML` file. In a file named ``helloworld.py``: .. code-block:: python :linenos: from webob import Response from wsgiref import simple_server from repoze.bfg.configuration import Configurator def hello_world(request): return Response('Hello world!') if __name__ == '__main__': config = Configurator(zcml_file='configure.zcml') app = config.make_wsgi_app() simple_server.make_server('', 8080, app).serve_forever() In a file named ``configure.zcml`` in the same directory as the previously created ``helloworld.py``: .. code-block:: xml :linenos: This pair of files forms an application functionally equivalent to the application we created earlier. Let's examine the differences between the code described in :ref:`helloworld_imperative` and the code above. In :ref:`helloworld_imperative_appconfig`, we had the following lines within the ``if __name__ == '__main__'`` section of ``helloworld.py``: .. code-block:: python :linenos: if __name__ == '__main__': config = Configurator() config.add_view(hello_world) config.add_view(goodbye_world, name='goodbye') app = config.make_wsgi_app() simple_server.make_server('', 8080, app).serve_forever() In our "declarative" code, we've added a ``zcml_file`` argument to the ``Configurator`` constructor's argument list with the value ``configure.zcml``, and we've removed the lines which read ``config.add_view(hello_world)`` and ``config.add_view(goodbye_world, name='goodbye')``, so that it now reads as: .. code-block:: python :linenos: if __name__ == '__main__': config = Configurator(zcml_file='configure.zcml') app = config.make_wsgi_app() simple_server.make_server('', 8080, app).serve_forever() Everything else is much the same. The ``zcml_file`` argument to the ``Configurator`` constructor tells the configurator to load configuration declarations from the ``configure.zcml`` file which sits next to ``helloworld.py``. Let's take a look at the ``configure.zcml`` file now: .. code-block:: xml :linenos: The ```` Tag ~~~~~~~~~~~~~~~~~~~~~~~ The ``configure.zcml`` ZCML file contains this bit of XML: .. code-block:: xml :linenos: ... body ... Because :term:`ZCML` is XML, and because XML requires a single root tag for each document, every ZCML file used by :mod:`repoze.bfg` must contain a ```` container tag, which acts as the root XML tag. Usually, the start tag of the ```` container tag has a default namespace associated with it. In the file above, the ``xmlns="http:/namepaces.repoze.org/bfg"`` attribute of the ``configure`` start tag names the default XML namespace, which is ``http://namespaces.repoze.org/bfg``. See :ref:`word_on_xml_namespaces` for more information about XML namespaces. The ```` Tag ~~~~~~~~~~~~~~~~~~~~~ The ``configure.zcml`` ZCML file contains this bit of XML within the ```` root tag: .. code-block:: xml :linenos: This singleton (self-closing) tag instructs ZCML to load a ZCML file from the Python package with the :term:`dotted Python name` ``repoze.bfg.includes``, as specified by its ``package`` attribute. This particular ```` declaration is required because it actually allows subseqent declaration tags (such as ````, which we'll see shortly) to be recognized. The ```` tag effectively just includes another ZCML file; this causes its declarations to be executed. In this case, we want to load the declarations from the file named ``configure.zcml`` within the ``repoze.bfg.includes`` Python package. We know we want to load the ``configure.zcml`` from this package because ``configure.zcml`` is the default value for another attribute of the ```` tag named ``file``. We could have spelled the include tag more verbosely, but equivalently as: .. code-block:: xml :linenos: The ```` tag that includes the ZCML statements implied by the ``configure.zcml`` file from the Python package named ``repoze.bfg.includes`` is basically required to come before any other named declaration in an application's ``configure.zcml``. If it is not included, subsequent declaration tags will fail to be recognized, and the configuration system will generate a traceback. However, the ```` tag needs to exist only in a "top-level" ZCML file, it needn't also exist in ZCML files *included by* a top-level ZCML file. The ```` Tag ~~~~~~~~~~~~~~~~~~ The ``configure.zcml`` ZCML file contains these bits of XML *after* the ```` tag, but *within* the ```` root tag: .. code-block:: xml :linenos: These ```` declaration tags direct :mod:`repoze.bfg` to create two :term:`view configuration` registrations. The first ```` tag has an attribute (the attribute is also named ``view``), which points at a :term:`dotted Python name`, referencing the ``hello_world`` function defined within the ``helloworld`` package. The second ```` tag has a ``view`` attribute which points at a :term:`dotted Python name`, referencing the ``goodbye_world`` function defined within the ``helloworld`` package. The second ```` tag also has an attribute called ``name`` with a value of ``goodbye``. These effect of the ```` tag declarations we've put into our ``configure.zcml`` is functionally equivalent to the effect of lines we've already seen in an imperatively-configured application. We're just spelling things differently, using XML instead of Python. In our previously defined application, in which we added view configurations imperatively, we saw this code: .. code-block:: python :linenos: config.add_view(hello_world) config.add_view(goodbye_world, name='goodbye') Each ```` declaration tag encountered in a ZCML file effectively invokes the ``add_view`` method of the ``Configurator`` object on the behalf of the developer. Various attributes can be specified on the ```` tag which influence the :term:`view configuration` it creates. Since the relative ordering of calls to ``Configuration.add_view`` doesn't matter (see the sidebar above entitled *View Dispatching and Ordering*), the relative order of ```` tags in ZCML doesn't matter either. The following ZCML orderings are completely equivalent: .. topic:: Hello Before Goodbye .. code-block:: xml :linenos: .. topic:: Goodbye Before Hello .. code-block:: xml :linenos: The ```` tag is an example of a :mod:`repoze.bfg` declaration tag. Other such tags include ````, ````, ````, ````, and others. Each of these tags is effectively a "macro" which calls methods on the ``Configurator`` object on your behalf. ZCML Conflict Detection ~~~~~~~~~~~~~~~~~~~~~~~ An additional feature of ZCML is *conflict detection*. If you define two declaration tags within the same ZCML file which logically "collide", an exception will be raised, and the application will not start. For example, the following ZCML file has two conflicting ```` tags: .. code-block:: xml :linenos: If you try to use this ZCML file as the source of ZCML for an application, a ``ConfigurationError`` will be raised when you attempt to start the application with information about which tags might have conflicted. .. _word_on_xml_namespaces: A Word On XML Namespaces ~~~~~~~~~~~~~~~~~~~~~~~~ Using the ``http://namespaces.repoze.org/bfg`` namespace as the default XML namespace isn't strictly necessary; you can use a different default namespace as the default. However, if you do, the declaration tags which are defined by :mod:`repoze.bfg` such as the ```` declaration tag will need to be defined in such a way that the XML parser that :mod:`repoze.bfg` uses knows which namespace the :mod:`repoze.bfg` tags are associated with. For example, the following files are all completely equivalent: .. topic:: Use of A Non-Default XML Namespace .. code-block:: xml :linenos: .. topic:: Use of A Per-Tag XML Namespace Without A Default XML Namespace .. code-block:: xml :linenos: For more information about XML namespaces, see `this older, but simple XML.com article `_. Conclusions ----------- :mod:`repoze.bfg` allows an application to perform configuration tasks either imperatively or declaratively. You can choose the mode that best fits your brain as necessary. For more information about the API of the ``Configurator`` object, see :ref:`configuration_module`. The equivalent ZCML declaration tags are introduced in narrative documentation chapters as necessary. For more information about :term:`view configuration`, see :ref:`views_chapter`.