Welcome to lala’s documentation!

Contents:

Installation

PyPI

Lala is available on the Python Package Index. This makes installing it with pip as easy as:

pip install lala

Git

If you want the latest code or even feel like contributing, the code is available on Github.

You can easily clone the code with git:

git clone git://github.com/mineo/lala.git

Now you can start hacking on the code or install it system-wide:

python2 setup.py install

Setup

Setting up the bot is relatively easy: Simply copy the supplied example config file from:

/usr/share/lala/config.example

to either:

/etc/lala.config

or:

$XDG_CONFIG_HOME/lala/config

or (if the latter is not set):

$HOME/.lala/config

After that, you can modify the config file as you wish.

Starting the bot

Starting the bot is very easy as it installs a twistd plugin:

twistd lala

For now, only a --verbose option is provided which makes the output written to the log file more verbose.

Additionally, twistd itself offers a few options, use:

twistd --help

to view them.

Updating

Some commits require a manual update of the SQLite databse used for the quotes.

The following is a list of those commits and the commands to run the update, where <sqlite-file> is the path to the quote database file. Newer commits appear first.

  • 410ccde58bf6f635b121c0a5349dce5fd643679a (part of release 0.4)

    sqlite3 <sqlite-file> misc/2-add-votes-to-quotes.sql

  • a602b32dfa8aeb0d89b18275fe9e371199f3fd7c (part of release 0.4)

    sqlite3 <sqlite-file> misc/1-add-id-columns.sql

  • 44f8b476a1e28af60b5e21704b5c1eafd2f9bb54 (part of release 0.3)

    sqlite3 <sqlite-file> misc/0-add-author-to-quotes.sql

Configuration file options

Both the basic configuration and the plugin configuration of Lala takes place in a central configuration file.

The basic options, which can be set in the base section, are:

  • server

    The server to connect to.

  • port

    The port on which the server listens.

  • nick

    The nick of the bot.

  • admins

    A comma-separated list of people allowed to issue admin-only commands (like reconnect or quit) to the bot.

  • nickserv_password

    Optional.

    The password which is used to identify with Nickserv.

  • channels

    Optional.

    A comma-separated list of channels which are joined automatically after connection to the server.

  • fallback_encoding

    Optional.

    Lala assumes all messages received are UTF-8 encoded. If that’s not the case, this is the second encoding to try.

  • plugins

    Optional.

    A comma-separated list of plugins to load at startup. The plugin “base” is always loaded, it contains basic commands like “help” and “reconnect”.

  • debug

    Optional.

    if “yes”, this has the same effect as specifying –verbose on the command line.

Plugins

Birthday Reminder

The birthday plugin is a simple birthday reminder. It will congratulate a user if he joins the first time on his birthday. It provides only one command:

  • my_birthday_is

    Sets the birthday of a user. Expects the date to be in the format %d.%m..

Options

  • None

Calendar

This plugin provides one command, weeknum, which simply echoes the current week number in the channel.

Options

  • None

Decide

This plugin provides one command, decide, which, given a list of options separated by a slash (/) chooses one of them.

Options

  • None

Downforeveryoneorjustme

This plugin provides a single command, isitdown that, given a URL checks its availability on Downforeveryoneorjustme.

Options

  • None

Feinstaubalarm

This plugin provides a single command, feinstaubalarm that checks if there’s currently a “Feinstaubalarm” in Stuttgart, Germany.

Options

  • None

Fortune

This plugin provides two commands, fortune and ofortune, both of which basically call the fortune command and post the result in the channel. In addition, ofortune supplies the -o option to fortune so that only offensive fortunes are chosen.

Options

  • fortune_files

    The fortune file(s) to use. Defaults to fortunes. This can be overridden when using either fortune or ofortune by adding the preferred fortune file after the command, like !fortune riddles.

  • fortune_path

    The full path to the fortune binary. Defaults to /usr/bin/fortune

HTTP Title

The httptitle plugin will print the <title> HTML element of every linked posted.

Options

  • None

Ilmenau weather

This plugin can be used to display information about the weather in Ilmenau, Germany.

It only provides one command:

  • iweather Displays weather information.

Options

  • None

Last Messages

The last plugin saves the last messages in memory. It provides a last command to retrieve them.

Options

  • max_lines
    The maximum number of lines to message upon the last command. Defaults to 30
  • datetime_format
    The format used to format the timestamps in the log. Have a look at the strftime documentation for all possible options. The default is %Y-%m-%d %H:%M:%S.

Chatlogger

The log plugin logs all received messages to a file.

Options

  • log_file
    The location of the log file.
  • max_log_days
    The number of days for which logs are kept. Set this to zero to keep them indefinitely.

Prometheus

The prompetheus plugin exposes metrics for Prometheus.

Options

  • port
    The port on which the web server exposes the metrics. Defaults to 9100.

Quotes

The quotes plugin can be used to capture quotes in a database. It will also print a quote containg the name of the joining person on every join.

It provides the following commands:

  • qadd <quote>

    Adds a new quote to the database

  • qdelete <quote id>

    Admin only.

    Deletes the quote with the specified ID.

  • qget <quote id>

    Get the quote with the specified ID.

  • qlast

    Get the last inserted quote.

  • qrandom

    Retrieve a random quote.

  • qdislike <quote id>

    Dislikes the quote.

  • qlike <quote id>

    Likes the quote.

  • qtop <limit>

    Shows the limit (default: max_quotes) quotes with the best rating.

  • qflop <limit>

    Shows the limit (default: max_quotes) quotes with the worst rating.

  • quotestats

    Display some stats about the quote database. This is currently limited to the total number of quotes and the percentage of quotes per author.

  • searchquote <text>

    Search for a quote containing text.

