irc3. pluggable irc client library based on python’s asyncio

https://travis-ci.org/gawel/irc3.png?branch=master https://coveralls.io/repos/gawel/irc3/badge.png?branch=master

A pluggable irc client library based on python’s asyncio.

Ceative Commons – Attribution (CC BY 3.0) - Hydra designed by Huu Nguyen from the Noun Project - http://thenounproject.com/term/hydra/46963/

Requires python 3.5+

Python 2 is no longer supported, but if you don’t have a choice you can use an older version:

$ pip install "irc3<0.9"

Source: https://github.com/gawel/irc3/

Docs: https://irc3.readthedocs.io/

Irc: irc://irc.freenode.net/irc3 (www)

I’ve spent hours writing this software, with love. Please consider tipping if you like it:

BTC: 1PruQAwByDndFZ7vTeJhyWefAghaZx9RZg

ETH: 0xb6418036d8E06c60C4D91c17d72Df6e1e5b15CE6

LTC: LY6CdZcDbxnBX9GFBJ45TqVj8NykBBqsmT

Installation

Using pip:

$ pip install irc3

Quick start

irc3 provides a basic template to help you to quickly test a bot. Here is how to create a bot named mybot.

Create a new directory and cd to it:

$ mkdir mybot
$ cd mybot

Then use the template:

$ python -m irc3.template mybot

This will create an almost ready to use config.ini file and a simple plugin named mybot_plugin.py that says «Hi» when the bot or someone else joins a channel and includes an echo command.

Here is what the config file will looks like:

[bot]
nick = mybot
username = mybot

host = localhost
port = 6667

# uncomment this if you want ssl support
# ssl = true
# uncomment this if you don't want to check the certificate
# ssl_verify = CERT_NONE

# uncomment this if you want to use sasl authentication
# sasl_username = mybot
# sasl_password = yourpassword

includes =
    irc3.plugins.command
#    irc3.plugins.uptime
#    irc3.plugins.ctcp
    mybot_plugin

# the bot will join #mybot_channel
# ${#} is replaced by the # char
autojoins =
    ${#}mybot_channel

# Autojoin delay, disabled by default
# float or int value
# autojoin_delay = 3.1

# The maximum amount of lines irc3 sends at once.
# Default to 4, set to 0 to disable
# flood_burst = 10

# The number of lines per $flood_rate_delay seconds irc3 sends after reaching
# the $flood_burst limit.
# Default to 1
# flood_rate = 2

# The bot will send $flood_rate messages per $flood_rate_delay seconds
# Default to 1
# flood_rate_delay = 5

[irc3.plugins.command]
# command plugin configuration

# set command char
cmd = !

# set guard policy
guard = irc3.plugins.command.mask_based_policy

[irc3.plugins.command.masks]
# this section is used by the guard to secure the bot's command
# change your nickname and uncomment the line below
# mynick!*@* = all_permissions
* = view

And here is the plugin:

# -*- coding: utf-8 -*-
from irc3.plugins.command import command
import irc3


@irc3.plugin
class Plugin:

    def __init__(self, bot):
        self.bot = bot

    @irc3.event(irc3.rfc.JOIN)
    def say_hi(self, mask, channel, **kw):
        """Say hi when someone join a channel"""
        if mask.nick != self.bot.nick:
            self.bot.privmsg(channel, 'Hi %s!' % mask.nick)
        else:
            self.bot.privmsg(channel, 'Hi!')

    @command(permission='view')
    def echo(self, mask, target, args):
        """Echo

            %%echo <message>...
        """
        yield ' '.join(args['<message>'])

Have a look at those file and edit the config file for your needs. You may have to edit:

  • the autojoin channel
  • your irc mask in the irc3.plugins.command.mask section

Once you’re done with editing, run:

$ irc3 config.ini

Check the help of the irc3 command.

$ irc3 -h

If you’re enjoying it, you can check for more detailed docs below. And some more examples here: https://github.com/gawel/irc3/tree/master/examples

Indices and tables