<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Werkzeug Documentation</title>
<link rel="stylesheet" href="_static/style.css" type="text/css">
<link rel="stylesheet" href="_static/print.css" type="text/css" media="print">
<link rel="stylesheet" href="_static/pygments.css" type="text/css">
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '#',
VERSION: '0.6.1'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/interface.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/werkzeug.js"></script>
<link rel="contents" title="Global table of contents" href="contents.html">
<link rel="index" title="Global index" href="genindex.html">
<link rel="search" title="Search" href="search.html">
<link rel="top" title="Werkzeug v0.6.1 documentation" href="index.html">
<link rel="next" title="Request / Response Objects" href="wrappers.html">
<link rel="prev" title="Debugging Applications" href="debug.html">
</head>
<body>
<div class="page">
<div class="header">
<h1 class="heading"><a href="index.html"
title="back to the documentation overview"><span>Werkzeug</span></a></h1>
</div>
<ul class="navigation">
<li class="indexlink"><a href="index.html">Overview</a></li>
<li><a href="debug.html">« Debugging Applications</a></li>
<li class="active"><a href="#">Management Script Utilities</a></li>
<li><a href="wrappers.html">Request / Response Objects »</a></li>
</ul>
<div class="body">
<div id="toc">
<h3>Table Of Contents</h3>
<div class="inner"><ul>
<li><a class="reference external" href="#">Management Script Utilities</a><ul>
<li><a class="reference external" href="#basic-usage">Basic Usage</a></li>
<li><a class="reference external" href="#using-the-scripts">Using The Scripts</a></li>
<li><a class="reference external" href="#writing-actions">Writing Actions</a></li>
<li><a class="reference external" href="#action-discovery">Action Discovery</a></li>
<li><a class="reference external" href="#reference">Reference</a></li>
<li><a class="reference external" href="#example-scripts">Example Scripts</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="section" id="module-werkzeug.script">
<span id="management-script-utilities"></span><h1>Management Script Utilities<a class="headerlink" href="#module-werkzeug.script" title="Permalink to this headline">¶</a></h1>
<p>Most of the time you have recurring tasks while writing an application
such as starting up an interactive python interpreter with some prefilled
imports, starting the development server, initializing the database or
something similar.</p>
<p>For that purpose werkzeug provides the <cite>werkzeug.script</cite> module which
helps you writing such scripts.</p>
<div class="section" id="basic-usage">
<h2>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h2>
<p>The following snippet is roughly the same in every werkzeug script:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c">#!/usr/bin/env python</span>
<span class="c"># -*- coding: utf-8 -*-</span>
<span class="kn">from</span> <span class="nn">werkzeug</span> <span class="kn">import</span> <span class="n">script</span>
<span class="c"># actions go here</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">'__main__'</span><span class="p">:</span>
<span class="n">script</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
<p>Starting this script now does nothing because no actions are defined.
An action is a function in the same module starting with <tt class="docutils literal"><span class="pre">"action_"</span></tt>
which takes a number of arguments where every argument has a default. The
type of the default value specifies the type of the argument.</p>
<p>Arguments can then be passed by position or using <tt class="docutils literal"><span class="pre">--name=value</span></tt> from
the shell.</p>
<p>Because a runserver and shell command is pretty common there are two
factory functions that create such commands:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">make_app</span><span class="p">():</span>
<span class="kn">from</span> <span class="nn">yourapplication</span> <span class="kn">import</span> <span class="n">YourApplication</span>
<span class="k">return</span> <span class="n">YourApplication</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
<span class="n">action_runserver</span> <span class="o">=</span> <span class="n">script</span><span class="o">.</span><span class="n">make_runserver</span><span class="p">(</span><span class="n">make_app</span><span class="p">,</span> <span class="n">use_reloader</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="n">action_shell</span> <span class="o">=</span> <span class="n">script</span><span class="o">.</span><span class="n">make_shell</span><span class="p">(</span><span class="k">lambda</span><span class="p">:</span> <span class="p">{</span><span class="s">'app'</span><span class="p">:</span> <span class="n">make_app</span><span class="p">()})</span>
</pre></div>
</div>
</div>
<div class="section" id="using-the-scripts">
<h2>Using The Scripts<a class="headerlink" href="#using-the-scripts" title="Permalink to this headline">¶</a></h2>
<p>The script from above can be used like this from the shell now:</p>
<div class="highlight-text"><div class="highlight"><pre>$ ./manage.py --help
$ ./manage.py runserver localhost 8080 --debugger --no-reloader
$ ./manage.py runserver -p 4000
$ ./manage.py shell
</pre></div>
</div>
<p>As you can see it’s possible to pass parameters as positional arguments
or as named parameters, pretty much like Python function calls.</p>
</div>
<div class="section" id="writing-actions">
<h2>Writing Actions<a class="headerlink" href="#writing-actions" title="Permalink to this headline">¶</a></h2>
<p>Writing new action functions is pretty straightforward. All you have to do is
to name the function <cite>action_COMMAND</cite> and it will be available as
<cite>./manage.py COMMAND</cite>. The docstring of the function is used for the help
screen and all arguments must have defaults which the <cite>run</cite> function can
inspect. As a matter of fact you cannot use <tt class="docutils literal"><span class="pre">*args</span></tt> or <tt class="docutils literal"><span class="pre">**kwargs</span></tt>
constructs.</p>
<p>An additional feature is the definition of tuples as defaults. The first item
in the tuple could be a short name for the command and the second the default
value:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">action_add_user</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="p">(</span><span class="s">'u'</span><span class="p">,</span> <span class="s">''</span><span class="p">),</span> <span class="n">password</span><span class="o">=</span><span class="p">(</span><span class="s">'p'</span><span class="p">,</span> <span class="s">''</span><span class="p">)):</span>
<span class="sd">"""Docstring goes here."""</span>
<span class="o">...</span>
</pre></div>
</div>
</div>
<div class="section" id="action-discovery">
<h2>Action Discovery<a class="headerlink" href="#action-discovery" title="Permalink to this headline">¶</a></h2>
<p>Per default, the <cite>run</cite> function looks up variables in the current locals.
That means if no arguments are provided, it implicitly assumes this call:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">script</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="nb">locals</span><span class="p">(),</span> <span class="s">'action_'</span><span class="p">)</span>
</pre></div>
</div>
<p>If you don’t want to use an action discovery, you can set the prefix to an
empty string and pass a dict with functions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">script</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="nb">dict</span><span class="p">(</span>
<span class="n">runserver</span><span class="o">=</span><span class="n">script</span><span class="o">.</span><span class="n">make_runserver</span><span class="p">(</span><span class="n">make_app</span><span class="p">,</span> <span class="n">use_reloader</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
<span class="n">shell</span><span class="o">=</span><span class="n">script</span><span class="o">.</span><span class="n">make_shell</span><span class="p">(</span><span class="k">lambda</span><span class="p">:</span> <span class="p">{</span><span class="s">'app'</span><span class="p">:</span> <span class="n">make_app</span><span class="p">()}),</span>
<span class="n">initdb</span><span class="o">=</span><span class="n">on_initdb</span>
<span class="p">),</span> <span class="s">''</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="reference">
<h2>Reference<a class="headerlink" href="#reference" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="werkzeug.script.run">
<tt class="descclassname">werkzeug.script.</tt><tt class="descname">run</tt><big>(</big><em>namespace=None</em>, <em>action_prefix='action_'</em>, <em>args=None</em><big>)</big><a class="headerlink" href="#werkzeug.script.run" title="Permalink to this definition">¶</a></dt>
<dd><p>Run the script. Participating actions are looked up in the caller’s
namespace if no namespace is given, otherwise in the dict provided.
Only items that start with action_prefix are processed as actions. If
you want to use all items in the namespace provided as actions set
action_prefix to an empty string.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>namespace</strong> – An optional dict where the functions are looked up in.
By default the local namespace of the caller is used.</li>
<li><strong>action_prefix</strong> – The prefix for the functions. Everything else
is ignored.</li>
<li><strong>args</strong> – the arguments for the function. If not specified
<a title="(in Python v2.7)" class="reference external" href="http://docs.python.org/dev/library/sys.html#sys.argv"><tt class="xref py py-data docutils literal"><span class="pre">sys.argv</span></tt></a> without the first argument is used.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="werkzeug.script.make_shell">
<tt class="descclassname">werkzeug.script.</tt><tt class="descname">make_shell</tt><big>(</big><em>init_func=None</em>, <em>banner=None</em>, <em>use_ipython=True</em><big>)</big><a class="headerlink" href="#werkzeug.script.make_shell" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an action callback that spawns a new interactive
python shell.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>init_func</strong> – an optional initialization function that is
called before the shell is started. The return
value of this function is the initial namespace.</li>
<li><strong>banner</strong> – the banner that is displayed before the shell. If
not specified a generic banner is used instead.</li>
<li><strong>use_ipython</strong> – if set to <cite>True</cite> ipython is used if available.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="werkzeug.script.make_runserver">
<tt class="descclassname">werkzeug.script.</tt><tt class="descname">make_runserver</tt><big>(</big><em>app_factory</em>, <em>hostname='localhost'</em>, <em>port=5000</em>, <em>use_reloader=False</em>, <em>use_debugger=False</em>, <em>use_evalex=True</em>, <em>threaded=False</em>, <em>processes=1</em>, <em>static_files=None</em>, <em>extra_files=None</em>, <em>ssl_context=None</em><big>)</big><a class="headerlink" href="#werkzeug.script.make_runserver" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an action callback that spawns a new development server.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.5: </span><cite>static_files</cite> and <cite>extra_files</cite> was added.</p>
<dl class="docutils">
<dt>..versionadded:: 0.6.1</dt>
<dd><cite>ssl_context</cite> was added.</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>app_factory</strong> – a function that returns a new WSGI application.</li>
<li><strong>hostname</strong> – the default hostname the server should listen on.</li>
<li><strong>port</strong> – the default port of the server.</li>
<li><strong>use_reloader</strong> – the default setting for the reloader.</li>
<li><strong>use_evalex</strong> – the default setting for the evalex flag of the debugger.</li>
<li><strong>threaded</strong> – the default threading setting.</li>
<li><strong>processes</strong> – the default number of processes to start.</li>
<li><strong>static_files</strong> – optional dict of static files.</li>
<li><strong>extra_files</strong> – optional list of extra files to track for reloading.</li>
<li><strong>ssl_context</strong> – optional SSL context for running server in HTTPS mode.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</div>
<div class="section" id="example-scripts">
<h2>Example Scripts<a class="headerlink" href="#example-scripts" title="Permalink to this headline">¶</a></h2>
<p>In the Werkzeug <a class="reference external" href="http://dev.pocoo.org/projects/werkzeug/browser/examples">example folder</a> there are some <tt class="docutils literal"><span class="pre">./manage-APP.py</span></tt> scripts
using <cite>werkzeug.script</cite>.</p>
</div>
</div>
<div style="clear: both"></div>
</div>
<div class="footer">
© Copyright 2008 by the <a href="http://pocoo.org/">Pocoo Team</a>,
documentation generated by <a href="http://sphinx.pocoo.org/">Sphinx</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
i386
>
media
>
os
>
by-pkgid
>
5c4f8358fd6fdc210fb0d926bd25802c
>
files
>
258
