Metadata-Version: 2.1
Name: phonkd_bot
Version: 1.0.0
Summary: A framework that makes discord bot programming easy
Author: Phonki
Author-email: <phonkibusiness@gmail.com>
Keywords: python,discord
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Description-Content-Type: text/markdown
License-File: LICENSE

<div align="center">
<pre>
██████╗ ██╗  ██╗ ██████╗ ███╗   ██╗██╗  ██╗██████╗     ██████╗  ██████╗ ████████╗
██╔══██╗██║  ██║██╔═══██╗████╗  ██║██║ ██╔╝██╔══██╗    ██╔══██╗██╔═══██╗╚══██╔══╝
██████╔╝███████║██║   ██║██╔██╗ ██║█████╔╝ ██║  ██║    ██████╔╝██║   ██║   ██║   
██╔═══╝ ██╔══██║██║   ██║██║╚██╗██║██╔═██╗ ██║  ██║    ██╔══██╗██║   ██║   ██║   
██║     ██║  ██║╚██████╔╝██║ ╚████║██║  ██╗██████╔╝    ██████╔╝╚██████╔╝   ██║   
╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚═════╝     ╚═════╝  ╚═════╝    ╚═╝   
---------------------------------------------------------------
A framework that makes discord bot programming easy
</pre>

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

</div>

## Installation and setup

Run this command in your terminal, it will download the framework along with the [discord](https://discordpy.readthedocs.io/en/stable/api.html) and [asyncio](https://docs.python.org/3/library/asyncio.html) libraries.

```shell
pip3 install phonkd_bot
```

Create a file named `config.json` in the same directory as your script. Copy and paste your bot token (from [discord.com/developers](https://discord.com/developers/applications)) into the file. The prefix field is optional.
```json
{
    "prefix": "/",
    "token": "YOUR BOT TOKEN HERE"
}
```

## Creating a Discord Bot
1. Go to [discord.com/developers/applications](https://discord.com/developers/applications)
2. Click `New Application`
3. Give the bot a name, agree to the terms, then click `Create`
4. (optional) give the bot a profile picture, tags, and or a description, then click `Save Changes`
5. Go to the `Bot` page on the side panel
6. (optional) give the bot a username
7. Click `Reset Token`, `Yes, do it!` and `Copy`, save the token somewhere safe
8. Allow `Presence Intent`, `Server Members Intent`, and `Message Content Intent`
9. Click `Save Changes`
10. Expand `OAuth2` on the side panel and go to `URL Generator`
11. Check `bot`, this will reveal `Bot Permissions`, you will need to check `Administrator` in this new section
12. Scroll down, and open the generated url in another tab
13. Select the server to add the bot to and click `Continue`
14. Make sure `Administrator` is checked and click `Authorize`
15. Do the captcha (if one appears) and close the window once you see `"Success!"` on your screen

## Usage Example

### Importing the bot

```python
import phonkd_bot
```

### Creating a bot instance

```python
bot = phonkd_bot.DiscordBot()
```

### Responding to messages
- Adding the `phonkd_bot.message` type hint to the `message` parameter allows your code editor to autocomplete attributes of the discord [`Message`](https://discordpy.readthedocs.io/en/stable/api.html#discord.Message) object, see their [documentation](https://discordpy.readthedocs.io/en/stable/api.html#discord.Message) for more information.
- The function passed into `call_on_message` will be called when a the bot receives a message. The return value is what the bot will respond with.
- The framework will pass a discord.Message object as a paramater to the function provided to `call_on_message`.
```python
def on_message(message: phonkd_bot.message):
    return "Hello!"

bot.call_on_message(on_message)
```

### Activating the bot

```python
bot.start()
```

### Logging Information

The `DiscordBot` class has a sub class called `logger`. The `logger` class has multiple methods that will help you debug or catch errors in your script. These methods are:
- `logger.info`
- `logger.warning`
- `logger.error`
- `logger.critical`

Here is an example script.

```python
import phonkd_bot

bot = DiscordBot()

bot.logger.info("info message")
bot.logger.warning("warning message")
bot.logger.error("error message")
bot.logger.critical("critical error message")
```

This is the result.

![image of terminal containing logged information](https://i.imgur.com/wiIKZEQ.png)

### Example Discord Bot Script

```python
import phonkd_bot

bot = phonkd_bot.DiscordBot()

def on_message(message: phonkd_bot.message):
    return "Hello!"

bot.call_on_message(on_message)
bot.start()
```

This is the result.

![image of discord bot saying hello](https://i.imgur.com/4hcMWHE.png)

## Meta
Gmail - phonkibusiness@gmail.com

Github - https://github.com/RealPhonki

Find me on the Python Discord Server - https://discord.com/invite/python

Discord Tags - `Phonki#0090`, `slamsandwich19`

Code distributed under the MIT license. See `LICENSE` for more information.
