Overhaul of Filters (#2759)

docs/source/conf.py

@@ -19,6 +19,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
+import inspect
 from docutils.nodes import Element
 from sphinx.application import Sphinx
 from sphinx.domains.python import PyXRefRole
@@ -358,7 +359,23 @@ def process_link(self, env: BuildEnvironment, refnode: Element,
 
 
 def autodoc_skip_member(app, what, name, obj, skip, options):
-    pass
+    """We use this to not document certain members like filter() or check_update() for filters.
+    See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#skipping-members"""
+
+    included = {'MessageFilter', 'UpdateFilter'}  # filter() and check_update() only for these.
+    included_in_obj = any(inc in repr(obj) for inc in included)
+
+    if included_in_obj:  # it's difficult to see if check_update is from an inherited-member or not
+        for frame in inspect.stack():  # From https://github.com/sphinx-doc/sphinx/issues/9533
+            if frame.function == "filter_members":
+                docobj = frame.frame.f_locals["self"].object
+                if not any(inc in str(docobj) for inc in included) and name == 'check_update':
+                    return True
+                break
+
+    if name == 'filter' and obj.__module__ == 'telegram.ext.filters':
+        if not included_in_obj:
+            return True  # return True to exclude from docs.
 
 
 def setup(app: Sphinx):

docs/source/telegram.ext.filters.rst

@@ -3,6 +3,11 @@
 telegram.ext.filters Module
 ===========================
 
+.. :bysource: since e.g filters.CHAT is much above filters.Chat() in the docs when it shouldn't.
+   The classes in `filters.py` are sorted alphabetically such that :bysource: still is readable
+
 .. automodule:: telegram.ext.filters
+    :inherited-members:
     :members:
     :show-inheritance:
+    :member-order: bysource

examples/conversationbot.py

@@ -20,7 +20,7 @@
 from telegram.ext import (
     CommandHandler,
     MessageHandler,
-    Filters,
+    filters,
     ConversationHandler,
     Updater,
     CallbackContext,
@@ -146,13 +146,13 @@ def main() -> None:
     conv_handler = ConversationHandler(
         entry_points=[CommandHandler('start', start)],
         states={
-            GENDER: [MessageHandler(Filters.regex('^(Boy|Girl|Other)$'), gender)],
-            PHOTO: [MessageHandler(Filters.photo, photo), CommandHandler('skip', skip_photo)],
+            GENDER: [MessageHandler(filters.Regex('^(Boy|Girl|Other)$'), gender)],
+            PHOTO: [MessageHandler(filters.PHOTO, photo), CommandHandler('skip', skip_photo)],
             LOCATION: [
-                MessageHandler(Filters.location, location),
+                MessageHandler(filters.LOCATION, location),
                 CommandHandler('skip', skip_location),
             ],
-            BIO: [MessageHandler(Filters.text & ~Filters.command, bio)],
+            BIO: [MessageHandler(filters.TEXT & ~filters.COMMAND, bio)],
         },
         fallbacks=[CommandHandler('cancel', cancel)],
     )

examples/conversationbot2.py

@@ -21,7 +21,7 @@
 from telegram.ext import (
     CommandHandler,
     MessageHandler,
-    Filters,
+    filters,
     ConversationHandler,
     Updater,
     CallbackContext,
@@ -126,23 +126,23 @@ def main() -> None:
         states={
             CHOOSING: [
                 MessageHandler(
-                    Filters.regex('^(Age|Favourite colour|Number of siblings)$'), regular_choice
+                    filters.Regex('^(Age|Favourite colour|Number of siblings)$'), regular_choice
                 ),
-                MessageHandler(Filters.regex('^Something else...$'), custom_choice),
+                MessageHandler(filters.Regex('^Something else...$'), custom_choice),
             ],
             TYPING_CHOICE: [
                 MessageHandler(
-                    Filters.text & ~(Filters.command | Filters.regex('^Done$')), regular_choice
+                    filters.TEXT & ~(filters.COMMAND | filters.Regex('^Done$')), regular_choice
                 )
             ],
             TYPING_REPLY: [
                 MessageHandler(
-                    Filters.text & ~(Filters.command | Filters.regex('^Done$')),
+                    filters.TEXT & ~(filters.COMMAND | filters.Regex('^Done$')),
                     received_information,
                 )
             ],
         },
-        fallbacks=[MessageHandler(Filters.regex('^Done$'), done)],
+        fallbacks=[MessageHandler(filters.Regex('^Done$'), done)],
     )
 
     dispatcher.add_handler(conv_handler)

examples/deeplinking.py

@@ -25,7 +25,7 @@
 from telegram.ext import (
     CommandHandler,
     CallbackQueryHandler,
-    Filters,
+    filters,
     Updater,
     CallbackContext,
 )
@@ -115,20 +115,20 @@ def main() -> None:
 
     # Register a deep-linking handler
     dispatcher.add_handler(
-        CommandHandler("start", deep_linked_level_1, Filters.regex(CHECK_THIS_OUT))
+        CommandHandler("start", deep_linked_level_1, filters.Regex(CHECK_THIS_OUT))
     )
 
     # This one works with a textual link instead of an URL
-    dispatcher.add_handler(CommandHandler("start", deep_linked_level_2, Filters.regex(SO_COOL)))
+    dispatcher.add_handler(CommandHandler("start", deep_linked_level_2, filters.Regex(SO_COOL)))
 
     # We can also pass on the deep-linking payload
     dispatcher.add_handler(
-        CommandHandler("start", deep_linked_level_3, Filters.regex(USING_ENTITIES))
+        CommandHandler("start", deep_linked_level_3, filters.Regex(USING_ENTITIES))
     )
 
     # Possible with inline keyboard buttons as well
     dispatcher.add_handler(
-        CommandHandler("start", deep_linked_level_4, Filters.regex(USING_KEYBOARD))
+        CommandHandler("start", deep_linked_level_4, filters.Regex(USING_KEYBOARD))
     )
 
     # register callback handler for inline keyboard button

examples/echobot.py

@@ -21,7 +21,7 @@
 from telegram.ext import (
     CommandHandler,
     MessageHandler,
-    Filters,
+    filters,
     Updater,
     CallbackContext,
 )
@@ -68,7 +68,7 @@ def main() -> None:
     dispatcher.add_handler(CommandHandler("help", help_command))
 
     # on non command i.e message - echo the message on Telegram
-    dispatcher.add_handler(MessageHandler(Filters.text & ~Filters.command, echo))
+    dispatcher.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
 
     # Start the Bot
     updater.start_polling()

examples/nestedconversationbot.py

@@ -21,7 +21,7 @@
 from telegram.ext import (
     CommandHandler,
     MessageHandler,
-    Filters,
+    filters,
     ConversationHandler,
     CallbackQueryHandler,
     Updater,
@@ -319,7 +319,7 @@ def main() -> None:
             SELECTING_FEATURE: [
                 CallbackQueryHandler(ask_for_input, pattern='^(?!' + str(END) + ').*$')
             ],
-            TYPING: [MessageHandler(Filters.text & ~Filters.command, save_input)],
+            TYPING: [MessageHandler(filters.TEXT & ~filters.COMMAND, save_input)],
         },
         fallbacks=[
             CallbackQueryHandler(end_describing, pattern='^' + str(END) + '$'),

examples/passportbot.py

@@ -14,7 +14,7 @@
 from pathlib import Path
 
 from telegram import Update
-from telegram.ext import MessageHandler, Filters, Updater, CallbackContext
+from telegram.ext import MessageHandler, filters, Updater, CallbackContext
 
 # Enable logging
 
@@ -110,7 +110,7 @@ def main() -> None:
     dispatcher = updater.dispatcher
 
     # On messages that include passport data call msg
-    dispatcher.add_handler(MessageHandler(Filters.passport_data, msg))
+    dispatcher.add_handler(MessageHandler(filters.PASSPORT_DATA, msg))
 
     # Start the Bot
     updater.start_polling()

examples/paymentbot.py

@@ -10,7 +10,7 @@
 from telegram.ext import (
     CommandHandler,
     MessageHandler,
-    Filters,
+    filters,
     PreCheckoutQueryHandler,
     ShippingQueryHandler,
     Updater,
@@ -149,7 +149,7 @@ def main() -> None:
     dispatcher.add_handler(PreCheckoutQueryHandler(precheckout_callback))
 
     # Success! Notify your user!
-    dispatcher.add_handler(MessageHandler(Filters.successful_payment, successful_payment_callback))
+    dispatcher.add_handler(MessageHandler(filters.SUCCESSFUL_PAYMENT, successful_payment_callback))
 
     # Start the Bot
     updater.start_polling()

examples/persistentconversationbot.py

@@ -21,7 +21,7 @@
 from telegram.ext import (
     CommandHandler,
     MessageHandler,
-    Filters,
+    filters,
     ConversationHandler,
     PicklePersistence,
     Updater,
@@ -144,23 +144,23 @@ def main() -> None:
         states={
             CHOOSING: [
                 MessageHandler(
-                    Filters.regex('^(Age|Favourite colour|Number of siblings)$'), regular_choice
+                    filters.Regex('^(Age|Favourite colour|Number of siblings)$'), regular_choice
                 ),
-                MessageHandler(Filters.regex('^Something else...$'), custom_choice),
+                MessageHandler(filters.Regex('^Something else...$'), custom_choice),
             ],
             TYPING_CHOICE: [
                 MessageHandler(
-                    Filters.text & ~(Filters.command | Filters.regex('^Done$')), regular_choice
+                    filters.TEXT & ~(filters.COMMAND | filters.Regex('^Done$')), regular_choice
                 )
             ],
             TYPING_REPLY: [
                 MessageHandler(
-                    Filters.text & ~(Filters.command | Filters.regex('^Done$')),
+                    filters.TEXT & ~(filters.COMMAND | filters.Regex('^Done$')),
                     received_information,
                 )
             ],
         },
-        fallbacks=[MessageHandler(Filters.regex('^Done$'), done)],
+        fallbacks=[MessageHandler(filters.Regex('^Done$'), done)],
         name="my_conversation",
         persistent=True,
     )

examples/pollbot.py

@@ -23,7 +23,7 @@
     PollAnswerHandler,
     PollHandler,
     MessageHandler,
-    Filters,
+    filters,
     Updater,
     CallbackContext,
 )
@@ -163,7 +163,7 @@ def main() -> None:
     dispatcher.add_handler(CommandHandler('quiz', quiz))
     dispatcher.add_handler(PollHandler(receive_quiz_answer))
     dispatcher.add_handler(CommandHandler('preview', preview))
-    dispatcher.add_handler(MessageHandler(Filters.poll, receive_poll))
+    dispatcher.add_handler(MessageHandler(filters.POLL, receive_poll))
     dispatcher.add_handler(CommandHandler('help', help_handler))
 
     # Start the Bot

telegram/ext/__init__.py

@@ -31,7 +31,7 @@
 from ._callbackqueryhandler import CallbackQueryHandler
 from ._choseninlineresulthandler import ChosenInlineResultHandler
 from ._inlinequeryhandler import InlineQueryHandler
-from .filters import BaseFilter, MessageFilter, UpdateFilter, Filters
+from . import filters
 from ._messagehandler import MessageHandler
 from ._commandhandler import CommandHandler, PrefixHandler
 from ._stringcommandhandler import StringCommandHandler
@@ -49,7 +49,6 @@
 from ._builders import DispatcherBuilder, UpdaterBuilder
 
 __all__ = (
-    'BaseFilter',
     'BasePersistence',
     'CallbackContext',
     'CallbackDataCache',
@@ -66,13 +65,12 @@
     'DispatcherBuilder',
     'DispatcherHandlerStop',
     'ExtBot',
-    'Filters',
+    'filters',
     'Handler',
     'InlineQueryHandler',
     'InvalidCallbackData',
     'Job',
     'JobQueue',
-    'MessageFilter',
     'MessageHandler',
     'PersistenceInput',
     'PicklePersistence',
@@ -84,7 +82,6 @@
     'StringCommandHandler',
     'StringRegexHandler',
     'TypeHandler',
-    'UpdateFilter',
     'Updater',
     'UpdaterBuilder',
 )

telegram/ext/_basepersistence.py

@@ -29,7 +29,7 @@
 from telegram.ext._utils.types import UD, CD, BD, ConversationDict, CDCData
 
 
-class PersistenceInput(NamedTuple):
+class PersistenceInput(NamedTuple):  # skipcq: PYL-E0239
     """Convenience wrapper to group boolean input for :class:`BasePersistence`.
 
     Args:

telegram/ext/_callbackcontext.py

@@ -68,10 +68,9 @@ class CallbackContext(Generic[BT, UD, CD, BD]):
 
     Attributes:
         matches (List[:obj:`re match object`]): Optional. If the associated update originated from
-            a regex-supported handler or had a :class:`Filters.regex`, this will contain a list of
-            match objects for every pattern where ``re.search(pattern, string)`` returned a match.
-            Note that filters short circuit, so combined regex filters will not always
-            be evaluated.
+            a :class:`filters.Regex`, this will contain a list of match objects for every pattern
+            where ``re.search(pattern, string)`` returned a match. Note that filters short circuit,
+            so combined regex filters will not always be evaluated.
         args (List[:obj:`str`]): Optional. Arguments passed to a command if the associated update
             is handled by :class:`telegram.ext.CommandHandler`, :class:`telegram.ext.PrefixHandler`
             or :class:`telegram.ext.StringCommandHandler`. It contains a list of the words in the