# 🍯 honeybot py [ [docs](https://pyhoneybot.github.io/honeybot/) ]
<div align="center">
<img src="./assets/honeybot_real.png" width="64" />
[](https://badge.fury.io/py/honeybot)
[](https://www.firsttimersonly.com/)
[](https://bestpractices.coreinfrastructure.org/projects/6329)
[](https://api.securityscorecards.dev/projects/github.com/pyhoneybot/honeybot)
## 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!](https://aviyel.com/projects/84/pyhoneybot/rewards)**
<hr>
🇲🇺 🇺🇸 🇨🇦 🇦🇷 🇮🇳 🇬🇧 🇬🇬 🇧🇷 🇸🇽 🇵🇱 🇩🇪
</div>
<div align="center">
[](https://www.codetriage.com/pyhoneybot/honeybot)
[](https://discordapp.com/invite/E6zD4XT)
</div>
## 📮 About
HoneyBot is a python-based IRC bot. (**python3.7**) | If you want to just run the bot, go to the [quick start section](https://github.com/pyhoneybot/honeybot#-quickstart)
> 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](https://github.com/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](https://discord.gg/E6zD4XT) !
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](https://github.com/pyhoneybot/cpp-client) by [@Macr0Nerd](https://github.com/Macr0Nerd)
## ⌚ Current Plugins
| Plugin | Description | Contributor |
| ---------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 💎 bitcoin | Get price of bitcoin | [@Macr0Nerd](https://github.com/Macr0Nerd) |
| ⏲ caesar cipher | Encode your text | [@kylegalloway](https://github.com/kylegalloway) |
| 🔢 calc | Evaluates maths expressions | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |
| 📐 maths | Trigonometry & random number generator | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |
| 🍃 conv sniff | Set triggers like how many times a word occur for one or more words and send response | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |
| ❄ greet | Demo plugin | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |
| ⛓ installed_modules | Checks dependencies installed | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |
| 🕶 joke | Get random joke | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ), [@colbyjayallen](https://github.com/colbyjayallen) |
| ❓ self Trivia | Random trivia | [@ajimenezUCLA](https://github.com/ajimenezUCLA) |
| 💢 username | Username generator | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ), [@sseryani](https://github.com/sseryani) |
| 📜 quotes | Inspirational quotes | [@German-Corpaz](https://github.com/German-Corpaz) |
| 📖 dictionary | Returns meaning of word | [@iamnishant14](https://github.com/iamnishant14) |
| 🔣 password generator | The name tells it all | [@iamnishant14](https://github.com/iamnishant14) |
| 🐜 debug | Prints all parameters passed to bot | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |
| 📚 wikipedia | Returns a wikipedia article | [@Macr0Nerd](https://github.com/Macr0Nerd) |
| 🗿 translate | Google translate plugin | [@a-deeb](https://github.com/a-deeb) |
| 📑 test | Runs tests | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |
| ⛅️ weather | Returns weather info for a given location | [@Macr0Nerd](https://github.com/Macr0Nerd) |
| ✉️ mail | Send emails within the chat | [@TannerFry](https://github.com/TannerFry) |
| 🕴️ hangman | Play hangman in the chat | [@JustinWalker4179](https://github.com/justinwalker4179) |
| 🎂 age | Takes in birthday and outputs age | [@JustinWalker4179](https://github.com/justinwalker4179) |
| ✔️ fact | Returns a random fact | [@JustinWalker4179](https://github.com/justinwalker4179) |
| 🔍 google | Returns three search results from google | [@JustinWalker4179](https://github.com/justinwalker4179) |
| 📮 send message | Sends a message to another channel | [@JustinWalker4179](https://github.com/justinwalker4179) |
| 📝 log | Logs the chat into a log file | [@RiceAbove](https://github.com/RiceAbove) |
| 🚪 joins | Greets everyone who joins the channel | [@RiceAbove](https://github.com/RiceAbove) |
| 📅 date | Posts the current date | [@RiceAbove](https://github.com/RiceAbove) |
| 🕵️ riddle | Returns a random riddle | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| 🗞 news | Gets the top 10 headlines from bbc world news | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| 📝 horoscope | Gets your daily horoscope for your starsign | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| 💵 currency converter | Converts currencies | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| 🔫 russian_roulette | May or may not kick you off the channel | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| 🏨 monopoly | Honeybot now supports the world's worst game! | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| ⚽️ transfer_rumour | Shows the day's transfer rumours | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| 🃏 blackjack/21 | Play 21 on honeybot! | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| 🤒 corona | Get the latest news on coronavirus with honeybot! | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| 📖 diary | Keep a diary with honeybot | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| 🛩 flight | Gets flight info from flightradar24 | [@AngeloGiacco](https://github.com/AngeloGiacco) |
| 🎲 roll | Rolls a dice | [@GlennToms](https://github.com/GlennToms) |
| ❓ help | Show link to plugin's information page | [@edumello](https://github.com/edumello) |
| ✅ channeljoin | Join command for bot | [@marceloyb](https://github.com/marceloyb) |
| :page_with_curl: comic | Returns a random comic | [@mboekhold](https://github.com/mboekhold) |
| 📝 todo | Makes a to do list | [@h-ranjan1110](https://github.com/h-ranjan1110) |
| 🎱 Magic 8 Ball | Answer questions using magic 8 ball | [@ZakariaTalhami](https://github.com/ZakariaTalhami) |
| 🎟 Random Excuse | Generates a random excuse for you. | [@rakeshseal0](https://github.com/rakeshseal0)
| 🦆 DuckDuckGo Search | Search queries in duckduckgo and return abstract. | [@rakeshseal0](https://github.com/rakeshseal0) |
| 🖼 Random Image | Returns a random image url. | [@rakeshseal0](https://github.com/rakeshseal0)
| 🛢 URL Shortener | Shortens a url | [@rakeshseal0](https://github.com/rakeshseal0)
## ⚡ Quickstart
setup
```bash
mkdir botx
cd botx
python -m venv venv
venv\scripts\activate # or source venv/bin/activate for linux
python -m pip install honeybot
```
run
```bash
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](https://kiwiirc.com) (easy)
- Desktop: [Hexchat](https://hexchat.github.io)
- Android: [Revolution IRC](https://github.com/MCMrARM/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](https://github.com/pyhoneybot/honeybot/blob/master/src/honeybot/settings/CONNECT.conf)
## 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.
```python
# -*- 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](https://github.com/pyhoneybot/honeybot/blob/master/src/honeybot/api/main.py) reveals
```python
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
```python
{
'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
```python
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
```python
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:
```rst
<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](https://pyhoneybot.github.io/honeybot/How_Tos/documentation.html)
## 🥄 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
- [x] 💐 humour
- [x] 🌨️ weather
- [x] ✉️ mail
- [x] 🎛️ 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](https://github.com/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](https://github.com/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](https://github.com/IronPenguin4179)
> 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](https://github.com/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](https://github.com/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 | arj.python@gmail.com
## 🖊 Credits
- [@arwinneil](https://github.com/arwinneil), "Open Source" and "Made In Moris" badges
Raw data
{
"_id": null,
"home_page": "https://github.com/pyhoneybot/honeybot",
"name": "honeybot",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.0",
"maintainer_email": "",
"keywords": "irc bot plugins",
"author": "Abdur-Rahmaan Janhnageer",
"author_email": "arj.python@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/81/83/0e7db147eb5f5ece4ee852501f59f82bafab9ce67a7a12c33dccdd6a4941/honeybot-6.0.2.tar.gz",
"platform": null,
"description": "# \ud83c\udf6f honeybot py [ [docs](https://pyhoneybot.github.io/honeybot/) ]\n\n<div align=\"center\">\n\n\n\n\n<img src=\"./assets/honeybot_real.png\" width=\"64\" />\n\n[](https://badge.fury.io/py/honeybot)\n[](https://www.firsttimersonly.com/)\n\n\n[](https://bestpractices.coreinfrastructure.org/projects/6329)\n[](https://api.securityscorecards.dev/projects/github.com/pyhoneybot/honeybot)\n\n## Launching pyhoneybot Rewards\n Contributed to pyhoneybot? Here is a big thank you from our community to you.\n Claim your badge and showcase them with pride.\n Let us inspire more folks !\n\n \n ### **[Claim Now!](https://aviyel.com/projects/84/pyhoneybot/rewards)**\n\n<hr>\n\ud83c\uddf2\ud83c\uddfa \ud83c\uddfa\ud83c\uddf8 \ud83c\udde8\ud83c\udde6 \ud83c\udde6\ud83c\uddf7 \ud83c\uddee\ud83c\uddf3 \ud83c\uddec\ud83c\udde7 \ud83c\uddec\ud83c\uddec \ud83c\udde7\ud83c\uddf7 \ud83c\uddf8\ud83c\uddfd \ud83c\uddf5\ud83c\uddf1 \ud83c\udde9\ud83c\uddea\n\n</div>\n<div align=\"center\">\n\n[](https://www.codetriage.com/pyhoneybot/honeybot)\n[](https://discordapp.com/invite/E6zD4XT)\n\n</div>\n\n## \ud83d\udcee About\n\nHoneyBot is a python-based IRC bot. (**python3.7**) | If you want to just run the bot, go to the [quick start section](https://github.com/pyhoneybot/honeybot#-quickstart)\n\n> 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](https://github.com/RiceAbove)\n\nFeel free to contribute to the project!\n\n## \ud83d\udd79 Project Motivation\n\nImplementing the project in Java was weird, py's connect was sleek. Thus, the project stack was shifted over to Python.\nIf 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](https://discord.gg/E6zD4XT) !\n\nPsst. Since I learnt py through this bot, we decided to keep a new-comers friendly policy. Feeling lost? Just ping.\n\n## \u2702 Current Features\n\n- \ud83c\udf6c OOP architecture\n- \ud83d\udef0\ufe0f keyword parameters\n- \ud83c\udf35 password security with config file [disabled for now]\n- \ud83d\udd0c now with plugins\n\n## :mountain: GUI clients\n\nGUI clients are used to manage plugins, launch bot as well as specify credentials.\n\n- [CPP client](https://github.com/pyhoneybot/cpp-client) by [@Macr0Nerd](https://github.com/Macr0Nerd)\n\n## \u231a Current Plugins\n\n| Plugin | Description | Contributor |\n| ---------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |\n| \ud83d\udc8e bitcoin | Get price of bitcoin | [@Macr0Nerd](https://github.com/Macr0Nerd) |\n| \u23f2 caesar cipher | Encode your text | [@kylegalloway](https://github.com/kylegalloway) |\n| \ud83d\udd22 calc | Evaluates maths expressions | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |\n| \ud83d\udcd0 maths | Trigonometry & random number generator | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |\n| \ud83c\udf43 conv sniff | Set triggers like how many times a word occur for one or more words and send response | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |\n| \u2744 greet | Demo plugin | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |\n| \u26d3 installed_modules | Checks dependencies installed | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |\n| \ud83d\udd76 joke | Get random joke | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ), [@colbyjayallen](https://github.com/colbyjayallen) |\n| \u2753 self Trivia | Random trivia | [@ajimenezUCLA](https://github.com/ajimenezUCLA) |\n| \ud83d\udca2 username | Username generator | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ), [@sseryani](https://github.com/sseryani) |\n| \ud83d\udcdc quotes | Inspirational quotes | [@German-Corpaz](https://github.com/German-Corpaz) |\n| \ud83d\udcd6 dictionary | Returns meaning of word | [@iamnishant14](https://github.com/iamnishant14) |\n| \ud83d\udd23 password generator | The name tells it all | [@iamnishant14](https://github.com/iamnishant14) |\n| \ud83d\udc1c debug | Prints all parameters passed to bot | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |\n| \ud83d\udcda wikipedia | Returns a wikipedia article | [@Macr0Nerd](https://github.com/Macr0Nerd) |\n| \ud83d\uddff translate | Google translate plugin | [@a-deeb](https://github.com/a-deeb) |\n| \ud83d\udcd1 test | Runs tests | [@Abdur-rahmaanJ](https://github.com/Abdur-rahmaanJ) |\n| \u26c5\ufe0f weather | Returns weather info for a given location | [@Macr0Nerd](https://github.com/Macr0Nerd) |\n| \u2709\ufe0f mail | Send emails within the chat | [@TannerFry](https://github.com/TannerFry) |\n| \ud83d\udd74\ufe0f hangman | Play hangman in the chat | [@JustinWalker4179](https://github.com/justinwalker4179) |\n| \ud83c\udf82 age | Takes in birthday and outputs age | [@JustinWalker4179](https://github.com/justinwalker4179) |\n| \u2714\ufe0f fact | Returns a random fact | [@JustinWalker4179](https://github.com/justinwalker4179) |\n| \ud83d\udd0d google | Returns three search results from google | [@JustinWalker4179](https://github.com/justinwalker4179) |\n| \ud83d\udcee send message | Sends a message to another channel | [@JustinWalker4179](https://github.com/justinwalker4179) |\n| \ud83d\udcdd log | Logs the chat into a log file | [@RiceAbove](https://github.com/RiceAbove) |\n| \ud83d\udeaa joins | Greets everyone who joins the channel | [@RiceAbove](https://github.com/RiceAbove) |\n| \ud83d\udcc5 date | Posts the current date | [@RiceAbove](https://github.com/RiceAbove) |\n| \ud83d\udd75\ufe0f\u200d riddle | Returns a random riddle | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \ud83d\uddde news | Gets the top 10 headlines from bbc world news | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \ud83d\udcdd horoscope | Gets your daily horoscope for your starsign | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \ud83d\udcb5 currency converter | Converts currencies | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \ud83d\udd2b russian_roulette | May or may not kick you off the channel | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \ud83c\udfe8 monopoly | Honeybot now supports the world's worst game! | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \u26bd\ufe0f transfer_rumour | Shows the day's transfer rumours | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \ud83c\udccf blackjack/21 | Play 21 on honeybot! | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \ud83e\udd12 corona | Get the latest news on coronavirus with honeybot! | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \ud83d\udcd6 diary | Keep a diary with honeybot | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \ud83d\udee9 flight | Gets flight info from flightradar24 | [@AngeloGiacco](https://github.com/AngeloGiacco) |\n| \ud83c\udfb2 roll | Rolls a dice | [@GlennToms](https://github.com/GlennToms) |\n| \u2753 help | Show link to plugin's information page | [@edumello](https://github.com/edumello) |\n| \u2705 channeljoin | Join command for bot | [@marceloyb](https://github.com/marceloyb) |\n| :page_with_curl: comic | Returns a random comic | [@mboekhold](https://github.com/mboekhold) |\n| \ud83d\udcdd todo | Makes a to do list | [@h-ranjan1110](https://github.com/h-ranjan1110) |\n| \ud83c\udfb1 Magic 8 Ball | Answer questions using magic 8 ball | [@ZakariaTalhami](https://github.com/ZakariaTalhami) |\n| \ud83c\udf9f Random Excuse | Generates a random excuse for you. | [@rakeshseal0](https://github.com/rakeshseal0)\n| \ud83e\udd86 DuckDuckGo Search | Search queries in duckduckgo and return abstract. | [@rakeshseal0](https://github.com/rakeshseal0) |\n| \ud83d\uddbc Random Image | Returns a random image url. | [@rakeshseal0](https://github.com/rakeshseal0) \n| \ud83d\udee2 URL Shortener | Shortens a url | [@rakeshseal0](https://github.com/rakeshseal0) \n\n## \u26a1 Quickstart\n\nsetup\n\n```bash\nmkdir botx\ncd botx\npython -m venv venv\nvenv\\scripts\\activate # or source venv/bin/activate for linux\npython -m pip install honeybot\n\n```\n\nrun\n\n```bash\nhoneybot init\nhoneybot run\n```\n\nin settings/CONNECT.conf\n\n```\n[INFO]\n\nserver_url = irc.libera.chat\nport = 6667\nname = appinventormuBot\n```\n\nIn settings/PLUGINS.conf listed plugins under plugins/downloaded will load. Plugins listed under plugins/core are auto loaded.\n\n## \ud83d\udcbb Seeing The Bot In Action\n\nGet an IRC client\n\n- Web: [Kiwiirc](https://kiwiirc.com) (easy)\n- Desktop: [Hexchat](https://hexchat.github.io)\n- Android: [Revolution IRC](https://github.com/MCMrARM/revolution-irc)\n\nconfigure\n\n```\nport: 6667\nurl: irc.libera.chat\n```\n\nthen join channel `#ltch`\n\nyou should see the bot as hbot ... or as it's name is in [settings](https://github.com/pyhoneybot/honeybot/blob/master/src/honeybot/settings/CONNECT.conf)\n\n## Docker\n\n** Building Docker image **\nChange SERVER, PORT and NICKNAME variables to match your preferences\n\n```\ndocker build -t honeybot -f ./docker/Dockerfile .\n```\n\n** Running Docker image **\n\n```\ndocker run honeybot\n```\n\n## \ud83d\udd27 Plugins Development\n\nEach plugin has a folder named after it. In it there is a file called main.py. In each there is a class called Plugin.\n\n```python\n# -*- coding: utf-8 -*-\n\nclass Plugin:\n def __init__(self):\n pass\n\n def run(self, incoming, methods, info, bot_info):\n try:\n if info['command'] == 'PRIVMSG' and info['args'][1] == '.hi':\n methods['send'](info['address'], 'hooo')\n except Exception as e:\n print('woops plugin error ', e)\n```\n\nwe see four parameters being passed to the run method `, incoming, methods, info, bot_info)`\n\n#### parameter1: incoming\n\n`incoming` is the raw line and is not used except if you are not satisfied with the already provided methods\n\n#### parameter2: methods\n\n`methods` is a dictionary of methods to ease your life. a quick look at [main.py](https://github.com/pyhoneybot/honeybot/blob/master/src/honeybot/api/main.py) reveals\n\n```python\ndef methods(self):\n return {\n 'send_raw': self.send,\n 'send': self.send_target,\n 'join': self.join\n }\n```\n\nwhere `send_raw` allows you to send in any string you want, thereby allowing you to implement any irc protocol from scratch\n\nbut, 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.\n\n`join` allows you to join a channel by `methods['join']('<channel name>')`\n\n#### parameter3: info (meaning message info)\n\nfor a normal run, info produces\n\n```python\n{\n'prefix': 'appinv!c5e342c5@gateway/web/cgi-irc/kiwiirc.com/ip.200.200.22.200',\n'command': 'PRIVMSG',\n'address': '##bottestingmu',\n'args': ['##bottestingmu', 'ef']\n}\n```\n\nhence if you want messages, `messages = info['args'][1:]` or the first word if you want to check for command will be `info['args'][1]`\n\n**use example**\n\n- the command info is used in the join channel plugin to detect a join command and greet the user who just joined\n\n### bot info\n\nbot_info returns info about the bot\n\n```python\n return {\n 'name': self.name,\n 'special_command': self.sp_command,\n 'required_modules': self.required_modules,\n 'owners': self.owners,\n 'time': self.time,\n 'friends': self.friends\n }\n```\n\nso that in run method you can access those.\n\n**use example**\n\n- 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.\n- The required modules is used in the installed plugin to determine what required plugin the bot runner did not install\n\n#### wrapping up\n\nhence\n\n```python\nif info['command'] == 'PRIVMSG' and info['args'][1] == '.hi':\n methods['send'](info['address'], 'hooo')\n```\n\nfrom above means\n\n```\nif message received == .hi:\n send(address, message)\n```\n\n## \ud83d\udcc3 Contributing Guide\n\n<https://pyhoneybot.github.io/honeybot/How_Tos/contributing.html>\n\n- don't forget to add your country flag here after accepted PR. i'll have to hunt it down on your profile if not.\n- make sure to follow PEP8\n\n**About PR**\n\nfirst clone the project\n\n```\ngit clone https://github.com/pyhoneybot/honeybot.git\n```\n\ncd into the project\n\n```\ncd honeybot\n```\n\ncreate a virtualenv to work with different python \\ libs versions\n\n```\npython -m venv venv\nsource venv/bin/activate\n```\n\ninstall the tools needed to make the constraint checks\n\n```\npip install black isort bandit pre-commit\npre-commit install\n```\n\ndifferent changes to different files. for example, someone making a weather plugin first he creates a new branch\n\n```\ngit checkout -b \"weather-plugin\"\n```\n\ntest if all files are well formatted, complying with style and security rules, before send the PR\n\n```\nblack --check --verbose --config ./pyproject.toml src/honeybot/plugins/downloaded/weather/main.py\nisort --check-only --settings-path ./pyproject.toml src/honeybot/plugins/downloaded/weather/main.py\nbandit -ll -c ./pyproject.toml -r src/honeybot/plugins/downloaded/weather/main.py \n```\n\nthen he commits\n\n```\ngit add *\ngit commit -m \"added weather plugin\"\n```\n\nor\n\n```\ngit commit -a -m \"did this\"\n```\n\nthen he push to create a PR with the branch\n\n```\ngit push origin head\n```\n\nor\n\n```\ngit push origin weather-plugin\n```\n\nnow let us say he wants to work on another issue, adding a joke in the jokes plugin, he creates another branch\n\n```\ngit checkout -b \"add-jokes\"\n```\n\nafter, same as before\n\n```\ngit add *\ngit commit -m \"added some jokes\"\ngit push origin head\n```\n\nnow he wants to fix his weather plugin, he changes branch\n\n```\ngit checkout weather-plugin\n```\n\nworks, then commit\n\n```\ngit add *\ngit commit -m \"fixed <issue>\"\n```\n\nthen a PR\n\n```\ngit push origin head\n```\n\n**Why all these?**\n\nSo as not to reject a whole PR just because of some oddities. Reject only unneeded part.\n\n**Updating the Documentation**\n\nIf you created a new plugin you should add your plugin to the documentation.\nTo do this, go into your cloned honeybot repo and then into the directory _docs/source/Plugins_ .\nDepending on the type of plugin write this into the development, fun, miscellaneous or utility RST file:\n\n```rst\n\n <Plugin-Name>\n ^^^^^^^^^^^^^\n .. automodule:: plugins.<your-plugin-filename>\n :members:\n```\n\nThis allows sphinx to automatically pull the docstrings from the code of your plugin and parse them accordingly.\n\nA small guide on how to further contribute to the documentation of the project can be found [here](https://pyhoneybot.github.io/honeybot/How_Tos/documentation.html)\n\n## \ud83e\udd44 Updating fork\n\nNow, other changes are ongoing, what if you need the latest changes?\n\n```\ngit pull origin master\n```\n\nhelps if you cloned your own repo. What if you want to update your local copy of someone else's repo that you forked?\nYou do it like that\n\n```\ncd <your/local/cloned/repo/path/here>\ngit remote add upstream https://github.com/pyhoneybot/honeybot.git\ngit fetch upstream\ngit pull upstream master\n```\n\n## \ud83d\udd0c Todo Plugins\n\n- [x] \ud83d\udc90 humour\n- [x] \ud83c\udf28\ufe0f weather\n- [x] \u2709\ufe0f mail\n- [x] \ud83c\udf9b\ufe0f maths\n- [ ] \ud83d\udce5 pm when user online\n- [ ] Random Colour\n\n## \u2611 Allowing Plugins\n\n**Plugins available**\n<https://pyhoneybot.github.io/honeybot/plugins.html>\n\nin PLUGINS.conf, add the plugin to allow on a new line !\n\n```\ncalc\nusername\n```\n\n## :thought_balloon: Project Testimonials\n\n[@TannerFry](https://github.com/TannerFry)\n\n> 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\n> 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\n> 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.\n\n[@RiceAbove](https://github.com/RiceAbove)\n\n> 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.\n\n[@justinwalker4179](https://github.com/IronPenguin4179)\n\n> 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.\n\n[@mboekhold](https://github.com/mboekhold)\n\n> 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.\n\n[@Macr0Nerd](https://github.com/Macr0Nerd)\n\n> 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!\n\n## \ud83d\udce7 Contact (Including vulnerabilities)\n\n### Email\n\n- Abdur-Rahmaan Janhangeer | arj.python@gmail.com\n\n## \ud83d\udd8a Credits\n\n- [@arwinneil](https://github.com/arwinneil), \"Open Source\" and \"Made In Moris\" badges\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "IRC bot with vast collection of plugins. First timers friendly",
"version": "6.0.2",
"split_keywords": [
"irc",
"bot",
"plugins"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "2cfb0017eb9a632abcc41122f28351a3",
"sha256": "4e8fb3ebe4f6989e7674e60a394d4caea186f76dc1656a16797fa87783bc47e5"
},
"downloads": -1,
"filename": "honeybot-6.0.2.tar.gz",
"has_sig": false,
"md5_digest": "2cfb0017eb9a632abcc41122f28351a3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.0",
"size": 107686,
"upload_time": "2022-11-30T11:35:58",
"upload_time_iso_8601": "2022-11-30T11:35:58.291217Z",
"url": "https://files.pythonhosted.org/packages/81/83/0e7db147eb5f5ece4ee852501f59f82bafab9ce67a7a12c33dccdd6a4941/honeybot-6.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-11-30 11:35:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "pyhoneybot",
"github_project": "honeybot",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "honeybot"
}
JSON
