How to write a custom plugin for Cardinal?

Create a Python class using decorators like @command for IRC commands, and define an entrypoint. Refer to the wiki for detailed examples on event handling and database access, as shown in the basic plugin snippet.

Cardinal vs Sopel for IRC bots – which is better?

Cardinal focuses on ease of development with hot-reloadable plugins and decorators, ideal for rapid prototyping. Sopel has a larger plugin ecosystem but a more traditional configuration-based approach; choose Cardinal for a Python-centric, decorator-driven workflow.

Can I run Cardinal without Docker?

The README specifies Docker-based deployment for simplicity, but since it's a Python application, you might run it manually with Twisted installed, though this requires more setup and is not officially supported.

How to handle persistent data in Cardinal plugins?

Use the built-in database API for simple JSON storage, documented in the wiki. For advanced needs, you can extend plugins to use external databases, but the default solution is lightweight and easy to use.

What IRC networks does Cardinal support?

Cardinal works with any standard IRC network; configure server details in the JSON config file, as outlined in the basic usage section, and it supports SSL connections like on the DarkScience network.

How to add admin commands in Cardinal?

Configure the admin plugin by editing its config.json with your nick and vhost, then use decorators to define commands with permission checks, allowing for bot management without restarting.

Open-Awesome

Cardinal

MITPythonv3.4.0

A Python IRC bot with reloadable async plugins, decorator-based commands, and simple JSON storage.

GitHub

104 stars40 forks0 contributors

What is Cardinal?

Cardinal is a Python-based IRC bot built on the Twisted framework, designed to simplify adding custom functionality to IRC channels. It solves the problem of complex bot development by providing reloadable asynchronous plugins, decorator-based command definitions, and easy persistent storage.

Target Audience

Developers and hobbyists looking to create or extend IRC bots with custom features, especially those familiar with Python and interested in chat automation.

Value Proposition

Developers choose Cardinal for its focus on ease of development, with features like hot-reloadable plugins and a clean decorator API that reduce boilerplate and accelerate iteration.

Overview

A Python IRC bot, designed to make adding functionality quick and simple. (est. 2013)

Use Cases

Best For

Adding custom commands and automation to IRC channels
Building modular IRC bots with hot-reloadable plugins
Prototyping chat-based tools using Python decorators
Integrating external APIs (e.g., weather, Wikipedia) into IRC
Creating persistent data storage for IRC bot state
Learning IRC bot development with a well-documented Python framework

Not Ideal For

Projects targeting modern chat platforms like Discord or Slack, as Cardinal is specifically designed for IRC and lacks built-in support for other protocols.
Teams wanting a graphical interface for bot management and monitoring, since Cardinal relies on configuration files and command-line tools without a web dashboard.
Applications requiring serverless deployment or easy cloud integration, due to its Docker-based setup which adds infrastructure complexity.

Pros & Cons

Pros

Hot-Reloadable Plugins

Plugins can be reloaded on the fly without restarting the bot, enabling rapid iteration and testing during development, as emphasized in the key features.

Decorator-Based Commands

Uses Python decorators to define IRC commands and event handlers, making code clean and intuitive, as shown in the example plugin snippet with @command and @help decorators.

Comprehensive Documentation

Features a well-documented API with wiki pages for methods, events, and plugin development, providing clear guidance for extending functionality.

Built-in Example Plugins

Includes ready-to-use plugins for common tasks like URL title fetching and weather reports, reducing initial setup time and serving as practical learning resources.

Cons

Docker Dependency

Requires Docker and docker-compose for running, which adds overhead and can be a barrier for developers not familiar with containerization, as specified in the basic usage.

IRC Protocol Limitation

Exclusively supports IRC, so it cannot be easily adapted to other chat platforms without significant code changes, limiting its versatility for broader automation needs.

Twisted Learning Curve

Built on the Twisted asynchronous framework, which has a steeper learning curve compared to modern Python async libraries, potentially challenging for newcomers.

Simple Storage Limitations

Uses lightweight JSON storage via a documented API, but this may not scale well for high-volume data or complex queries compared to dedicated databases.

Frequently Asked Questions

Related Projects

Wayback

An archiving tool with an IM-style interface that prioritizes privacy and accessibility, integrated with various archival services including Internet Archive, archive.today, Ghostarchive, IPFS, Telegraph, and file systems.

Stars2,220

Forks86

Last commit2 days ago

Limnoria

A robust, full-featured, and user/programmer-friendly Python IRC bot, with many existing plugins.

Twitch IRC bot that takes input from the chat and presses the corresponding key.

Stars275

Forks55

Last commit12 years ago

Skybot

Python IRC bot

Stars248

Forks171

Last commit7 days ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub