Metadata-Version: 2.4
Name: osonbot
Version: 1.2.8
Summary: Simple Telegram bot framework with some built-in features.
Author: Sino Farmonov
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Requires-Dist: watchdog
Requires-Dist: pydantic
Provides-Extra: userbot
Requires-Dist: telethon; extra == "userbot"
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: provides-extra
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}")



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

```

## Sending and Receiving 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 sending media

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

```

### example receivig media

```python

from osonbot import Bot, Photo, Video, Audio, Voice, Sticker, Document



bot = Bot("BOT_TOKEN")



bot.when("/photo", Photo("URL_OR_PATH_TO_PHOTO", caption="optional"))

bot.when("/video", Video("URL_OR_PATH_TO_VIDEO", caption="optional"))

same with Audio, Voice, Sticker, and Document

```



# 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

```



# Userbot is coming in later updates

