Skip to main content

asyncio-based rfc2812-compliant IRC Client

Project description

https://readthedocs.org/projects/bottom-docs/badge?style=flat-square https://img.shields.io/travis/numberoverzero/bottom/master.svg?style=flat-square https://img.shields.io/pypi/v/bottom.svg?style=flat-square https://img.shields.io/github/issues-raw/numberoverzero/bottom.svg?style=flat-square https://img.shields.io/pypi/l/bottom.svg?style=flat-square

asyncio-based rfc2812-compliant IRC Client (3.8+)

bottom isn’t a kitchen-sink library. Instead, it provides a consistent API with a small surface area, tuned for performance and ease of extension. Similar to the routing style of bottle.py, hooking into events is one line.

Installation

pip install bottom

Getting Started

(the full documentation is available here: http://bottom-docs.readthedocs.io/)

Create an instance:

import asyncio
import bottom

host = 'chat.freenode.net'
port = 6697
ssl = True

NICK = "bottom-bot"
CHANNEL = "#bottom-dev"

bot = bottom.Client(host=host, port=port, ssl=ssl)

Send nick/user/join when connection is established:

@bot.on('CLIENT_CONNECT')
async def connect(**kwargs):
    bot.send('NICK', nick=NICK)
    bot.send('USER', user=NICK,
             realname='https://github.com/numberoverzero/bottom')

    # Don't try to join channels until the server has
    # sent the MOTD, or signaled that there's no MOTD.
    done, pending = await asyncio.wait(
        [bot.wait("RPL_ENDOFMOTD"),
         bot.wait("ERR_NOMOTD")],
        loop=bot.loop,
        return_when=asyncio.FIRST_COMPLETED
    )

    # Cancel whichever waiter's event didn't come in.
    for future in pending:
        future.cancel()

    bot.send('JOIN', channel=CHANNEL)

Respond to ping:

@bot.on('PING')
def keepalive(message, **kwargs):
    bot.send('PONG', message=message)

Echo messages (channel and direct):

@bot.on('PRIVMSG')
def message(nick, target, message, **kwargs):
    """ Echo all messages """
    # don't echo self
    if nick == NICK: return
    # respond directly
    if target == NICK: target = nick
    bot.send("PRIVMSG", target=target, message=message)

Connect and run the bot forever:

bot.loop.create_task(bot.connect())
bot.loop.run_forever()

API

The full API consists of 1 class, with 8 methods:

# manage connections

async Client.connect()
async Client.disconnect()

# send, receive, and wait for rfc-2812 messages

Client.send(command, **kwargs)
@Client.on(event)
Client.trigger(event, **kwargs)
async Client.wait(event)

# send and receive anything newline-terminated,
# provided for eg. IRCv3 extensions

Client.send_raw(message)
Client.handle_raw(message)

Contributors

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

bottom-2.2.0.tar.gz (14.0 kB view hashes)

Uploaded Source

Built Distribution

bottom-2.2.0-py2.py3-none-any.whl (13.6 kB view hashes)

Uploaded Python 2 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