WILLIE(1)

NAME
willie - Willie IRC Bot Documentation

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.

  Contents

•   Introduction

•   Getting started: Your functions, willie, and trigger

•   Your modules

•   The Willie class

•   The Trigger class

•   More advanced: db and config

•   The WillieDB class

•   The Config class

•   Miscellaneous: web, tools, module, formatting

•   willie.web

•   willie.tools

•   willie.module

•   willie.formatting

•   Indices and tables

    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 Willie object (Phenny in 1.x and Jenni in 2.x) and a Trigger object (CommandInput in 1.x and 2.x). By convention, these are named phenny and input in 1.x, jenni and input in 2.x, willie and trigger in 3.x, and bot and trigger from version 4.0 onward. For the purposes of this guide, the 4.0 names will be used.

YOUR MODULES

A Willie module contains one or more callables. It may optionally contain configure, setup, and shutdown functions. callables are given a number of attributes, which determine when they will be executed. This is done with decorators, imported from willie.module. It may also be done by adding the attributes directly, at the same indentation level as the function's def line, following the last line of the function; this is the only option in versions prior to 4.0.

callable(bot, trigger)
    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 Willie object and a Trigger object, as noted above. Usually, methods of the Willie object will be used in reply to the trigger, but this isn't a requirement.

    The return value of a callable will usually be None. This doesn't need to be explicit; if the function has no return statement (or simply uses return with no arguments), None will be returned. In 3.2+, the return value can be a constant; in prior versions return values were ignored. Returning a constant instructs the bot to perform some action after the callable's execution. For example, returning NOLIMIT will suspend rate limiting on that call. These constants are defined in willie.module, except in version 3.2 in which they are defined as attributes of the Willie class.

    Note that the name can, and should, be anything - it doesn't need to be called callable.

commands
    See also: willie.module.commands()

    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.

rule
    See also: willie.module.rule()

    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 Trigger object later.

    Inside the regular expression, some special directives can be used. $nick will be replaced with the nick of the bot and , or :, and $nickname will be replaced with the nick of the bot.

    Prior to 3.1, 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 3.1.

event
    See also: willie.module.event()

    This is one of a number of events, such as 'JOIN', 'PART', 'QUIT', etc. (More details can be found in RFC 1459.) 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 rule to match (though it may be '.*', which will always match) or they will not be triggered.

rate
    Availability: 2+

    See also: willie.module.rate()

    This limits the frequency with which a single user may use the function. If a function is given a rate of 20, a single user may only use that function once every 20 seconds. This limit applies to each user individually. Users on the admin list in Willie's configuration are exempted from rate limits.

priority
    See also: willie.module.priority()

    Priority can be one of high, medium, low. It allows you to control the order of callable execution, if your module needs it. Defaults to medium

setup(willie)
    This is an optional function of a module, which will be called while the module is being loaded. 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 exist and are set). Note that this normally occurs prior to connection to the server, so the behavior of the Willie object's messaging functions is undefined.

    Throwing an exception from this function (such as a ConfigurationError) will prevent any callables in the module from being registered, and provide an error message to the user. This is useful when requiring the presence of configuration values or making other environmental requirements.

    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.

shutdown(willie)
    Availability: 4.1+

    This is an optional function of a module, which will be called while the Willie is quitting. Note that this normally occurs after closing 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 properly clean up (e.g, ensuring that any temporary cache files are deleted).

    The bot will not continue notifying other modules or continue quitting during the execution of this function. As such, an infinite loop (such as an unthreaded polling loop) will cause the bot to hang.

configure(config)
    Availability: 3+

    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 Config object in order to create the configuration variables it needs to function properly.

    In 3.1+, 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.

THE WILLIE CLASS

class willie.bot.Willie(config, daemon=False)

Job alias of JobScheduler

class JobScheduler(bot)
    Calls jobs assigned to it in steady intervals.

    JobScheduler is a thread that keeps track of Jobs and calls them every X seconds, where X is a property of the Job. It maintains jobs in a priority queue, where the next job to be called is always the first item. Thread safety is maintained with a mutex that is released during long operations, so methods add_job and clear_jobs can be safely called from the main thread.

