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 eitherfortune
orofortune
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
orqtop
/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
-
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 toidentified_admins
.
-
msg
(channel, message, log, length=None)[source]¶ Sends
message
tochannel
.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.
-
signedOn
()[source]¶ Called after a connection to the server has been established.
Joins all configured channels and identifies with Nickserv.
-
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 – Return type: int
-
lala.config.
get_list
(*args)[source]¶ Gets a list option.
Parameters: *args – Return type: list of strings
-
lala.config.
set
(key, value, plugin=None)[source]¶ Sets the
value
ofkey
. The section is the name of the calling file.
-
lala.config.
set_list
(key, value, *args)[source]¶ Sets option
key
tovalue
wherevalue
is a list of values.None of the values in
value
are allowed to containlala.config._LIST_SEPARATOR
.This method does not preserve the type of the items in the list, they’re all passed through
str()
.Parameters: - key – See
lala.config.set()
- value – A list of values for
key
.
- key – See
-
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.
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 are.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.
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line