<!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">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>ForceScheduler — Buildbot 0.8.12 documentation</title>
<link rel="stylesheet" href="../_static/agogo.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.8.12',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="shortcut icon" href="../_static/buildbot.ico"/>
<link rel="top" title="Buildbot 0.8.12 documentation" href="../index.html" />
<link rel="up" title="Classes" href="classes.html" />
<link rel="next" title="IRenderable" href="cls-irenderable.html" />
<link rel="prev" title="BuildSteps" href="cls-buildsteps.html" />
</head>
<body role="document">
<div class="header-wrapper" role="banner">
<div class="header">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/header-text-transparent.png" alt="Logo"/>
</a></p>
<div class="headertitle"><a
href="../index.html">Buildbot 0.8.12 documentation</a></div>
<div class="rel" role="navigation" aria-label="related navigation">
<a href="cls-buildsteps.html" title="BuildSteps"
accesskey="P">previous</a> |
<a href="cls-irenderable.html" title="IRenderable"
accesskey="N">next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
accesskey="I">index</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="forcescheduler">
<span id="id1"></span><h1>ForceScheduler<a class="headerlink" href="#forcescheduler" title="Permalink to this headline">¶</a></h1>
<p>The force scheduler has a symbiotic relationship with the web status, so it
deserves some further description.</p>
<div class="section" id="parameters">
<h2>Parameters<a class="headerlink" href="#parameters" title="Permalink to this headline">¶</a></h2>
<p>The force scheduler comes with a fleet of parameter classes. This section
contains information to help users or developers who are interested in adding
new parameter types or hacking the existing types.</p>
<span class="target" id="module-buildbot.schedulers.forceshed"></span><dl class="class">
<dt id="buildbot.schedulers.forceshed.BaseParameter">
<em class="property">class </em><code class="descclassname">buildbot.schedulers.forceshed.</code><code class="descname">BaseParameter</code><span class="sig-paren">(</span><em>name</em>, <em>label</em>, <em>regex</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the base implementation for most parameters, it will check validity,
ensure the arg is present if the <code class="xref py py-attr docutils literal"><span class="pre">required</span></code> attribute
is set, and implement the default value. It will finally call
<code class="xref py py-meth docutils literal"><span class="pre">updateFromKwargs</span></code> to process the string(s) from the
HTTP POST.</p>
<p>The <a class="reference internal" href="#buildbot.schedulers.forceshed.BaseParameter" title="buildbot.schedulers.forceshed.BaseParameter"><code class="xref py py-class docutils literal"><span class="pre">BaseParameter</span></code></a> constructor converts all keyword arguments
into instance attributes, so it is generally not necessary for subclasses to
implement a constructor.</p>
<p>For custom parameters that set properties, one simple customization point
is <cite>getFromKwargs</cite>:</p>
<blockquote>
<div><dl class="method">
<dt id="buildbot.schedulers.forceshed.BaseParameter.getFromKwargs">
<code class="descname">getFromKwargs</code><span class="sig-paren">(</span><em>kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.getFromKwargs" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>kwargs</strong> -- a dictionary of the posted values</td>
</tr>
</tbody>
</table>
<p>Given the passed-in POST parameters, return the value of the property
that should be set.</p>
</dd></dl>
</div></blockquote>
<p>For more control over parameter parsing, including modifying sourcestamps or
changeids, override the <code class="docutils literal"><span class="pre">updateFromKwargs</span></code> function, which is the function
that <code class="xref py py-class docutils literal"><span class="pre">ForceScheduler</span></code> invokes for processing:</p>
<blockquote>
<div><dl class="method">
<dt id="buildbot.schedulers.forceshed.BaseParameter.updateFromKwargs">
<code class="descname">updateFromKwargs</code><span class="sig-paren">(</span><em>master</em>, <em>properties</em>, <em>changes</em>, <em>sourcestamps</em>, <em>kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.updateFromKwargs" title="Permalink to this definition">¶</a></dt>
<dd><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>master</strong> -- the <code class="xref py py-class docutils literal"><span class="pre">BuildMaster</span></code> instance</li>
<li><strong>properties</strong> -- a dictionary of properties</li>
<li><strong>changes</strong> -- a list of changeids that will be used to build the
SourceStamp for the forced builds</li>
<li><strong>sourcestamps</strong> -- the SourceStamp dictionary that will be passed to the
build; some parameters modify sourcestamps rather than properties.</li>
<li><strong>kwargs</strong> -- a dictionary of the posted values</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>This method updates <code class="docutils literal"><span class="pre">properties</span></code>, <code class="docutils literal"><span class="pre">changes</span></code>, and/or <code class="docutils literal"><span class="pre">sourcestamps</span></code>
according to the request. The default implementation is good for many simple
uses, but can be overridden for more complex purposes.</p>
<p>When overriding this function, take all parameters by name (not by position),
and include an <code class="docutils literal"><span class="pre">**unused</span></code> catch-all to guard against future changes.</p>
</dd></dl>
<p>The remaining attributes and methods should be overridden by subclasses, although
<a class="reference internal" href="#buildbot.schedulers.forceshed.BaseParameter" title="buildbot.schedulers.forceshed.BaseParameter"><code class="xref py py-class docutils literal"><span class="pre">BaseParameter</span></code></a> provides appropriate defaults.</p>
<dl class="attribute">
<dt id="buildbot.schedulers.forceshed.BaseParameter.name">
<code class="descname">name</code><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.name" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of the parameter. This corresponds to the name of the
property that your parameter will set. This name is also used
internally as identifier for http POST arguments</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.schedulers.forceshed.BaseParameter.label">
<code class="descname">label</code><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.label" title="Permalink to this definition">¶</a></dt>
<dd><p>The label of the parameter, as displayed to the user. This value
can contain raw HTML.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.schedulers.forceshed.BaseParameter.fullName">
<code class="descname">fullName</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.fullName" title="Permalink to this definition">¶</a></dt>
<dd><p>A fully-qualified name that uniquely identifies the parameter in the
scheduler. This name is used internally as the identifier for HTTP
POST arguments. It is a mix of <cite>name</cite> and the parent's <cite>name</cite> (in the
case of nested parameters). This field is not modifiable.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.schedulers.forceshed.BaseParameter.type">
<code class="descname">type</code><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.type" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of types that the parameter conforms to. These are used by the
jinja template to create appropriate html form widget. The available
values are visible in <a class="reference external" href="https://github.com/buildbot/buildbot/blob/master/master/buildbot/status/web/template/forms.html" title="master/buildbot/status/web/template/forms.html"><code class="docutils literal"><span class="pre">master/buildbot/status/web/template/forms.html</span></code></a>
in the <code class="docutils literal"><span class="pre">force_build_one_scheduler</span></code> macro.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.schedulers.forceshed.BaseParameter.default">
<code class="descname">default</code><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.default" title="Permalink to this definition">¶</a></dt>
<dd><p>The default value to use if there is no user input. This is also
used to fill in the form presented to the user.</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.schedulers.forceshed.BaseParameter.required">
<code class="descname">required</code><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.required" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, an error will be shown to user if there is no input in this
field</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.schedulers.forceshed.BaseParameter.multiple">
<code class="descname">multiple</code><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.multiple" title="Permalink to this definition">¶</a></dt>
<dd><p>If true, this parameter represents a list of values (e.g. list of
tests to run)</p>
</dd></dl>
<dl class="attribute">
<dt id="buildbot.schedulers.forceshed.BaseParameter.regex">
<code class="descname">regex</code><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.regex" title="Permalink to this definition">¶</a></dt>
<dd><p>A string that will be compiled as a regex and used to validate the
string value of this parameter. If None, then no validation will
take place.</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.schedulers.forceshed.BaseParameter.parse_from_args">
<code class="descname">parse_from_args</code><span class="sig-paren">(</span><em>l</em><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.parse_from_args" title="Permalink to this definition">¶</a></dt>
<dd><p>return the list of object corresponding to the list or string passed
default function will just call <a class="reference internal" href="#buildbot.schedulers.forceshed.BaseParameter.parse_from_arg" title="buildbot.schedulers.forceshed.BaseParameter.parse_from_arg"><code class="xref py py-func docutils literal"><span class="pre">parse_from_arg</span></code></a> with the
first argument</p>
</dd></dl>
<dl class="method">
<dt id="buildbot.schedulers.forceshed.BaseParameter.parse_from_arg">
<code class="descname">parse_from_arg</code><span class="sig-paren">(</span><em>s</em><span class="sig-paren">)</span><a class="headerlink" href="#buildbot.schedulers.forceshed.BaseParameter.parse_from_arg" title="Permalink to this definition">¶</a></dt>
<dd><p>return the object corresponding to the string passed
default function will just return the unmodified string</p>
</dd></dl>
</div></blockquote>
</dd></dl>
</div>
<div class="section" id="nested-parameters">
<h2>Nested Parameters<a class="headerlink" href="#nested-parameters" title="Permalink to this headline">¶</a></h2>
<p>The <code class="xref py py-class docutils literal"><span class="pre">NestedParameter</span></code> class is a container for parameters. The motivating purpose for this feature
is the multiple-codebase configuration, which needs to provide the user with a form to control
the branch (et al) for each codebase independently. Each branch parameter is a string field with name
'branch' and these must be disambiguated.</p>
<p>Each of the child parameters mixes in the parent's name to create the fully qualified <code class="docutils literal"><span class="pre">fullName</span></code>. This
allows, for example, each of the 'branch' fields to have a unique name in the POST request. The
<cite>NestedParameter</cite> handles adding this extra bit to the name to each of the children. When the <cite>kwarg</cite>
dictionary is posted back, this class also converts the flat POST dictionary into a richer structure
that represents the nested structure.</p>
<p>As illustration, if the nested parameter has the name 'foo', and has children 'bar1' and 'bar2', then the
POST will have entries like "foo-bar1" and "foo-bar2". The nested parameter will translate this into a
dictionary in the 'kwargs' structure, resulting in something like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">kwargs</span> <span class="o">=</span> <span class="p">{</span>
<span class="c1"># ...</span>
<span class="s1">'foo'</span><span class="p">:</span> <span class="p">{</span>
<span class="s1">'bar1'</span><span class="p">:</span> <span class="s1">'...'</span><span class="p">,</span>
<span class="s1">'bar2'</span><span class="p">:</span> <span class="s1">'...'</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Arbitrary nesting is allowed and results in a deeper dictionary structure.</p>
<p>Nesting can also be used for presentation purposes. If the name of the <code class="xref py py-class docutils literal"><span class="pre">NestedParameter</span></code> is empty, the
nest is "anonymous" and does not mangle the child names. However, in the HTML layout, the nest
will be presented as a logical group.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h3>Table Of Contents</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Buildbot Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../manual/index.html">Buildbot Manual</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Buildbot Development</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="master-overview.html">Master Organization</a></li>
<li class="toctree-l2"><a class="reference internal" href="definitions.html">Definitions</a></li>
<li class="toctree-l2"><a class="reference internal" href="style.html">Buildbot Coding Style</a></li>
<li class="toctree-l2"><a class="reference internal" href="tests.html">Buildbot's Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="config.html">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="utils.html">Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="database.html">Database</a></li>
<li class="toctree-l2"><a class="reference internal" href="results.html">Build Result Codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="formats.html">File Formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="webstatus.html">Web Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="master-slave.html">Master-Slave API</a></li>
<li class="toctree-l2"><a class="reference internal" href="encodings.html">String Encodings</a></li>
<li class="toctree-l2"><a class="reference internal" href="metrics.html">Metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="plugins-publish.html">How to package Buildbot plugins</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="classes.html">Classes</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="cls-buildfactory.html">BuildFactory</a></li>
<li class="toctree-l3"><a class="reference internal" href="cls-buildsetsummarynotifiermixin.html">BuildSetSummaryNotifierMixin</a></li>
<li class="toctree-l3"><a class="reference internal" href="cls-remotecommands.html">RemoteCommands</a></li>
<li class="toctree-l3"><a class="reference internal" href="cls-buildsteps.html">BuildSteps</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">ForceScheduler</a><ul class="simple">
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="cls-irenderable.html">IRenderable</a></li>
<li class="toctree-l3"><a class="reference internal" href="cls-iproperties.html">IProperties</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../relnotes/index.html">Release Notes for Buildbot 0.8.12</a></li>
</ul>
<div role="search">
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<div role="navigation" aria-label="related navigaton">
<a href="cls-buildsteps.html" title="BuildSteps"
>previous</a> |
<a href="cls-irenderable.html" title="IRenderable"
>next</a> |
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="../genindex.html" title="General Index"
>index</a>
</div>
<div role="note" aria-label="source link">
<br/>
<a href="../_sources/developer/cls-forcesched.txt"
rel="nofollow">Show Source</a>
</div>
</div>
<div class="right">
<div class="footer" role="contentinfo">
© Copyright Buildbot Team Members.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.1.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