add_job(job)
    Add a Job to the current job queue.

clear_jobs()
    Clear current Job queue and start fresh.

run()
    Run forever.

Willie.cap_req(module_name, capability, failure_callback)
    Tell Willie to request a capability when it starts.

    By prefixing the capability with -, it will be ensured that the capability is not enabled. Simmilarly, by prefixing the capability with =, it will be ensured that the capability is enabled. Requiring and disabling is "first come, first served"; if one module requires a capability, and another prohibits it, this function will raise an exception in whichever module loads second. An exception will also be raised if the module is being loaded after the bot has already started, and the request would change the set of enabled capabilities.

    If the capability is not prefixed, and no other module prohibits it, it will be requested. Otherwise, it will not be requested. Since capability requests that are not mandatory may be rejected by the server, as well as by other modules, a module which makes such a request should account for that possibility.

    The actual capability request to the server is handled after the completion of this function. In the event that the server denies a request, the failure_callback function will be called, if provided. The arguments will be a Willie object, and the capability which was rejected. This can be used to disable callables which rely on the capability.

Willie.config = None
    The Config for the current Willie instance.

Willie.db = None
    The bot's database.

Willie.doc = None
    A dictionary of command names to their docstring and example, if declared. The first item in a callable's commands list is used as the key in version 3.2 onward. Prior to 3.2, the name of the function as declared in the source code was used.

Willie.enabled_capabilities = None
    A set containing the IRCv3 capabilities that the bot has enabled.

static Willie.is_callable(obj)
    Return true if object is a willie callable.

    Object must be both be callable and have hashable. Furthermore, it must have either "commands", "rule" or "interval" as attributes to mark it as a willie callable.

static Willie.is_shutdown(obj)
    Return true if object is a willie shutdown method.

    Object must be both be callable and named shutdown.

Willie.memory = None
    A thread-safe dict for storage of runtime data to be shared between modules. See WillieMemory

Willie.privileges = None
    A dictionary of channels to their users and privilege levels

    The value associated with each channel is a dictionary of Identifiers to a bitwise integer value, determined by combining the appropriate constants from module.

Willie.register(variables)
    Register all willie callables.

    With the __dict__ attribute from a Willie module, update or add the trigger commands and rules, to allow the function to be triggered, and shutdown methods, to allow the modules to be notified when willie is quitting.

Willie.server_capabilities = None
    A set containing the IRCv3 capabilities that the server supports.

    For servers that do not support IRCv3, this will be an empty set.

Willie.stats = None
    A dictionary which maps a tuple of a function name and where it was used to the nuber of times it was used there.

Willie.sub(pattern)
    Replace any of the following special directives in a function's rule expression: $nickname -> the bot's nick $nick -> the bot's nick followed by : or ,

Willie.times = None
    A dictionary mapping lower-case'd nicks to dictionaries which map funtion names to the time which they were last used by that nick.

Willie.unregister(variables)
    Unregister all willie callables in variables, and their bindings.

    When unloading a module, this ensures that the unloaded modules will not get called and that the objects can be garbage collected. Objects that have not been registered are ignored.

    Args: variables -- A list of callable objects from a willie module.

reply(text, notice=False)
    In a module function, send text to the channel in which the function was triggered, preceeded by the nick of the user who triggered it.

    If notice is set to True, this function will send the reply in an IRC NOTICE instead of a regular IRC PRIVMSG.

    This function is not available outside of module functions. It can not be used, for example, in a module's setup or shutdown function.

    The same behavior regarding loop detection and length restrictions apply to reply as to msg, though reply does not offer automatic message splitting.

say(text, max_messages=1)
    In a module function, send text to the channel in which the function was triggered.

    This function is not available outside of module functions. It can not be used, for example, in a module's configure function.

    The same behavior regarding loop detection and length restrictions, as well as message splitting, apply to say as to msg.

action(text, recipient=None)
    In a module function, send text to the channel in which the function was triggered preceeded by CTCP ACTION directive (result identical to using /me in most clients).

    If recipient is specified and is not None, this function will send the message to recipient instead of the originating channel. recipient can be either a channel or a user.

    This function is not available outside of module functions. It can not be used, for example, in a module's configure function.

    The same behavior regarding loop detection and length restrictions apply to action as to msg and say, though like reply there is no facility for message splitting.

