Skip to main content

A miniirc-based IRC bot.

Project description


lurklite

Available on PyPI. License: AGPLv3

luk3yx's "lightweight™" IRC and Discord bot (excluding commands).

Official bot

If you can't or don't want to run your own bot, you can request that the official bot be added to your channel.

The official bot is available on the following IRC networks (PM luk3yx on any of them):

  • EdgyIRC: lurk
  • Freenode: lurk` (or lurk3)
  • xeroxIRC: lurk (or lurklite)

Alternatively, if you use Discord, you can use https://bit.ly/lurkdiscord to add lurklite (without any permissions) to your Discord guild/server.

Installation

To install lurklite, you can simply install it with pip (sudo pip3 install miniirc on most GNU/Linux distributions). After installation, you should be able to run lurklite (or python3 -m lurklite).

Config file

The lurklite config file has a format similar to ini files. It must have a [core] section with the following values:

[core]
# The tempcmd db, commands added with .tempcmd are stored here.
# If you have msgpack installed, this database will be slightly smaller and
#   faster to read/write to/from.
command_db = /path/to/tempcmd/database

# The bot's command prefix.
prefix     = .

# (Optional) A list of hostmasks to ignore.
# ignored  = *!*@*/bot/*, baduser!*@*

# (Optional) Disable "Yay!" and "Ouch." replies.
# disable_yay  = false
# disable_ouch = false

Connecting to IRC servers

You can then create sections starting with irc. (for example irc.freenode) to connect to IRC servers:

[irc.freenode]
ip   = chat.freenode.net
port = 6697
nick = testbot
channels = #botwar,#other-channel

# List of hostmasks to ignore (optional)
# ignored = *!*@*/bot/*, *!*sopel*@*

# List of hostmasks for admins
# admins = *!*@unaffiliated/user

The following optional values may be added to the above config, and are sent directly to miniirc:

connect_modes = +g
ident         = ident
ns_identity   = username password
quit_message  = Quit message
realname      = realname
ssl           = true

Connecting to Discord servers

You can also connect to Discord servers (via miniirc_discord) with the following config section:

[discord]
# You need miniirc_discord installed for this to work.
token    = your-discord-token

# admins = userid#1234

You can only have one Discord connection per bot process, and lurklite will use slightly more RAM if [discord] exists, as miniirc_discord will be imported (and if you don't specify a Discord bot token, miniirc_discord won't be imported).

Creating commands

Once your bot has connected to IRC (or Discord), you can use tempcmd to create (permanent) commands. You can either do .tempcmd <command> <type> <code> to add a tempcmd with a set type, or .tempcmd <command> <code> to auto-detect the type (as long as the first word in <code> is not a valid type).

For now, tempcmds.py has a list of code types/formats and what they do.

To delete commands, you can use tempcmd del/delete/remove <command>. To create a command called del, delete or remove, you can prepend your bot's prefix to the command name.

Creating non-"tempcmd" commands

If you want more fine-grained control over a command, you can add a custom_cmds line to the [core] section of config.ini. The file specified will be loaded and can define more powerful commands, for example:

# A simple version command
# The "requires_admin" parameter is optional and defaults to False.
@register_command('version', requires_admin = False)
def version_command(irc, hostmask, is_admin, args):
    # irc: The miniirc.IRC (or miniirc_discord.Discord) object.
    # hostmask: The hostmask tuple, mostly from miniirc. Note that relayed
    #   messages (for example "<relayed_user> test") will have a hostmask
    #   similar to ('relayed_user@relay_bot', 'relay_bot_ident',
    #       'relay.bot.host/relayed/relayed_user').
    # is_admin: Either `False` or a string with the admin match (for example
    #   a hostmask or Discord tag.
    # args: ["#channel", "command parameters"]
    #   For PMs, "#channel" will be the sender (hostmask[0]).

    irc.msg(args[0], miniirc.version)

You do not have to import anything to get register_command.

If custom_cmds is a directory, all .py files in that directory will be loaded. If you want your custom commands file/directory in lurklite's source directory, you can name it custom_cmds.py (or, for directories, custom_cmds or commands) to make git ignore it.

Built-in commands

lurklite has the following built-in commands:

  • reboot: Reboot the bot.
  • tempcmd: Create and delete commands.
  • version: Display the miniirc version and quit.

Migrating from older versions of lurklite

Older versions of lurklite (pre-v0.1.0) had a tempcmds.db created using repr(). This is slow(-ish) and inefficient, so is no longer supported. If you still have a pre-v0.1.0 tempcmds.db, you can run lurklite/tempcmds_migrate.py to update it to the new msgpack/JSON format.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lurklite-0.4.3.tar.gz (12.1 kB view hashes)

Uploaded Source

Built Distribution

lurklite-0.4.3-py3-none-any.whl (25.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page