README.md edited

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/basehandler.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the base class for handlers as used by the Application."""
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Generic, Optional, TypeVar, Union
+
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.repr import build_repr_with_selected_attrs
+from telegram._utils.types import DVType
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+if TYPE_CHECKING:
+    from telegram.ext import Application
+
+RT = TypeVar("RT")
+UT = TypeVar("UT")
+
+
+class BaseHandler(Generic[UT, CCT, RT], ABC):
+    """The base class for all update handlers. Create custom handlers by inheriting from it.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    This class is a :class:`~typing.Generic` class and accepts three type variables:
+
+    1. The type of the updates that this handler will handle. Must coincide with the type of the
+       first argument of :paramref:`callback`. :meth:`check_update` must only accept
+       updates of this type.
+    2. The type of the second argument of :paramref:`callback`. Must coincide with the type of the
+       parameters :paramref:`handle_update.context` and
+       :paramref:`collect_additional_context.context` as well as the second argument of
+       :paramref:`callback`. Must be either :class:`~telegram.ext.CallbackContext` or a subclass
+       of that class.
+
+       .. tip::
+           For this type variable, one should usually provide a :class:`~typing.TypeVar` that is
+           also used for the mentioned method arguments. That way, a type checker can check whether
+           this handler fits the definition of the :class:`~Application`.
+    3. The return type of the :paramref:`callback` function accepted by this handler.
+
+    .. seealso:: :wiki:`Types of Handlers <Types-of-Handlers>`
+
+    .. versionchanged:: 20.0
+
+        * The attribute ``run_async`` is now :paramref:`block`.
+        * This class was previously named ``Handler``.
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the callback will run in a blocking way.
+
+    """
+
+    __slots__ = (
+        "block",
+        "callback",
+    )
+
+    def __init__(
+        self: "BaseHandler[UT, CCT, RT]",
+        callback: HandlerCallback[UT, CCT, RT],
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        self.callback: HandlerCallback[UT, CCT, RT] = callback
+        self.block: DVType[bool] = block
+
+    def __repr__(self) -> str:
+        """Give a string representation of the handler in the form ``ClassName[callback=...]``.
+
+        As this class doesn't implement :meth:`object.__str__`, the default implementation
+        will be used, which is equivalent to :meth:`__repr__`.
+
+        Returns:
+            :obj:`str`
+        """
+        try:
+            callback_name = self.callback.__qualname__
+        except AttributeError:
+            callback_name = repr(self.callback)
+        return build_repr_with_selected_attrs(self, callback=callback_name)
+
+    @abstractmethod
+    def check_update(self, update: object) -> Optional[Union[bool, object]]:
+        """
+        This method is called to determine if an update should be handled by
+        this handler instance. It should always be overridden.
+
+        Note:
+            Custom updates types can be handled by the application. Therefore, an implementation of
+            this method should always check the type of :paramref:`update`.
+
+        Args:
+            update (:obj:`object` | :class:`telegram.Update`): The update to be tested.
+
+        Returns:
+            Either :obj:`None` or :obj:`False` if the update should not be handled. Otherwise an
+            object that will be passed to :meth:`handle_update` and
+            :meth:`collect_additional_context` when the update gets handled.
+
+        """
+
+    async def handle_update(
+        self,
+        update: UT,
+        application: "Application[Any, CCT, Any, Any, Any, Any]",
+        check_result: object,
+        context: CCT,
+    ) -> RT:
+        """
+        This method is called if it was determined that an update should indeed
+        be handled by this instance. Calls :attr:`callback` along with its respectful
+        arguments. To work with the :class:`telegram.ext.ConversationHandler`, this method
+        returns the value returned from :attr:`callback`.
+        Note that it can be overridden if needed by the subclassing handler.
+
+        Args:
+            update (:obj:`str` | :class:`telegram.Update`): The update to be handled.
+            application (:class:`telegram.ext.Application`): The calling application.
+            check_result (:class:`object`): The result from :meth:`check_update`.
+            context (:class:`telegram.ext.CallbackContext`): The context as provided by
+                the application.
+
+        """
+        self.collect_additional_context(context, update, application, check_result)
+        return await self.callback(update, context)
+
+    def collect_additional_context(
+        self,
+        context: CCT,
+        update: UT,
+        application: "Application[Any, CCT, Any, Any, Any, Any]",
+        check_result: Any,
+    ) -> None:
+        """Prepares additional arguments for the context. Override if needed.
+
+        Args:
+            context (:class:`telegram.ext.CallbackContext`): The context object.
+            update (:class:`telegram.Update`): The update to gather chat/user id from.
+            application (:class:`telegram.ext.Application`): The calling application.
+            check_result: The result (return value) from :meth:`check_update`.
+
+        """

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/businessconnectionhandler.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the BusinessConnectionHandler class."""
+from typing import Optional, TypeVar
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import SCT, DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils._update_parsing import parse_chat_id, parse_username
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+RT = TypeVar("RT")
+
+
+class BusinessConnectionHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram
+    :attr:`Business Connections <telegram.Update.business_connection>`.
+
+    .. versionadded:: 21.1
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+        user_id (:obj:`int` | Collection[:obj:`int`], optional): Filters requests to allow only
+            those which are from the specified user ID(s).
+
+        username (:obj:`str` | Collection[:obj:`str`], optional): Filters requests to allow only
+            those which are from the specified username(s).
+
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+    """
+
+    __slots__ = (
+        "_user_ids",
+        "_usernames",
+    )
+
+    def __init__(
+        self: "BusinessConnectionHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        user_id: Optional[SCT[int]] = None,
+        username: Optional[SCT[str]] = None,
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback, block=block)
+
+        self._user_ids = parse_chat_id(user_id)
+        self._usernames = parse_username(username)
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if isinstance(update, Update) and update.business_connection:
+            if not self._user_ids and not self._usernames:
+                return True
+            if update.business_connection.user.id in self._user_ids:
+                return True
+            return update.business_connection.user.username in self._usernames
+        return False

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/businessmessagesdeletedhandler.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the BusinessMessagesDeletedHandler class."""
+from typing import Optional, TypeVar
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import SCT, DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils._update_parsing import parse_chat_id, parse_username
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+RT = TypeVar("RT")
+
+
+class BusinessMessagesDeletedHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle
+    :attr:`deleted Telegram Business messages <telegram.Update.deleted_business_messages>`.
+
+    .. versionadded:: 21.1
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+        chat_id (:obj:`int` | Collection[:obj:`int`], optional): Filters requests to allow only
+            those which are from the specified chat ID(s).
+
+        username (:obj:`str` | Collection[:obj:`str`], optional): Filters requests to allow only
+            those which are from the specified username(s).
+
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+    """
+
+    __slots__ = (
+        "_chat_ids",
+        "_usernames",
+    )
+
+    def __init__(
+        self: "BusinessMessagesDeletedHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        chat_id: Optional[SCT[int]] = None,
+        username: Optional[SCT[str]] = None,
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback, block=block)
+
+        self._chat_ids = parse_chat_id(chat_id)
+        self._usernames = parse_username(username)
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if isinstance(update, Update) and update.deleted_business_messages:
+            if not self._chat_ids and not self._usernames:
+                return True
+            if update.deleted_business_messages.chat.id in self._chat_ids:
+                return True
+            return update.deleted_business_messages.chat.username in self._usernames
+        return False

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/callbackqueryhandler.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the CallbackQueryHandler class."""
+import asyncio
+import re
+from re import Match, Pattern
+from typing import TYPE_CHECKING, Any, Callable, Optional, TypeVar, Union, cast
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+if TYPE_CHECKING:
+    from telegram.ext import Application
+
+RT = TypeVar("RT")
+
+
+class CallbackQueryHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram
+    :attr:`callback queries <telegram.Update.callback_query>`. Optionally based on a regex.
+
+    Read the documentation of the :mod:`re` module for more information.
+
+    Note:
+        * If your bot allows arbitrary objects as
+          :paramref:`~telegram.InlineKeyboardButton.callback_data`, it may happen that the
+          original :attr:`~telegram.InlineKeyboardButton.callback_data` for the incoming
+          :class:`telegram.CallbackQuery` can not be found. This is the case when either a
+          malicious client tempered with the :attr:`telegram.CallbackQuery.data` or the data was
+          simply dropped from cache or not persisted. In these
+          cases, an instance of :class:`telegram.ext.InvalidCallbackData` will be set as
+          :attr:`telegram.CallbackQuery.data`.
+
+          .. versionadded:: 13.6
+
+        * If neither :paramref:`pattern` nor :paramref:`game_pattern` is set, `any`
+          ``CallbackQuery`` will be handled. If only :paramref:`pattern` is set, queries with
+          :attr:`~telegram.CallbackQuery.game_short_name` will `not` be considered and vice versa.
+          If both patterns are set, queries with either :attr:
+          `~telegram.CallbackQuery.game_short_name` or :attr:`~telegram.CallbackQuery.data`
+          matching the defined pattern will be handled
+
+          .. versionadded:: 21.5
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        pattern (:obj:`str` | :func:`re.Pattern <re.compile>` | :obj:`callable` | :obj:`type`, \
+            optional):
+            Pattern to test :attr:`telegram.CallbackQuery.data` against. If a string or a regex
+            pattern is passed, :func:`re.match` is used on :attr:`telegram.CallbackQuery.data` to
+            determine if an update should be handled by this handler. If your bot allows arbitrary
+            objects as :paramref:`~telegram.InlineKeyboardButton.callback_data`, non-strings will
+            be accepted. To filter arbitrary objects you may pass:
+
+            - a callable, accepting exactly one argument, namely the
+              :attr:`telegram.CallbackQuery.data`. It must return :obj:`True` or
+              :obj:`False`/:obj:`None` to indicate, whether the update should be handled.
+            - a :obj:`type`. If :attr:`telegram.CallbackQuery.data` is an instance of that type
+              (or a subclass), the update will be handled.
+
+            If :attr:`telegram.CallbackQuery.data` is :obj:`None`, the
+            :class:`telegram.CallbackQuery` update will not be handled.
+
+            .. seealso:: :wiki:`Arbitrary callback_data <Arbitrary-callback_data>`
+
+            .. versionchanged:: 13.6
+               Added support for arbitrary callback data.
+        game_pattern (:obj:`str` | :func:`re.Pattern <re.compile>` | optional)
+            Pattern to test :attr:`telegram.CallbackQuery.game_short_name` against. If a string or
+            a regex pattern is passed, :func:`re.match` is used on
+            :attr:`telegram.CallbackQuery.game_short_name` to determine if an update should be
+            handled by this handler.
+
+            .. versionadded:: 21.5
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        pattern (:func:`re.Pattern <re.compile>` | :obj:`callable` | :obj:`type`): Optional.
+            Regex pattern, callback or type to test :attr:`telegram.CallbackQuery.data` against.
+
+            .. versionchanged:: 13.6
+               Added support for arbitrary callback data.
+        game_pattern (:func:`re.Pattern <re.compile>`): Optional.
+            Regex pattern to test :attr:`telegram.CallbackQuery.game_short_name`
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+
+    """
+
+    __slots__ = ("game_pattern", "pattern")
+
+    def __init__(
+        self: "CallbackQueryHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        pattern: Optional[
+            Union[str, Pattern[str], type, Callable[[object], Optional[bool]]]
+        ] = None,
+        game_pattern: Optional[Union[str, Pattern[str]]] = None,
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback, block=block)
+
+        if callable(pattern) and asyncio.iscoroutinefunction(pattern):
+            raise TypeError(
+                "The `pattern` must not be a coroutine function! Use an ordinary function instead."
+            )
+        if isinstance(pattern, str):
+            pattern = re.compile(pattern)
+
+        if isinstance(game_pattern, str):
+            game_pattern = re.compile(game_pattern)
+        self.pattern: Optional[
+            Union[str, Pattern[str], type, Callable[[object], Optional[bool]]]
+        ] = pattern
+        self.game_pattern: Optional[Union[str, Pattern[str]]] = game_pattern
+
+    def check_update(self, update: object) -> Optional[Union[bool, object]]:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        # pylint: disable=too-many-return-statements
+        if not (isinstance(update, Update) and update.callback_query):
+            return None
+
+        callback_data = update.callback_query.data
+        game_short_name = update.callback_query.game_short_name
+
+        if not any([self.pattern, self.game_pattern]):
+            return True
+
+        # we check for .data or .game_short_name from update to filter based on whats coming
+        # this gives xor-like behavior
+        if callback_data:
+            if not self.pattern:
+                return False
+            if isinstance(self.pattern, type):
+                return isinstance(callback_data, self.pattern)
+            if callable(self.pattern):
+                return self.pattern(callback_data)
+            if not isinstance(callback_data, str):
+                return False
+            if match := re.match(self.pattern, callback_data):
+                return match
+
+        elif game_short_name:
+            if not self.game_pattern:
+                return False
+            if match := re.match(self.game_pattern, game_short_name):
+                return match
+        else:
+            return True
+        return False
+
+    def collect_additional_context(
+        self,
+        context: CCT,
+        update: Update,  # noqa: ARG002
+        application: "Application[Any, CCT, Any, Any, Any, Any]",  # noqa: ARG002
+        check_result: Union[bool, Match[str]],
+    ) -> None:
+        """Add the result of ``re.match(pattern, update.callback_query.data)`` to
+        :attr:`CallbackContext.matches` as list with one element.
+        """
+        if self.pattern:
+            check_result = cast(Match, check_result)
+            context.matches = [check_result]

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/chatboosthandler.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the ChatBoostHandler class."""
+
+from typing import Final, Optional
+
+from telegram import Update
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils._update_parsing import parse_chat_id, parse_username
+from telegram.ext._utils.types import CCT, RT, HandlerCallback
+
+
+class ChatBoostHandler(BaseHandler[Update, CCT, RT]):
+    """
+    Handler class to handle Telegram updates that contain a chat boost.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    .. versionadded:: 20.8
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        chat_boost_types (:obj:`int`, optional): Pass one of
+            :attr:`CHAT_BOOST`, :attr:`REMOVED_CHAT_BOOST` or
+            :attr:`ANY_CHAT_BOOST` to specify if this handler should handle only updates with
+            :attr:`telegram.Update.chat_boost`,
+            :attr:`telegram.Update.removed_chat_boost` or both. Defaults to
+            :attr:`CHAT_BOOST`.
+        chat_id (:obj:`int` | Collection[:obj:`int`], optional): Filters reactions to allow
+            only those which happen in the specified chat ID(s).
+        chat_username (:obj:`str` | Collection[:obj:`str`], optional): Filters reactions to allow
+            only those which happen in the specified username(s).
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        chat_boost_types (:obj:`int`): Optional. Specifies if this handler should handle only
+            updates with :attr:`telegram.Update.chat_boost`,
+            :attr:`telegram.Update.removed_chat_boost` or both.
+        block (:obj:`bool`): Determines whether the callback will run in a blocking way.
+    """
+
+    __slots__ = (
+        "_chat_ids",
+        "_chat_usernames",
+        "chat_boost_types",
+    )
+
+    CHAT_BOOST: Final[int] = -1
+    """ :obj:`int`: Used as a constant to handle only :attr:`telegram.Update.chat_boost`."""
+    REMOVED_CHAT_BOOST: Final[int] = 0
+    """:obj:`int`: Used as a constant to handle only :attr:`telegram.Update.removed_chat_boost`."""
+    ANY_CHAT_BOOST: Final[int] = 1
+    """:obj:`int`: Used as a constant to handle both :attr:`telegram.Update.chat_boost`
+    and :attr:`telegram.Update.removed_chat_boost`."""
+
+    def __init__(
+        self: "ChatBoostHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        chat_boost_types: int = CHAT_BOOST,
+        chat_id: Optional[int] = None,
+        chat_username: Optional[str] = None,
+        block: bool = True,
+    ):
+        super().__init__(callback, block=block)
+        self.chat_boost_types: int = chat_boost_types
+        self._chat_ids = parse_chat_id(chat_id)
+        self._chat_usernames = parse_username(chat_username)
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if not isinstance(update, Update):
+            return False
+
+        if not (update.chat_boost or update.removed_chat_boost):
+            return False
+
+        if self.chat_boost_types == self.CHAT_BOOST and not update.chat_boost:
+            return False
+
+        if self.chat_boost_types == self.REMOVED_CHAT_BOOST and not update.removed_chat_boost:
+            return False
+
+        if not any((self._chat_ids, self._chat_usernames)):
+            return True
+
+        # Extract chat and user IDs and usernames from the update for comparison
+        chat_id = chat.id if (chat := update.effective_chat) else None
+        chat_username = chat.username if chat else None
+
+        return bool(self._chat_ids and (chat_id in self._chat_ids)) or bool(
+            self._chat_usernames and (chat_username in self._chat_usernames)
+        )

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/chatjoinrequesthandler.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the ChatJoinRequestHandler class."""
+
+from typing import Optional
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import RT, SCT, DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils._update_parsing import parse_chat_id, parse_username
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+
+class ChatJoinRequestHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram updates that contain
+    :attr:`telegram.Update.chat_join_request`.
+
+    Note:
+        If neither of :paramref:`username` and the :paramref:`chat_id` are passed, this handler
+        accepts *any* join request. Otherwise, this handler accepts all requests to join chats
+        for which the chat ID is listed in :paramref:`chat_id` or the username is listed in
+        :paramref:`username`, or both.
+
+        .. versionadded:: 20.0
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    .. versionadded:: 13.8
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        chat_id (:obj:`int` | Collection[:obj:`int`], optional): Filters requests to allow only
+            those which are asking to join the specified chat ID(s).
+
+            .. versionadded:: 20.0
+        username (:obj:`str` | Collection[:obj:`str`], optional): Filters requests to allow only
+            those which are asking to join the specified username(s).
+
+            .. versionadded:: 20.0
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the callback will run in a blocking way..
+
+    """
+
+    __slots__ = (
+        "_chat_ids",
+        "_usernames",
+    )
+
+    def __init__(
+        self: "ChatJoinRequestHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        chat_id: Optional[SCT[int]] = None,
+        username: Optional[SCT[str]] = None,
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback, block=block)
+
+        self._chat_ids = parse_chat_id(chat_id)
+        self._usernames = parse_username(username)
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if isinstance(update, Update) and update.chat_join_request:
+            if not self._chat_ids and not self._usernames:
+                return True
+            if update.chat_join_request.chat.id in self._chat_ids:
+                return True
+            return update.chat_join_request.from_user.username in self._usernames
+        return False

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/chatmemberhandler.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the ChatMemberHandler class."""
+from typing import Final, Optional, TypeVar
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import SCT, DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils._update_parsing import parse_chat_id
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+RT = TypeVar("RT")
+
+
+class ChatMemberHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram updates that contain a chat member update.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Examples:
+        :any:`Chat Member Bot <examples.chatmemberbot>`
+
+    .. versionadded:: 13.4
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        chat_member_types (:obj:`int`, optional): Pass one of :attr:`MY_CHAT_MEMBER`,
+            :attr:`CHAT_MEMBER` or :attr:`ANY_CHAT_MEMBER` to specify if this handler should handle
+            only updates with :attr:`telegram.Update.my_chat_member`,
+            :attr:`telegram.Update.chat_member` or both. Defaults to :attr:`MY_CHAT_MEMBER`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+        chat_id (:obj:`int` | Collection[:obj:`int`], optional): Filters chat member updates from
+            specified chat ID(s) only.
+            .. versionadded:: 21.3
+
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        chat_member_types (:obj:`int`): Optional. Specifies if this handler should handle
+            only updates with :attr:`telegram.Update.my_chat_member`,
+            :attr:`telegram.Update.chat_member` or both.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+
+    """
+
+    __slots__ = (
+        "_chat_ids",
+        "chat_member_types",
+    )
+    MY_CHAT_MEMBER: Final[int] = -1
+    """:obj:`int`: Used as a constant to handle only :attr:`telegram.Update.my_chat_member`."""
+    CHAT_MEMBER: Final[int] = 0
+    """:obj:`int`: Used as a constant to handle only :attr:`telegram.Update.chat_member`."""
+    ANY_CHAT_MEMBER: Final[int] = 1
+    """:obj:`int`: Used as a constant to handle both :attr:`telegram.Update.my_chat_member`
+    and :attr:`telegram.Update.chat_member`."""
+
+    def __init__(
+        self: "ChatMemberHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        chat_member_types: int = MY_CHAT_MEMBER,
+        block: DVType[bool] = DEFAULT_TRUE,
+        chat_id: Optional[SCT[int]] = None,
+    ):
+        super().__init__(callback, block=block)
+
+        self.chat_member_types: Optional[int] = chat_member_types
+        self._chat_ids = parse_chat_id(chat_id)
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if not isinstance(update, Update):
+            return False
+        if not (update.my_chat_member or update.chat_member):
+            return False
+        if (
+            self._chat_ids
+            and update.effective_chat
+            and update.effective_chat.id not in self._chat_ids
+        ):
+            return False
+        if self.chat_member_types == self.ANY_CHAT_MEMBER:
+            return True
+        if self.chat_member_types == self.CHAT_MEMBER:
+            return bool(update.chat_member)
+        return bool(update.my_chat_member)

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/choseninlineresulthandler.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the ChosenInlineResultHandler class."""
+import re
+from re import Match, Pattern
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union, cast
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+RT = TypeVar("RT")
+
+if TYPE_CHECKING:
+    from telegram.ext import Application
+
+
+class ChosenInlineResultHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram updates that contain
+    :attr:`telegram.Update.chosen_inline_result`.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+        pattern (:obj:`str` | :func:`re.Pattern <re.compile>`, optional): Regex pattern. If not
+            :obj:`None`, :func:`re.match`
+            is used on :attr:`telegram.ChosenInlineResult.result_id` to determine if an update
+            should be handled by this handler. This is accessible in the callback as
+            :attr:`telegram.ext.CallbackContext.matches`.
+
+            .. versionadded:: 13.6
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+        pattern (`Pattern`): Optional. Regex pattern to test
+            :attr:`telegram.ChosenInlineResult.result_id` against.
+
+            .. versionadded:: 13.6
+
+    """
+
+    __slots__ = ("pattern",)
+
+    def __init__(
+        self: "ChosenInlineResultHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        block: DVType[bool] = DEFAULT_TRUE,
+        pattern: Optional[Union[str, Pattern[str]]] = None,
+    ):
+        super().__init__(callback, block=block)
+
+        if isinstance(pattern, str):
+            pattern = re.compile(pattern)
+
+        self.pattern: Optional[Union[str, Pattern[str]]] = pattern
+
+    def check_update(self, update: object) -> Optional[Union[bool, object]]:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool` | :obj:`re.match`
+
+        """
+        if isinstance(update, Update) and update.chosen_inline_result:
+            if self.pattern:
+                if match := re.match(self.pattern, update.chosen_inline_result.result_id):
+                    return match
+            else:
+                return True
+        return None
+
+    def collect_additional_context(
+        self,
+        context: CCT,
+        update: Update,  # noqa: ARG002
+        application: "Application[Any, CCT, Any, Any, Any, Any]",  # noqa: ARG002
+        check_result: Union[bool, Match[str]],
+    ) -> None:
+        """This function adds the matched regex pattern result to
+        :attr:`telegram.ext.CallbackContext.matches`.
+        """
+        if self.pattern:
+            check_result = cast(Match, check_result)
+            context.matches = [check_result]

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/commandhandler.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the CommandHandler class."""
+import re
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
+
+from telegram import MessageEntity, Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import SCT, DVType
+from telegram.ext import filters as filters_module
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, FilterDataDict, HandlerCallback
+
+if TYPE_CHECKING:
+    from telegram.ext import Application
+
+RT = TypeVar("RT")
+
+
+class CommandHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram commands.
+
+    Commands are Telegram messages that start with a :attr:`telegram.MessageEntity.BOT_COMMAND`
+    (so with ``/``, optionally followed by an ``@`` and the bot's name and/or some additional
+    text). The handler will add a :obj:`list` to the :class:`CallbackContext` named
+    :attr:`CallbackContext.args`. It will contain a list of strings, which is the text following
+    the command split on single or consecutive whitespace characters.
+
+    By default, the handler listens to messages as well as edited messages. To change this behavior
+    use :attr:`~filters.UpdateType.EDITED_MESSAGE <telegram.ext.filters.UpdateType.EDITED_MESSAGE>`
+    in the filter argument.
+
+    Note:
+        :class:`CommandHandler` does *not* handle (edited) channel posts and does *not* handle
+        commands that are part of a caption. Please use :class:`~telegram.ext.MessageHandler`
+        with a suitable combination of filters (e.g.
+        :attr:`telegram.ext.filters.UpdateType.CHANNEL_POSTS`,
+        :attr:`telegram.ext.filters.CAPTION` and :class:`telegram.ext.filters.Regex`) to handle
+        those messages.
+
+    Note:
+        If you want to support a different entity in the beginning, e.g. if a command message is
+        wrapped in a :attr:`telegram.MessageEntity.CODE`, use the
+        :class:`telegram.ext.PrefixHandler`.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Examples:
+        * :any:`Timer Bot <examples.timerbot>`
+        * :any:`Error Handler Bot <examples.errorhandlerbot>`
+
+    .. versionchanged:: 20.0
+
+        * Renamed the attribute ``command`` to :attr:`commands`, which now is always a
+          :class:`frozenset`
+        * Updating the commands this handler listens to is no longer possible.
+
+    Args:
+        command (:obj:`str` | Collection[:obj:`str`]):
+            The command or list of commands this handler should listen for. Case-insensitive.
+            Limitations are the same as for :attr:`telegram.BotCommand.command`.
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        filters (:class:`telegram.ext.filters.BaseFilter`, optional): A filter inheriting from
+            :class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
+            :mod:`telegram.ext.filters`. Filters can be combined using bitwise
+            operators (``&`` for :keyword:`and`, ``|`` for :keyword:`or`, ``~`` for :keyword:`not`)
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+        has_args (:obj:`bool` | :obj:`int`, optional):
+            Determines whether the command handler should process the update or not.
+            If :obj:`True`, the handler will process any non-zero number of args.
+            If :obj:`False`, the handler will only process if there are no args.
+            if :obj:`int`, the handler will only process if there are exactly that many args.
+            Defaults to :obj:`None`, which means the handler will process any or no args.
+
+            .. versionadded:: 20.5
+
+    Raises:
+        :exc:`ValueError`: When the command is too long or has illegal chars.
+
+    Attributes:
+        commands (frozenset[:obj:`str`]): The set of commands this handler should listen for.
+        callback (:term:`coroutine function`): The callback function for this handler.
+        filters (:class:`telegram.ext.filters.BaseFilter`): Optional. Only allow updates with these
+            filters.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+        has_args (:obj:`bool` | :obj:`int` | None):
+            Optional argument, otherwise all implementations of :class:`CommandHandler` will break.
+            Defaults to :obj:`None`, which means the handler will process any args or no args.
+
+            .. versionadded:: 20.5
+    """
+
+    __slots__ = ("commands", "filters", "has_args")
+
+    def __init__(
+        self: "CommandHandler[CCT, RT]",
+        command: SCT[str],
+        callback: HandlerCallback[Update, CCT, RT],
+        filters: Optional[filters_module.BaseFilter] = None,
+        block: DVType[bool] = DEFAULT_TRUE,
+        has_args: Optional[Union[bool, int]] = None,
+    ):
+        super().__init__(callback, block=block)
+
+        if isinstance(command, str):
+            commands = frozenset({command.lower()})
+        else:
+            commands = frozenset(x.lower() for x in command)
+        for comm in commands:
+            if not re.match(r"^[\da-z_]{1,32}$", comm):
+                raise ValueError(f"Command `{comm}` is not a valid bot command")
+        self.commands: frozenset[str] = commands
+
+        self.filters: filters_module.BaseFilter = (
+            filters if filters is not None else filters_module.UpdateType.MESSAGES
+        )
+
+        self.has_args: Optional[Union[bool, int]] = has_args
+
+        if (isinstance(self.has_args, int)) and (self.has_args < 0):
+            raise ValueError("CommandHandler argument has_args cannot be a negative integer")
+
+    def _check_correct_args(self, args: list[str]) -> Optional[bool]:
+        """Determines whether the args are correct for this handler. Implemented in check_update().
+        Args:
+            args (:obj:`list`): The args for the handler.
+        Returns:
+            :obj:`bool`: Whether the args are valid for this handler.
+        """
+        return bool(
+            (self.has_args is None)
+            or (self.has_args is True and args)
+            or (self.has_args is False and not args)
+            or (isinstance(self.has_args, int) and len(args) == self.has_args)
+        )
+
+    def check_update(
+        self, update: object
+    ) -> Optional[Union[bool, tuple[list[str], Optional[Union[bool, FilterDataDict]]]]]:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`list`: The list of args for the handler.
+
+        """
+        if isinstance(update, Update) and update.effective_message:
+            message = update.effective_message
+
+            if (
+                message.entities
+                and message.entities[0].type == MessageEntity.BOT_COMMAND
+                and message.entities[0].offset == 0
+                and message.text
+                and message.get_bot()
+            ):
+                command = message.text[1 : message.entities[0].length]
+                args = message.text.split()[1:]
+                command_parts = command.split("@")
+                command_parts.append(message.get_bot().username)
+
+                if not (
+                    command_parts[0].lower() in self.commands
+                    and command_parts[1].lower() == message.get_bot().username.lower()
+                ):
+                    return None
+
+                if not self._check_correct_args(args):
+                    return None
+
+                filter_result = self.filters.check_update(update)
+                if filter_result:
+                    return args, filter_result
+                return False
+        return None
+
+    def collect_additional_context(
+        self,
+        context: CCT,
+        update: Update,  # noqa: ARG002
+        application: "Application[Any, CCT, Any, Any, Any, Any]",  # noqa: ARG002
+        check_result: Optional[Union[bool, tuple[list[str], Optional[bool]]]],
+    ) -> None:
+        """Add text after the command to :attr:`CallbackContext.args` as list, split on single
+        whitespaces and add output of data filters to :attr:`CallbackContext` as well.
+        """
+        if isinstance(check_result, tuple):
+            context.args = check_result[0]
+            if isinstance(check_result[1], dict):
+                context.update(check_result[1])

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/conversationhandler.py

@@ -0,0 +1,960 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the ConversationHandler."""
+import asyncio
+import datetime
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Final, Generic, NoReturn, Optional, Union, cast
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE, DefaultValue
+from telegram._utils.logging import get_logger
+from telegram._utils.repr import build_repr_with_selected_attrs
+from telegram._utils.types import DVType
+from telegram._utils.warnings import warn
+from telegram.ext._application import ApplicationHandlerStop
+from telegram.ext._extbot import ExtBot
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._handlers.callbackqueryhandler import CallbackQueryHandler
+from telegram.ext._handlers.choseninlineresulthandler import ChosenInlineResultHandler
+from telegram.ext._handlers.inlinequeryhandler import InlineQueryHandler
+from telegram.ext._handlers.stringcommandhandler import StringCommandHandler
+from telegram.ext._handlers.stringregexhandler import StringRegexHandler
+from telegram.ext._handlers.typehandler import TypeHandler
+from telegram.ext._utils.trackingdict import TrackingDict
+from telegram.ext._utils.types import CCT, ConversationDict, ConversationKey
+
+if TYPE_CHECKING:
+    from telegram.ext import Application, Job, JobQueue
+_CheckUpdateType = tuple[object, ConversationKey, BaseHandler[Update, CCT, object], object]
+
+_LOGGER = get_logger(__name__, class_name="ConversationHandler")
+
+
+@dataclass
+class _ConversationTimeoutContext(Generic[CCT]):
+    """Used as a datastore for conversation timeouts. Passed in the
+    :paramref:`JobQueue.run_once.data` parameter. See :meth:`_trigger_timeout`.
+    """
+
+    __slots__ = ("application", "callback_context", "conversation_key", "update")
+
+    conversation_key: ConversationKey
+    update: Update
+    application: "Application[Any, CCT, Any, Any, Any, JobQueue]"
+    callback_context: CCT
+
+
+@dataclass
+class PendingState:
+    """Thin wrapper around :class:`asyncio.Task` to handle block=False handlers. Note that this is
+    a public class of this module, since :meth:`Application.update_persistence` needs to access it.
+    It's still hidden from users, since this module itself is private.
+    """
+
+    __slots__ = ("old_state", "task")
+
+    task: asyncio.Task
+    old_state: object
+
+    def done(self) -> bool:
+        return self.task.done()
+
+    def resolve(self) -> object:
+        """Returns the new state of the :class:`ConversationHandler` if available. If there was an
+        exception during the task execution, then return the old state. If both the new and old
+        state are :obj:`None`, return `CH.END`. If only the new state is :obj:`None`, return the
+        old state.
+
+        Raises:
+            :exc:`RuntimeError`: If the current task has not yet finished.
+        """
+        if not self.task.done():
+            raise RuntimeError("New state is not yet available")
+
+        exc = self.task.exception()
+        if exc:
+            _LOGGER.exception(
+                "Task function raised exception. Falling back to old state %s",
+                self.old_state,
+            )
+            return self.old_state
+
+        res = self.task.result()
+        if res is None and self.old_state is None:
+            res = ConversationHandler.END
+        elif res is None:
+            # returning None from a callback means that we want to stay in the old state
+            return self.old_state
+
+        return res
+
+
+class ConversationHandler(BaseHandler[Update, CCT, object]):
+    """
+    A handler to hold a conversation with a single or multiple users through Telegram updates by
+    managing three collections of other handlers.
+
+    Warning:
+        :class:`ConversationHandler` heavily relies on incoming updates being processed one by one.
+        When using this handler, :attr:`telegram.ext.ApplicationBuilder.concurrent_updates` should
+        be set to :obj:`False`.
+
+    Note:
+        :class:`ConversationHandler` will only accept updates that are (subclass-)instances of
+        :class:`telegram.Update`. This is, because depending on the :attr:`per_user` and
+        :attr:`per_chat`, :class:`ConversationHandler` relies on
+        :attr:`telegram.Update.effective_user` and/or :attr:`telegram.Update.effective_chat` in
+        order to determine which conversation an update should belong to. For
+        :attr:`per_message=True <per_message>`, :class:`ConversationHandler` uses
+        :attr:`update.callback_query.message.message_id <telegram.Message.message_id>` when
+        :attr:`per_chat=True <per_chat>` and
+        :attr:`update.callback_query.inline_message_id <.CallbackQuery.inline_message_id>` when
+        :attr:`per_chat=False <per_chat>`. For a more detailed explanation, please see our `FAQ`_.
+
+        Finally, :class:`ConversationHandler`, does *not* handle (edited) channel posts.
+
+    .. _`FAQ`: https://github.com/python-telegram-bot/python-telegram-bot/wiki\
+        /Frequently-Asked-Questions#what-do-the-per_-settings-in-conversation handler-do
+
+    The first collection, a :obj:`list` named :attr:`entry_points`, is used to initiate the
+    conversation, for example with a :class:`telegram.ext.CommandHandler` or
+    :class:`telegram.ext.MessageHandler`.
+
+    The second collection, a :obj:`dict` named :attr:`states`, contains the different conversation
+    steps and one or more associated handlers that should be used if the user sends a message when
+    the conversation with them is currently in that state. Here you can also define a state for
+    :attr:`TIMEOUT` to define the behavior when :attr:`conversation_timeout` is exceeded, and a
+    state for :attr:`WAITING` to define behavior when a new update is received while the previous
+    :attr:`block=False <block>` handler is not finished.
+
+    The third collection, a :obj:`list` named :attr:`fallbacks`, is used if the user is currently
+    in a conversation but the state has either no associated handler or the handler that is
+    associated to the state is inappropriate for the update, for example if the update contains a
+    command, but a regular text message is expected. You could use this for a ``/cancel`` command
+    or to let the user know their message was not recognized.
+
+    To change the state of conversation, the callback function of a handler must return the new
+    state after responding to the user. If it does not return anything (returning :obj:`None` by
+    default), the state will not change. If an entry point callback function returns :obj:`None`,
+    the conversation ends immediately after the execution of this callback function.
+    To end the conversation, the callback function must return :attr:`END` or ``-1``. To
+    handle the conversation timeout, use handler :attr:`TIMEOUT` or ``-2``.
+    Finally, :class:`telegram.ext.ApplicationHandlerStop` can be used in conversations as described
+    in its documentation.
+
+    Note:
+        In each of the described collections of handlers, a handler may in turn be a
+        :class:`ConversationHandler`. In that case, the child :class:`ConversationHandler` should
+        have the attribute :attr:`map_to_parent` which allows returning to the parent conversation
+        at specified states within the child conversation.
+
+        Note that the keys in :attr:`map_to_parent` must not appear as keys in :attr:`states`
+        attribute or else the latter will be ignored. You may map :attr:`END` to one of the parents
+        states to continue the parent conversation after the child conversation has ended or even
+        map a state to :attr:`END` to end the *parent* conversation from within the child
+        conversation. For an example on nested :class:`ConversationHandler` s, see
+        :any:`examples.nestedconversationbot`.
+
+    Examples:
+        * :any:`Conversation Bot <examples.conversationbot>`
+        * :any:`Conversation Bot 2 <examples.conversationbot2>`
+        * :any:`Nested Conversation Bot <examples.nestedconversationbot>`
+        * :any:`Persistent Conversation Bot <examples.persistentconversationbot>`
+
+    Args:
+        entry_points (list[:class:`telegram.ext.BaseHandler`]): A list of :obj:`BaseHandler`
+            objects that
+            can trigger the start of the conversation. The first handler whose :meth:`check_update`
+            method returns :obj:`True` will be used. If all return :obj:`False`, the update is not
+            handled.
+        states (dict[:obj:`object`, list[:class:`telegram.ext.BaseHandler`]]): A :obj:`dict` that
+            defines the different states of conversation a user can be in and one or more
+            associated :obj:`BaseHandler` objects that should be used in that state. The first
+            handler whose :meth:`check_update` method returns :obj:`True` will be used.
+        fallbacks (list[:class:`telegram.ext.BaseHandler`]): A list of handlers that might be used
+            if the user is in a conversation, but every handler for their current state returned
+            :obj:`False` on :meth:`check_update`. The first handler which :meth:`check_update`
+            method returns :obj:`True` will be used. If all return :obj:`False`, the update is not
+            handled.
+        allow_reentry (:obj:`bool`, optional): If set to :obj:`True`, a user that is currently in a
+            conversation can restart the conversation by triggering one of the entry points.
+            Default is :obj:`False`.
+        per_chat (:obj:`bool`, optional): If the conversation key should contain the Chat's ID.
+            Default is :obj:`True`.
+        per_user (:obj:`bool`, optional): If the conversation key should contain the User's ID.
+            Default is :obj:`True`.
+        per_message (:obj:`bool`, optional): If the conversation key should contain the Message's
+            ID. Default is :obj:`False`.
+        conversation_timeout (:obj:`float` | :obj:`datetime.timedelta`, optional): When this
+            handler is inactive more than this timeout (in seconds), it will be automatically
+            ended. If this value is ``0`` or :obj:`None` (default), there will be no timeout. The
+            last received update and the corresponding :class:`context <.CallbackContext>` will be
+            handled by *ALL* the handler's whose :meth:`check_update` method returns :obj:`True`
+            that are in the state :attr:`ConversationHandler.TIMEOUT`.
+
+            Caution:
+                * This feature relies on the :attr:`telegram.ext.Application.job_queue` being set
+                  and hence requires that the dependencies that :class:`telegram.ext.JobQueue`
+                  relies on are installed.
+                * Using :paramref:`conversation_timeout` with nested conversations is currently
+                  not supported. You can still try to use it, but it will likely behave
+                  differently from what you expect.
+
+        name (:obj:`str`, optional): The name for this conversation handler. Required for
+            persistence.
+        persistent (:obj:`bool`, optional): If the conversation's dict for this handler should be
+            saved. :paramref:`name` is required and persistence has to be set in
+            :attr:`Application <.Application.persistence>`.
+
+            .. versionchanged:: 20.0
+                Was previously named as ``persistence``.
+        map_to_parent (dict[:obj:`object`, :obj:`object`], optional): A :obj:`dict` that can be
+            used to instruct a child conversation handler to transition into a mapped state on
+            its parent conversation handler in place of a specified nested state.
+        block (:obj:`bool`, optional): Pass :obj:`False` or :obj:`True` to set a default value for
+            the :attr:`BaseHandler.block` setting of all handlers (in :attr:`entry_points`,
+            :attr:`states` and :attr:`fallbacks`). The resolution order for checking if a handler
+            should be run non-blocking is:
+
+            1. :attr:`telegram.ext.BaseHandler.block` (if set)
+            2. the value passed to this parameter (if any)
+            3. :attr:`telegram.ext.Defaults.block` (if defaults are used)
+
+            .. seealso:: :wiki:`Concurrency`
+
+            .. versionchanged:: 20.0
+                No longer overrides the handlers settings. Resolution order was changed.
+
+    Raises:
+        :exc:`ValueError`: If :paramref:`persistent` is used but :paramref:`name` was not set, or
+            when :attr:`per_message`, :attr:`per_chat`, :attr:`per_user` are all :obj:`False`.
+
+    Attributes:
+        block (:obj:`bool`): Determines whether the callback will run in a blocking way. Always
+            :obj:`True` since conversation handlers handle any non-blocking callbacks internally.
+
+    """
+
+    __slots__ = (
+        "_allow_reentry",
+        "_block",
+        "_child_conversations",
+        "_conversation_timeout",
+        "_conversations",
+        "_entry_points",
+        "_fallbacks",
+        "_map_to_parent",
+        "_name",
+        "_per_chat",
+        "_per_message",
+        "_per_user",
+        "_persistent",
+        "_states",
+        "_timeout_jobs_lock",
+        "timeout_jobs",
+    )
+
+    END: Final[int] = -1
+    """:obj:`int`: Used as a constant to return when a conversation is ended."""
+    TIMEOUT: Final[int] = -2
+    """:obj:`int`: Used as a constant to handle state when a conversation is timed out
+    (exceeded :attr:`conversation_timeout`).
+    """
+    WAITING: Final[int] = -3
+    """:obj:`int`: Used as a constant to handle state when a conversation is still waiting on the
+    previous :attr:`block=False <block>` handler to finish."""
+
+    # pylint: disable=super-init-not-called
+    def __init__(
+        self: "ConversationHandler[CCT]",
+        entry_points: list[BaseHandler[Update, CCT, object]],
+        states: dict[object, list[BaseHandler[Update, CCT, object]]],
+        fallbacks: list[BaseHandler[Update, CCT, object]],
+        allow_reentry: bool = False,
+        per_chat: bool = True,
+        per_user: bool = True,
+        per_message: bool = False,
+        conversation_timeout: Optional[Union[float, datetime.timedelta]] = None,
+        name: Optional[str] = None,
+        persistent: bool = False,
+        map_to_parent: Optional[dict[object, object]] = None,
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        # these imports need to be here because of circular import error otherwise
+        from telegram.ext import (  # pylint: disable=import-outside-toplevel
+            PollAnswerHandler,
+            PollHandler,
+            PreCheckoutQueryHandler,
+            ShippingQueryHandler,
+        )
+
+        # self.block is what the Application checks and we want it to always run CH in a blocking
+        # way so that CH can take care of any non-blocking logic internally
+        self.block: DVType[bool] = True
+        # Store the actual setting in a protected variable instead
+        self._block: DVType[bool] = block
+
+        self._entry_points: list[BaseHandler[Update, CCT, object]] = entry_points
+        self._states: dict[object, list[BaseHandler[Update, CCT, object]]] = states
+        self._fallbacks: list[BaseHandler[Update, CCT, object]] = fallbacks
+
+        self._allow_reentry: bool = allow_reentry
+        self._per_user: bool = per_user
+        self._per_chat: bool = per_chat
+        self._per_message: bool = per_message
+        self._conversation_timeout: Optional[Union[float, datetime.timedelta]] = (
+            conversation_timeout
+        )
+        self._name: Optional[str] = name
+        self._map_to_parent: Optional[dict[object, object]] = map_to_parent
+
+        # if conversation_timeout is used, this dict is used to schedule a job which runs when the
+        # conv has timed out.
+        self.timeout_jobs: dict[ConversationKey, Job[Any]] = {}
+        self._timeout_jobs_lock = asyncio.Lock()
+        self._conversations: ConversationDict = {}
+        self._child_conversations: set[ConversationHandler] = set()
+
+        if persistent and not self.name:
+            raise ValueError("Conversations can't be persistent when handler is unnamed.")
+        self._persistent: bool = persistent
+
+        if not any((self.per_user, self.per_chat, self.per_message)):
+            raise ValueError("'per_user', 'per_chat' and 'per_message' can't all be 'False'")
+
+        if self.per_message and not self.per_chat:
+            warn(
+                "If 'per_message=True' is used, 'per_chat=True' should also be used, "
+                "since message IDs are not globally unique.",
+                stacklevel=2,
+            )
+
+        all_handlers: list[BaseHandler[Update, CCT, object]] = []
+        all_handlers.extend(entry_points)
+        all_handlers.extend(fallbacks)
+
+        for state_handlers in states.values():
+            all_handlers.extend(state_handlers)
+
+        self._child_conversations.update(
+            handler for handler in all_handlers if isinstance(handler, ConversationHandler)
+        )
+
+        # this link will be added to all warnings tied to per_* setting
+        per_faq_link = (
+            " Read this FAQ entry to learn more about the per_* settings: "
+            "https://github.com/python-telegram-bot/python-telegram-bot/wiki"
+            "/Frequently-Asked-Questions#what-do-the-per_-settings-in-conversationhandler-do."
+        )
+
+        # this loop is going to warn the user about handlers which can work unexpectedly
+        # in conversations
+        for handler in all_handlers:
+            if isinstance(handler, (StringCommandHandler, StringRegexHandler)):
+                warn(
+                    "The `ConversationHandler` only handles updates of type `telegram.Update`. "
+                    f"{handler.__class__.__name__} handles updates of type `str`.",
+                    stacklevel=2,
+                )
+            elif isinstance(handler, TypeHandler) and not issubclass(handler.type, Update):
+                warn(
+                    "The `ConversationHandler` only handles updates of type `telegram.Update`."
+                    f" The TypeHandler is set to handle {handler.type.__name__}.",
+                    stacklevel=2,
+                )
+            elif isinstance(handler, PollHandler):
+                warn(
+                    "PollHandler will never trigger in a conversation since it has no information "
+                    "about the chat or the user who voted in it. Do you mean the "
+                    "`PollAnswerHandler`?",
+                    stacklevel=2,
+                )
+
+            elif self.per_chat and (
+                isinstance(
+                    handler,
+                    (
+                        ShippingQueryHandler,
+                        InlineQueryHandler,
+                        ChosenInlineResultHandler,
+                        PreCheckoutQueryHandler,
+                        PollAnswerHandler,
+                    ),
+                )
+            ):
+                warn(
+                    f"Updates handled by {handler.__class__.__name__} only have information about "
+                    "the user, so this handler won't ever be triggered if `per_chat=True`."
+                    f"{per_faq_link}",
+                    stacklevel=2,
+                )
+
+            elif self.per_message and not isinstance(handler, CallbackQueryHandler):
+                warn(
+                    "If 'per_message=True', all entry points, state handlers, and fallbacks"
+                    " must be 'CallbackQueryHandler', since no other handlers "
+                    f"have a message context.{per_faq_link}",
+                    stacklevel=2,
+                )
+            elif not self.per_message and isinstance(handler, CallbackQueryHandler):
+                warn(
+                    "If 'per_message=False', 'CallbackQueryHandler' will not be "
+                    f"tracked for every message.{per_faq_link}",
+                    stacklevel=2,
+                )
+
+            if self.conversation_timeout and isinstance(handler, self.__class__):
+                warn(
+                    "Using `conversation_timeout` with nested conversations is currently not "
+                    "supported. You can still try to use it, but it will likely behave "
+                    "differently from what you expect.",
+                    stacklevel=2,
+                )
+
+    def __repr__(self) -> str:
+        """Give a string representation of the ConversationHandler in the form
+        ``ConversationHandler[name=..., states={...}]``.
+
+        If there are more than 3 states, only the first 3 states are listed.
+
+        As this class doesn't implement :meth:`object.__str__`, the default implementation
+        will be used, which is equivalent to :meth:`__repr__`.
+
+        Returns:
+            :obj:`str`
+        """
+        truncation_threshold = 3
+        states = dict(list(self.states.items())[:truncation_threshold])
+        states_string = str(states)
+        if len(self.states) > truncation_threshold:
+            states_string = states_string[:-1] + ", ...}"
+
+        return build_repr_with_selected_attrs(
+            self,
+            name=self.name,
+            states=states_string,
+        )
+
+    @property
+    def entry_points(self) -> list[BaseHandler[Update, CCT, object]]:
+        """list[:class:`telegram.ext.BaseHandler`]: A list of :obj:`BaseHandler` objects that can
+        trigger the start of the conversation.
+        """
+        return self._entry_points
+
+    @entry_points.setter
+    def entry_points(self, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to entry_points after initialization."
+        )
+
+    @property
+    def states(self) -> dict[object, list[BaseHandler[Update, CCT, object]]]:
+        """dict[:obj:`object`, list[:class:`telegram.ext.BaseHandler`]]: A :obj:`dict` that
+        defines the different states of conversation a user can be in and one or more
+        associated :obj:`BaseHandler` objects that should be used in that state.
+        """
+        return self._states
+
+    @states.setter
+    def states(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to states after initialization.")
+
+    @property
+    def fallbacks(self) -> list[BaseHandler[Update, CCT, object]]:
+        """list[:class:`telegram.ext.BaseHandler`]: A list of handlers that might be used if
+        the user is in a conversation, but every handler for their current state returned
+        :obj:`False` on :meth:`check_update`.
+        """
+        return self._fallbacks
+
+    @fallbacks.setter
+    def fallbacks(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to fallbacks after initialization.")
+
+    @property
+    def allow_reentry(self) -> bool:
+        """:obj:`bool`: Determines if a user can restart a conversation with an entry point."""
+        return self._allow_reentry
+
+    @allow_reentry.setter
+    def allow_reentry(self, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to allow_reentry after initialization."
+        )
+
+    @property
+    def per_user(self) -> bool:
+        """:obj:`bool`: If the conversation key should contain the User's ID."""
+        return self._per_user
+
+    @per_user.setter
+    def per_user(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to per_user after initialization.")
+
+    @property
+    def per_chat(self) -> bool:
+        """:obj:`bool`: If the conversation key should contain the Chat's ID."""
+        return self._per_chat
+
+    @per_chat.setter
+    def per_chat(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to per_chat after initialization.")
+
+    @property
+    def per_message(self) -> bool:
+        """:obj:`bool`: If the conversation key should contain the message's ID."""
+        return self._per_message
+
+    @per_message.setter
+    def per_message(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to per_message after initialization.")
+
+    @property
+    def conversation_timeout(
+        self,
+    ) -> Optional[Union[float, datetime.timedelta]]:
+        """:obj:`float` | :obj:`datetime.timedelta`: Optional. When this
+        handler is inactive more than this timeout (in seconds), it will be automatically
+        ended.
+        """
+        return self._conversation_timeout
+
+    @conversation_timeout.setter
+    def conversation_timeout(self, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to conversation_timeout after initialization."
+        )
+
+    @property
+    def name(self) -> Optional[str]:
+        """:obj:`str`: Optional. The name for this :class:`ConversationHandler`."""
+        return self._name
+
+    @name.setter
+    def name(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to name after initialization.")
+
+    @property
+    def persistent(self) -> bool:
+        """:obj:`bool`: Optional. If the conversations dict for this handler should be
+        saved. :attr:`name` is required and persistence has to be set in
+        :attr:`Application <.Application.persistence>`.
+        """
+        return self._persistent
+
+    @persistent.setter
+    def persistent(self, _: object) -> NoReturn:
+        raise AttributeError("You can not assign a new value to persistent after initialization.")
+
+    @property
+    def map_to_parent(self) -> Optional[dict[object, object]]:
+        """dict[:obj:`object`, :obj:`object`]: Optional. A :obj:`dict` that can be
+        used to instruct a nested :class:`ConversationHandler` to transition into a mapped state on
+        its parent :class:`ConversationHandler` in place of a specified nested state.
+        """
+        return self._map_to_parent
+
+    @map_to_parent.setter
+    def map_to_parent(self, _: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to map_to_parent after initialization."
+        )
+
+    async def _initialize_persistence(
+        self, application: "Application"
+    ) -> dict[str, TrackingDict[ConversationKey, object]]:
+        """Initializes the persistence for this handler and its child conversations.
+        While this method is marked as protected, we expect it to be called by the
+        Application/parent conversations. It's just protected to hide it from users.
+
+        Args:
+            application (:class:`telegram.ext.Application`): The application.
+
+        Returns:
+            A dict {conversation.name -> TrackingDict}, which contains all dict of this
+            conversation and possible child conversations.
+
+        """
+        if not (self.persistent and self.name and application.persistence):
+            raise RuntimeError(
+                "This handler is not persistent, has no name or the application has no "
+                "persistence!"
+            )
+
+        current_conversations = self._conversations
+        self._conversations = cast(
+            TrackingDict[ConversationKey, object],
+            TrackingDict(),
+        )
+        # In the conversation already processed updates
+        self._conversations.update(current_conversations)
+        # above might be partly overridden but that's okay since we warn about that in
+        # add_handler
+        stored_data = await application.persistence.get_conversations(self.name)
+        self._conversations.update_no_track(stored_data)
+
+        # Since CH.END is stored as normal state, we need to properly parse it here in order to
+        # actually end the conversation, i.e. delete the key from the _conversations dict
+        # This also makes sure that these entries are deleted from the persisted data on the next
+        # run of Application.update_persistence
+        for key, state in stored_data.items():
+            if state == self.END:
+                self._update_state(new_state=self.END, key=key)
+
+        out = {self.name: self._conversations}
+
+        for handler in self._child_conversations:
+            out.update(
+                await handler._initialize_persistence(  # pylint: disable=protected-access
+                    application=application
+                )
+            )
+
+        return out
+
+    def _get_key(self, update: Update) -> ConversationKey:
+        """Builds the conversation key associated with the update."""
+        chat = update.effective_chat
+        user = update.effective_user
+
+        key: list[Union[int, str]] = []
+
+        if self.per_chat:
+            if chat is None:
+                raise RuntimeError("Can't build key for update without effective chat!")
+            key.append(chat.id)
+
+        if self.per_user:
+            if user is None:
+                raise RuntimeError("Can't build key for update without effective user!")
+            key.append(user.id)
+
+        if self.per_message:
+            if update.callback_query is None:
+                raise RuntimeError("Can't build key for update without CallbackQuery!")
+            if update.callback_query.inline_message_id:
+                key.append(update.callback_query.inline_message_id)
+            else:
+                key.append(update.callback_query.message.message_id)  # type: ignore[union-attr]
+
+        return tuple(key)
+
+    async def _schedule_job_delayed(
+        self,
+        new_state: asyncio.Task,
+        application: "Application[Any, CCT, Any, Any, Any, JobQueue]",
+        update: Update,
+        context: CCT,
+        conversation_key: ConversationKey,
+    ) -> None:
+        try:
+            effective_new_state = await new_state
+        except Exception as exc:
+            _LOGGER.debug(
+                "Non-blocking handler callback raised exception. Not scheduling conversation "
+                "timeout.",
+                exc_info=exc,
+            )
+            return None
+        return self._schedule_job(
+            new_state=effective_new_state,
+            application=application,
+            update=update,
+            context=context,
+            conversation_key=conversation_key,
+        )
+
+    def _schedule_job(
+        self,
+        new_state: object,
+        application: "Application[Any, CCT, Any, Any, Any, JobQueue]",
+        update: Update,
+        context: CCT,
+        conversation_key: ConversationKey,
+    ) -> None:
+        """Schedules a job which executes :meth:`_trigger_timeout` upon conversation timeout."""
+        if new_state == self.END:
+            return
+
+        try:
+            # both job_queue & conversation_timeout are checked before calling _schedule_job
+            j_queue = application.job_queue
+            self.timeout_jobs[conversation_key] = j_queue.run_once(  # type: ignore[union-attr]
+                self._trigger_timeout,
+                self.conversation_timeout,  # type: ignore[arg-type]
+                data=_ConversationTimeoutContext(conversation_key, update, application, context),
+            )
+        except Exception as exc:
+            _LOGGER.exception("Failed to schedule timeout.", exc_info=exc)
+
+    # pylint: disable=too-many-return-statements
+    def check_update(self, update: object) -> Optional[_CheckUpdateType[CCT]]:
+        """
+        Determines whether an update should be handled by this conversation handler, and if so in
+        which state the conversation currently is.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if not isinstance(update, Update):
+            return None
+        # Ignore messages in channels
+        if update.channel_post or update.edited_channel_post:
+            return None
+        if self.per_chat and not update.effective_chat:
+            return None
+        if self.per_user and not update.effective_user:
+            return None
+        if self.per_message and not update.callback_query:
+            return None
+        if update.callback_query and self.per_chat and not update.callback_query.message:
+            return None
+
+        key = self._get_key(update)
+        state = self._conversations.get(key)
+        check: Optional[object] = None
+
+        # Resolve futures
+        if isinstance(state, PendingState):
+            _LOGGER.debug("Waiting for asyncio Task to finish ...")
+
+            # check if future is finished or not
+            if state.done():
+                res = state.resolve()
+                # Special case if an error was raised in a non-blocking entry-point
+                if state.old_state is None and state.task.exception():
+                    self._conversations.pop(key, None)
+                    state = None
+                else:
+                    self._update_state(res, key)
+                    state = self._conversations.get(key)
+
+            # if not then handle WAITING state instead
+            else:
+                handlers = self.states.get(self.WAITING, [])
+                for handler_ in handlers:
+                    check = handler_.check_update(update)
+                    if check is not None and check is not False:
+                        return self.WAITING, key, handler_, check
+                return None
+
+        _LOGGER.debug("Selecting conversation %s with state %s", str(key), str(state))
+
+        handler: Optional[BaseHandler] = None
+
+        # Search entry points for a match
+        if state is None or self.allow_reentry:
+            for entry_point in self.entry_points:
+                check = entry_point.check_update(update)
+                if check is not None and check is not False:
+                    handler = entry_point
+                    break
+
+            else:
+                if state is None:
+                    return None
+
+        # Get the handler list for current state, if we didn't find one yet and we're still here
+        if state is not None and handler is None:
+            for candidate in self.states.get(state, []):
+                check = candidate.check_update(update)
+                if check is not None and check is not False:
+                    handler = candidate
+                    break
+
+            # Find a fallback handler if all other handlers fail
+            else:
+                for fallback in self.fallbacks:
+                    check = fallback.check_update(update)
+                    if check is not None and check is not False:
+                        handler = fallback
+                        break
+
+                else:
+                    return None
+
+        return state, key, handler, check  # type: ignore[return-value]
+
+    async def handle_update(  # type: ignore[override]
+        self,
+        update: Update,
+        application: "Application[Any, CCT, Any, Any, Any, Any]",
+        check_result: _CheckUpdateType[CCT],
+        context: CCT,
+    ) -> Optional[object]:
+        """Send the update to the callback for the current state and BaseHandler
+
+        Args:
+            check_result: The result from :meth:`check_update`. For this handler it's a tuple of
+                the conversation state, key, handler, and the handler's check result.
+            update (:class:`telegram.Update`): Incoming telegram update.
+            application (:class:`telegram.ext.Application`): Application that originated the
+                update.
+            context (:class:`telegram.ext.CallbackContext`): The context as provided by
+                the application.
+
+        """
+        current_state, conversation_key, handler, handler_check_result = check_result
+        raise_dp_handler_stop = False
+
+        async with self._timeout_jobs_lock:
+            # Remove the old timeout job (if present)
+            timeout_job = self.timeout_jobs.pop(conversation_key, None)
+
+            if timeout_job is not None:
+                timeout_job.schedule_removal()
+
+        # Resolution order of "block":
+        # 1. Setting of the selected handler
+        # 2. Setting of the ConversationHandler
+        # 3. Default values of the bot
+        if handler.block is not DEFAULT_TRUE:
+            block = handler.block
+        elif self._block is not DEFAULT_TRUE:
+            block = self._block
+        elif isinstance(application.bot, ExtBot) and application.bot.defaults is not None:
+            block = application.bot.defaults.block
+        else:
+            block = DefaultValue.get_value(handler.block)
+
+        try:  # Now create task or await the callback
+            if block:
+                new_state: object = await handler.handle_update(
+                    update, application, handler_check_result, context
+                )
+            else:
+                new_state = application.create_task(
+                    coroutine=handler.handle_update(
+                        update, application, handler_check_result, context
+                    ),
+                    update=update,
+                    name=f"ConversationHandler:{update.update_id}:handle_update:non_blocking_cb",
+                )
+        except ApplicationHandlerStop as exception:
+            new_state = exception.state
+            raise_dp_handler_stop = True
+        async with self._timeout_jobs_lock:
+            if self.conversation_timeout:
+                if application.job_queue is None:
+                    warn(
+                        "Ignoring `conversation_timeout` because the Application has no JobQueue.",
+                        stacklevel=1,
+                    )
+                elif not application.job_queue.scheduler.running:
+                    warn(
+                        "Ignoring `conversation_timeout` because the Applications JobQueue is "
+                        "not running.",
+                        stacklevel=1,
+                    )
+                elif isinstance(new_state, asyncio.Task):
+                    # Add the new timeout job
+                    # checking if the new state is self.END is done in _schedule_job
+                    application.create_task(
+                        self._schedule_job_delayed(
+                            new_state, application, update, context, conversation_key
+                        ),
+                        update=update,
+                        name=f"ConversationHandler:{update.update_id}:handle_update:timeout_job",
+                    )
+                else:
+                    self._schedule_job(new_state, application, update, context, conversation_key)
+
+        if isinstance(self.map_to_parent, dict) and new_state in self.map_to_parent:
+            self._update_state(self.END, conversation_key, handler)
+            if raise_dp_handler_stop:
+                raise ApplicationHandlerStop(self.map_to_parent.get(new_state))
+            return self.map_to_parent.get(new_state)
+
+        if current_state != self.WAITING:
+            self._update_state(new_state, conversation_key, handler)
+
+        if raise_dp_handler_stop:
+            # Don't pass the new state here. If we're in a nested conversation, the parent is
+            # expecting None as return value.
+            raise ApplicationHandlerStop
+        # Signals a possible parent conversation to stay in the current state
+        return None
+
+    def _update_state(
+        self, new_state: object, key: ConversationKey, handler: Optional[BaseHandler] = None
+    ) -> None:
+        if new_state == self.END:
+            if key in self._conversations:
+                # If there is no key in conversations, nothing is done.
+                del self._conversations[key]
+
+        elif isinstance(new_state, asyncio.Task):
+            self._conversations[key] = PendingState(
+                old_state=self._conversations.get(key), task=new_state
+            )
+
+        elif new_state is not None:
+            if new_state not in self.states:
+                warn(
+                    f"{repr(handler.callback.__name__) if handler is not None else 'BaseHandler'} "
+                    f"returned state {new_state} which is unknown to the "
+                    f"ConversationHandler{' ' + self.name if self.name is not None else ''}.",
+                    stacklevel=2,
+                )
+            self._conversations[key] = new_state
+
+    async def _trigger_timeout(self, context: CCT) -> None:
+        """This is run whenever a conversation has timed out. Also makes sure that all handlers
+        which are in the :attr:`TIMEOUT` state and whose :meth:`BaseHandler.check_update` returns
+        :obj:`True` is handled.
+        """
+        job = cast("Job", context.job)
+        ctxt = cast(_ConversationTimeoutContext, job.data)
+
+        _LOGGER.debug(
+            "Conversation timeout was triggered for conversation %s!", ctxt.conversation_key
+        )
+
+        callback_context = ctxt.callback_context
+
+        async with self._timeout_jobs_lock:
+            found_job = self.timeout_jobs.get(ctxt.conversation_key)
+            if found_job is not job:
+                # The timeout has been cancelled in handle_update
+                return
+            del self.timeout_jobs[ctxt.conversation_key]
+
+        # Now run all handlers which are in TIMEOUT state
+        handlers = self.states.get(self.TIMEOUT, [])
+        for handler in handlers:
+            check = handler.check_update(ctxt.update)
+            if check is not None and check is not False:
+                try:
+                    await handler.handle_update(
+                        ctxt.update, ctxt.application, check, callback_context
+                    )
+                except ApplicationHandlerStop:
+                    warn(
+                        "ApplicationHandlerStop in TIMEOUT state of "
+                        "ConversationHandler has no effect. Ignoring.",
+                        stacklevel=2,
+                    )
+
+        self._update_state(self.END, ctxt.conversation_key)

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/inlinequeryhandler.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the InlineQueryHandler class."""
+import re
+from re import Match, Pattern
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union, cast
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+if TYPE_CHECKING:
+    from telegram.ext import Application
+
+RT = TypeVar("RT")
+
+
+class InlineQueryHandler(BaseHandler[Update, CCT, RT]):
+    """
+    BaseHandler class to handle Telegram updates that contain a
+    :attr:`telegram.Update.inline_query`.
+    Optionally based on a regex. Read the documentation of the :mod:`re` module for more
+    information.
+
+    Warning:
+        * When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+          attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+        * :attr:`telegram.InlineQuery.chat_type` will not be set for inline queries from secret
+          chats and may not be set for inline queries coming from third-party clients. These
+          updates won't be handled, if :attr:`chat_types` is passed.
+
+    Examples:
+        :any:`Inline Bot <examples.inlinebot>`
+
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        pattern (:obj:`str` | :func:`re.Pattern <re.compile>`, optional): Regex pattern.
+            If not :obj:`None`, :func:`re.match` is used on :attr:`telegram.InlineQuery.query`
+            to determine if an update should be handled by this handler.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+        chat_types (list[:obj:`str`], optional): List of allowed chat types. If passed, will only
+            handle inline queries with the appropriate :attr:`telegram.InlineQuery.chat_type`.
+
+            .. versionadded:: 13.5
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): Optional. Regex pattern to test
+            :attr:`telegram.InlineQuery.query` against.
+        chat_types (list[:obj:`str`]): Optional. List of allowed chat types.
+
+            .. versionadded:: 13.5
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+
+    """
+
+    __slots__ = ("chat_types", "pattern")
+
+    def __init__(
+        self: "InlineQueryHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        pattern: Optional[Union[str, Pattern[str]]] = None,
+        block: DVType[bool] = DEFAULT_TRUE,
+        chat_types: Optional[list[str]] = None,
+    ):
+        super().__init__(callback, block=block)
+
+        if isinstance(pattern, str):
+            pattern = re.compile(pattern)
+
+        self.pattern: Optional[Union[str, Pattern[str]]] = pattern
+        self.chat_types: Optional[list[str]] = chat_types
+
+    def check_update(self, update: object) -> Optional[Union[bool, Match[str]]]:
+        """
+        Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool` | :obj:`re.match`
+
+        """
+        if isinstance(update, Update) and update.inline_query:
+            if (self.chat_types is not None) and (
+                update.inline_query.chat_type not in self.chat_types
+            ):
+                return False
+            if (
+                self.pattern
+                and update.inline_query.query
+                and (match := re.match(self.pattern, update.inline_query.query))
+            ):
+                return match
+            if not self.pattern:
+                return True
+        return None
+
+    def collect_additional_context(
+        self,
+        context: CCT,
+        update: Update,  # noqa: ARG002
+        application: "Application[Any, CCT, Any, Any, Any, Any]",  # noqa: ARG002
+        check_result: Optional[Union[bool, Match[str]]],
+    ) -> None:
+        """Add the result of ``re.match(pattern, update.inline_query.query)`` to
+        :attr:`CallbackContext.matches` as list with one element.
+        """
+        if self.pattern:
+            check_result = cast(Match, check_result)
+            context.matches = [check_result]

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/messagehandler.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the MessageHandler class."""
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import DVType
+from telegram.ext import filters as filters_module
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+if TYPE_CHECKING:
+    from telegram.ext import Application
+
+RT = TypeVar("RT")
+
+
+class MessageHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram messages. They might contain text, media or status
+    updates.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Args:
+        filters (:class:`telegram.ext.filters.BaseFilter`): A filter inheriting from
+            :class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
+            :mod:`telegram.ext.filters`. Filters can be combined using bitwise
+            operators (& for and, | for or, ~ for not). Passing :obj:`None` is a shortcut
+            to passing :class:`telegram.ext.filters.ALL`.
+
+            .. seealso:: :wiki:`Advanced Filters <Extensions---Advanced-Filters>`
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        filters (:class:`telegram.ext.filters.BaseFilter`): Only allow updates with these Filters.
+            See :mod:`telegram.ext.filters` for a full list of all available filters.
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+
+    """
+
+    __slots__ = ("filters",)
+
+    def __init__(
+        self: "MessageHandler[CCT, RT]",
+        filters: Optional[filters_module.BaseFilter],
+        callback: HandlerCallback[Update, CCT, RT],
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback, block=block)
+        self.filters: filters_module.BaseFilter = (
+            filters if filters is not None else filters_module.ALL
+        )
+
+    def check_update(self, update: object) -> Optional[Union[bool, dict[str, list[Any]]]]:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if isinstance(update, Update):
+            return self.filters.check_update(update) or False
+        return None
+
+    def collect_additional_context(
+        self,
+        context: CCT,
+        update: Update,  # noqa: ARG002
+        application: "Application[Any, CCT, Any, Any, Any, Any]",  # noqa: ARG002
+        check_result: Optional[Union[bool, dict[str, object]]],
+    ) -> None:
+        """Adds possible output of data filters to the :class:`CallbackContext`."""
+        if isinstance(check_result, dict):
+            context.update(check_result)

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/messagereactionhandler.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the MessageReactionHandler class."""
+
+from typing import Final, Optional
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import RT, SCT, DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils._update_parsing import parse_chat_id, parse_username
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+
+class MessageReactionHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram updates that contain a message reaction.
+
+    Note:
+        The following rules apply to both ``username`` and the ``chat_id`` param groups,
+        respectively:
+
+         * If none of them are passed, the handler does not filter the update for that specific
+            attribute.
+         * If a chat ID **or** a username is passed, the updates will be filtered with that
+            specific attribute.
+         * If a chat ID **and** a username are passed, an update containing **any** of them will be
+            filtered.
+         * :attr:`telegram.MessageReactionUpdated.actor_chat` is *not* considered for
+           :paramref:`user_id` and :paramref:`user_username` filtering.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    .. versionadded:: 20.8
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        message_reaction_types (:obj:`int`, optional): Pass one of
+            :attr:`MESSAGE_REACTION_UPDATED`, :attr:`MESSAGE_REACTION_COUNT_UPDATED` or
+            :attr:`MESSAGE_REACTION` to specify if this handler should handle only updates with
+            :attr:`telegram.Update.message_reaction`,
+            :attr:`telegram.Update.message_reaction_count` or both. Defaults to
+            :attr:`MESSAGE_REACTION`.
+        chat_id (:obj:`int` | Collection[:obj:`int`], optional): Filters reactions to allow
+            only those which happen in the specified chat ID(s).
+        chat_username (:obj:`str` | Collection[:obj:`str`], optional): Filters reactions to allow
+            only those which happen in the specified username(s).
+        user_id (:obj:`int` | Collection[:obj:`int`], optional): Filters reactions to allow
+            only those which are set by the specified chat ID(s) (this can be the chat itself in
+            the case of anonymous users, see the
+            :paramref:`telegram.MessageReactionUpdated.actor_chat`).
+        user_username (:obj:`str` | Collection[:obj:`str`], optional): Filters reactions to allow
+            only those which are set by the specified username(s) (this can be the chat itself in
+            the case of anonymous users, see the
+            :paramref:`telegram.MessageReactionUpdated.actor_chat`).
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        message_reaction_types (:obj:`int`): Optional. Specifies if this handler should handle only
+            updates with :attr:`telegram.Update.message_reaction`,
+            :attr:`telegram.Update.message_reaction_count` or both.
+        block (:obj:`bool`): Determines whether the callback will run in a blocking way.
+
+    """
+
+    __slots__ = (
+        "_chat_ids",
+        "_chat_usernames",
+        "_user_ids",
+        "_user_usernames",
+        "message_reaction_types",
+    )
+
+    MESSAGE_REACTION_UPDATED: Final[int] = -1
+    """:obj:`int`: Used as a constant to handle only :attr:`telegram.Update.message_reaction`."""
+    MESSAGE_REACTION_COUNT_UPDATED: Final[int] = 0
+    """:obj:`int`: Used as a constant to handle only
+    :attr:`telegram.Update.message_reaction_count`."""
+    MESSAGE_REACTION: Final[int] = 1
+    """:obj:`int`: Used as a constant to handle both :attr:`telegram.Update.message_reaction`
+    and :attr:`telegram.Update.message_reaction_count`."""
+
+    def __init__(
+        self: "MessageReactionHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        chat_id: Optional[SCT[int]] = None,
+        chat_username: Optional[SCT[str]] = None,
+        user_id: Optional[SCT[int]] = None,
+        user_username: Optional[SCT[str]] = None,
+        message_reaction_types: int = MESSAGE_REACTION,
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback, block=block)
+        self.message_reaction_types: int = message_reaction_types
+
+        self._chat_ids = parse_chat_id(chat_id)
+        self._chat_usernames = parse_username(chat_username)
+        if (user_id or user_username) and message_reaction_types in (
+            self.MESSAGE_REACTION,
+            self.MESSAGE_REACTION_COUNT_UPDATED,
+        ):
+            raise ValueError(
+                "You can not filter for users and include anonymous reactions. Set "
+                "`message_reaction_types` to MESSAGE_REACTION_UPDATED."
+            )
+        self._user_ids = parse_chat_id(user_id)
+        self._user_usernames = parse_username(user_username)
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if not isinstance(update, Update):
+            return False
+
+        if not (update.message_reaction or update.message_reaction_count):
+            return False
+
+        if (
+            self.message_reaction_types == self.MESSAGE_REACTION_UPDATED
+            and update.message_reaction_count
+        ):
+            return False
+
+        if (
+            self.message_reaction_types == self.MESSAGE_REACTION_COUNT_UPDATED
+            and update.message_reaction
+        ):
+            return False
+
+        if not any((self._chat_ids, self._chat_usernames, self._user_ids, self._user_usernames)):
+            return True
+
+        # Extract chat and user IDs and usernames from the update for comparison
+        chat_id = chat.id if (chat := update.effective_chat) else None
+        chat_username = chat.username if chat else None
+        user_id = user.id if (user := update.effective_user) else None
+        user_username = user.username if user else None
+
+        return (
+            bool(self._chat_ids and (chat_id in self._chat_ids))
+            or bool(self._chat_usernames and (chat_username in self._chat_usernames))
+            or bool(self._user_ids and (user_id in self._user_ids))
+            or bool(self._user_usernames and (user_username in self._user_usernames))
+        )

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/paidmediapurchasedhandler.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program. If not, see [http://www.gnu.org/licenses/].
+"""This module contains the PaidMediaPurchased class."""
+
+from typing import Optional
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import SCT, DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils._update_parsing import parse_chat_id, parse_username
+from telegram.ext._utils.types import CCT, RT, HandlerCallback
+
+
+class PaidMediaPurchasedHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram
+    :attr:`purchased paid media <telegram.Update.purchased_paid_media>`.
+
+    .. versionadded:: 21.6
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+        user_id (:obj:`int` | Collection[:obj:`int`], optional): Filters requests to allow only
+            those which are from the specified user ID(s).
+
+        username (:obj:`str` | Collection[:obj:`str`], optional): Filters requests to allow only
+            those which are from the specified username(s).
+
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+    """
+
+    __slots__ = (
+        "_user_ids",
+        "_usernames",
+    )
+
+    def __init__(
+        self: "PaidMediaPurchasedHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        user_id: Optional[SCT[int]] = None,
+        username: Optional[SCT[str]] = None,
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback, block=block)
+
+        self._user_ids = parse_chat_id(user_id)
+        self._usernames = parse_username(username)
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if not isinstance(update, Update) or not update.purchased_paid_media:
+            return False
+
+        if not self._user_ids and not self._usernames:
+            return True
+        if update.purchased_paid_media.from_user.id in self._user_ids:
+            return True
+        return update.purchased_paid_media.from_user.username in self._usernames

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/pollanswerhandler.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser Public License
+#  along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the PollAnswerHandler class."""
+
+
+from telegram import Update
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, RT
+
+
+class PollAnswerHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram updates that contain a
+    :attr:`poll answer <telegram.Update.poll_answer>`.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Examples:
+        :any:`Poll Bot <examples.pollbot>`
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the callback will run in a blocking way..
+
+    """
+
+    __slots__ = ()
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        return isinstance(update, Update) and bool(update.poll_answer)

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/pollhandler.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the PollHandler class."""
+
+
+from telegram import Update
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, RT
+
+
+class PollHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram updates that contain a
+    :attr:`poll <telegram.Update.poll>`.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Examples:
+        :any:`Poll Bot <examples.pollbot>`
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the callback will run in a blocking way..
+
+    """
+
+    __slots__ = ()
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        return isinstance(update, Update) and bool(update.poll)

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/precheckoutqueryhandler.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the PreCheckoutQueryHandler class."""
+
+
+import re
+from re import Pattern
+from typing import Optional, TypeVar, Union
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+RT = TypeVar("RT")
+
+
+class PreCheckoutQueryHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram :attr:`telegram.Update.pre_checkout_query`.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Examples:
+        :any:`Payment Bot <examples.paymentbot>`
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+        pattern (:obj:`str` | :func:`re.Pattern <re.compile>`, optional): Optional. Regex pattern
+            to test :attr:`telegram.PreCheckoutQuery.invoice_payload` against.
+
+            .. versionadded:: 20.8
+
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the callback will run in a blocking way..
+        pattern (:obj:`str` | :func:`re.Pattern <re.compile>`, optional): Optional. Regex pattern
+            to test :attr:`telegram.PreCheckoutQuery.invoice_payload` against.
+
+            .. versionadded:: 20.8
+
+    """
+
+    __slots__ = ("pattern",)
+
+    def __init__(
+        self: "PreCheckoutQueryHandler[CCT, RT]",
+        callback: HandlerCallback[Update, CCT, RT],
+        block: DVType[bool] = DEFAULT_TRUE,
+        pattern: Optional[Union[str, Pattern[str]]] = None,
+    ):
+        super().__init__(callback, block=block)
+
+        self.pattern: Optional[Pattern[str]] = re.compile(pattern) if pattern is not None else None
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if isinstance(update, Update) and update.pre_checkout_query:
+            invoice_payload = update.pre_checkout_query.invoice_payload
+            if self.pattern:
+                if self.pattern.match(invoice_payload):
+                    return True
+            else:
+                return True
+        return False

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/prefixhandler.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the PrefixHandler class."""
+import itertools
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
+
+from telegram import Update
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import SCT, DVType
+from telegram.ext import filters as filters_module
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+if TYPE_CHECKING:
+    from telegram.ext import Application
+
+RT = TypeVar("RT")
+
+
+class PrefixHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle custom prefix commands.
+
+    This is an intermediate handler between :class:`MessageHandler` and :class:`CommandHandler`.
+    It supports configurable commands with the same options as :class:`CommandHandler`. It will
+    respond to every combination of :paramref:`prefix` and :paramref:`command`.
+    It will add a :obj:`list` to the :class:`CallbackContext` named :attr:`CallbackContext.args`,
+    containing a list of strings, which is the text following the command split on single or
+    consecutive whitespace characters.
+
+    Examples:
+
+        Single prefix and command:
+
+        .. code:: python
+
+            PrefixHandler("!", "test", callback)  # will respond to '!test'.
+
+        Multiple prefixes, single command:
+
+        .. code:: python
+
+            PrefixHandler(["!", "#"], "test", callback)  # will respond to '!test' and '#test'.
+
+        Multiple prefixes and commands:
+
+        .. code:: python
+
+            PrefixHandler(
+                ["!", "#"], ["test", "help"], callback
+            )  # will respond to '!test', '#test', '!help' and '#help'.
+
+
+    By default, the handler listens to messages as well as edited messages. To change this behavior
+    use :attr:`~filters.UpdateType.EDITED_MESSAGE <telegram.ext.filters.UpdateType.EDITED_MESSAGE>`
+
+    Note:
+        * :class:`PrefixHandler` does *not* handle (edited) channel posts.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    .. versionchanged:: 20.0
+
+        * :class:`PrefixHandler` is no longer a subclass of :class:`CommandHandler`.
+        * Removed the attributes ``command`` and ``prefix``. Instead, the new :attr:`commands`
+          contains all commands that this handler listens to as a :class:`frozenset`, which
+          includes the prefixes.
+        * Updating the prefixes and commands this handler listens to is no longer possible.
+
+    Args:
+        prefix (:obj:`str` | Collection[:obj:`str`]):
+            The prefix(es) that will precede :paramref:`command`.
+        command (:obj:`str` | Collection[:obj:`str`]):
+            The command or list of commands this handler should listen for. Case-insensitive.
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        filters (:class:`telegram.ext.filters.BaseFilter`, optional): A filter inheriting from
+            :class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
+            :mod:`telegram.ext.filters`. Filters can be combined using bitwise
+            operators (``&`` for :keyword:`and`, ``|`` for :keyword:`or`, ``~`` for :keyword:`not`)
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        commands (frozenset[:obj:`str`]): The commands that this handler will listen for, i.e. the
+            combinations of :paramref:`prefix` and :paramref:`command`.
+        callback (:term:`coroutine function`): The callback function for this handler.
+        filters (:class:`telegram.ext.filters.BaseFilter`): Optional. Only allow updates with these
+            Filters.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+
+    """
+
+    # 'prefix' is a class property, & 'command' is included in the superclass, so they're left out.
+    __slots__ = ("commands", "filters")
+
+    def __init__(
+        self: "PrefixHandler[CCT, RT]",
+        prefix: SCT[str],
+        command: SCT[str],
+        callback: HandlerCallback[Update, CCT, RT],
+        filters: Optional[filters_module.BaseFilter] = None,
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback=callback, block=block)
+
+        prefixes = {prefix.lower()} if isinstance(prefix, str) else {x.lower() for x in prefix}
+
+        commands = {command.lower()} if isinstance(command, str) else {x.lower() for x in command}
+
+        self.commands: frozenset[str] = frozenset(
+            p + c for p, c in itertools.product(prefixes, commands)
+        )
+        self.filters: filters_module.BaseFilter = (
+            filters if filters is not None else filters_module.UpdateType.MESSAGES
+        )
+
+    def check_update(
+        self, update: object
+    ) -> Optional[Union[bool, tuple[list[str], Optional[Union[bool, dict[Any, Any]]]]]]:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`list`: The list of args for the handler.
+
+        """
+        if isinstance(update, Update) and update.effective_message:
+            message = update.effective_message
+
+            if message.text:
+                text_list = message.text.split()
+                if text_list[0].lower() not in self.commands:
+                    return None
+                filter_result = self.filters.check_update(update)
+                if filter_result:
+                    return text_list[1:], filter_result
+                return False
+        return None
+
+    def collect_additional_context(
+        self,
+        context: CCT,
+        update: Update,  # noqa: ARG002
+        application: "Application[Any, CCT, Any, Any, Any, Any]",  # noqa: ARG002
+        check_result: Optional[Union[bool, tuple[list[str], Optional[bool]]]],
+    ) -> None:
+        """Add text after the command to :attr:`CallbackContext.args` as list, split on single
+        whitespaces and add output of data filters to :attr:`CallbackContext` as well.
+        """
+        if isinstance(check_result, tuple):
+            context.args = check_result[0]
+            if isinstance(check_result[1], dict):
+                context.update(check_result[1])

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/shippingqueryhandler.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the ShippingQueryHandler class."""
+
+
+from telegram import Update
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, RT
+
+
+class ShippingQueryHandler(BaseHandler[Update, CCT, RT]):
+    """Handler class to handle Telegram :attr:`telegram.Update.shipping_query`.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Examples:
+        :any:`Payment Bot <examples.paymentbot>`
+
+    Args:
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: Update, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the callback will run in a blocking way..
+
+    """
+
+    __slots__ = ()
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        return isinstance(update, Update) and bool(update.shipping_query)

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/stringcommandhandler.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the StringCommandHandler class."""
+
+from typing import TYPE_CHECKING, Any, Optional
+
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, RT, HandlerCallback
+
+if TYPE_CHECKING:
+    from telegram.ext import Application
+
+
+class StringCommandHandler(BaseHandler[str, CCT, RT]):
+    """Handler class to handle string commands. Commands are string updates that start with
+    ``/``. The handler will add a :obj:`list` to the
+    :class:`CallbackContext` named :attr:`CallbackContext.args`. It will contain a list of strings,
+    which is the text following the command split on single whitespace characters.
+
+    Note:
+        This handler is not used to handle Telegram :class:`telegram.Update`, but strings manually
+        put in the queue. For example to send messages with the bot using command line or API.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Args:
+        command (:obj:`str`): The command this handler should listen for.
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: str, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        command (:obj:`str`): The command this handler should listen for.
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+
+    """
+
+    __slots__ = ("command",)
+
+    def __init__(
+        self: "StringCommandHandler[CCT, RT]",
+        command: str,
+        callback: HandlerCallback[str, CCT, RT],
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback, block=block)
+        self.command: str = command
+
+    def check_update(self, update: object) -> Optional[list[str]]:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:obj:`object`): The incoming update.
+
+        Returns:
+            list[:obj:`str`]: List containing the text command split on whitespace.
+
+        """
+        if isinstance(update, str) and update.startswith("/"):
+            args = update[1:].split(" ")
+            if args[0] == self.command:
+                return args[1:]
+        return None
+
+    def collect_additional_context(
+        self,
+        context: CCT,
+        update: str,  # noqa: ARG002
+        application: "Application[Any, CCT, Any, Any, Any, Any]",  # noqa: ARG002
+        check_result: Optional[list[str]],
+    ) -> None:
+        """Add text after the command to :attr:`CallbackContext.args` as list, split on single
+        whitespaces.
+        """
+        context.args = check_result

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/stringregexhandler.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the StringRegexHandler class."""
+
+import re
+from re import Match, Pattern
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
+
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+if TYPE_CHECKING:
+    from telegram.ext import Application
+
+RT = TypeVar("RT")
+
+
+class StringRegexHandler(BaseHandler[str, CCT, RT]):
+    """Handler class to handle string updates based on a regex which checks the update content.
+
+    Read the documentation of the :mod:`re` module for more information. The :func:`re.match`
+    function is used to determine if an update should be handled by this handler.
+
+    Note:
+        This handler is not used to handle Telegram :class:`telegram.Update`, but strings manually
+        put in the queue. For example to send messages with the bot using command line or API.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Args:
+        pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: str, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        pattern (:obj:`str` | :func:`re.Pattern <re.compile>`): The regex pattern.
+        callback (:term:`coroutine function`): The callback function for this handler.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+
+    """
+
+    __slots__ = ("pattern",)
+
+    def __init__(
+        self: "StringRegexHandler[CCT, RT]",
+        pattern: Union[str, Pattern[str]],
+        callback: HandlerCallback[str, CCT, RT],
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback, block=block)
+
+        if isinstance(pattern, str):
+            pattern = re.compile(pattern)
+
+        self.pattern: Union[str, Pattern[str]] = pattern
+
+    def check_update(self, update: object) -> Optional[Match[str]]:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:obj:`object`): The incoming update.
+
+        Returns:
+            :obj:`None` | :obj:`re.match`
+
+        """
+        if isinstance(update, str) and (match := re.match(self.pattern, update)):
+            return match
+        return None
+
+    def collect_additional_context(
+        self,
+        context: CCT,
+        update: str,  # noqa: ARG002
+        application: "Application[Any, CCT, Any, Any, Any, Any]",  # noqa: ARG002
+        check_result: Optional[Match[str]],
+    ) -> None:
+        """Add the result of ``re.match(pattern, update)`` to :attr:`CallbackContext.matches` as
+        list with one element.
+        """
+        if self.pattern and check_result:
+            context.matches = [check_result]

.venv/lib/python3.10/site-packages/telegram/ext/_handlers/typehandler.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2024
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the TypeHandler class."""
+
+from typing import Optional, TypeVar
+
+from telegram._utils.defaultvalue import DEFAULT_TRUE
+from telegram._utils.types import DVType
+from telegram.ext._handlers.basehandler import BaseHandler
+from telegram.ext._utils.types import CCT, HandlerCallback
+
+RT = TypeVar("RT")
+UT = TypeVar("UT")
+# If this is written directly next to the type variable mypy gets confused with [valid-type]. This
+# could be reported to them, but I doubt they would change this since we override a builtin type
+GenericUT = type[UT]
+
+
+class TypeHandler(BaseHandler[UT, CCT, RT]):
+    """Handler class to handle updates of custom types.
+
+    Warning:
+        When setting :paramref:`block` to :obj:`False`, you cannot rely on adding custom
+        attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
+    Args:
+        type (:external:class:`type`): The :external:class:`type` of updates this handler should
+            process, as determined by :obj:`isinstance`
+        callback (:term:`coroutine function`): The callback function for this handler. Will be
+            called when :meth:`check_update` has determined that an update should be processed by
+            this handler. Callback signature::
+
+                async def callback(update: object, context: CallbackContext)
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        strict (:obj:`bool`, optional): Use ``type`` instead of :obj:`isinstance`.
+            Default is :obj:`False`.
+        block (:obj:`bool`, optional): Determines whether the return value of the callback should
+            be awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`. Defaults to :obj:`True`.
+
+            .. seealso:: :wiki:`Concurrency`
+
+    Attributes:
+        type (:external:class:`type`): The :external:class:`type` of updates this handler should
+            process.
+        callback (:term:`coroutine function`): The callback function for this handler.
+        strict (:obj:`bool`): Use :external:class:`type` instead of :obj:`isinstance`. Default is
+            :obj:`False`.
+        block (:obj:`bool`): Determines whether the return value of the callback should be
+            awaited before processing the next handler in
+            :meth:`telegram.ext.Application.process_update`.
+
+    """
+
+    __slots__ = ("strict", "type")
+
+    def __init__(
+        self: "TypeHandler[UT, CCT, RT]",
+        type: GenericUT[UT],  # pylint: disable=redefined-builtin
+        callback: HandlerCallback[UT, CCT, RT],
+        strict: bool = False,
+        block: DVType[bool] = DEFAULT_TRUE,
+    ):
+        super().__init__(callback, block=block)
+        self.type: GenericUT[UT] = type
+        self.strict: Optional[bool] = strict
+
+    def check_update(self, update: object) -> bool:
+        """Determines whether an update should be passed to this handler's :attr:`callback`.
+
+        Args:
+            update (:obj:`object`): Incoming update.
+
+        Returns:
+            :obj:`bool`
+
+        """
+        if not self.strict:
+            return isinstance(update, self.type)
+        return type(update) is self.type  # pylint: disable=unidiomatic-typecheck