notice(text, recipient=None)
    In a module function, send text to the channel in which the function was triggered as an IRC NOTICE.

    If recipient is specified and is not None, this function will send the message to recipient instead of the originating channel. recipient can be either a channel or a user.

    This function is not available outside of module functions. It can not be used, for example, in a module's configure function.

    The same behavior regarding loop detection and length restrictions apply to action as to msg and say, though like reply there is no facility for message splitting.

quit(message)
    Gracefully quit and shutdown, using message as the quit message.

    Willie will notify modules that it is quitting should the modules have a shutdown method.

part(channel)
    Part channel

join(channel, password = None)
    Join a channel named channel.

nick
    Willie's current nick. Changing this while Willie is running is unsupported.

name
    Willie's "real name", as used for whois.

password
    Willie's NickServ password

channels
    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.

ops

halfplus
    Availability: 3+

    Dictionary mapping channels to a list of their ops, and half-ops and ops respectively.

write(args, text=None)
    Send a command to the server

    args is an iterable of strings, which are joined by spaces. text is treated as though it were the final item in args, but is preceeded by a :. This is a special case which means that text, unlike the items in args may contain spaces (though this constraint is not checked by write).

    In other words, both willie.write(('PRIVMSG',), 'Hello, world!') and willie.write(('PRIVMSG', ':Hello, world!')) will send PRIVMSG :Hello, world! to the server.

    Newlines and carriage returns ('\n' and '\r') are removed before sending. Additionally, if the message (after joining) is longer than than 510 characters, any remaining characters will not be sent.

msg(recipient, text, max_messages=1)
    Send a PRIVMSG of text to recipient. If the same text was the message in 5 or more of the last 8 calls to msg, '...' will be sent instead. If this condition is met, and '...' 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.

    If max_messages argument is optional, and defaults to 1. The message will be split into that number of segments. Each segment will be 400 bytes long or less (bearing in mind that messages are UTF-8 encoded). The message will be split at the last space before the 400th byte, or at the 400th byte if no such space exists. The remainder will be split in the same manner until either the given number of segments is reached or the remainder is less than 400 bytes.

    If the message is too long to fit into the given number of segments (or if no number is given), the bot will send as many bytes to the server as it can. The server, due to the structure of the protocol, will likely truncate the message further, to a length that is not determinable by Willie (though you can generally rely on 400 bytes making it through).

    Note that when a message is split not on a space but on a byte number, no attention is given to Unicode character boundaries, and no other word boundaries besides space will be split upon. This will not cause problems in the vast majority of cases.

debug(tag, text, level)
    Availability: 3+

    Send text to Willie's configured debug_target. This can be either an IRC channel (starting with #) or stdio. Suppress the message if the given level is lower than Willie's configured verbose setting. Acceptable values for level are 'verbose' (only send if Willie is in verbose mode), 'warning' (send if Willie is in verbose or warning mode), always (send debug message regardless of the configured debug level). Returns True if the message is sent or printed, and False if it is not.

    If debug_target is a channel, the same behavior regarding loop detection and length restrictions apply to debug as to msg.

add_op(channel, name)

add_halfop(channel, name)
    Availability: 3+, deprecated in 4.1.0

    Add name to channel's entry in the ops or halfplus dictionaries, respectively.

del_op(channel, name)

del_halfop(channel, name)
    Availability: 3+, deprecated in 4.1.0

    Remove name from channel's entry in the ops or halfplus dictionaries, respectively.

flush_ops(channel)
    Availability: 3+, deprecated in 4.1.0

    Re-initialize and empty the ops and halfops entry for channel.

init_ops_list(self, channel)
    Availability: 3+, deprecated in 4.1.0

    Create an empty entry in ops and halfops for channel. This will not damage existing entries, but must be done before users can be added to either dictionary.

THE TRIGGER CLASS

class willie.trigger.Trigger
    A line from the server, which has matched a callable's rules.

    Note that CTCP messages (PRIVMSG`es and `NOTICE`es which start and end with `'x01') will have the 'x01' bytes stripped, and the command (e.g. ACTION) placed mapped to the 'intent' key in Trigger.tags.

