<!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>Willie IRC Bot 3.2.0 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '3.2.0',
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="top" title="None" href="index.html#document-index" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li><a href="index.html#document-index">Willie IRC Bot 3.2.0 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
<p>This package contains a framework for an easily set-up, multi-purpose IRC bot.
The intent with this package is not that it be included with other packages,
but rather be run as a standalone program. However, it is intended (and
encouraged) that users write new “modules” for it. This documentation is
intended to serve that goal.</p>
<p>Due to the high level of customization encouraged by this bot, there are a few
different versions of it floating around. For this documentation, we will cover
three: the original “phenny” by Sean B. Palmer the “jenni” fork by Michael
Yanovich, and the “Willie” fork by Edward Powell et al. While all receive
periodic updates, the above lists them in a generally ascending order of
recentness.</p>
<p>For clarity’s sake, this documentation will refer to these forks as different
“API levels” or “API versions”. The original phenny fork will be termed <em>1.x</em>,
the jenni fork will be termed <em>2.x</em>, and Willie, which this guide will focus
on, will be termed <em>3.x</em>.</p>
<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="#getting-started-your-functions-willie-and-line" id="id2">Getting started: Your functions, <tt class="docutils literal"><span class="pre">willie</span></tt>, and <tt class="docutils literal"><span class="pre">line</span></tt></a><ul>
<li><a class="reference internal" href="#your-modules" id="id3">Your modules</a></li>
<li><a class="reference internal" href="#the-willie-class" id="id4">The <tt class="docutils literal"><span class="pre">Willie</span></tt> class</a></li>
<li><a class="reference internal" href="#the-trigger-class" id="id5">The <tt class="docutils literal"><span class="pre">Trigger</span></tt> class</a></li>
</ul>
</li>
<li><a class="reference internal" href="#more-advanced-db-and-config" id="id6">More advanced: <tt class="docutils literal"><span class="pre">db</span></tt> and <tt class="docutils literal"><span class="pre">config</span></tt></a><ul>
<li><a class="reference internal" href="#module-willie.db" id="id7">The <tt class="docutils literal"><span class="pre">WillieDB</span></tt> class</a></li>
<li><a class="reference internal" href="#module-willie.config" id="id8">The <tt class="docutils literal"><span class="pre">Config</span></tt> class</a></li>
</ul>
</li>
<li><a class="reference internal" href="#miscellaneous-web-tools" id="id9">Miscellaneous: <tt class="docutils literal"><span class="pre">web</span></tt>, <tt class="docutils literal"><span class="pre">tools</span></tt></a><ul>
<li><a class="reference internal" href="#module-willie.web" id="id10">willie.web</a></li>
<li><a class="reference internal" href="#module-willie.tools" id="id11">willie.tools</a></li>
</ul>
</li>
<li><a class="reference internal" href="#indices-and-tables" id="id12">Indices and tables</a></li>
</ul>
</div>
</div>
<div class="section" id="getting-started-your-functions-willie-and-line">
<h1><a class="toc-backref" href="#id2">Getting started: Your functions, <tt class="docutils literal"><span class="pre">willie</span></tt>, and <tt class="docutils literal"><span class="pre">line</span></tt></a><a class="headerlink" href="#getting-started-your-functions-willie-and-line" title="Permalink to this headline">¶</a></h1>
<p>At its most basic, writing a Willie module involves creating a Python file with
some number of functions in it. Each of these functions will be passed a
<tt class="docutils literal"><span class="pre">Willie</span></tt> object (<tt class="docutils literal"><span class="pre">Phenny</span></tt> in <em>1.x</em> and <tt class="docutils literal"><span class="pre">Jenni</span></tt> in <em>2.x</em>) and a <tt class="docutils literal"><span class="pre">Trigger</span></tt>
object (<tt class="docutils literal"><span class="pre">CommandInput</span></tt> in <em>1.x</em> and <em>2.x</em>). By convention, these are named
<tt class="docutils literal"><span class="pre">phenny</span></tt> and <tt class="docutils literal"><span class="pre">input</span></tt> in <em>1.x</em>, <tt class="docutils literal"><span class="pre">jenni</span></tt> and <tt class="docutils literal"><span class="pre">input</span></tt> in <em>2.x</em>, and
<tt class="docutils literal"><span class="pre">willie</span></tt> and <tt class="docutils literal"><span class="pre">trigger</span></tt> in <em>3.x</em>. For the purposes of this guide, the <em>3.x</em>
names will be used.</p>
<div class="section" id="your-modules">
<h2><a class="toc-backref" href="#id3">Your modules</a><a class="headerlink" href="#your-modules" title="Permalink to this headline">¶</a></h2>
<p>A Willie module contains one or more <tt class="docutils literal"><span class="pre">callable</span></tt>s. It may optionally contain a
<tt class="docutils literal"><span class="pre">configure</span></tt> or <tt class="docutils literal"><span class="pre">setup</span></tt> function. <tt class="docutils literal"><span class="pre">callable</span></tt>s are given a number of
attributes, which determine when they will be executed. Syntactically, this is
done at the same indentation level as the function’s <tt class="docutils literal"><span class="pre">def</span></tt> line, following the
last line of the function.</p>
<dl class="method">
<dt id="callable">
<tt class="descname">callable</tt><big>(</big><em>willie</em>, <em>trigger</em><big>)</big><a class="headerlink" href="#callable" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the general function format, called by Willie when a command is used,
a rule is matched, or an event is seen, as determined by the attributes of
the function. The details of what this function does are entirely up to the
module writer - the only hard requirement from the bot is that it be callable
with a <tt class="docutils literal"><span class="pre">Willie</span></tt> object and a <tt class="docutils literal"><span class="pre">Trigger</span></tt> object , as noted above. Usually,
methods of the Willie object will be used in reply to the trigger, but this
isn’t a requirement.</p>
<p>The return value of a callable will usually be <tt class="docutils literal"><span class="pre">None</span></tt>. This doesn’t need
to be explicit; if the function has no <tt class="docutils literal"><span class="pre">return</span></tt> statement (or simply
uses <tt class="docutils literal"><span class="pre">return</span></tt> with no arguments), <tt class="docutils literal"><span class="pre">None</span></tt> will be returned. In <em>3.2+</em>,
the return value can be a constant defined by the <tt class="docutils literal"><span class="pre">Willie</span></tt> class; in prior
versions return values were ignored. Returning a constant instructs the bot
to perform some action after the <tt class="docutils literal"><span class="pre">callable</span></tt>‘s execution. For example,
returning <tt class="docutils literal"><span class="pre">NOLIMIT</span></tt> will suspend rate limiting on that call.</p>
<p>Note that the name can, and should, be anything - it doesn’t need to be called
callable.</p>
<dl class="attribute">
<dt id="commands">
<tt class="descname">commands</tt><a class="headerlink" href="#commands" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of commands which will trigger the function. If the Willie instance
is in a channel, or sent a PRIVMSG, where one of these strings is said,
preceeded only by the configured prefix (a period, by default), the
function will execute.</p>
</dd></dl>
<dl class="attribute">
<dt id="rule">
<tt class="descname">rule</tt><a class="headerlink" href="#rule" title="Permalink to this definition">¶</a></dt>
<dd><p>A regular expression which will trigger the function. If the Willie
instance is in a channel, or sent a PRIVMSG, where a string matching this
expression is said, the function will execute. Note that captured groups
here will be retrievable through the <tt class="docutils literal"><span class="pre">Trigger</span></tt> object later.</p>
<p>Inside the regular expression, some special directives can be used. <tt class="docutils literal"><span class="pre">$nick</span></tt> will be replaced with the nick of the bot and <tt class="docutils literal"><span class="pre">,</span></tt> or <tt class="docutils literal"><span class="pre">:</span></tt>, and <tt class="docutils literal"><span class="pre">$nickname</span></tt> will be replaced with the nick of the bot.</p>
<p>Prior to <em>3.1</em>, rules could also be made one of three formats of tuple.
The values would be joined together to form a singular regular expression.
However, these kinds of rules add no functionality over simple regular
expressions, and are considered deprecated in <em>3.1</em>.</p>
</dd></dl>
<dl class="attribute">
<dt id="event">
<tt class="descname">event</tt><a class="headerlink" href="#event" title="Permalink to this definition">¶</a></dt>
<dd><p>This is one of a number of events, such as <tt class="docutils literal"><span class="pre">'JOIN'</span></tt>, <tt class="docutils literal"><span class="pre">'PART'</span></tt>,
<tt class="docutils literal"><span class="pre">'QUIT'</span></tt>, etc. (More details can be found in <a class="reference external" href="http://www.irchelp.org/irchelp/rfc/rfc.html">RFC 1459</a>.) When the Willie
bot is sent one of these events, the function will execute. Note that
functions with an event must also be given a <tt class="docutils literal"><span class="pre">rule</span></tt> to match (though
it may be <tt class="docutils literal"><span class="pre">'.*'</span></tt>, which will always match) or they will not be triggered.</p>
</dd></dl>
<dl class="attribute">
<dt id="rate">
<tt class="descname">rate</tt><a class="headerlink" href="#rate" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: 2+</em></p>
<p>This limits the frequency with which a single user may use the function.
If a function is given a <tt class="docutils literal"><span class="pre">rate</span></tt> of <tt class="docutils literal"><span class="pre">20</span></tt>, a single user may only use
that function once every 20 seconds. This limit applies to each user
individually. Users on the <tt class="docutils literal"><span class="pre">admin</span></tt> list in Willie’s configuration are
exempted from rate limits.</p>
</dd></dl>
<dl class="attribute">
<dt id="priority">
<tt class="descname">priority</tt><a class="headerlink" href="#priority" title="Permalink to this definition">¶</a></dt>
<dd><p>Priority can be one of <tt class="docutils literal"><span class="pre">high</span></tt>, <tt class="docutils literal"><span class="pre">medium</span></tt>, <tt class="docutils literal"><span class="pre">low</span></tt>. It allows you to
control the order of callable execution, if your module needs it. Defaults to <tt class="docutils literal"><span class="pre">medium</span></tt></p>
</dd></dl>
</dd></dl>
<dl class="method">
<dt id="setup">
<tt class="descname">setup</tt><big>(</big><em>willie</em><big>)</big><a class="headerlink" href="#setup" title="Permalink to this definition">¶</a></dt>
<dd><p>This is an optional function of a module, which will be called while the
module is being loaded. Note that this normally occurs prior to connection
to the server, so the behavior of the Willie object’s messaging functions is
undefined. The purpose of this function is to perform whatever actions are
needed to allow a module to function properly (e.g, ensuring that the
appropriate configuration variables are set and exist).</p>
<p>The bot will not continue loading modules or connecting during the execution
of this function. As such, an infinite loop (such as an unthreaded polling
loop) will cause the bot to hang.</p>
</dd></dl>
<dl class="method">
<dt id="configure">
<tt class="descname">configure</tt><big>(</big><em>config</em><big>)</big><a class="headerlink" href="#configure" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: 3+</em></p>
<p>This is an optional function of a module, which will be called during the
user’s setup of the bot. It’s intended purpose is to use the methods of the
passed <tt class="docutils literal"><span class="pre">Config</span></tt> object in order to create the configuration variables it
needs to function properly.</p>
<p>In <em>3.1+</em>, the docstring of this function can be used to document the
configuration variables that the module uses. This is not currently used
by the bot itself; it is merely convention.</p>
</dd></dl>
</div>
<div class="section" id="the-willie-class">
<h2><a class="toc-backref" href="#id4">The <tt class="docutils literal"><span class="pre">Willie</span></tt> class</a><a class="headerlink" href="#the-willie-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="willie.bot.Willie">
<em class="property">class </em><tt class="descclassname">willie.bot.</tt><tt class="descname">Willie</tt><big>(</big><em>config</em><big>)</big><a class="headerlink" href="#willie.bot.Willie" title="Permalink to this definition">¶</a></dt>
<dd><dl class="function">
<dt id="Willie.reply">
<tt class="descname">reply</tt><big>(</big><em>text</em><big>)</big><a class="headerlink" href="#Willie.reply" title="Permalink to this definition">¶</a></dt>
<dd><p>In a module function, send <tt class="docutils literal"><span class="pre">text</span></tt> to the channel in which the function
was triggered, preceeded by the nick of the user who triggered it.</p>
<p>This function is not available outside of module functions. It can not
be used, for example, in a module’s <tt class="docutils literal"><span class="pre">setup</span></tt> function.</p>
<p>The same behavior regarding loop detection and length restrictions apply
to <tt class="docutils literal"><span class="pre">reply</span></tt> as to <tt class="docutils literal"><span class="pre">msg</span></tt>.</p>
</dd></dl>
<dl class="function">
<dt id="Willie.say">
<tt class="descname">say</tt><big>(</big><em>text</em><big>)</big><a class="headerlink" href="#Willie.say" title="Permalink to this definition">¶</a></dt>
<dd><p>In a module function, send <tt class="docutils literal"><span class="pre">text</span></tt> to the channel in which the function
was triggered.</p>
<p>This function is not available outside of module functions. It can not
be used, for example, in a module’s <tt class="docutils literal"><span class="pre">configure</span></tt> function.</p>
<p>The same behavior regarding loop detection and length restrictions apply
to <tt class="docutils literal"><span class="pre">say</span></tt> as to <tt class="docutils literal"><span class="pre">msg</span></tt> and <tt class="docutils literal"><span class="pre">action</span></tt>.</p>
</dd></dl>
<dl class="function">
<dt id="Willie.action">
<tt class="descname">action</tt><big>(</big><em>text</em><big>)</big><a class="headerlink" href="#Willie.action" title="Permalink to this definition">¶</a></dt>
<dd><p>In a module function, send <tt class="docutils literal"><span class="pre">text</span></tt> to the channel in which the function
was triggered preceeded by CTCP ACTION directive (result identical to using /me in most clients).</p>
<p>This function is not available outside of module functions. It can not
be used, for example, in a module’s <tt class="docutils literal"><span class="pre">configure</span></tt> function.</p>
<p>The same behavior regarding loop detection and length restrictions apply
to <tt class="docutils literal"><span class="pre">action</span></tt> as to <tt class="docutils literal"><span class="pre">msg</span></tt> and <tt class="docutils literal"><span class="pre">say</span></tt>.</p>
</dd></dl>
<dl class="function">
<dt id="Willie.quit">
<tt class="descname">quit</tt><big>(</big><em>message</em><big>)</big><a class="headerlink" href="#Willie.quit" title="Permalink to this definition">¶</a></dt>
<dd><p>Gracefully quit and shutdown, using <tt class="docutils literal"><span class="pre">message</span></tt> as the quit message</p>
</dd></dl>
<dl class="function">
<dt id="Willie.part">
<tt class="descname">part</tt><big>(</big><em>channel</em><big>)</big><a class="headerlink" href="#Willie.part" title="Permalink to this definition">¶</a></dt>
<dd><p>Part <tt class="docutils literal"><span class="pre">channel</span></tt></p>
</dd></dl>
<dl class="function">
<dt id="Willie.join">
<tt class="descname">join</tt><big>(</big><em>channel</em>, <em>password = None</em><big>)</big><a class="headerlink" href="#Willie.join" title="Permalink to this definition">¶</a></dt>
<dd><p>Join a channel named <tt class="docutils literal"><span class="pre">channel</span></tt>.</p>
</dd></dl>
<dl class="attribute">
<dt id="Willie.nick">
<tt class="descname">nick</tt><a class="headerlink" href="#Willie.nick" title="Permalink to this definition">¶</a></dt>
<dd><p>Willie’s current nick. Changing this while Willie is running is unsupported.</p>
</dd></dl>
<dl class="attribute">
<dt id="Willie.name">
<tt class="descname">name</tt><a class="headerlink" href="#Willie.name" title="Permalink to this definition">¶</a></dt>
<dd><p>Willie’s “real name”, as used for whois.</p>
</dd></dl>
<dl class="attribute">
<dt id="Willie.password">
<tt class="descname">password</tt><a class="headerlink" href="#Willie.password" title="Permalink to this definition">¶</a></dt>
<dd><p>Willie’s NickServ password</p>
</dd></dl>
<dl class="attribute">
<dt id="Willie.channels">
<tt class="descname">channels</tt><a class="headerlink" href="#Willie.channels" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of Willie’s initial channels. This list will initially be the same
as the one given in the config file, but is not guaranteed to be kept
up-to-date.</p>
</dd></dl>
<dl class="attribute">
<dt id="Willie.ops">
<tt class="descname">ops</tt><a class="headerlink" href="#Willie.ops" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="attribute">
<dt id="Willie.halfplus">
<tt class="descname">halfplus</tt><a class="headerlink" href="#Willie.halfplus" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: 3+</em></p>
<p>Dictionary mapping channels to a list of their ops, and half-ops and ops
respectively.</p>
</dd></dl>
<dl class="function">
<dt id="Willie.write">
<tt class="descname">write</tt><big>(</big><em>args</em>, <em>text=None</em><big>)</big><a class="headerlink" href="#Willie.write" title="Permalink to this definition">¶</a></dt>
<dd><p>Send a command to the server. In the simplest case, <tt class="docutils literal"><span class="pre">args</span></tt> is a list
containing just the command you wish to send, and <tt class="docutils literal"><span class="pre">text</span></tt> the argument
to that command {e.g. write([‘JOIN’], ‘#channel’)}</p>
<p>More specifically, <tt class="docutils literal"><span class="pre">args</span></tt> will be joined together, separated by a
space. If text is given, it will be added preceeded by a space and a
colon (‘ :’).</p>
<p>Newlines and carriage returns (‘\n’ and ‘\r’) are removed before
sending. Additionally, if the joined <tt class="docutils literal"><span class="pre">args</span></tt> and <tt class="docutils literal"><span class="pre">text</span></tt> are more than
510 characters, any remaining characters will not be sent.</p>
</dd></dl>
<dl class="function">
<dt id="Willie.msg">
<tt class="descname">msg</tt><big>(</big><em>recipient</em>, <em>text</em><big>)</big><a class="headerlink" href="#Willie.msg" title="Permalink to this definition">¶</a></dt>
<dd><p>Send a PRIVMSG of <tt class="docutils literal"><span class="pre">text</span></tt> to <tt class="docutils literal"><span class="pre">recipient</span></tt>. If the same <tt class="docutils literal"><span class="pre">text</span></tt> was
the message in 5 or more of the last 8 calls to <tt class="docutils literal"><span class="pre">msg</span></tt>, <tt class="docutils literal"><span class="pre">'...'</span></tt> will
be sent instead. If this condition is met, and <tt class="docutils literal"><span class="pre">'...'</span></tt> is more than 3
of the last 8 calls, no message will be sent. This is intended to prevent
Willie from being caught in an infinite loop with another bot, or being
used to spam.</p>
<p>After loop detection, the message is checked for length. If the sum of
the lengths of <tt class="docutils literal"><span class="pre">text</span></tt> and <tt class="docutils literal"><span class="pre">recipient</span></tt> are greater than 500, <tt class="docutils literal"><span class="pre">text</span></tt>
will be truncated to fit this limit.</p>
</dd></dl>
<dl class="function">
<dt id="Willie.debug">
<tt class="descname">debug</tt><big>(</big><em>tag</em>, <em>text</em>, <em>level</em><big>)</big><a class="headerlink" href="#Willie.debug" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: 3+</em></p>
<p>Send <tt class="docutils literal"><span class="pre">text</span></tt> to Willie’s configured <tt class="docutils literal"><span class="pre">debug_target</span></tt>. This can be either
an IRC channel (starting with <tt class="docutils literal"><span class="pre">#</span></tt>) or <tt class="docutils literal"><span class="pre">stdio</span></tt>. Suppress the message
if the given <tt class="docutils literal"><span class="pre">level</span></tt> is lower than Willie’s configured <tt class="docutils literal"><span class="pre">verbose</span></tt>
setting. Acceptable values for <tt class="docutils literal"><span class="pre">level</span></tt> are <tt class="docutils literal"><span class="pre">'verbose'</span></tt> (only send if
Willie is in verbose mode), <tt class="docutils literal"><span class="pre">'warning'</span></tt> (send if Willie is in verbose
or warning mode), <tt class="docutils literal"><span class="pre">always</span></tt> (send debug message regardless of the configured debug level).
Returns True if the message is sent or printed, and False if it
is not.</p>
<p>If <tt class="docutils literal"><span class="pre">debug_target</span></tt> is a channel, the same behavior regarding loop
detection and length restrictions apply to <tt class="docutils literal"><span class="pre">debug</span></tt> as to <tt class="docutils literal"><span class="pre">msg</span></tt>.</p>
</dd></dl>
<dl class="function">
<dt id="Willie.add_op">
<tt class="descname">add_op</tt><big>(</big><em>channel</em>, <em>name</em><big>)</big><a class="headerlink" href="#Willie.add_op" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="Willie.add_halfop">
<tt class="descname">add_halfop</tt><big>(</big><em>channel</em>, <em>name</em><big>)</big><a class="headerlink" href="#Willie.add_halfop" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: 3+</em></p>
<p>Add <tt class="docutils literal"><span class="pre">name</span></tt> to <tt class="docutils literal"><span class="pre">channel</span></tt>‘s entry in the <tt class="docutils literal"><span class="pre">ops</span></tt> or <tt class="docutils literal"><span class="pre">halfplus</span></tt>
dictionaries, respectively.</p>
</dd></dl>
<dl class="function">
<dt id="Willie.del_op">
<tt class="descname">del_op</tt><big>(</big><em>channel</em>, <em>name</em><big>)</big><a class="headerlink" href="#Willie.del_op" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="Willie.del_halfop">
<tt class="descname">del_halfop</tt><big>(</big><em>channel</em>, <em>name</em><big>)</big><a class="headerlink" href="#Willie.del_halfop" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: 3+</em></p>
<p>Remove <tt class="docutils literal"><span class="pre">name</span></tt> from <tt class="docutils literal"><span class="pre">channel</span></tt>‘s entry in the <tt class="docutils literal"><span class="pre">ops</span></tt> or <tt class="docutils literal"><span class="pre">halfplus</span></tt>
dictionaries, respectively.</p>
</dd></dl>
<dl class="function">
<dt id="Willie.flush_ops">
<tt class="descname">flush_ops</tt><big>(</big><em>channel</em><big>)</big><a class="headerlink" href="#Willie.flush_ops" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: 3+</em></p>
<p>Re-initialize and empty the <tt class="docutils literal"><span class="pre">ops</span></tt> and <tt class="docutils literal"><span class="pre">halfops</span></tt> entry for
<tt class="docutils literal"><span class="pre">channel</span></tt>.</p>
</dd></dl>
<dl class="function">
<dt id="Willie.init_ops_list">
<tt class="descname">init_ops_list</tt><big>(</big><em>self</em>, <em>channel</em><big>)</big><a class="headerlink" href="#Willie.init_ops_list" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: 3+</em></p>
<p>Create an empty entry in <tt class="docutils literal"><span class="pre">ops</span></tt> and <tt class="docutils literal"><span class="pre">halfops</span></tt> for <tt class="docutils literal"><span class="pre">channel</span></tt>. This
will not damage existing entries, but must be done before users can be
added to either dictionary.</p>
</dd></dl>
<dl class="attribute">
<dt id="willie.bot.Willie.NOLIMIT">
<tt class="descname">NOLIMIT</tt><em class="property"> = 1</em><a class="headerlink" href="#willie.bot.Willie.NOLIMIT" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Avalability: 3.2+</em></p>
<p>Return value for <tt class="docutils literal"><span class="pre">callable</span></tt>s, which supresses rate limiting for that
call. That is, returning this value means the triggering user will not be
prevented from triggering the command again within the rate limit. This can
be used, for example, to allow a user to rety a failed command immediately.</p>
</dd></dl>
<dl class="class">
<dt id="willie.bot.Willie.WillieMemory">
<em class="property">class </em><tt class="descname">WillieMemory</tt><big>(</big><em>*args</em><big>)</big><a class="headerlink" href="#willie.bot.Willie.WillieMemory" title="Permalink to this definition">¶</a></dt>
<dd><p>Availability: 3.1+</p>
<p>A simple thread-safe dict implementation. In order to prevent
exceptions when iterating over the values and changing them at the same
time from different threads, we use a blocking lock on <tt class="docutils literal"><span class="pre">__setitem__</span></tt>
and <tt class="docutils literal"><span class="pre">contains</span></tt>.</p>
<dl class="method">
<dt id="willie.bot.Willie.WillieMemory.contains">
<tt class="descname">contains</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#willie.bot.Willie.WillieMemory.contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Check if a key is in the dict. Use this instead of the <tt class="docutils literal"><span class="pre">in</span></tt>
keyword if you want to be thread-safe.</p>
</dd></dl>
</dd></dl>
<dl class="attribute">
<dt id="willie.bot.Willie.config">
<tt class="descclassname">Willie.</tt><tt class="descname">config</tt><em class="property"> = None</em><a class="headerlink" href="#willie.bot.Willie.config" title="Permalink to this definition">¶</a></dt>
<dd><p>The <tt class="docutils literal"><span class="pre">Config</span></tt> for the current Willie instance.</p>
</dd></dl>
<dl class="method">
<dt id="willie.bot.Willie.debug">
<tt class="descclassname">Willie.</tt><tt class="descname">debug</tt><big>(</big><em>tag</em>, <em>text</em>, <em>level</em><big>)</big><a class="headerlink" href="#willie.bot.Willie.debug" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends an error to Willie’s configured <tt class="docutils literal"><span class="pre">debug_target</span></tt>.</p>
</dd></dl>
<dl class="attribute">
<dt id="willie.bot.Willie.doc">
<tt class="descclassname">Willie.</tt><tt class="descname">doc</tt><em class="property"> = None</em><a class="headerlink" href="#willie.bot.Willie.doc" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Removed in 3.1.2</em></p>
<p>A dictionary of module functions to their docstring and example, if
declared. As of 3.1.2, this dict will be empty, and not updated.</p>
</dd></dl>
<dl class="attribute">
<dt id="willie.bot.Willie.memory">
<tt class="descclassname">Willie.</tt><tt class="descname">memory</tt><em class="property"> = None</em><a class="headerlink" href="#willie.bot.Willie.memory" title="Permalink to this definition">¶</a></dt>
<dd><p>A thread-safe dict for storage of runtime data to be shared between
modules. See <a class="reference external" href="#bot.Willie.WillieMemory">WillieMemory</a></p>
</dd></dl>
<dl class="method">
<dt id="willie.bot.Willie.register">
<tt class="descclassname">Willie.</tt><tt class="descname">register</tt><big>(</big><em>variables</em><big>)</big><a class="headerlink" href="#willie.bot.Willie.register" title="Permalink to this definition">¶</a></dt>
<dd><p>With the <tt class="docutils literal"><span class="pre">__dict__</span></tt> attribute from a Willie module, update or add the
trigger commands and rules to allow the function to be triggered.</p>
</dd></dl>
<dl class="attribute">
<dt id="willie.bot.Willie.stats">
<tt class="descclassname">Willie.</tt><tt class="descname">stats</tt><em class="property"> = None</em><a class="headerlink" href="#willie.bot.Willie.stats" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary which maps a tuple of a function name and where it was
used to the nuber of times it was used there.</p>
</dd></dl>
<dl class="attribute">
<dt id="willie.bot.Willie.times">
<tt class="descclassname">Willie.</tt><tt class="descname">times</tt><em class="property"> = None</em><a class="headerlink" href="#willie.bot.Willie.times" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary mapping lower-case’d nicks to dictionaries which map
funtion names to the time which they were last used by that nick.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="the-trigger-class">
<h2><a class="toc-backref" href="#id5">The <tt class="docutils literal"><span class="pre">Trigger</span></tt> class</a><a class="headerlink" href="#the-trigger-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="Trigger">
<em class="property">class </em><tt class="descname">Trigger</tt><a class="headerlink" href="#Trigger" title="Permalink to this definition">¶</a></dt>
<dd><dl class="attribute">
<dt id="Trigger.sender">
<tt class="descname">sender</tt><a class="headerlink" href="#Trigger.sender" title="Permalink to this definition">¶</a></dt>
<dd><p>The channel (or nick, in a private message) from which the message was
sent.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.nick">
<tt class="descname">nick</tt><a class="headerlink" href="#Trigger.nick" title="Permalink to this definition">¶</a></dt>
<dd><p>The nick of the person who sent the message.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.event">
<tt class="descname">event</tt><a class="headerlink" href="#Trigger.event" title="Permalink to this definition">¶</a></dt>
<dd><p>The event which triggered the message.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.bytes">
<tt class="descname">bytes</tt><a class="headerlink" href="#Trigger.bytes" title="Permalink to this definition">¶</a></dt>
<dd><p>The line which triggered the message.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.match">
<tt class="descname">match</tt><a class="headerlink" href="#Trigger.match" title="Permalink to this definition">¶</a></dt>
<dd><p>The regular expression <a class="reference external" href="http://docs.python.org/library/re.html#match-objects">MatchObject</a> for the triggering line.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.group">
<tt class="descname">group</tt><a class="headerlink" href="#Trigger.group" title="Permalink to this definition">¶</a></dt>
<dd><p>The <tt class="docutils literal"><span class="pre">group</span></tt> function of the <tt class="docutils literal"><span class="pre">match</span></tt> attribute.</p>
<p>See Python <a class="reference external" href="http://docs.python.org/library/re.html">re</a> documentation for details.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.groups">
<tt class="descname">groups</tt><a class="headerlink" href="#Trigger.groups" title="Permalink to this definition">¶</a></dt>
<dd><p>The <tt class="docutils literal"><span class="pre">groups</span></tt> function of the <tt class="docutils literal"><span class="pre">match</span></tt> attribute.</p>
<p>See Python <a class="reference external" href="http://docs.python.org/library/re.html">re</a> documentation for details.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.args">
<tt class="descname">args</tt><a class="headerlink" href="#Trigger.args" title="Permalink to this definition">¶</a></dt>
<dd><p>The arguments given to a command.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.admin">
<tt class="descname">admin</tt><a class="headerlink" href="#Trigger.admin" title="Permalink to this definition">¶</a></dt>
<dd><p>True if the nick which triggered the command is in Willie’s admin list as
defined in the config file.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.owner">
<tt class="descname">owner</tt><a class="headerlink" href="#Trigger.owner" title="Permalink to this definition">¶</a></dt>
<dd><p>True if the nick which triggered the command is the owner stated in the
config file.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.host">
<tt class="descname">host</tt><a class="headerlink" href="#Trigger.host" title="Permalink to this definition">¶</a></dt>
<dd><p>The host which sent the triggering message.</p>
</dd></dl>
<dl class="attribute">
<dt id="Trigger.isop">
<tt class="descname">isop</tt><a class="headerlink" href="#Trigger.isop" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: 3+</em></p>
<p>True if the nick which triggered the command is an op on the channel it was triggered in.
Will always be False if the command was triggered by a private message</p>
</dd></dl>
</dd></dl>
</div>
</div>
<div class="section" id="more-advanced-db-and-config">
<h1><a class="toc-backref" href="#id6">More advanced: <tt class="docutils literal"><span class="pre">db</span></tt> and <tt class="docutils literal"><span class="pre">config</span></tt></a><a class="headerlink" href="#more-advanced-db-and-config" title="Permalink to this headline">¶</a></h1>
<p>The <tt class="docutils literal"><span class="pre">willie</span></tt> object has, among others, the attributes <tt class="docutils literal"><span class="pre">db</span></tt> and
<tt class="docutils literal"><span class="pre">config</span></tt>. These can be used for a number of functions and features.</p>
<div class="section" id="module-willie.db">
<span id="the-williedb-class"></span><h2><a class="toc-backref" href="#id7">The <tt class="docutils literal"><span class="pre">WillieDB</span></tt> class</a><a class="headerlink" href="#module-willie.db" title="Permalink to this headline">¶</a></h2>
<p><em>Availability: 3.1+</em></p>
<p><em>Note:</em> This supersedes the <tt class="docutils literal"><span class="pre">SettingsDB</span></tt> object of v3. Within Willie modules,
simmilar functionallity can be found using <tt class="docutils literal"><span class="pre">willie.db.preferences</span></tt>.</p>
<p>This class defines an interface for a semi-arbitrary database type. It is meant
to allow module writers to operate without regard to how the end user has
decided to set up the database.</p>
<dl class="class">
<dt id="willie.db.Table">
<em class="property">class </em><tt class="descclassname">willie.db.</tt><tt class="descname">Table</tt><big>(</big><em>db</em>, <em>name</em>, <em>columns</em>, <em>key</em><big>)</big><a class="headerlink" href="#willie.db.Table" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an object which represents a table in the given WillieDB, with the
given attributes. This will not check if <tt class="docutils literal"><span class="pre">db</span></tt> already has a table with the
given <tt class="docutils literal"><span class="pre">name</span></tt>; the <tt class="docutils literal"><span class="pre">db</span></tt>‘s <tt class="docutils literal"><span class="pre">add_table</span></tt> provides that functionality.</p>
<p><tt class="docutils literal"><span class="pre">key</span></tt> must be a string, which is in the list of strings <tt class="docutils literal"><span class="pre">columns</span></tt>, or an
Exception will be thrown.</p>
<dl class="method">
<dt id="willie.db.Table.add_columns">
<tt class="descname">add_columns</tt><big>(</big><em>columns</em><big>)</big><a class="headerlink" href="#willie.db.Table.add_columns" title="Permalink to this definition">¶</a></dt>
<dd><p>Insert a new column into the table, and add it to the column cache.
This is the preferred way to add new columns to the database.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.Table.channels">
<tt class="descname">channels</tt><big>(</big><big>)</big><a class="headerlink" href="#willie.db.Table.channels" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the number of users (entries starting with # or &) in the
table’s <tt class="docutils literal"><span class="pre">key</span></tt> column.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.Table.contains">
<tt class="descname">contains</tt><big>(</big><em>row</em>, <em>key=None</em><big>)</big><a class="headerlink" href="#willie.db.Table.contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <tt class="docutils literal"><span class="pre">True</span></tt> if this table has a row where the key value is equal to
<tt class="docutils literal"><span class="pre">key</span></tt>, else <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">key</span> <span class="pre">in</span> <span class="pre">db</span></tt> will also work, where db is your SettingsDB object.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.Table.delete">
<tt class="descname">delete</tt><big>(</big><em>row</em>, <em>key=None</em><big>)</big><a class="headerlink" href="#willie.db.Table.delete" title="Permalink to this definition">¶</a></dt>
<dd><p>Deletes the row for <tt class="docutils literal"><span class="pre">row</span></tt> in the database, removing its values in
all columns.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.Table.get">
<tt class="descname">get</tt><big>(</big><em>row</em>, <em>columns</em>, <em>key=None</em><big>)</big><a class="headerlink" href="#willie.db.Table.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve the value(s) in one or more <tt class="docutils literal"><span class="pre">columns</span></tt> in the row where the
<tt class="docutils literal"><span class="pre">key</span></tt> column(s) match the value(s) given in <tt class="docutils literal"><span class="pre">row</span></tt>. This is basically
equivalent to executing <tt class="docutils literal"><span class="pre">SELECT</span> <span class="pre"><columns></span> <span class="pre">FROM</span> <span class="pre"><self></span> <span class="pre">WHERE</span> <span class="pre"><key></span> <span class="pre">=</span>
<span class="pre"><row></span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">key</span></tt> can be either the name of one column as a string, or a tuple
of the names of multiple columns. <tt class="docutils literal"><span class="pre">row</span></tt> is the value or values of this
column or columns for which data will be retrieved. If multiple columns
are being used, the order in which the columns are presented should match
between <tt class="docutils literal"><span class="pre">row</span></tt> and <tt class="docutils literal"><span class="pre">key</span></tt>. A <tt class="docutils literal"><span class="pre">KeyError</span></tt> will be raised if no have
values matching <tt class="docutils literal"><span class="pre">row</span></tt> in <tt class="docutils literal"><span class="pre">key</span></tt>. If <tt class="docutils literal"><span class="pre">key</span></tt> is not passed, it will
default to the table’s primary key.</p>
<p><tt class="docutils literal"><span class="pre">columns</span></tt> can either be a single column name, or a tuple of column
names. If one name is passed, a single string will be returned. If a
tuple of names is passed, the return value will be a tuple in the same
order.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.Table.has_columns">
<tt class="descname">has_columns</tt><big>(</big><em>column</em><big>)</big><a class="headerlink" href="#willie.db.Table.has_columns" title="Permalink to this definition">¶</a></dt>
<dd><p>Each Table contains a cached list of its columns. <tt class="docutils literal"><span class="pre">hascolumn(column)</span></tt>
checks this list, and returns True if it contains <tt class="docutils literal"><span class="pre">column</span></tt>. If
<tt class="docutils literal"><span class="pre">column</span></tt> is an iterable, this returns true if all of the values in
<tt class="docutils literal"><span class="pre">column</span></tt> are in the column cache. Note that this will not check the
database itself; it’s meant for speed, not accuracy. However, unless
you have multiple bots using the same database, or are adding columns
while the bot is running, you are unlikely to encounter errors.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.Table.keys">
<tt class="descname">keys</tt><big>(</big><em>key=None</em><big>)</big><a class="headerlink" href="#willie.db.Table.keys" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an iterator over the keys and values in the table.</p>
<p>In a for each loop, you can use <tt class="docutils literal"><span class="pre">for</span> <span class="pre">key</span> <span class="pre">in</span> <span class="pre">table:</span></tt>, where key will be
the value of the <tt class="docutils literal"><span class="pre">key</span></tt> column(s), which defaults to the primary key,
and table is the Table. This may be deprecated in future versions.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.Table.size">
<tt class="descname">size</tt><big>(</big><big>)</big><a class="headerlink" href="#willie.db.Table.size" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the total number of rows in the table.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.Table.update">
<tt class="descname">update</tt><big>(</big><em>row</em>, <em>values</em>, <em>key=None</em><big>)</big><a class="headerlink" href="#willie.db.Table.update" title="Permalink to this definition">¶</a></dt>
<dd><p>Update the row where the values in <tt class="docutils literal"><span class="pre">row</span></tt> match the <tt class="docutils literal"><span class="pre">key</span></tt> columns.
If the row does not exist, it will be created. The same rules regarding
the type and length of <tt class="docutils literal"><span class="pre">key</span></tt> and <tt class="docutils literal"><span class="pre">row</span></tt> apply for <tt class="docutils literal"><span class="pre">update</span></tt> as for
<tt class="docutils literal"><span class="pre">get</span></tt>.</p>
<p>The given <tt class="docutils literal"><span class="pre">values</span></tt> must be a dict of column name to new value.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.Table.users">
<tt class="descname">users</tt><big>(</big><big>)</big><a class="headerlink" href="#willie.db.Table.users" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the number of users (entries not starting with # or &) in the
table’s <tt class="docutils literal"><span class="pre">key</span></tt> column.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="willie.db.WillieDB">
<em class="property">class </em><tt class="descclassname">willie.db.</tt><tt class="descname">WillieDB</tt><big>(</big><em>config</em><big>)</big><a class="headerlink" href="#willie.db.WillieDB" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a WillieDB object configured with the options in the given Config
object. The exact settgins used vary depending on the type of database
chosen to back the SettingsDB, as determined by the <tt class="docutils literal"><span class="pre">userdb_type</span></tt>
attribute of <em>config</em>.</p>
<p>Currently, two values for <tt class="docutils literal"><span class="pre">userdb_type</span></tt> are supported: <tt class="docutils literal"><span class="pre">sqlite</span></tt> and
<tt class="docutils literal"><span class="pre">mysql</span></tt>. The <tt class="docutils literal"><span class="pre">sqlite</span></tt> type requires that <tt class="docutils literal"><span class="pre">userdb_file</span></tt> be set in the
<tt class="docutils literal"><span class="pre">db</span></tt> section of <tt class="docutils literal"><span class="pre">config</span></tt> (that is, under the <tt class="docutils literal"><span class="pre">[db]</span></tt> heading in the
config file), and refer to a writeable sqlite database. The <tt class="docutils literal"><span class="pre">mysql</span></tt> type
requires <tt class="docutils literal"><span class="pre">userdb_host</span></tt>, <tt class="docutils literal"><span class="pre">userdb_user</span></tt>, <tt class="docutils literal"><span class="pre">userdb_pass</span></tt>, and
<tt class="docutils literal"><span class="pre">userdb_name</span></tt> to be set, and provide the host and name of a MySQL database,
as well as a username and password for a user able to write to said database.</p>
<p>Upon creation of the object, the tables currently existing in the given
database will be registered, as though added through <tt class="docutils literal"><span class="pre">add_table</span></tt>.</p>
<dl class="method">
<dt id="willie.db.WillieDB.add_table">
<tt class="descname">add_table</tt><big>(</big><em>name</em>, <em>columns</em>, <em>key</em><big>)</big><a class="headerlink" href="#willie.db.WillieDB.add_table" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a column with the given <tt class="docutils literal"><span class="pre">name</span></tt> and <tt class="docutils literal"><span class="pre">key</span></tt>, which has the given
<tt class="docutils literal"><span class="pre">columns</span></tt>. Each element in <tt class="docutils literal"><span class="pre">columns</span></tt> may be either a string giving
the name of the column, or a tuple containing the name of the column and
its type (using SQL type names). If the former, the type will be assumed
as string.</p>
<p>This will attempt to create the table within the database. If an error
is encountered while adding the table, it will not be added to the
WillieDB object. If a table with the same name and key already exists,
the given columns will be added (if they don’t already exist).</p>
<p>The given <tt class="docutils literal"><span class="pre">name</span></tt> can not be the same as any function or attribute
(with the exception of other tables) of the <tt class="docutils literal"><span class="pre">WillieDB</span></tt> object, nor may
it start with <tt class="docutils literal"><span class="pre">'_'</span></tt>. If it does not meet this requirement, or if the
<tt class="docutils literal"><span class="pre">name</span></tt> matches that of an existing table with a different <tt class="docutils literal"><span class="pre">key</span></tt>, a
<tt class="docutils literal"><span class="pre">ValueError</span></tt> will be thrown.</p>
<p>When a table is created, the column <tt class="docutils literal"><span class="pre">key</span></tt> will be declared as the
primary key of the table. If it is desired that there be no primary key,
this can be achieved by creating the table manually, or with a custom
query, and then creating the WillieDB object.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.WillieDB.check_table">
<tt class="descname">check_table</tt><big>(</big><em>name</em>, <em>columns</em>, <em>key</em><big>)</big><a class="headerlink" href="#willie.db.WillieDB.check_table" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <tt class="docutils literal"><span class="pre">True</span></tt> if the WillieDB contains a table with the same <tt class="docutils literal"><span class="pre">name</span></tt>
and <tt class="docutils literal"><span class="pre">key</span></tt>, and which contains a column with the same name as each element
in the given list <tt class="docutils literal"><span class="pre">columns</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="willie.db.WillieDB.connect">
<tt class="descname">connect</tt><big>(</big><big>)</big><a class="headerlink" href="#willie.db.WillieDB.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a database connection object. This functions essentially the same
as the <tt class="docutils literal"><span class="pre">connect</span></tt> function of the appropriate database type, allowing
for custom queries to be executed.</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="willie.db.configure">
<tt class="descclassname">willie.db.</tt><tt class="descname">configure</tt><big>(</big><em>config</em><big>)</big><a class="headerlink" href="#willie.db.configure" title="Permalink to this definition">¶</a></dt>
<dd><p>Interactively create configuration options and add the attributes to
the Config object <tt class="docutils literal"><span class="pre">config</span></tt>.</p>
</dd></dl>
</div>
<div class="section" id="module-willie.config">
<span id="the-config-class"></span><h2><a class="toc-backref" href="#id8">The <tt class="docutils literal"><span class="pre">Config</span></tt> class</a><a class="headerlink" href="#module-willie.config" title="Permalink to this headline">¶</a></h2>
<p><em>Availability: 3+ for all functions; attributes may vary.</em></p>
<p>The config class is an abstraction class for accessing the active Willie
configuration file.</p>
<p>The Willie config file is divided to sections, and each section contains keys
and values. A section is an attribute of the config class, and is of type
<tt class="docutils literal"><span class="pre">ConfigSection</span></tt>. Each section contains the keys as attributes. For example,
if you want to access key example from section test, use
<tt class="docutils literal"><span class="pre">config.test.example</span></tt>. Note that the key names are made lower-case by the
parser, regardless of whether they are upper-case in the file.</p>
<p>The <tt class="docutils literal"><span class="pre">core</span></tt> section will always be present, and contains configuration used by
the Willie core. Modules are allowed to read those, but must not change them.</p>
<p>The config file can store strings, booleans and lists. If you need to store a
number, cast it to <tt class="docutils literal"><span class="pre">int()</span></tt> when reading.</p>
<p>For backwards compatibility, every key in the core section is an attribute of
the config class as well as of config.core. For new code, always specify the
name of the section, because this behavior might be removed in the future.</p>
<p>Running the <tt class="docutils literal"><span class="pre">config.py</span></tt> file directly will give the user an interactive
series of dialogs to create the configuration file. This will guide the user
through creating settings for the Willie core, the settings database, and any
modules which have a configuration function.</p>
<p>The configuration function, if used, must be declared with the signature
<tt class="docutils literal"><span class="pre">configure(config)</span></tt>. To add options, use <tt class="docutils literal"><span class="pre">interactive_add</span></tt>, <tt class="docutils literal"><span class="pre">add_list</span></tt>
and <tt class="docutils literal"><span class="pre">add_option</span></tt>.</p>
<dl class="class">
<dt id="willie.config.Config">
<em class="property">class </em><tt class="descclassname">willie.config.</tt><tt class="descname">Config</tt><big>(</big><em>filename</em>, <em>load=True</em>, <em>ignore_errors=False</em><big>)</big><a class="headerlink" href="#willie.config.Config" title="Permalink to this definition">¶</a></dt>
<dd><dl class="class">
<dt id="willie.config.Config.ConfigSection">
<em class="property">class </em><tt class="descname">ConfigSection</tt><big>(</big><em>name</em>, <em>items</em>, <em>parent</em><big>)</big><a class="headerlink" href="#willie.config.Config.ConfigSection" title="Permalink to this definition">¶</a></dt>
<dd><p>Represents a section of the config file, contains all keys in the
section as attributes.</p>
<dl class="method">
<dt id="willie.config.Config.ConfigSection.get_list">
<tt class="descname">get_list</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#willie.config.Config.ConfigSection.get_list" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dl class="method">
<dt id="willie.config.Config.add_list">
<tt class="descclassname">Config.</tt><tt class="descname">add_list</tt><big>(</big><em>section</em>, <em>option</em>, <em>message</em>, <em>prompt</em><big>)</big><a class="headerlink" href="#willie.config.Config.add_list" title="Permalink to this definition">¶</a></dt>
<dd><p>Ask user in terminal for a list to assign to <tt class="docutils literal"><span class="pre">option</span></tt>. If
<tt class="docutils literal"><span class="pre">option</span></tt> is already defined under <tt class="docutils literal"><span class="pre">section</span></tt>, show the user the
current values and ask if the user would like to keep them. If so,
additional values can be entered.</p>
</dd></dl>
<dl class="method">
<dt id="willie.config.Config.add_option">
<tt class="descclassname">Config.</tt><tt class="descname">add_option</tt><big>(</big><em>section</em>, <em>option</em>, <em>question</em>, <em>default=False</em><big>)</big><a class="headerlink" href="#willie.config.Config.add_option" title="Permalink to this definition">¶</a></dt>
<dd><p>Show user in terminal a “y/n” prompt, and set <cite>option</cite> to True or False
based on the response. If default is passed as true, the default will be
shown as <tt class="docutils literal"><span class="pre">[y]</span></tt>, else it will be <tt class="docutils literal"><span class="pre">[n]</span></tt>. <tt class="docutils literal"><span class="pre">question</span></tt> should be phrased
as a question, but without a question mark at the end. If <tt class="docutils literal"><span class="pre">option</span></tt> is
already defined, it will be used instead of <tt class="docutils literal"><span class="pre">default</span></tt>, regardless of
wheather <tt class="docutils literal"><span class="pre">default</span></tt> is passed.</p>
</dd></dl>
<dl class="method">
<dt id="willie.config.Config.add_section">
<tt class="descclassname">Config.</tt><tt class="descname">add_section</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#willie.config.Config.add_section" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a section to the config file, returns <tt class="docutils literal"><span class="pre">False</span></tt> if already exists.</p>
</dd></dl>
<dl class="attribute">
<dt id="willie.config.Config.filename">
<tt class="descclassname">Config.</tt><tt class="descname">filename</tt><em class="property"> = None</em><a class="headerlink" href="#willie.config.Config.filename" title="Permalink to this definition">¶</a></dt>
<dd><p>The config object’s associated file, as noted above.</p>
</dd></dl>
<dl class="method">
<dt id="willie.config.Config.has_option">
<tt class="descclassname">Config.</tt><tt class="descname">has_option</tt><big>(</big><em>section</em>, <em>name</em><big>)</big><a class="headerlink" href="#willie.config.Config.has_option" title="Permalink to this definition">¶</a></dt>
<dd><p>Check if option <tt class="docutils literal"><span class="pre">name</span></tt> exists under section <tt class="docutils literal"><span class="pre">section</span></tt></p>
</dd></dl>
<dl class="method">
<dt id="willie.config.Config.has_section">
<tt class="descclassname">Config.</tt><tt class="descname">has_section</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#willie.config.Config.has_section" title="Permalink to this definition">¶</a></dt>
<dd><p>Check if section <tt class="docutils literal"><span class="pre">name</span></tt> exists</p>
</dd></dl>
<dl class="method">
<dt id="willie.config.Config.interactive_add">
<tt class="descclassname">Config.</tt><tt class="descname">interactive_add</tt><big>(</big><em>section</em>, <em>option</em>, <em>prompt</em>, <em>default=None</em>, <em>ispass=False</em><big>)</big><a class="headerlink" href="#willie.config.Config.interactive_add" title="Permalink to this definition">¶</a></dt>
<dd><p>Ask user in terminal for the value to assign to <tt class="docutils literal"><span class="pre">option</span></tt> under
<tt class="docutils literal"><span class="pre">section</span></tt>. If <tt class="docutils literal"><span class="pre">default</span></tt> is passed, it will be shown as the default
value in the prompt. If <tt class="docutils literal"><span class="pre">option</span></tt> is already defined in <tt class="docutils literal"><span class="pre">section</span></tt>,
it will be used instead of <tt class="docutils literal"><span class="pre">default</span></tt>, regardless of wheather
<tt class="docutils literal"><span class="pre">default</span></tt> is passed.</p>
</dd></dl>
<dl class="method">
<dt id="willie.config.Config.option">
<tt class="descclassname">Config.</tt><tt class="descname">option</tt><big>(</big><em>question</em>, <em>default=False</em><big>)</big><a class="headerlink" href="#willie.config.Config.option" title="Permalink to this definition">¶</a></dt>
<dd><p>Show user in terminal a “y/n” prompt, and return true or false based on
the response. If default is passed as true, the default will be shown as
<tt class="docutils literal"><span class="pre">[y]</span></tt>, else it will be <tt class="docutils literal"><span class="pre">[n]</span></tt>. <tt class="docutils literal"><span class="pre">question</span></tt> should be phrased as a
question, but without a question mark at the end.</p>
</dd></dl>
<dl class="method">
<dt id="willie.config.Config.save">
<tt class="descclassname">Config.</tt><tt class="descname">save</tt><big>(</big><big>)</big><a class="headerlink" href="#willie.config.Config.save" title="Permalink to this definition">¶</a></dt>
<dd><p>Save all changes to the config file</p>
</dd></dl>
</dd></dl>
<dl class="exception">
<dt id="willie.config.ConfigurationError">
<em class="property">exception </em><tt class="descclassname">willie.config.</tt><tt class="descname">ConfigurationError</tt><big>(</big><em>value</em><big>)</big><a class="headerlink" href="#willie.config.ConfigurationError" title="Permalink to this definition">¶</a></dt>
<dd><p>Exception type for configuration errors</p>
</dd></dl>
<dl class="function">
<dt id="willie.config.check_dir">
<tt class="descclassname">willie.config.</tt><tt class="descname">check_dir</tt><big>(</big><em>create=True</em><big>)</big><a class="headerlink" href="#willie.config.check_dir" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="willie.config.create_config">
<tt class="descclassname">willie.config.</tt><tt class="descname">create_config</tt><big>(</big><em>configpath</em><big>)</big><a class="headerlink" href="#willie.config.create_config" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="willie.config.wizard">
<tt class="descclassname">willie.config.</tt><tt class="descname">wizard</tt><big>(</big><em>section</em>, <em>config=None</em><big>)</big><a class="headerlink" href="#willie.config.wizard" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</div>
</div>
<div class="section" id="miscellaneous-web-tools">
<h1><a class="toc-backref" href="#id9">Miscellaneous: <tt class="docutils literal"><span class="pre">web</span></tt>, <tt class="docutils literal"><span class="pre">tools</span></tt></a><a class="headerlink" href="#miscellaneous-web-tools" title="Permalink to this headline">¶</a></h1>
<p>These provide a number of useful shortcuts for common tasks.</p>
<div class="section" id="module-willie.web">
<span id="willie-web"></span><h2><a class="toc-backref" href="#id10">willie.web</a><a class="headerlink" href="#module-willie.web" title="Permalink to this headline">¶</a></h2>
<p><em>Availability: 3+</em></p>
<p>The web class contains essential web-related functions for interaction with web applications or websites in your modules.
It supports HTTP GET, HTTP POST and HTTP HEAD.</p>
<dl class="function">
<dt id="willie.web.get">
<tt class="descclassname">willie.web.</tt><tt class="descname">get</tt><big>(</big><em>uri</em>, <em>timeout=20</em><big>)</big><a class="headerlink" href="#willie.web.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Execute an HTTP GET query on <cite>uri</cite>, and return the result.
<cite>timeout</cite> is an optional argument, which represents how much time we should wait before throwing a timeout exception. It defualts to 20, but can be set to higher values if you are communicating with a slow web application.</p>
</dd></dl>
<dl class="function">
<dt id="willie.web.get_urllib_object">
<tt class="descclassname">willie.web.</tt><tt class="descname">get_urllib_object</tt><big>(</big><em>uri</em>, <em>timeout</em><big>)</big><a class="headerlink" href="#willie.web.get_urllib_object" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a urllib2 object for <cite>uri</cite> and <cite>timeout</cite>. This is better than using urrlib2 directly, for it handles redirects, makes sure URI is utf8, and is shorter and easier to use.
Modules may use this if they need a urllib2 object to execute .read() on. For more information, refer to the urllib2 documentation.</p>
</dd></dl>
<dl class="function">
<dt id="willie.web.head">
<tt class="descclassname">willie.web.</tt><tt class="descname">head</tt><big>(</big><em>uri</em>, <em>timeout=20</em><big>)</big><a class="headerlink" href="#willie.web.head" title="Permalink to this definition">¶</a></dt>
<dd><p>Execute an HTTP GET query on <cite>uri</cite>, and return the headers.
<cite>timeout</cite> is an optional argument, which represents how much time we should wait before throwing a timeout exception. It defualts to 20, but can be set to higher values if you are communicating with a slow web application.</p>
</dd></dl>
<dl class="function">
<dt id="willie.web.post">
<tt class="descclassname">willie.web.</tt><tt class="descname">post</tt><big>(</big><em>uri</em>, <em>query</em><big>)</big><a class="headerlink" href="#willie.web.post" title="Permalink to this definition">¶</a></dt>
<dd><p>Execute an HTTP POST query. <cite>uri</cite> is the target URI, and <cite>query</cite> is the POST data.</p>
</dd></dl>
<dl class="function">
<dt id="willie.web.quote">
<tt class="descclassname">willie.web.</tt><tt class="descname">quote</tt><big>(</big><em>string</em><big>)</big><a class="headerlink" href="#willie.web.quote" title="Permalink to this definition">¶</a></dt>
<dd><p>Identical to urllib2.quote. Use this if you already importing web in your module and don’t want to import urllib2 just to use the quote function.</p>
</dd></dl>
<dl class="function">
<dt id="willie.web.urlencode">
<tt class="descclassname">willie.web.</tt><tt class="descname">urlencode</tt><big>(</big><em>data</em><big>)</big><a class="headerlink" href="#willie.web.urlencode" title="Permalink to this definition">¶</a></dt>
<dd><p>Identical to urllib.urlencode. Use this if you already importing web in your module and don’t want to import urllib just to use the urlencode function.</p>
</dd></dl>
</div>
<div class="section" id="module-willie.tools">
<span id="willie-tools"></span><h2><a class="toc-backref" href="#id11">willie.tools</a><a class="headerlink" href="#module-willie.tools" title="Permalink to this headline">¶</a></h2>
<p><em>Availability: 3+</em>
<tt class="docutils literal"><span class="pre">tools</span></tt> contains a number of useful miscellaneous tools and shortcuts for use
in Willie modules.</p>
<dl class="class">
<dt id="willie.tools.Ddict">
<em class="property">class </em><tt class="descclassname">willie.tools.</tt><tt class="descname">Ddict</tt><big>(</big><em>default=None</em><big>)</big><a class="headerlink" href="#willie.tools.Ddict" title="Permalink to this definition">¶</a></dt>
<dd><p>A simple helper class to ease the creation of multi-dimensional <tt class="docutils literal"><span class="pre">dict</span></tt>s.</p>
</dd></dl>
<dl class="class">
<dt id="willie.tools.Nick">
<em class="property">class </em><tt class="descclassname">willie.tools.</tt><tt class="descname">Nick</tt><a class="headerlink" href="#willie.tools.Nick" title="Permalink to this definition">¶</a></dt>
<dd><p>A <cite>unicode</cite> subclass which acts appropriately for an IRC nickname. When used
as normal <cite>unicode</cite> objects, case will be preserved. However, when comparing
two Nick objects, or comparing a Nick object with a <cite>unicode</cite> object, the
comparison will be case insensitive. This case insensitivity includes the
case convention conventions regarding <tt class="docutils literal"><span class="pre">[]</span></tt>, <tt class="docutils literal"><span class="pre">{}</span></tt>, <tt class="docutils literal"><span class="pre">|</span></tt>, and <tt class="docutils literal"><span class="pre">\</span></tt>
described in RFC 1459.</p>
<dl class="method">
<dt id="willie.tools.Nick.lower">
<tt class="descname">lower</tt><big>(</big><big>)</big><a class="headerlink" href="#willie.tools.Nick.lower" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <cite>nick</cite>, converted to lower-case per RFC 1459</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="willie.tools.OutputRedirect">
<em class="property">class </em><tt class="descclassname">willie.tools.</tt><tt class="descname">OutputRedirect</tt><big>(</big><em>logpath</em>, <em>stderr=False</em>, <em>quiet=False</em><big>)</big><a class="headerlink" href="#willie.tools.OutputRedirect" title="Permalink to this definition">¶</a></dt>
<dd><p>A simplified object used to write to both the terminal and a log file.</p>
<dl class="method">
<dt id="willie.tools.OutputRedirect.write">
<tt class="descname">write</tt><big>(</big><em>string</em><big>)</big><a class="headerlink" href="#willie.tools.OutputRedirect.write" title="Permalink to this definition">¶</a></dt>
<dd><p>Write the given <tt class="docutils literal"><span class="pre">string</span></tt> to the logfile and terminal.</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="willie.tools.check_pid">
<tt class="descclassname">willie.tools.</tt><tt class="descname">check_pid</tt><big>(</big><em>pid</em><big>)</big><a class="headerlink" href="#willie.tools.check_pid" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: Only on POSIX systems</em></p>
<p>Return <tt class="docutils literal"><span class="pre">True</span></tt> if there is a process running with the given <tt class="docutils literal"><span class="pre">PID</span></tt>.</p>
</dd></dl>
<dl class="function">
<dt id="willie.tools.stderr">
<tt class="descclassname">willie.tools.</tt><tt class="descname">stderr</tt><big>(</big><em>string</em><big>)</big><a class="headerlink" href="#willie.tools.stderr" title="Permalink to this definition">¶</a></dt>
<dd><p>Print the given <tt class="docutils literal"><span class="pre">string</span></tt> to stderr. This is equivalent to <tt class="docutils literal"><span class="pre">print</span> <span class="pre">>></span>
<span class="pre">sys.stderr,</span> <span class="pre">string</span></tt></p>
</dd></dl>
<dl class="function">
<dt id="willie.tools.verify_ssl_cn">
<tt class="descclassname">willie.tools.</tt><tt class="descname">verify_ssl_cn</tt><big>(</big><em>server</em>, <em>port</em><big>)</big><a class="headerlink" href="#willie.tools.verify_ssl_cn" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Availability: Must have the OpenSSL Python module installed.</em></p>
<p>Verify the SSL certificate given by the <tt class="docutils literal"><span class="pre">server</span></tt> when connecting on the
given <tt class="docutils literal"><span class="pre">port</span></tt>. This returns <tt class="docutils literal"><span class="pre">None</span></tt> if OpenSSL is not available or
‘NoCertFound’ if there was no certificate given. Otherwise, a two-tuple
containing a boolean of whether the certificate is valid and the
certificate information is returned.</p>
</dd></dl>
</div>
</div>
<div class="section" id="indices-and-tables">
<h1><a class="toc-backref" href="#id12">Indices and tables</a><a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h1>
<ul class="simple">
<li><a class="reference internal" href="genindex.html"><em>Index</em></a></li>
<li><a class="reference internal" href="py-modindex.html"><em>Module Index</em></a></li>
<li><a class="reference internal" href="search.html"><em>Search Page</em></a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<div id="searchbox" style="display: none">
<h3>Quick 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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li><a href="index.html#document-index">Willie IRC Bot 3.2.0 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2012, E. Powell, et al..
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
