diff --git a/README.md b/README.md index a68a957..849efad 100644 --- a/README.md +++ b/README.md @@ -169,7 +169,7 @@ TeleBot supports the following filters: |commands|list of strings|`True` if `message.content_type == 'text'` and `message.text` starts with a command that is in the list of strings.| |chat_types|list of chat types|`True` if `message.chat.type` in your filter |func|a function (lambda or function reference)|`True` if the lambda or function reference returns `True` - + Here are some examples of using the filters and message handlers: ```python @@ -287,6 +287,43 @@ def start(message): assert message.another_text == message.text + ':changed' ``` There are other examples using middleware handler in the [examples/middleware](examples/middleware) directory. + + +### Custom filters +Also, you can use built-in custom filters. Or, you can create your own filter. + +[Example of custom filter](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/custom_filters.py) + +Also, we have examples on them. Check this links: + +You can check some built-in filters in source [code](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/telebot/custom_filters.py) + +Example of [filtering by id](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/id_filter_example.py) + +Example of [filtering by text](https://github.com/eternnoir/pyTelegramBotAPI/blob/master/examples/text_filter_example.py) + +If you want to add some built-in filter, you are welcome to add it in custom_filters.py file. + +Here is example of creating filter-class: + +```python +class IsAdmin(util.SimpleCustomFilter): + # Class will check whether the user is admin or creator in group or not + key='is_admin' + @staticmethod + def check(message: telebot.types.Message): + return bot.get_chat_member(message.chat.id,message.from_user.id).status in ['administrator','creator'] + +# To register filter, you need to use method add_custom_filter. +bot.add_custom_filter(IsAdmin()) + +# Now, you can use it in handler. +@bot.message_handler(is_admin=True) +def admin_of_group(message): + bot.send_message(message.chat.id, 'You are admin of this group'!) + +``` + #### TeleBot ```python diff --git a/examples/custom_filters.py b/examples/custom_filters.py index e9e40e8..18c8c26 100644 --- a/examples/custom_filters.py +++ b/examples/custom_filters.py @@ -16,10 +16,7 @@ class IsAdmin(util.SimpleCustomFilter): key='is_admin' @staticmethod def check(message: telebot.types.Message): - if bot.get_chat_member(message.chat.id,message.from_user.id).status in ['administrator','creator']: - return True - else: - return False + return bot.get_chat_member(message.chat.id,message.from_user.id).status in ['administrator','creator'] @bot.message_handler(is_admin=True, commands=['admin']) # Check if user is admin diff --git a/examples/id_filter_example.py b/examples/id_filter_example.py new file mode 100644 index 0000000..3c83841 --- /dev/null +++ b/examples/id_filter_example.py @@ -0,0 +1,21 @@ +import telebot +from telebot import custom_filters + +bot = telebot.TeleBot('token') + + +# Chat id can be private or supergroups. +@bot.message_handler(chat_id=[12345678], commands=['admin']) # chat_id checks id corresponds to your list or not. +def admin_rep(message): + bot.send_message(message.chat.id, "You are allowed to use this command.") + +@bot.message_handler(commands=['admin']) +def not_admin(message): + bot.send_message(message.chat.id, "You are not allowed to use this command") + + +# Do not forget to register +bot.add_custom_filter(custom_filters.UserFilter()) + + +bot.polling(non_stop=True) \ No newline at end of file diff --git a/examples/text_filter_example.py b/examples/text_filter_example.py new file mode 100644 index 0000000..12b62f1 --- /dev/null +++ b/examples/text_filter_example.py @@ -0,0 +1,21 @@ +import telebot +from telebot import custom_filters + +bot = telebot.TeleBot('TOKEN') + + +# Check if message starts with @admin tag +@bot.message_handler(text_startswith="@admin") +def start_filter(message): + bot.send_message(message.chat.id, "Looks like you are calling admin, wait...") + +# Check if text is hi or hello +@bot.message_handler(text=['hi','hello']) +def text_filter(message): + bot.send_message(message.chat.id, "Hi, {name}!".format(name=message.from_user.first_name)) + +# Do not forget to register filters +bot.add_custom_filter(custom_filters.TextFilter()) +bot.add_custom_filter(custom_filters.TextStarts()) + +bot.polling(non_stop=True) \ No newline at end of file diff --git a/telebot/custom_filters.py b/telebot/custom_filters.py new file mode 100644 index 0000000..00b0f75 --- /dev/null +++ b/telebot/custom_filters.py @@ -0,0 +1,61 @@ +from telebot import util + + + +class TextFilter(util.AdvancedCustomFilter): + """ + Filter to check Text message. + key: text + + Example: + @bot.message_handler(text=['account']) + """ + + key = 'text' + + def check(self, message, text): + if type(text) is list:return message.text in text + else: return text == message.text + +class TextContains(util.AdvancedCustomFilter): + """ + Filter to check Text message. + key: text + + Example: + # Will respond if any message.text contains word 'account' + @bot.message_handler(text_contains=['account']) + """ + + key = 'text_contains' + + def check(self, message, text): + return text in message.text + +class UserFilter(util.AdvancedCustomFilter): + """ + Check whether chat_id corresponds to given chat_id. + + Example: + @bot.message_handler(chat_id=[99999]) + + """ + + key = 'chat_id' + def check(self, message, text): + return message.chat.id in text + + +class TextStarts(util.AdvancedCustomFilter): + """ + Filter to check whether message starts with some text. + + Example: + # Will work if message.text starts with 'Sir'. + @bot.message_handler(text_startswith='Sir') + + """ + + key = 'text_startswith' + def check(self, message, text): + return message.text.startswith(text) diff --git a/telebot/util.py b/telebot/util.py index 8607ff2..7bcb257 100644 --- a/telebot/util.py +++ b/telebot/util.py @@ -485,3 +485,5 @@ class AdvancedCustomFilter(ABC): Perform a check. """ pass + + \ No newline at end of file