admin
    True if the nick which triggered the command is one of the bot's admins.

args
    A tuple containing each of the arguments to an event. These are the strings passed between the event name and the colon. For example, setting mode -m on the channel #example, args would be ('#example', '-m')

event
    The IRC event (e.g. PRIVMSG or MODE) which triggered the message.

group
    The group function of the match attribute.

    See Python re documentation for details.

groups
    The groups function of the match attribute.

    See Python re documentation for details.

host
    The hostname of the person who sent the message

hostmask
    Hostmask of the person who sent the message as <nick>!<user>@<host>

is_privmsg
    True if the trigger is from a user, False if it's from a channel.

match
    The regular expression MatchObject for the triggering line.

nick
    The Identifier of the person who sent the message.

owner
    True if the nick which triggered the command is the bot's owner.

raw The entire message, as sent from the server. This includes the CTCP x01 bytes and command, if they were included.

sender
    The channel from which the message was sent.

    In a private message, this is the nick that sent the message.

tags
    A map of the IRCv3 message tags on the message.

user
    Local username of the person who sent the message

    The willie object has, among others, the attributes db and config. These can be used for a number of functions and features.

THE WILLIEDB CLASS

class willie.db.WillieDB(config)
    Availability: 5.0+

    This defines an interface for basic, common operations on a sqlite database. It simplifies those common operations, and allows direct access to the database, wherever the user has configured it to be.

    When configured with a relative filename, it is assumed to be in the same directory as the config.

alias_nick(nick, alias)
    Create an alias for a nick.

    Raises ValueError if the alias already exists. If nick does not already exist, it will be added along with the alias.

connect()
    Return a raw database connection object.

delete_nick_group(nick)
    Removes a nickname, and all associated aliases and settings.

execute(*args, **kwargs)
    Execute an arbitrary SQL query against the database.

    Returns a cursor object, on which things like .fetchall() can be called per PEP 249.

get_channel_value(channel, key)
    Retrieves the value for a given key associated with a channel.

get_nick_id(nick, create=True)
    Return the internal identifier for a given nick.

    This identifier is unique to a user, and shared across all of that user's aliases. If create is True, a new ID will be created if one does not already exist

get_nick_or_channel_value(name, key)
    Gets the value key associated to the nick or channel name.

get_nick_value(nick, key)
    Retrieves the value for a given key associated with a nick.

get_preferred_value(names, key)
    Gets the value for the first name which has it set.

    names is a list of channel and/or user names. Returns None if none of the names have the key set.

get_uri()
    Returns a URL for the database, usable to connect with SQLAlchemy.

merge_nick_groups(first_nick, second_nick)
    Merges the nick groups for the specified nicks.

    Takes two nicks, which may or may not be registered. Unregistered nicks will be registered. Keys which are set for only one of the given nicks will be preserved. Where multiple nicks have values for a given key, the value set for the first nick will be used.

    Note that merging of data only applies to the native key-value store. If modules define their own tables which rely on the nick table, they will need to have their merging done separately.

set_nick_value(nick, key, value)
    Sets the value for a given key to be associated with the nick.

unalias_nick(alias)
    Removes an alias.

    Raises ValueError if there is not at least one other nick in the group. To delete an entire group, use delete_group.

THE CONFIG CLASS

Availability: 3+ for all functions; attributes may vary.

The config class is an abstraction class for accessing the active Willie configuration file.

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 ConfigSection. Each section contains the keys as attributes. For example, if you want to access key example from section test, use config.test.example. Note that the key names are made lower-case by the parser, regardless of whether they are upper-case in the file.

The core section will always be present, and contains configuration used by the Willie core. Modules are allowed to read those, but must not change them.

The config file can store strings, booleans and lists. If you need to store a number, cast it to int() when reading.

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.

Running the config.py 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.

The configuration function, if used, must be declared with the signature configure(config). To add options, use interactive_add, add_list and add_option.

class willie.config.Config(filename, load=True, ignore_errors=False)

