pydle 1.1.0

A compact, flexible, and standards-abiding IRC library for python3.

pydle

Python IRC library.

pydle is a compact, flexible and standards-abiding IRC library for Python 3.10+.

Features

• Well-organized: Thanks to the modularized feature system, it's not hard to find what you're looking for in the well-organised source code.
• Standards-abiding: Based on RFC1459 with some small extension tweaks, with full support of optional extension standards:
  • TLS
  • CTCP
  • (coming soon) DCC and extensions
  • ISUPPORT/PROTOCTL
  • IRCv3.1 (full)
  • IRCv3.2 (base complete, most optional extensions)
  • IRCv3.3 (base in progress)
• Asynchronous: IRC is an asynchronous protocol and so should be a library that implements it. Coroutines are used to process events from the server asynchronously.
• Modularised and extensible: Features on top of RFC1459 are implemented as separate modules for a user to pick and choose, and write their own. Broad features are written to be as extensible as possible.
• Liberally licensed: The 3-clause BSD license ensures you can use it everywhere.

Basic Usage

pip install pydle

From there, you can import pydle and subclass pydle.Client for your own functionality.

To enable SSL support, install the sasl extra. pip install pydle[sasl]

Setting a nickname and starting a connection over TLS:

import pydle

# Simple echo bot.
class MyOwnBot(pydle.Client):
    async def on_connect(self):
         await self.join('#bottest')

    async def on_message(self, target, source, message):
         # don't respond to our own messages, as this leads to a positive feedback loop
         if source != self.nickname:
            await self.message(target, message)

client = MyOwnBot('MyBot', realname='My Bot')
client.run('irc.rizon.net', tls=True, tls_verify=False)

But wait, I want to handle multiple clients!

No worries! Use pydle.ClientPool like such:

pool = pydle.ClientPool()
for i in range(10):
    client = MyOwnBot('MyBot' + str(i))
    pool.connect(client, 'irc.rizon.net', 6697, tls=True, tls_verify=False)

# This will make sure all clients are treated in a fair way priority-wise.
pool.handle_forever()

Furthermore, since pydle is simply asyncio-based, you can run the client in your own event loop, like this:

import asyncio

client = MyOwnBot('MyBot')
asyncio.run(client.connect('irc.rizon.net', tls=True, tls_verify=False))

Customization

If you want to customize bot features, you can subclass pydle.BasicClient and one or more features from pydle.features or your own feature classes, like such:

# Only support RFC1459 (+small features), CTCP and our own ACME extension to IRC.
class MyFeaturedBot(pydle.features.ctcp.CTCPSupport, acme.ACMESupport, rfc1459.RFC1459Support):
    pass

To create your own features, just subclass from pydle.BasicClient and start adding callbacks for IRC messages:

# Support custom ACME extension.
class ACMESupport(pydle.BasicClient):
    async def on_raw_999(self, source, params):
        """ ACME's custom 999 numeric tells us to change our nickname. """
        nickname = params[0]
        await self.set_nickname(nickname)

FAQ

Q: When constructing my own client class from several base classes, I get the following error: TypeError: Cannot create a consistent method resolution order (MRO) for bases X, Y, Z. What causes this and how can I solve it?

Pydle's use of class inheritance as a feature model may cause method resolution order conflicts if a feature inherits from a different feature, while a class inherits from both the original feature and the inheriting feature. To solve such problem, pydle offers a featurize function that will automatically put all classes in the right order and create an appropriate base class:

# Purposely mis-ordered base classes, as SASLSupport inherits from CapabilityNegotiationSupport, but everything works fine.
MyBase = pydle.featurize(pydle.features.CapabilityNegotiationSupport, pydle.features.SASLSupport)
class Client(MyBase):
    pass

Q: How do I...?

Stop! Read the documentation first. If you're still in need of support, please raise a new issue in this repository! Also, we are on IRC! We hang at #pydle on irc.libera.chat. If someone is around, they'll most likely gladly help you.

License

Pydle is licensed under the 3-clause BSD license. See LICENSE.md for details.