From bce09cafb4c5161d459e2935a60bcdc6c5757acc Mon Sep 17 00:00:00 2001 From: Ian Bicking Date: Mon, 22 Aug 2005 22:54:02 +0000 Subject: Removed defunct docs --- docs/configuration.txt | 159 ------------------------------------------------- docs/integration.txt | 132 ---------------------------------------- docs/rebuild | 4 +- docs/servers.txt | 97 ------------------------------ 4 files changed, 2 insertions(+), 390 deletions(-) delete mode 100644 docs/configuration.txt delete mode 100644 docs/integration.txt delete mode 100644 docs/servers.txt diff --git a/docs/configuration.txt b/docs/configuration.txt deleted file mode 100644 index a7f155d..0000000 --- a/docs/configuration.txt +++ /dev/null @@ -1,159 +0,0 @@ -Configuration In Paste -====================== - -:author: Ian Bicking -:revision: $Rev$ -:date: $LastChangedDate$ - -.. contents:: - -Introduction ------------- - -This document covers Paste configuration; both how to use the -configuration from your application, and how to configure Paste -applications. - -Configuration Format --------------------- - -Configuration files are Python syntax. That means any Python -expression can go in the files, and of course that they must be valid -Python. - -By default Paste will look for a configuration file named -``server.conf``, though you can specify a different (or additional) -configuration file with the ``-f`` option to ``paster``. - -All global variables in a configuration file are put into the -configuration. So a configuration file just looks like:: - - connection_string = 'dbname=foo' - server = 'wsgiutils' - port = 5000 - publish_object = 'myapp:app' - framework = 'fancy_framework' - -This configuration will be given to nearly all parts of the system, -and those parts will pick out variables that are of interest to them. -For example ``server = 'wsgiutils'`` is used by ``paster serve`` to -pick a server. ``framework = 'fancy_framework'`` is used to build -your WSGI application from the configuration file. -``connection_string = 'dbname=foo'`` is, presumably, used by your -application to open a database connection. - -Command-line Options --------------------- - -The ``paster serve`` command also takes arbitrary command-line options, -and turns them into configuration values. So -``--connection-string=dbname=foo`` will add or overwrite the -configuration value. - -If the application or component cannot accept strings for a -configuration value, this will not work. Most components included -with Paste accept strings. Note that the empty string is false (e.g., -``--do-something=``) and a non-empty string is true (e.g., -``--do-something=t``). ``--do-something=f`` is **true** (since all -non-empty strings are true in Python). - -Other ``paster`` commands do not take arbitrary configuration values -like this. - -Including and Nesting Configuration ------------------------------------ - -Several configuration files can be loaded, and configuration files can -include other configuration files. Two commands in particular are -important for this:: - - include('filename.conf') - options = load('filename.conf') - -``include(filename)`` loads the given file, and uses all its -configuration values. ``load(filename)`` loads the file, but -*returns* all its configuration values -- this is for nested -configuration. So in this example ``options`` would be a dictionary -of configuration values. In most cases you'll use ``include()``. - -When a configuration file is being evaluated, it also has access to -all the values already loaded. So you can do:: - - index_files = ['index', 'main'] - include('other_file.conf') - -And in ``other_file.conf``:: - - index_files.append('default') - -This kind of flexibility is very useful, and gives -sub-configuration-files the ability to augment or replace previous -values. You can also use any other Python commands you like, -including things like:: - - js_url = '/js-lib' - calendar_url = js_url + '/calendar' - -One useful thing is to have "profiles". So you would start your -server like:: - - $ paster serve --profile=devel - -And in your configuration:: - - value1 = ... - (and other defaults) - include(profile + '.conf') - -This is a good way for overriding configuration for development and -production environments. - -Accessing Configuration ------------------------ - -When in a request, the object ``environ['paste.config']`` will give -you the configuration. This object is a dictionary-like object. You -can change values, and load more configuration files with -``conf.load(filename)``. For instance, you could use this to load -additional configuration for different requests. The configuration is -copied for every request, so modifications to the configuration do not -effect future or concurrent requests. As an example, if you are using -``urlparser.URLParser`` you could put this in your ``__init__.py``:: - - def urlparser_hook(environ): - environ['paste.config'].load( - os.path.join(os.path.dirname(__file__), 'dir.conf')) - -Frameworks are free to make this variable available through more -convenient means. - -Often, though, you'll find you need a configuration value in some -routine, and the request or the configuration was not passed in. In -these cases you can use ``paste.CONFIG``, which acts like a dictionary -and represents the current configuration (for this request or -process). - -``paste.CONFIG`` is a global object that can have configuration -*registered*. You do this like:: - - from paste import CONFIG - from paste.pyconfig import Config - conf = Config() - conf.load('file.conf') - CONFIG.push_process_config(conf) - -You can also use ``CONFIG.push_thread_config(conf)`` to just set the -configuration for the current thread. During a web request this is -done for you, so you can safely use ``paste.CONFIG`` to access the -configuration. If you are using the same configuration for other -means, like a background process, you can use ``push_process_config`` -to load the configuration manually. Also, the "main" -(``server.conf``) configuration is loaded as the process configuration -when using ``paster serve``. - -More Information ----------------- - -For more details of the configuration object and its use, see the -`reference documentation -`_. diff --git a/docs/integration.txt b/docs/integration.txt deleted file mode 100644 index 0582283..0000000 --- a/docs/integration.txt +++ /dev/null @@ -1,132 +0,0 @@ -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``. - diff --git a/docs/rebuild b/docs/rebuild index ea73637..114ea9b 100755 --- a/docs/rebuild +++ b/docs/rebuild @@ -6,9 +6,9 @@ echo "Adding $parent to \$PYTHONPATH" export PYTHONPATH=$parent:$PYTHONPATH DEPLOY_BASE="/home/paste/Paste-Deploy" -NORMAL="DeveloperGuidelines Paste servers StyleGuide index web/index \ +NORMAL="DeveloperGuidelines Paste StyleGuide index web/index \ what-is-paste testing-applications url-parsing-with-wsgi \ - roadmap configuration integration web/community/mailing-list + roadmap web/community/mailing-list web/community/repository web/community/index web/download/index web/package_index" DOCTEST_BUILD="blog-tutorial TodoTutorial" diff --git a/docs/servers.txt b/docs/servers.txt deleted file mode 100644 index a0a478e..0000000 --- a/docs/servers.txt +++ /dev/null @@ -1,97 +0,0 @@ -++++++++++++++++++++ -Python Paste Servers -++++++++++++++++++++ - -:author: A.M. Kuchling -:revision: $Rev$ -:date: $LastChangedDate$ - - -Introduction -============ - -This file describes the operation of the wsgi-server script, and -explains how to package applications so that wsgi-server can run them. - -Overview: wsgi-server creates a configuration, which contains both -information about a particular application and how the application -should be executed (e.g. as a CGI, as a standalone server). -Configuration files are just Python code that sets variables; the -configuration is then just a dictionary constructed from the resulting -namespace - -The application is then executed based on this configuration. -Applications can be run in different modes (CGI, standalone HTTP, -etc.); the different modes look at various configuration parameters to -control the results. - - -Configuration -============= - -Configuration information is read from a number of sources, in the -following order. - - 1. A set of default values, contained in the code of the - paste.server module. - 2. From wsgi-server's command line arguments. - 3. From the ``default_config.conf`` file in the installed ``paste`` directory. - 4. From the `server.conf` file in the current working directory. - (You can set a `no_server_conf` config setting to skip - reading this file.) - 5. If the `config_file` setting is present at this point, - it should contain the path of a configuration file. - This file is parsed and processed last. - -After going through these steps, configuration is complete. - - -Servers --------- - -Paste can run a web application in a number of different modes: CGI, -standalone HTTP, SCGI, and a console mode which simulates CGI. Some -of these modes require additional software; the ``build-pkg`` script -will download the necessary packages for you. - - -cgi -========== - -Outputs a CGI script to standard output for running the application. - - -console -========== - -Simulates a web application from the console. - - -scgi -========== - -Runs a SCGI server. - -Configuration settings: - - * ``scgi_prefix`` -- URL prefix that the SCGI server will expect. - * ``port`` -- port number that SCGI server will listen on - - -twisted -======== - -Runs an HTTP server using Twisted. - - -wsgiutils -=========== - -Runs an HTTP server using the wsgiref code and the Python stdlib. - -Configuration settings: - - * ``host`` -- hostname that the HTTP server will bind to (default: - localhost). - * ``port`` -- port number that HTTP server will listen on (default: 8080) - -- cgit v1.2.1