class ConfigSection(name, items, parent)
    Represents a section of the config file.

    Contains all keys in thesection as attributes.

get_list(name)

Config.add_list(section, option, message, prompt)
    Ask for a list to assign to option.

    Ask user in terminal for a list to assign to option. If option is already defined under section, show the user the current values and ask if the user would like to keep them. If so, additional values can be entered.

Config.add_option(section, option, question, default=False)
    Ask "y/n" and set option based in the response.

    Show user in terminal a "y/n" prompt, and set option to True or False based on the response. If default is passed as true, the default will be shown as [y], else it will be [n]. question should be phrased as a question, but without a question mark at the end. If option is already defined, it will be used instead of default, regardless of wheather default is passed.

Config.add_section(name)
    Add a section to the config file.

    Returns False if already exists.

Config.define_section(name, cls_)
    Define the available settings in a section.

    cls_ must be a subclass of StaticSection. If the section has already been defined with a different class, ValueError is raised.

Config.enumerate_modules(show_all=False)
    Map the names of modules to the location of their file.

    Availability: 4.0+

    Return a dict mapping the names of modules to the location of their file. This searches the regular modules directory and all directories specified in the core.extra attribute of the config object. If two modules have the same name, the last one to be found will be returned and the rest will be ignored. Modules are found starting in the regular directory, followed by ~/.willie/modules, and then through the extra directories in the order that the are specified.

    If show_all is given as True, the enable and exclude configuration options will be ignored, and all modules will be shown (though duplicates will still be ignored as above).

Config.filename = None
    The config object's associated file, as noted above.

Config.has_option(section, name)
    Check if option name exists under section section.

Config.has_section(name)
    Check if section name exists.

Config.homedir
    An alias to config.core.homedir

Config.interactive_add(section, option, prompt, default=None, ispass=False)
    Ask for the value to assign to option under section.

    Ask user in terminal for the value to assign to option under section. If default is passed, it will be shown as the default value in the prompt. If option is already defined in section, it will be used instead of default, regardless of wheather default is passed.

Config.option(question, default=False)
    Ask "y/n" and return the corresponding boolean answer.

    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 [y], else it will be [n]. question should be phrased as a question, but without a question mark at the end.

Config.save()
    Save all changes to the config file.

exception willie.config.ConfigurationError(value)
    Exception type for configuration errors

willie.config.check_dir(create=True)

willie.config.create_config(configpath)

willie.config.wizard(section, config=None)

    These provide a number of useful shortcuts for common tasks.

WILLIE.WEB

Availability: 3+

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.

class willie.web.VerifiedHTTPSConnection(*args, **kwargs)
    Verified HTTPS Connection handler

connect()
    Connect to the host and port specified in __init__.

willie.web.get(uri, timeout=20, headers=None, return_headers=False, limit_bytes=None, verify_ssl=True, dont_decode=False)
    Execute an HTTP GET query on uri, and return the result.

    timeout is an optional argument, which represents how much time we should wait before throwing a timeout exception. It defaults to 20, but can be set to higher values if you are communicating with a slow web application. headers is a dict of HTTP headers to send with the request. If return_headers is True, return a tuple of (bytes, headers)

    If limit_bytes is provided, only read that many bytes from the URL. This may be a good idea when reading from unknown sites, to prevent excessively large files from being downloaded.

willie.web.get_urllib_object(uri, timeout, headers=None, verify_ssl=True, data=None)
    Return a urllib2 object for uri and timeout and headers.

    This is better than using urlib2 directly, for it handles SSL verifcation, 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.

willie.web.head(uri, timeout=20, headers=None, verify_ssl=True)
    Execute an HTTP GET query on uri, and return the headers.

    timeout is an optional argument, which represents how much time we should wait before throwing a timeout exception. It defaults to 20, but can be set to higher values if you are communicating with a slow web application.

willie.web.post(uri, query, limit_bytes=None, timeout=20, verify_ssl=True, return_headers=False)
    Execute an HTTP POST query.

    uri is the target URI, and query is the POST data. headers is a dict of HTTP headers to send with the request.

    If limit_bytes is provided, only read that many bytes from the URL. This may be a good idea when reading from unknown sites, to prevent excessively large files from being downloaded.

