Metadata-Version: 2.4
Name: osonbot
Version: 1.2.9
Summary: Simple Telegram bot framework with some built-in features that makes the writing telegram bots easier.
Home-page: https://github.com/sinofarmonov323/osonbot
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: home-page
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 with 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())

```



# Handling States

Here is the code

```pyhton

bot.state.register("YOUR_STATE_NAME", states=['FIRST_STATE_NAME', 'SECOND_STATE_NAME', 'THIRD_STATE_NAME'...])



bot.when_state("YOUR_EXISTING_STATE_NAME:FIRST_STATE_NAME", 'something to send back when the state is handled', next_state='YOUR_EXISTING_STATE_NAME:SECOND_STATE_NAME')

```

Note that next_state attribute is optional, and next_state will trigger the next state that comes after if next_state is not changed. The point is that you can skip some states according your idea.



# Automatic Database

osonbot offers is a simple built-in automatic database - it creates database automatically, 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")

```



## automatic Admin panel

osonbot also automatically creates admin panel on your telegram bot

set your telegram id to admin_id attribute on Bot class like this and send /admin to your bot (more features like setting specific command to open admin panel and managing database better will be added in the future)

```

bot = Bot('bot_token', admin_id=your_integer_telegram_id)

```



# 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

# Other Telegram Bot API features will be added in the future

