From 4aba5d5e12c6bf62771ce2eb918dc636154a033a Mon Sep 17 00:00:00 2001 From: ianb Date: Tue, 14 Jun 2005 06:19:30 +0000 Subject: New document, Integrating Frameworks Into Paste --- docs/integration.txt | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 docs/integration.txt (limited to 'docs/integration.txt') diff --git a/docs/integration.txt b/docs/integration.txt new file mode 100644 index 0000000..5e97e15 --- /dev/null +++ b/docs/integration.txt @@ -0,0 +1,132 @@ +Integrating Frameworks Into Paste +================================= + +:author: Ian Bicking +:revision: $Rev$ +:date: $LastChangedDate$ + +.. contents:: + +Introduction and Audience +------------------------- + +This document is intended for Python web framework developers who want +to integrate or support Paste with their frameworks. + +Its Paste's intention to support all frameworks that support WSGI. +However, there are many levels of integration with paste, and it takes +some minimal glue. + +WSGI +---- + +`WSGI `_ is at the core of +everything in Paste. For a framework to work in Paste, it has to +support WSGI. If you haven't done that, then you know where to start. + +Creating the Application +------------------------ + +Once your framework supports WSGI, you will have added the code to +create a WSGI "application". Paste brings together the WSGI server, a +series of middleware, and a WSGI application. + +Paste does this with a configuration file. Paste instantiates a +server based on the configuration, collects the middleware (from the +``middleware`` configuration variable), and the application. + +Configuration in Paste is "pull". That is, the configuration is a +dumb dictionary, and you pull whatever keys out of it that you are +interested in. The sole function your framework needs to provide is +``build_application(conf)``, which takes the `configuration +`_ object and returns +a WSGI application. That's it. + +However, to be a friendly framework, this function should look +something like this:: + + from paste import makeapp + + def build_application(conf): + app = (something framework specific) + app = makeapp.apply_conf_middleware( + app, conf, [other middleware]) + app = makeapp.apply_default_middleware(app, conf) + return app + +The ``makeapp.apply_conf_middleware`` function uses the ``middleware`` +configuration variable. The third argument is an optional list of +other middleware. All this middleware must take just one argument, +the application that it wraps. + +The ``makeapp.apply_default_middleware`` function applies middleware +that should always be present, specifically `ConfigMiddleware +`_ +and `ErrorMiddleware +`_. + +The ``(something framework specific)`` portion is up to you. You +might pull out configuration variables, e.g., ``publish_dir`` or +``publish_object``. Whatever you want; just be sure to tell your +users. + +Paste Plugins +------------- + +Now you are thinking, *where do I put build_application*? Well, I'm +glad you asked. + +First, every framework has a name. The configuration file must +contain ``framework = "framework_name"``. + +Paste puts different plugins in different directories in the ``paste`` +package. The framework plugins go in +``paste/frameworks/*_framework.*``. + +For instance, the ``webkit`` framework goes in +``paste/frameworks/webkit_framework.txt``. The file can be either a +``.txt`` file, or a ``.py`` file. + +A ``.py`` file is a module that contains the ``build_application`` +function. A ``.txt`` file contains the name of the module that +contains the ``build_application`` function. So if you don't want to +put a Python file in the ``paste`` package, you can just put a +reference back into your package. + +To install a plugin, you can do:: + + import os + import paste + f = open(os.path.join(os.path.dirname(paste.__file__), + 'frameworks', 'foobar_framework.txt'), 'w') + f.write('.'.join(__name__.split('.')[:-1] + ['paste_setup'])) + f.write('\n') + f.close() + +This is assuming that this is a module in the package, and there's a +sister module in ``package.paste_setup``. + +Application Templates +--------------------- + +The framework is a good starting point. An application template is a +nice second step. + +An application template is a set of commands to ``paster``, and +typically a bare set of files for a new application. This is meant to +help users get examples set up quickly, and provide some guidance. A +framework can have multiple application templates. + +For now, the best way to understand this is to look at the +``webkit_zpt`` template included with Paste. This combines +Webkit/Webware and Zope Page Templates; another application template +might use a different templating language, or might bring in other +sub-frameworks. + +Application templates are also plugins, put in +``paste/app_templates/*_tmpl.*``. They contain one function, ``run``. +This is typically implemented by +``paste.app_setup.CommandRunner.run``, and the actual commands (since +``paster`` is a two-level command-line application) are subclasses of +``paste.app_setup.Command``. + -- cgit v1.2.1