willie.web.quote(string, safe='/')
    Like urllib2.quote but handles unicode properly.

willie.web.quote_query(string)
    Quotes the query parameters.

WILLIE.TOOLS

Availability: 3+ tools contains a number of useful miscellaneous tools and shortcuts for use in Willie modules. A number of things are moved into sub-modules like tools.time in 5.3; they will be removed from tools itself in 6.0.

class willie.tools.Ddict(default=None)
    Class for multi-dimensional dict.

    A simple helper class to ease the creation of multi-dimensional dicts.

class willie.tools.Identifier
    A unicode subclass which acts appropriately for IRC identifiers.

    When used as normal unicode objects, case will be preserved. However, when comparing two Identifier objects, or comparing a Identifier object with a unicode object, the comparison will be case insensitive. This case insensitivity includes the case convention conventions regarding [], {}, |, \, ^ and ~ described in RFC 2812.

is_nick()
    Returns True if the Identifier is a nickname (as opposed to channel)

lower()
    Return the identifier converted to lower-case per RFC 2812.

class willie.tools.OutputRedirect(logpath, stderr=False, quiet=False)
    Redirect te output to the terminal and a log file.

    A simplified object used to write to both the terminal and a log file.

write(string)
    Write the given string to the logfile and terminal.

class willie.tools.WillieMemory(*args)
    A simple thread-safe dict implementation.

    Availability: 4.0; available as ``Willie.WillieMemory`` in 3.1.0 - 3.2.0

    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 __setitem__ and contains.

contains(key)
    Backwards compatability with 3.x, use in operator instead.

unlock()
    Release the write lock.

class willie.tools.WillieMemoryWithDefault(*args)
    Same as WillieMemory, but subclasses from collections.defaultdict.

contains(key)
    Backwards compatability with 3.x, use in operator instead.

lock()
    Lock this instance from writes. Useful if you want to iterate.

unlock()
    Release the write lock.

willie.tools.check_pid(pid)
    Check if a process is running with the given PID.

    Availability: Only on POSIX systems

    Return True if there is a process running with the given PID.

willie.tools.get_command_regexp(prefix, command)
    Return a compiled regexp object that implements the command.

willie.tools.get_hostmask_regex(mask)
    Return a compiled re.RegexObject for an IRC hostmask

