Metadata-Version: 2.4
Name: osonbot
Version: 1.0.6
Summary: A simple and lightweight Telegram bot framework
Home-page: https://github.com/sinofarmonov323/osonbot
Author: https://t.me/jackson_rodger
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires: httpx
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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}") # * handles evey message if it is a 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}")
```

#### 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

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")
```

# 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())
```

# Coming Soon
automatic database which osonbot creates users and saves users' info to database automatically, and built-in admin panel which osonbot will have admin panel that you can see those users and do some more stuff
