From 660895f3db499a3f8483db5e3e806510cc015134 Mon Sep 17 00:00:00 2001 From: Mustafa Asaad Date: Wed, 23 Mar 2022 13:14:26 +0300 Subject: [PATCH] Update index.md --- docs/index.md | 205 ++++++++++++++++++++++++++++---------------------- 1 file changed, 114 insertions(+), 91 deletions(-) diff --git a/docs/index.md b/docs/index.md index 02dc6c2..d287c13 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,148 +1,171 @@ # tgbotapi -The Ultimate [Telegram Bot API](https://core.telegram.org/bots/api) Client Framework +The Ultimate [Telegram Bot API](https://core.telegram.org/bots/api) Framework [![GPLv2 license](https://img.shields.io/badge/LICENSE-GPLv2-red)](https://github.com/ma24th/tgbotapi/blob/master/LICENSE) [![PyPI](https://img.shields.io/badge/PyPI-v5.7-yellow.svg)](https://pypi.org/project/tgbotapi/) -![Python package](https://github.com/MA24th/tgbotapi/workflows/Python%20package/badge.svg) -![Upload Python Package](https://github.com/MA24th/tgbotapi/workflows/Upload%20Python%20Package/badge.svg) +[![Python package](https://github.com/MA24th/tgbotapi/workflows/Python%20package/badge.svg)]() +[![Upload Python Package](https://github.com/MA24th/tgbotapi/workflows/Upload%20Python%20Package/badge.svg)]() +[![Telegram Group](https://img.shields.io/badge/Telegram-Group-blue.svg)](https://t.me/GuardBotc) -> Based On [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) -## How to Use -### Installation -There are two ways to install the framework: -* Installation using pip (a Python package manager)*: -```bash -$ pip install tgbotapi -``` -* Installation from source (requires git): -```bash -$ git clone https://github.com/ma24th/tgbotapi.git -$ cd tgbotapi -$ python setup.py install -``` - -It is generally recommended to use the first option. - -*While the API is production-ready, it is still under development and it has regular updates, do not forget to update it regularly by calling `pip install tgbotapi --upgrade`* +> Based On [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) -## Writing your first bot +## How to Use ### Prerequisites -It is presumed that you [have obtained an API token with @BotFather](https://core.telegram.org/bots#botfather). We will call this token `TOKEN`. -Furthermore, you have basic knowledge of the Python programming language and more importantly [the Telegram Bot API](https://core.telegram.org/bots/api). +> Presumed you have obtained a bot token with [@BotFather](https://core.telegram.org/bots#botfather) ### A simple echo bot -The Bot class (defined in \__init__.py) encapsulates all API calls in a single class. It provides functions such as `send_xyz` (`send_message`, `send_document` etc.) and several ways to listen for incoming messages. +The Bot class encapsulates all API calls in a single class, It provides functions such as `send_xyz` (`send_message` +, `send_document` etc.) +and several ways to listen for incoming messages. + +Create a file called `echo_bot.py`. Then, open the file and create an instance of the Bot class. -Create a file called `echo_bot.py`. -Then, open the file and create an instance of the TBot class. ```python import tgbotapi -bot = tgbotapi.Bot(based_url="https://api.telegram.org/bot"+ "BOT_TOKEN") -``` -*Note: Make sure to actually replace TOKEN with your own API token.* +# Note: Make sure to actually replace TOKEN with your own API token +bot = tgbotapi.Bot(access_token="TOKEN") -After that declaration, we need to register some so-called message handlers. -Message handlers define filters which a message must pass. If a message passes the filter, -the decorated function is called and the incoming message is passed as an argument. -Let's define a message handler which handles incoming `/start` and `/help` bot_command. -```python -@bot.update_handler(update_type='message', bot_command=['start', 'help']) +# After that declaration, we need to register some so-called update handler. +# update_type define filters which can be a message, If a message passes the filter, +# the decorated function is called and the incoming message is passed as an argument. + +# Let's define an update handler which handles incoming `/start` and `/help` bot_command. +@bot.update_handler(update_type='message', bot_command=['/start', '/help']) +# A function which is decorated by an update handler can have an arbitrary name, +# however, it must have only one parameter (the msg) def send_welcome(msg): - bot.send_message(chat_id=msg.chat.uid, text="Howdy, how are you doing?", parse_mode=None, entities=None, + bot.send_message(chat_id=msg.chat.uid, text="Howdy, how are you doing?", parse_mode=None, entities=None, disable_web_page_preview=False, disable_notification=False, reply_to_message_id=msg.message_id, allow_sending_without_reply=True, reply_markup=None) -``` -A function which is decorated by a message handler __can have an arbitrary name, however, it must have only one parameter (the message)__. -Let's add another handler: -```python + +# This one echoes all incoming text messages back to the sender. +# It uses a lambda function to test a message. If the lambda returns True, +# the message is handled by the decorated function. +# Since we want all text messages to be handled by this function, +# so it simply always return True. @bot.update_handler(update_type='message', func=lambda message: message.text) def echo_all(msg): bot.send_message(chat_id=msg.chat.uid, text=msg.text, parse_mode=None, entities=None, disable_web_page_preview=False, disable_notification=False, reply_to_message_id=None, allow_sending_without_reply=True, reply_markup=None) -``` -This one echoes all incoming text messages back to the sender. It uses a lambda function to test a message. If the lambda returns True, the message is handled by the decorated function. Since we want all messages to be handled by this function, we simply always return True. - -*Note: all handlers are tested in the order in which they were declared* -We now have a basic bot which replies a static message to "/start" and "/help" commands and which echoes the rest of the sent messages. To start the bot, add the following to our source file: -```python +# Finally, we call long polling function bot.polling() ``` -Alright, that's it! Our source file now looks like this: + +Alright, that's it! Our source file, To start the bot, simply open up a terminal and enter `python echo_bot.py` to run +the bot! +Test it by sending commands ('/start' and '/help') and arbitrary text messages. + +### ChangeLog + +**_version 5.7_** + +- Added support for Video Stickers. Added the field is_video to the classes Sticker and StickerSet. +- Added the parameter webm_sticker to the methods createNewStickerSet and addStickerToSet. + +**_Fixes_** + +- No Issues until Now + +### Framework Explanation + +A `handler` is a function that is decorated with the `update_handler` decorator of a Bot instance, handlers consist of +one or multiple filters, Each filter match returns True for a certain message in order for an update handler to become +eligible. + +Here are some examples of using the filters and handlers: + +| update_type | filters | return types | function argument | +|-----------------------|----------------------------------------------|---------------------|-------------------| +| `message` | `chat_type`, `bot_command`, `regexp`, `func` | `Message` | `message` | +| `message_edited` | `chat_type`, `bot_command`, `regexp`, `func` | `Message` | `message` | +| `channel_post` | `chat_type`, `bot_command`, `regexp`, `func` | `Message` | `message` | +| `edited_channel_post` | `chat_type`, `bot_command`, `regexp`, `func` | `Message` | `message` | +| `inline_query` | `regexp`, `func` | `InlineQuery` | `query` | +| `chosen_inline_query` | `regexp`, `func` | `ChosenInlineQuery` | `query` | +| `callback_query` | `regexp`, `func` | `CallbackQuery` | `query` | +| `shipping_query` | `regexp`, `func` | `ShippingQuery` | `query` | +| `per_checkout_query` | `regexp`, `func` | `PreCheckoutQuery` | `query` | +| `poll` | `regexp`, `func` | `Poll` | `poll` | +| `poll_answer` | `regexp`, `func` | `PollAnswer` | `poll` | +| `my_chat_member` | `regexp`, `func` | `ChatMemberUpdated` | `member` | +| `chat_member` | `regexp`, `func` | `ChatMemberUpdated` | `member` | +| `chat_join_request` | `regexp`, `func` | `ChatJoinRequest` | `member` | + +A message handler is declared in the following way: + ```python import tgbotapi -bot = tgbotapi.Bot(based_url="https://api.telegram.org/bot"+ "BOT_TOKEN") +bot = tgbotapi.Bot(access_token="TOKEN") -@bot.update_handler(update_type='message', bot_command=['start', 'help']) -def send_welcome(msg): - bot.send_message(chat_id=msg.chat.uid, text="Howdy, how are you doing?", parse_mode=None, entities=None, - disable_web_page_preview=False, disable_notification=False, reply_to_message_id=msg.message_id, - allow_sending_without_reply=True, reply_markup=None) +@bot.update_handler(update_type='message') # filters +def function_name(message): + bot.send_message(chat_id=message.chat.uid, text="This is a message handler") +``` -@bot.update_handler(update_type='message', func=lambda message: message.text) -def echo_all(msg): - bot.send_message(chat_id=msg.chat.uid, text=msg.text, parse_mode=None, entities=None, - disable_web_page_preview=False, disable_notification=False, reply_to_message_id=None, - allow_sending_without_reply=True, reply_markup=None) +`function_name` is not bound to any restrictions. Any function name is permitted with update handlers. The function must +accept at most one argument, which will be the message that the function must handle. +`filters` is a list of keyword arguments. A filter is declared in the following manner: `name=argument`. One handler may +have multiple filters. -bot.polling() -``` -To start the bot, simply open up a terminal and enter `python echo_bot.py` to run the bot! Test it by sending commands ('/start' and '/help') and arbitrary text messages. +Bot supports the following filters: -### ChangeLog -**_version 5.7_** -Added support for Video Stickers. -Added the field is_video to the classes Sticker and StickerSet. -Added the parameter webm_sticker to the methods createNewStickerSet and addStickerToSet. +| name | argument(s) | Condition | +|:-----------:|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------| +| update_type | list of strings or string (default `['message']`) | `True` if `update.message` is present. | +| chat_type | list of strings or string (`private`, `channel`, `group`, `supergroup`) | `True` if `message.chat.ttype` in `chat_type` | +| bot_command | list of strings or string (`/start`) | `True` if `message.entities[0].bot_command` and `message.text` starts with a command | +| regex | a regular expression as a string | `True` if `re.search(regexp_arg)` returns `True` | +| func | a function (lambda or function reference) | `True` if the lambda or function reference returns `True` | -**_Fixes_** -- No Issues until Now -### Guide -For more explanation goto [Wiki Tab](https://github.com/MA24th/tgbotapi/wiki). +`Logging` You can use the tgbotapi module logger to log debug info about Bot. + +It is possible to add custom logging Handlers to the logger, +Refer to the [Python logging](https://docs.python.org/3/library/logging.html) for more info. + +```python +import logging +from tgbotapi import logger + +logger.setLevel(logging.DEBUG) # Outputs debug messages to console. +``` ## How to Contribute -- You must follow [Contributing](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/CONTRIBUTING.md) Guidelines. -- We are committed to providing a friendly community, for more experience read [Code Of Conduct](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/CODE_OF_CONDUCT.md). +- You must follow [Contributing](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/CONTRIBUTING.md) + Guidelines. +- We are committed to providing a friendly community, for more experience + read [Code Of Conduct](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/CODE_OF_CONDUCT.md). ## How to Communicate -You're welcome to drop in and ask questions, -discuss bugs and such, Check [Communication](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/COMMUNICATION.md) Methods. +You're welcome to drop in and ask questions, discuss bugs and such, +Check [Communication](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/COMMUNICATION.md) Methods. ## Frequently Asked Questions -- How can I distinguish a User and a GroupChat in message.chat? ->Telegram Bot API supports new type Chat for message.chat. -Check the ```ttype``` attribute in ```Chat``` object: -```python -if message.chat.ttype == "private": - # private chat message -if message.chat.ttype == "group": - # group chat message +- How can I distinguish a User and a GroupChat in Message Chat? + +> Telegram Bot API supports type Chat for message Check the ```ttype``` attribute in ```Chat``` object -if message.chat.ttype == "supergroup": - # supergroup chat message -``` ## Attribution -These Documents are adapted for [MA24th Open Source Software](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/), -For more information [contact me](mailto:ma24th@yahoo.com) with any additional questions or comments. -## Support -Join our channel on [![Telegram Group](https://img.shields.io/badge/Telegram-Group-blue.svg)](https://t.me/GuardBotc) -and [![Discord Server](https://img.shields.io/badge/Discord-Server-blue.svg)](https://discord.gg/g65AqbPK6g) . +These Documents are adapted +for [MA24th Open Source Software](https://github.com/MA24th/MA24th/blob/main/OpenSource/Software/), + +For more information [Contact](mailto:ma24th@yahoo.com) with any additional questions or comments.