willie.tools.get_input(prompt)
    Get decoded input from the terminal (equivalent to python 3's input).

willie.tools.get_raising_file_and_line(tb=None)
    Return the file and line number of the statement that raised the tb.

    Returns: (filename, lineno) tuple

willie.tools.stderr(string)
    Print the given string to stderr.

    This is equivalent to print >> sys.stderr, string

    Tools for getting and displaying the time.

willie.tools.time.format_time(db=None, config=None, zone=None, nick=None, channel=None, time=None)
    Return a formatted string of the given time in the given zone.

    time, if given, should be a naive datetime.datetime object and will be treated as being in the UTC timezone. If it is not given, the current time will be used. If zone is given and pytz is available, zone must be present in the IANA Time Zone Database; get_timezone can be helpful for this. If zone is not given or pytz is not available, UTC will be assumed.

    The format for the string is chosen in the following order:

1.  The format for the nick nick in db, if one is set and valid.

2.  The format for the channel channel in db, if one is set and valid.

3.  The default format in config, if one is set and valid.

4.  ISO-8601

    If db is not given or is not set up, steps 1 and 2 are skipped. If config is not given, step 3 will be skipped.

willie.tools.time.get_timezone(db=None, config=None, zone=None, nick=None, channel=None)
    Find, and return, the approriate timezone

    Time zone is pulled in the following priority: 1. zone, if it is valid 2. The timezone for the channel or nick zone in db if one is set and valid. 3. The timezone for the nick nick in db, if one is set and valid. 4. The timezone for the channel channel in db, if one is set and valid. 5. The default timezone in config, if one is set and valid.

    If db is not given, or given but not set up, steps 2 and 3 will be skipped. If config is not given, step 4 will be skipped. If no step yeilds a valid timezone, None is returned.

    Valid timezones are those present in the IANA Time Zone Database. Prior to checking timezones, two translations are made to make the zone names more human-friendly. First, the string is split on ', ', the pieces reversed, and then joined with '/'. Next, remaining spaces are replaced with '_'. Finally, strings longer than 4 characters are made title-case, and those 4 characters and shorter are made upper-case. This means "new york, america" becomes "America/New_York", and "utc" becomes "UTC".

    This function relies on pytz being available. If it is not available, None will always be returned.

    Tools to help safely do calculations from user input

willie.tools.calculation.eval_equation = <willie.tools.calculation.EquationEvaluator object>
    Evaluates a Python equation expression and returns the result.

    Supports addition (+), subtraction (-), multiplication (*), division (/), power (**) and modulo (%).

WILLIE.MODULE

This module is meant to be imported from willie modules.

It defines the following decorators for defining willie callables: willie.module.rule willie.module.thread willie.module.commands willie.module.nickname_commands willie.module.priority willie.module.event willie.module.rate willie.module.example

willie.module.NOLIMIT = 1
    Return value for callables, which supresses rate limiting for the call.

    Avalability: 4.0+; available as ``Willie.NOLIMIT`` in 3.2

    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.

willie.module.commands(*command_list)
    Decorator. Sets a command list for a callable.

    This decorator can be used to add multiple commands to one callable in a single line. The resulting match object will have the command as the first group, rest of the line, excluding leading whitespace, as the second group. Parameters 1 through 4, seperated by whitespace, will be groups 3-6.

Args:
    command: A string, which can be a regular expression.

Returns:
    A function with a new command appended to the commands attribute. If there is no commands attribute, it is added.

Example:

@command("hello"):
    If the command prefix is ".", this would trigger on lines starting with ".hello".

@commands('j', 'join')
    If the command prefix is ".", this would trigger on lines starting with either ".j" or ".join".

willie.module.event(*event_list)
    Decorator. Equivalent to func.event = value.

    This is one of a number of events, such as 'JOIN', 'PART', 'QUIT', etc. (More details can be found in RFC 1459.) 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 rule to match (though it may be '.*', which will always match) or they will not be triggered.

class willie.module.example(msg, result=None, privmsg=False, admin=False, owner=False, repeat=1, re=False, ignore=None)
    Decorator. Add an example.

    Add an example attribute into a function and generate a test.

willie.module.intent(*intent_list)
    Make a callable trigger on a message with any of the given intents.

    Availability: 5.2.0+

    NOTE: Due to a bug, messages sent with the intent in the CTCP format (rather than IRCv3 message tags) which do not include a message (for example, a message like \x01VERSION\x01) are not correctly parsed by the bot, and as such do not get caught by this decorator. This erroneous behavior is kept in 5.x for compatability, but will be rectified in 6.0.

    Additionally in 5.x, a rule or command must be specified in addition to this, even if it is just '.*.

willie.module.interval(*args)
    Decorator. Equivalent to func.interval.append(value).

    A function that uses this decorator will be called every X seconds, where X is the argument. This decorator can be used multiple times for multiple intervals, or all intervals can be given at once as arguments. The first time the function will be called is X seconds after the bot was started.

    For the callable, the first argument will be the bot itself, but it will not have the say, reply or action methods as would be the case when called due to rule or command.

    There is no guarantee that the bot is connected to a server or joined a channel when the function is called, so care must be taken.

    Example::

    import willie.module
    @willie.module.interval(5)
    def spam_every_5s(bot):
        if "#here" in bot.channels:
            bot.msg("#here", "It has been five seconds!")

willie.module.nickname_commands(*command_list)
    Decorator. Triggers on lines starting with "$nickname: command".

    This decorator can be used multiple times to add multiple rules. The resulting match object will have the command as the first group, rest of the line, excluding leading whitespace, as the second group. Parameters 1 through 4, seperated by whitespace, will be groups 3-6.

Args:
    command: A string, which can be a regular expression.

Returns:
    A function with a new regular expression appended to the rule attribute. If there is no rule attribute, it is added.

Example:

@nickname_commands("hello!"):
    Would trigger on "$nickname: hello!", "$nickname, hello!", "$nickname hello!", "$nickname hello! parameter1" and "$nickname hello! p1 p2 p3 p4 p5 p6 p7 p8 p9".

@nickname_commands(".*"):
    Would trigger on anything starting with "$nickname[:,]? ", and would have never have any additional parameters, as the command would match the rest of the line.

willie.module.priority(value)
    Decorator. Equivalent to func.priority = value.

Args:

value: Priority can be one of high , medium , low . Defaults to
    medium.

    Priority allows you to control the order of callable execution, if your module needs it.

willie.module.rate(value)
    Decorator. Equivalent to func.rate = value.

    Availability: 2+

    This limits the frequency with which a single user may use the function. If a function is given a rate of 20, a single user may only use that function once every 20 seconds. This limit applies to each user individually. Users on the admin list in Willie’s configuration are exempted from rate limits.

    Rate-limited functions that use scheduled future commands should import threading.Timer() instead of sched, or rate limiting will not work properly.

willie.module.require_admin(message=None)
    Decorator. Require the user triggering the message to be a bot admin.

    If they are not, message will be said if given.

willie.module.require_chanmsg(message=None)
    Decorator, this allows functions to specify if they should be only allowed via channel message.

    If it is not, message will be said if given.

willie.module.require_owner(message=None)
    Decorator. Require the user triggering the message to be the bot owner.

    If they are not, message will be said if given.

willie.module.require_privilege(level, message=None)
    Decorator. Require at lesat the given channel privilege level to execute the function.

    level can be one of the privilege levels defined in this module. If the user does not have the privilege, message will be said if given. If it is a private message, no checking will be done.

willie.module.require_privmsg(message=None)
    Decorator, this allows functions to specify if they should be only allowed via private message.

    If it is not, message will be said if given.

willie.module.rule(value)
    Decorator. Equivalent to func.rule.append(value).

    This decorator can be used multiple times to add more rules.

Args:
    value: 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 Trigger object later.

    Inside the regular expression, some special directives can be used. $nick will be replaced with the nick of the bot and , or :, and $nickname will be replaced with the nick of the bot.

willie.module.thread(value)
    Decorator. Equivalent to func.thread = value.

Args:

value: Either True or False. If True the function is called in
    a separate thread. If False from the main thread.

willie.module.unblockable(function)
    Decorator. Equivalent to func.unblockable = True.

    If this decorator is used, the function will be called, even if the bot has been configured to ignore commands from the user. This can be used to ensure events such as JOIN are always recorded.

WILLIE.FORMATTING

Availability: 4.5+

The formatting module includes functions to apply IRC formatting to text.

willie.formatting.CONTROL_BOLD = '\x02'
    The control code to start or end bold formatting

willie.formatting.CONTROL_COLOR = '\x03'
    The control code to start or end color formatting

willie.formatting.CONTROL_NORMAL = '\x0f'
    The control code to reset formatting

willie.formatting.CONTROL_UNDERLINE = '\x1f'
    The control code to start or end underlining

willie.formatting.bold(text)
    Return the text, with bold IRC formatting.

willie.formatting.color(text, fg=None, bg=None)
    Return the text, with the given colors applied in IRC formatting.

    The color can be a string of the color name, or an integer between 0 and 99. The known color names can be found in the colors class of this module.

class willie.formatting.colors

BLACK = '01'

BLUE = '02'

BROWN = '05'

CYAN = '11'

FUCHSIA = '13'

GREEN = '03'

GREY = '14'

LIGHT_BLUE = '12'

LIGHT_CYAN = '11'

LIGHT_GREEN = '09'

LIGHT_GREY = '15'

LIGHT_PURPLE = '13'

LIME = '09'

MAROON = '05'

NAVY = '02'

OLIVE = '07'

ORANGE = '07'

PINK = '13'

PURPLE = '06'

RED = '04'

ROYAL = '12'

SILVER = '15'

TEAL = '10'

WHITE = '00'

YELLOW = '08'

willie.formatting.underline(text)
    Return the text, with underline IRC formatting.

•   genindex

•   modindex

•   search

AUTHOR
E. Powell, et al.

COPYRIGHT
2012, E. Powell, et al.