osonbot 1.2.0
A simple and lightweight Telegram bot framework
Requires Python: >=3.10

# osonbot

A simple Telegram bot framework.

# Installation
```shell
pip install osonbot
```

Example echo bot
```python
from osonbot import Bot

bot = Bot("YOUR_BOT_TOKEN")

bot.when("/start", "Hello {first_name}!")
bot.when("*", "{message_text}")

bot.run()
```

# Documentation
# Handling messages
```python
bot.when("MESSAGE_YOU_WANT_TO_HANDLE", "TEXT_YOU_WANT_TO_SEND_WHEN_MESSAGE_IS_HANDLED")
```
### example
```python
bot.when("/start", "Hello {first_name}")
```
#### you can give function to do if you want to do multiple task
```python
from osonbot import Bot

bot = Bot("YOUR_BOT_TOKEN")

def tasks(msg):
    # task 1
    # task 2
    bot.send_message(msg.chat.id, "tasks are completed")

bot.when("/do_task", tasks)
```
if you run this code above, you will get "All the tasks are done" message from your telegram bot

#### since when method returns self, you can write everything in one line like this. Example in echo bot
```python
from osonbot import Bot

Bot("YOUR_BOT_TOKEN").when("/start", "Hello, {first_name}").when("/help", "How can i help you").when("{message_text}")
```

first_name will be formatted as the telegram users real first name automatically
here are the texts that the osonbot formats automatically:
 - first_name: telegram user's first name
 - last_name: telegram user's last name
 - full_name: telegram user's full name
 - message_text: message's text sent by user
 - user_id: telegram user's id
 - message_id: message's id sent by user

#### examples on these
```python
bot.when("/firstname", "your first name is {first_name}")
bot.when("/fullname", "your full name is {full_name}")
bot.when("/lastname", "your last name is {last_name}")
bot.when("/text", "you sent {message_text}")
bot.when("/id", "your telegram id is {user_id}")
bot.when("/msgid", "your message's id is {message_id}")
```
## Handling Medias
to handle medias, use when method, but instead of putting string like this `when("photo")` or `when("video")`, use osonbot's Photo or Video objects
### example
```python
from osonbot import Bot, Photo, Video, Audio, Voice, Sticker, Document

bot = Bot("BOT_TOKEN")

bot.when(Photo, "you sent a photo")
bot.when(Video, "you sent a video")
bot.when(Audio, "you sent a Audio")
bot.when(Voice, "you sent a Voice")
bot.when(Sticker, "you sent a Sticker")
bot.when(Document, "document is received")
```

# Editing
## messages
parse mode, caption and reply_markup is available in this method
```python
bot.edit_message_text(chat_id, message_id, "new message")
```

# Sending Buttons
## Sending keyboard buttons
To send reply keyboard buttons, use osonbot's `KeyboardButton` function. Set `KeyboardButton` to `reply_markup` attribute in bot.when 
```python
from osonbot import Bot, KeyboardButton

bot = Bot("YOUR_BOT_TOKEN")

row1 = ["Button 1", "Button 2"]
row2 = ["Button 3"]
row3 = ["Button 4", "Button 5"]

bot.when("hi", "hi, {first_name}\nchoose", reply_markup=KeyboardButton(row1, row2, row3))
```
you can give buttons as many as you want. KeyboardButton has `resize_keyboard` attribute which is True by default and `one_time_keyboard` which is False by default.

## Sending inline keyboard buttons
To send inline keybaord buttons, use osonbot's `InlineKeyboardButton` function. Set `InlineKeyboardButton` function to `reply_markup` attribute in bot.when
### InlineKeyboardButton Usage
```python
InlineKeyboardButton(
    [["BUTTON_TEXT", "BUTTON_CALLBACK_DATA"], ["BUTTON_TEXT", "BUTTON_CALLBACK_DATA"]],
    [same here]
)
```
### Example
```python
from osonbot import Bot, InlineKeyboardButton

bot = Bot("YOUR_BOT_TOKEN")

row1 = [["Button 1", "btn1"], ["Button 2", "btn2"]]
row2 = [["Button 3", "btn3"]]

bot.when("buttons", "choose buttons", reply_markup=InlineKeyboardButton(row1, row2))
```

## Sending inline keyboard buttons, while setting url to them
To do this, use `URLKeyboardButton` from osonbot. Its usage is same as InlineKeyboardButton, but instead of putting callback_data, put valid url
```python
from osonbot import Bot, URLKeyboardButton

bot = Bot("YOUR_BOT_TOKEN")

row1 = [["Github", "https://github.com/"], ["Google", "https://google.com"]]
row2 = [["YouTube", "https://www.youtube.com"]]

bot.when("buttons", "choose buttons", reply_markup=URLKeyboardButton(row1, row2))
```

## Remove Keyboard Buttons
To remove it, import `RemoveKeyboardButton` function from osonbot
```python
from osonbot import Bot, RemoveKeyboardButton

bot = Bot("YOUR_BOT_TOKEN")

bot.when("remove", "keyboard buttons are removed", reply_markup=RemoveKeyboardButton())
```

# Automatic Database and Admin Panel
osonbot handles database and admin automatically which means there is a simple built-in admin panel, and it creates database automatically and saves users' username and user ids. To get the data from database, use `bot.db.get_data()`
```python
bot.db.get_data()
```
#### Overwrite the table
by default, osonbot only saves users' usernames and user ids
To this and add another columns, use `bot.db.overwrite_table()` function
```python
bot.db.overwrite_table("TABLE_NAME", username=str, phone_number=int, first_name=str)
```

#### Creating tables
```python
bot.db.create_table("TABLE_NAME", column1=str, column2=int)
```

#### Getting a data of a table
to do this use `bot.db.get_data()` method
```python
bot.db.get_data("TABLE_NAME")
```

# osonbot CLI
## Run the bot
cli tool can run your python file, while watching it, and if it spots any change it will rerun it, so you don't need to stop and rerun it manually
```shell
osonbot [filename].py
```

# Making a Bot Builder Bot

use `BotBuilder` from `osonbot`
#### Example Echo Bot
```python
from osonbot import Bot, BotBuilder

bot = Bot("token")
builder = BotBuilder()

bot.when("/start", "Hello, i am bot builder")

builder.add_bot(token, {"/start": {"response": "Hello {first_name}"}, "/help": {"response": "How can i help you?"}, "*": {"response": "{message_text}"}})
builder.when("NEW_BOT_TOKEN", "/start", "Hello, i am built usng bot builder")

bot.run()
```