Options

  • database_path

    The path to the SQLite database file. Defaults to ~/.lala/quotes.sqlite3.

  • max_quotes

    The maximum number of quotes to print when using searchquote or qtop/qflop. Defaults to 5.

Roulette

The roulette plugin provides a basic version of Russian roulette with two commands:

  • shoot

    Shoots the revolver.

  • reload

    Reloads the revolver.

Options

  • None

API:

Lala IRC Bot

class lala.bot.Lala(*args, **kwargs)[source]

Bases: twisted.words.protocols.irc.IRCClient

action(user, channel, data)[source]

Called when a user performs an ACTION on a channel.

irc_RPL_WHOISREGNICK(prefix, params)[source]
joined(channel)[source]

Called after joining a channel.

lineRate = 1
modeChanged(user, channel, set, modes, args)[source]

The mode of a user has been changed. If it was added by Chanserv and the user is in the admin list, append him to identified_admins.

msg(channel, message, log, length=None)[source]

Sends message to channel.

Depending on log, the message will be logged or not.

Do not use this method from plugins, use lala.util.msg() instead.

nickname
noticed(user, channel, message)[source]

Same as lala.bot.Lala.privmsg() for NOTICEs.

privmsg(user, channel, message)[source]

Handles received messages.

signedOn()[source]

Called after a connection to the server has been established.

Joins all configured channels and identifies with Nickserv.

userJoined(user, channel)[source]

Handles join events.

userKicked(user, message)[source]
userLeft(user, channel)[source]
userQuit(user, message)[source]
versionName = 'lala'
versionNum = '0.5.dev125+gf14a51a'

Lala Config Module

Config module

Changed in version 0.5.

The function set_default_options was removed. To achieve the same behaviour, set a module-level dict called “DEFAULT_OPTIONS” where the keys are the option names and the values are the default values in your plugin.

lala.config.get(key, converter=None)[source]

Returns the value of a config option. The section is the name of the calling file.

Default values for all keys can be set with set_default_options().

Parameters:key – The key to lookup
lala.config.get_int(*args)[source]

Returns the value of a config option as an int.

Parameters:*args

See lala.config.get()

Return type:int
lala.config.get_list(*args)[source]

Gets a list option.

Parameters:*args

See lala.config.get()

Return type:list of strings
lala.config.set(key, value, plugin=None)[source]

Sets the value of key. The section is the name of the calling file.

lala.config.set_list(key, value, *args)[source]

Sets option key to value where value is a list of values.

None of the values in value are allowed to contain lala.config._LIST_SEPARATOR.

This method does not preserve the type of the items in the list, they’re all passed through str().

Parameters:
lala.config._LIST_SEPARATOR = ','

Used as a separator when storing lists of values in the config file

Lala utils

Helpers to be used with plugins

class lala.util.command(command=None, admin_only=False, aliases=None)[source]

Bases: object

Decorator to register a command. The name of the command is the __name__ attribute of the decorated function. Example:

@command
def heyiamacommand(user, channel, text):
    pass

You can also pass a command parameter to overwrite the name of the command:

@command(command="yetanothercommand")
def command_with_a_really_stupid_or_insanely_long_name(user,
channel, text):
    pass

aliases can be a list of names under which the function will be available in addition to its primary name.

An additional argument, admin_only can be used to make a function available to admins only:

@command(admin_only=True)
def give_me_the_one_ring(user, channel, text):
    pass

New in version 0.5.

If the function returns a twisted.internet.defer.Deferred or a generator function that’s generating them, an Errback will automatically be added to the Deferred(s).

Changed in version 0.5.

The third argument received by a command function used to include the name of the command itself. Since version 0.5 this is no longer the case.

lala.util.msg(target, message, log=True)[source]

Send a message to a target.

Parameters:
  • target (str) – Target to send the message to. Can be a channel or user
  • message (str or [str]) – One or more messages to send
  • log (bool) – Whether or not to log the message
lala.util.on_join(f)[source]

Decorator for functions reacting to joins

Parameters:f – The function which should be called on joins.
class lala.util.regex(regex)[source]

Bases: object

Decorator to register a regex. Example:

@regex("(https?://.+)\s?")
def somefunc(user, channel, text, match_obj):
    pass

match_obj is a re.MatchObject.

Parameters:regex – A re.RegexObject or a string representing a regular expression.
lala.pluginmanager.disable(trigger)[source]

Disables trigger.

Parameters:trigger (str) – The trigger to disable. Can be a key for a callback or a regular expression
lala.pluginmanager.enable(trigger)[source]

Enables trigger.

Parameters:trigger (str) – The trigger to enable. Can be a key for a callback or a regular expression
lala.pluginmanager.is_admin(user)[source]

Check whether user is an admin.

If a nickserv password is set, this will work by checking an internal list of identified admins.

If no nickserv password is set, this simply checks if user is in the “admins” option of the “base” section.

class lala.pluginmanager.PluginFunc(func, enabled=True, admin_only=False, aliases=None)[source]

Bases: object

lala.pluginmanager.load_plugin(name)[source]

Indices and tables