Skip to content

๐Ÿ›ฉ A python IRC bot with simple plugins dev. Ignited in mauritius, first-timers friendly!

License

Notifications You must be signed in to change notification settings

pyhoneybot/honeybot

Repository files navigation

๐Ÿฏ honeybot py [ docs ]

PyPI version First Timers Only Open Source Love Made in Moris CII Best Practices OpenSSF Scorecard


๐Ÿ‡ฒ๐Ÿ‡บ ๐Ÿ‡บ๐Ÿ‡ธ ๐Ÿ‡จ๐Ÿ‡ฆ ๐Ÿ‡ฆ๐Ÿ‡ท ๐Ÿ‡ฎ๐Ÿ‡ณ ๐Ÿ‡ฌ๐Ÿ‡ง ๐Ÿ‡ฌ๐Ÿ‡ฌ ๐Ÿ‡ง๐Ÿ‡ท ๐Ÿ‡ธ๐Ÿ‡ฝ ๐Ÿ‡ต๐Ÿ‡ฑ ๐Ÿ‡ฉ๐Ÿ‡ช ๐Ÿ‡ฒ๐Ÿ‡ผ ๐Ÿ‡ฒ๐Ÿ‡ฆ

Open Source Helpers Discord

Table of Contents

๐Ÿ“ฎ About

HoneyBot is a python-based IRC bot. (python3.7) | If you want to just run the bot, go to the quick start section

HoneyBot is my first time collaborating to an open source project and I'm loving it. Before discovering HoneyBot, I was very intimidated on the idea of working with other people and had no idea what an IRC even was. Now I realize how much fun and rewarding it is to work together on a project with dedicated and friendly individuals. The documentation is easy to follow and everyone is super helpful. I highly recommend any new programmer who want to contribute on an open source project to try out HoneyBot. Personally I enjoy working on this project more than my own schoolwork. --@RiceAbove

Feel free to contribute to the project!

๐Ÿ•น Project Motivation

Implementing the project in Java was weird, py's connect was sleek. Thus, the project stack was shifted over to Python. If you can think of any features, plugins, or functionality you wish to see in the project. Feel free to add it yourself, or create an issue detailing your ideas. We highly recommend you attempt to implement it yourself first and ask for help in our discord server !

Psst. Since I learnt py through this bot, we decided to keep a new-comers friendly policy. Feeling lost? Just ping.

โœ‚ Current Features

  • ๐Ÿฌ OOP architecture
  • ๐Ÿ›ฐ๏ธ keyword parameters
  • ๐ŸŒต password security with config file [disabled for now]
  • ๐Ÿ”Œ now with plugins

โ›ฐ๏ธ GUI clients

GUI clients are used to manage plugins, launch bot as well as specify credentials.

โŒš Current Plugins

Plugin Description Contributor
๐Ÿ’Ž bitcoin Get price of bitcoin @Macr0Nerd
โฒ caesar cipher Encode your text @kylegalloway
๐Ÿ”ข calc Evaluates maths expressions @Abdur-rahmaanJ
๐Ÿ“ maths Trigonometry & random number generator @Abdur-rahmaanJ
๐Ÿƒ conv sniff Set triggers like how many times a word occur for one or more words and send response @Abdur-rahmaanJ
โ„ greet Demo plugin @Abdur-rahmaanJ
โ›“ installed_modules Checks dependencies installed @Abdur-rahmaanJ
๐Ÿ•ถ joke Get random joke @Abdur-rahmaanJ, @colbyjayallen
โ“ self Trivia Random trivia @ajimenezUCLA
๐Ÿ’ข username Username generator @Abdur-rahmaanJ, @sseryani
๐Ÿ“œ quotes Inspirational quotes @German-Corpaz
๐Ÿ“– dictionary Returns meaning of word @iamnishant14
๐Ÿ”ฃ password generator The name tells it all @iamnishant14
๐Ÿœ debug Prints all parameters passed to bot @Abdur-rahmaanJ
๐Ÿ“š wikipedia Returns a wikipedia article @Macr0Nerd
๐Ÿ—ฟ translate Google translate plugin @a-deeb
๐Ÿ“‘ test Runs tests @Abdur-rahmaanJ
โ›…๏ธ weather Returns weather info for a given location @Macr0Nerd
โœ‰๏ธ mail Send emails within the chat @TannerFry
๐Ÿ•ด๏ธ hangman Play hangman in the chat @JustinWalker4179
๐ŸŽ‚ age Takes in birthday and outputs age @JustinWalker4179
โœ”๏ธ fact Returns a random fact @JustinWalker4179
๐Ÿ” google Returns three search results from google @JustinWalker4179
๐Ÿ“ฎ send message Sends a message to another channel @JustinWalker4179
๐Ÿ“ log Logs the chat into a log file @RiceAbove
๐Ÿšช joins Greets everyone who joins the channel @RiceAbove
๐Ÿ“… date Posts the current date @RiceAbove
๐Ÿ•ต๏ธโ€ riddle Returns a random riddle @AngeloGiacco
๐Ÿ—ž news Gets the top 10 headlines from bbc world news @AngeloGiacco
๐Ÿ“ horoscope Gets your daily horoscope for your starsign @AngeloGiacco
๐Ÿ’ต currency converter Converts currencies @AngeloGiacco
๐Ÿ”ซ russian_roulette May or may not kick you off the channel @AngeloGiacco
๐Ÿจ monopoly Honeybot now supports the world's worst game! @AngeloGiacco
โšฝ๏ธ transfer_rumour Shows the day's transfer rumours @AngeloGiacco
๐Ÿƒ blackjack/21 Play 21 on honeybot! @AngeloGiacco
๐Ÿค’ corona Get the latest news on coronavirus with honeybot! @AngeloGiacco
๐Ÿ“– diary Keep a diary with honeybot @AngeloGiacco
๐Ÿ›ฉ flight Gets flight info from flightradar24 @AngeloGiacco
๐ŸŽฒ roll Rolls a dice @GlennToms
โ“ help Show link to plugin's information page @edumello
โœ… channeljoin Join command for bot @marceloyb
๐Ÿ“ƒ comic Returns a random comic @mboekhold
๐Ÿ“ todo Makes a to do list @h-ranjan1110
๐ŸŽฑ Magic 8 Ball Answer questions using magic 8 ball @ZakariaTalhami
๐ŸŽŸ Random Excuse Generates a random excuse for you. @rakeshseal0
๐Ÿฆ† DuckDuckGo Search Search queries in duckduckgo and return abstract. @rakeshseal0
๐Ÿ–ผ Random Image Returns a random image url. @rakeshseal0
๐Ÿ›ข URL Shortener Shortens a url @rakeshseal0
๐Ÿ˜ emoji Returns emoji meaning @deadex-ng
๐ŸŽ‚ birthday Shows birthday match probability on a people group. @paulosgf
๐Ÿ€ basketball Shows information about the medals of euroBasket and Basketball world cup @kefthymic
๐ŸŽฌ movies_imdb Returns certain information about a certain movie or shows 250 all time best movies @ZoeyKats
โ›ฉ๏ธ anime Returns certain information about the top 100 anime @cdkontos

