honeybot 6.0.2

IRC bot with vast collection of plugins. First timers friendly

🍯 honeybot py [ docs ]

Launching pyhoneybot Rewards

Contributed to pyhoneybot? Here is a big thank you from our community to you. Claim your badge and showcase them with pride. Let us inspire more folks !

Claim Now!

---

🇲🇺 🇺🇸 🇨🇦 🇦🇷 🇮🇳 🇬🇧 🇬🇬 🇧🇷 🇸🇽 🇵🇱 🇩🇪

📮 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

:mountain: GUI clients

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

• CPP client by @Macr0Nerd

⌚ 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
:page_with_curl: 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

⚡ 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/CONNECT.conf

[INFO]

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

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

💻 Seeing The Bot In Action

Get an IRC client

• Web: Kiwiirc (easy)
• Desktop: Hexchat
• Android: Revolution IRC

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 -f ./docker/Dockerfile .

** Running Docker image **

docker run honeybot

🔧 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

About PR

first clone the project

git clone https://github.com/pyhoneybot/honeybot.git

cd into the project

cd honeybot

create a virtualenv to work with different python \ libs versions

python -m venv venv
source venv/bin/activate

install the tools needed to make the constraint checks

pip install black isort bandit pre-commit
pre-commit install

different changes to different files. for example, someone making a weather plugin first he creates a new branch

git checkout -b "weather-plugin"

test if all files are well formatted, complying with style and security rules, before send the PR

black --check --verbose --config ./pyproject.toml src/honeybot/plugins/downloaded/weather/main.py
isort --check-only --settings-path ./pyproject.toml src/honeybot/plugins/downloaded/weather/main.py
bandit -ll -c ./pyproject.toml -r src/honeybot/plugins/downloaded/weather/main.py 

then he commits

git add *
git commit -m "added weather plugin"

or

git commit -a -m "did this"

then he push to create a PR with the branch

git push origin head

or

git push origin weather-plugin

now let us say he wants to work on another issue, adding a joke in the jokes plugin, he creates another branch

git checkout -b "add-jokes"

after, same as before

git add *
git commit -m "added some jokes"
git push origin head

now he wants to fix his weather plugin, he changes branch

git checkout weather-plugin

works, then commit

git add *
git commit -m "fixed <issue>"

then a PR

git push origin head

Why all these?

So as not to reject a whole PR just because of some oddities. Reject only unneeded part.

Updating the Documentation

If you created a new plugin you should add your plugin to the documentation. To do this, go into your cloned honeybot repo and then into the directory docs/source/Plugins . Depending on the type of plugin write this into the development, fun, miscellaneous or utility RST file:

   <Plugin-Name>
   ^^^^^^^^^^^^^
   .. automodule:: plugins.<your-plugin-filename>
      :members:

This allows sphinx to automatically pull the docstrings from the code of your plugin and parse them accordingly.

A small guide on how to further contribute to the documentation of the project can be found here

🥄 Updating fork

Now, other changes are ongoing, what if you need the latest changes?

git pull origin master

helps if you cloned your own repo. What if you want to update your local copy of someone else's repo that you forked? You do it like that

cd <your/local/cloned/repo/path/here>
git remote add upstream https://github.com/pyhoneybot/honeybot.git
git fetch upstream
git pull upstream master

🔌 Todo Plugins

• 💐 humour
• 🌨️ weather
• ✉️ mail
• 🎛️ maths
• 📥 pm when user online
• Random Colour

☑ Allowing Plugins

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

in PLUGINS.conf, add the plugin to allow on a new line !

calc
username

:thought_balloon: Project Testimonials

@TannerFry

With experience in programming in Python, and implementing an SMTP email plugin for a different system, picking up HoneyBot and following the documentation provided for new-comers made it very simple to implement the same SMTP email plugin to the HoneyBot system. This was my first time contributing to an open-source project on GitHub and it was an overall great experience. The welcoming of new contributors and documentation on how to contribute and implement plugins is great for people who have never contributed to a project before, and Abdur-Rahmaan Janhangeer was extremely helpful when answering my questions and helping me along the way.

@RiceAbove

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.

@justinwalker4179

HoneyBot is my first open source project and I had never worked with an IRC before. For school I was required to contribute to projects, but it was always so intimidating to me. I had always heard it gets easier once you've gotten over the fear wall, and that's what HoneyBot did for me. Excellent readme and quick feedback allowed me to make my first plugin. Now I've made many contributions, and look forward to any new issues I can get my hands on. Abdur-Rahmaan Janhangeer has been extremely helpful and I owe him and this project a lot for getting me into the open source world.

@mboekhold

HoneyBot is a very friendly and welcoming community. They provided quick feedback and I would defenitely recommend this project to newcomers to give them that first boost on contributing to open source. HoneyBot helps you all the way there to issuing your first PR, step by step. I contributed a comic plugin, and I was thankful for meeting all the friendly and passionate people who are active in this community.

@Macr0Nerd

I came onto this project in October of 2018. At the time, my experience with open source was nil. I wasn't even sure I was good with python; I just happened to be better than everyone in class. Working on HoneyBot really opened my eyes to the power of community and programming, and has sent me on a path I don't wanna turn from. Just seeing how this project has evolved over the past year and how I've grown with it, I wouldn't trade it for the world. My name might not be on any of the recent plugins or doc strings, but I'll never forget that it'll always be tied to this project and a lot of the code. Also, I don't know if they'll check my commit so go look at the C++ Client! It's cool I promise!

📧 Contact (Including vulnerabilities)

Email

• Abdur-Rahmaan Janhangeer | [e-mail]

🖊 Credits

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