/usr/share/doc/python-pastewebkit/docs/paste-webkit.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
<title>Paste WebKit</title>
<meta name="author" content="Ian Bicking &lt;ianb&#64;colorstudy.com&gt;" />
<meta name="date" content="2005-09-26 12:08:24 -0500 (Mon, 26 Sep 2005)" />
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
  overflow: hidden;
}

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left, object.align-left {
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right, object.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: inherit }

/* div.align-center * { */
/*   text-align: left } */

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block, pre.math {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="paste-webkit">
<h1 class="title">Paste WebKit</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Ian Bicking &lt;<a class="reference external" href="mailto:ianb&#37;&#52;&#48;colorstudy&#46;com">ianb<span>&#64;</span>colorstudy<span>&#46;</span>com</a>&gt;</td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>3287</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2005-09-26 12:08:24 -0500 (Mon, 26 Sep 2005)</td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
<li><a class="reference internal" href="#installation" id="id2">Installation</a></li>
<li><a class="reference internal" href="#configuration" id="id3">Configuration</a></li>
<li><a class="reference internal" href="#deploying-an-application" id="id4">Deploying an Application</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1>Introduction</h1>
<p>This is a basic description of how to get Paste WebKit installed and
working.  It is not a tutorial (see the <a class="reference external" href="http://pythonpaste.org/docs/TodoTutorial.html">Todo Tutorial</a> for now -- but note
the installation instructions here differ from that document).</p>
</div>
<div class="section" id="installation">
<h1>Installation</h1>
<p>To install, first get <a class="reference external" href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy_install</a>.  Currently,
as not all prerequisites are fully packaged, do:</p>
<pre class="literal-block">
$ easy_install.py http://svn.pythonpaste.org/Paste/branches/mainline-refactor
$ easy_install.py http://svn.pythonpaste.org/Paste/WebKit/trunk
</pre>
<p>You may need to run these as root.  The second command should install
<a class="reference external" href="http://pythonpaste.org/deploy/paste-deploy.html">Paste Deployment</a>
on its own.</p>
</div>
<div class="section" id="configuration">
<h1>Configuration</h1>
<p>This uses Paste Deploy, so to configure your application write a .ini
file like:</p>
<pre class="literal-block">
[app:main]
use = egg:PasteWebKit
package_name = mypackage
myconfig_var = foo1
</pre>
<p>There are several configuration keys WebKit uses.  The first are to
find your application; you can use <em>one</em> of these:</p>
<p><tt class="docutils literal">servlet_directory</tt>:</p>
<blockquote>
The directory where you've put your servlets.  You can use
<tt class="docutils literal">%(here)s</tt> to refer to the directory that contains the
configuration file.</blockquote>
<p><tt class="docutils literal">package_name</tt>:</p>
<blockquote>
The package for your application.  Servlets are expected in a
<tt class="docutils literal">web</tt> subpackage.  So if you give <tt class="docutils literal">mypackage</tt> it will look in
<tt class="docutils literal">mypackage.web</tt> for the servlets.</blockquote>
<p>The other keys configure various filters/middleware:</p>
<p><tt class="docutils literal">complete_stack</tt> (default true):</p>
<blockquote>
If false, then none of the middleware will be installed.  This may
be useful if you are nesting one WebKit app inside another (and
don't want to duplicate the stack).</blockquote>
<p><tt class="docutils literal">debug</tt> (default false):</p>
<blockquote>
<p>This controls a number of settings.  Mostly errors will be
displayed in the browser with this on.  It is also picked up from
the global <tt class="docutils literal">debug</tt> setting if not given.</p>
<p>Also, with this on, the <tt class="docutils literal">printdebug</tt> filter will be installed,
which catches all print statements and shows them in a <tt class="docutils literal">&lt;pre&gt;</tt>
in each response page.</p>
</blockquote>
<p><tt class="docutils literal">cookie_name</tt> (default <tt class="docutils literal">_SID_</tt> -- for session):</p>
<blockquote>
The cookie name the session will use.</blockquote>
<p><tt class="docutils literal">session_file_path</tt> (default <tt class="docutils literal">/tmp</tt>):</p>
<blockquote>
Where the session files are kept.</blockquote>
<p><tt class="docutils literal">error_email</tt> (default: none):</p>
<blockquote>
<p>Any email addresses that should be used when reporting errors.
Adding emails here will enable this feature.  Use spaces to
separate multiple addresses.</p>
<p>If you don't give this in the application section, the keys
<tt class="docutils literal">error_email</tt> or <tt class="docutils literal">sysadmin_email</tt> (in that order) will be
pulled from te global configuration (<tt class="docutils literal">[DEFAULTS]</tt>).</p>
</blockquote>
<p><tt class="docutils literal">error_log</tt> (default: none):</p>
<blockquote>
A file to append to with error reports.</blockquote>
<p><tt class="docutils literal">show_exceptions_in_wsgi_errors</tt> (default: not debug):</p>
<blockquote>
If true then errors will show up in the server error logs.  Where
this goes depends on the server.  If debug is on, this defaults to
off, and vice versa.</blockquote>
<p><tt class="docutils literal">from_address</tt> (default: <tt class="docutils literal">errors&#64;localhost</tt>):</p>
<blockquote>
What address errors appear to come from.</blockquote>
<p><tt class="docutils literal">smtp_server</tt> (default: <tt class="docutils literal">localhost</tt>):</p>
<blockquote>
The SMTP server (for sending errors).</blockquote>
<p><tt class="docutils literal">error_subject_prefix</tt> (default: <tt class="docutils literal">[app_name]</tt>):</p>
<blockquote>
The prefix to put on error email subjects.  If an <tt class="docutils literal">app_name</tt> is
given (globally or locally) then that will be used.</blockquote>
<p><tt class="docutils literal">error_message</tt> (default: none):</p>
<blockquote>
Extra text to use in error messages presented to users (when debug
mode is off)</blockquote>
<p><tt class="docutils literal">profile</tt> (default: false):</p>
<blockquote>
If on, then all requests will be profiled.  This slows down the
app considerable, so <em>absolutely</em> don't use it except in
development.</blockquote>
<p><tt class="docutils literal">profile_limit</tt> (default: 40):</p>
<blockquote>
Show the top N slowest parts of the system.</blockquote>
<p>All other configuration keys will be sent to the application.  So in
the example <tt class="docutils literal">myconfig_var</tt> would be application configuration.</p>
<p>Applications can access this information like:</p>
<pre class="literal-block">
from paste.deploy import CONFIG

def my_routine():
    var = CONFIG['myconfig_var']
</pre>
<p>The <tt class="docutils literal">CONFIG</tt> variable dispatches to the configuration for the
<em>current request</em>, whatever that request might be.  This means you
can't use it at the module-level, because modules are loaded once,
before any per-request configuration is available.</p>
</div>
<div class="section" id="deploying-an-application">
<h1>Deploying an Application</h1>
<p>Once you've configured your application, you use Paste Deploy to
create a WSGI application.  WSGI applications can be used by many
servers.</p>
<p>To get an application you do:</p>
<pre class="literal-block">
from paste.deploy import loadapp

wsgi_app = loadapp('config:myconfig_file.ini',
                   relative_to=config_dir)
</pre>
<p>This loads the app described by <tt class="docutils literal">app:main</tt> from the configuration
file.  You can give <tt class="docutils literal"><span class="pre">config:/absolute_path</span></tt>, or use <tt class="docutils literal">relative_to</tt>
to allow relative paths.</p>
<p>You can also run the server with <a class="reference external" href="http://svn.pythonpaste.org/Paste/Script/trunk">PasteScript</a>.  Add a
<tt class="docutils literal">[server:main]</tt> section to your configuration, like:</p>
<pre class="literal-block">
[server:main]
# this is a good testing server:
use = egg:PasteScript#wsgiutils
host = 127.0.0.1
port = 8080
</pre>
<p>And then use <tt class="docutils literal">paster serve <span class="pre">--reload</span> path/to/conf.ini</tt>.  The
<tt class="docutils literal"><span class="pre">--reload</span></tt> option causes the server to restart when files are edited
(this is kind of expensive, so should only be used during
development).</p>
</div>
</div>
</body>
</html>
python-pastewebkit 1.0-7 / usr / share / doc / python-pastewebkit / docs / paste-webkit.html