โšก Quickstart

setup

mkdir botx
cd botx
python -m venv venv
venv\scripts\activate # or source venv/bin/activate for linux
python -m pip install honeybot

run

honeybot init
honeybot run

in settings/settings.toml

[INFO]

server_url = irc.libera.chat
port = 6667
name = appinventormuBot

In settings/settings.toml listed plugins under PLUGINS/downloaded will load. Plugins in directory plugins/core are auto loaded.

๐Ÿ’ป Seeing The Bot In Action

Get an IRC client

configure

port: 6667
url: irc.libera.chat

then join channel #ltch

you should see the bot as hbot ... or as it's name is in settings

Docker

Building Docker image

Change SERVER, PORT and NICKNAME variables to match your preferences

docker build -t "honeybot/honeybot:6.0.2" .

Running Docker image

docker run -d --name=honeybot honeybot/honeybot:v6.0.2 honeybot run

๐Ÿ”ง Plugins Development

Each plugin has a folder named after it. In it there is a file called main.py. In each there is a class called Plugin.

# -*- coding: utf-8 -*-

class Plugin:
    def __init__(self):
        pass

    def run(self, incoming, methods, info, bot_info):
        try:
            if info['command'] == 'PRIVMSG' and info['args'][1] == '.hi':
                methods['send'](info['address'], 'hooo')
        except Exception as e:
            print('woops plugin error ', e)

we see four parameters being passed to the run method , incoming, methods, info, bot_info)

parameter1: incoming

incoming is the raw line and is not used except if you are not satisfied with the already provided methods

parameter2: methods

methods is a dictionary of methods to ease your life. a quick look at main.py reveals

def methods(self):
        return {
                'send_raw': self.send,
                'send': self.send_target,
                'join': self.join
                }

where send_raw allows you to send in any string you want, thereby allowing you to implement any irc protocol from scratch

but, for most uses, send allows you to send a message to an address methods['send']('<address>', '<message>'). using it in conjunction with info parameter allows you to send messages where it came from, in pm to the bot or in a channel. you can however hardcode the address.

join allows you to join a channel by methods['join']('<channel name>')

parameter3: info (meaning message info)

for a normal run, info produces

{
'prefix': 'appinv!c5e342c5@gateway/web/cgi-irc/kiwiirc.com/ip.200.200.22.200',
'command': 'PRIVMSG',
'address': '##bottestingmu',
'args': ['##bottestingmu', 'ef']
}

hence if you want messages, messages = info['args'][1:] or the first word if you want to check for command will be info['args'][1]

use example

  • the command info is used in the join channel plugin to detect a join command and greet the user who just joined

bot info

bot_info returns info about the bot

        return {
            'name': self.name,
            'special_command': self.sp_command,
            'required_modules': self.required_modules,
            'owners': self.owners,
            'time': self.time,
            'friends': self.friends
        }

so that in run method you can access those.

use example

  • For example, the time info is used in the uptime plugin by minussing it from the current time to get time bot has been running.
  • The required modules is used in the installed plugin to determine what required plugin the bot runner did not install

wrapping up

hence

if info['command'] == 'PRIVMSG' and info['args'][1] == '.hi':
    methods['send'](info['address'], 'hooo')

from above means

if message received == .hi:
    send(address, message)

๐Ÿ“ƒ Contributing Guide

https://pyhoneybot.github.io/honeybot/How_Tos/contributing.html

  • don't forget to add your country flag here after accepted PR. i'll have to hunt it down on your profile if not.
  • make sure to follow PEP8

Check out Contributing to get started on contributing.

๐Ÿ”Œ Todo Plugins

  • ๐Ÿ’ humour
  • ๐ŸŒจ๏ธ weather
  • โœ‰๏ธ mail
  • ๐ŸŽ›๏ธ maths
  • ๐Ÿ“ฅ pm when user online
  • Random Colour

โ˜‘ Allowing Plugins

Plugins available https://pyhoneybot.github.io/honeybot/plugins.html

in settings/settings.toml, add the plugin to allow!

[PLUGINS]

downloaded = ["greet",] # Downloaded plugins to load

๐Ÿ“ง Contact (Including vulnerabilities)

Email

๐Ÿ–Š Credits

  • @arwinneil, "Open Source" and "Made In Moris" badges