# 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 greet(msg):
    # task 1
    # task 2
    return "All the tasks are done"

bot.when("/do_task", greet)
```
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")
```

# 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.create_table()` function
```python
bot.db.create_table("TABLE_NAME", username=str, phone_number=int, first_name=str)
```

# osonbot CLI
## Run the bot
```shell
osonbot [filename].py
```
