Merge pull request #1302 from coder2020official/master

Some useful filters

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

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

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)

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)

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) 

telebot/util.py

@@ -485,3 +485,5 @@ class AdvancedCustomFilter(ABC):
         Perform a check.
         """
         pass
+
+