Accept datetime.timedelta Input in Bot Method Parameters (python-…

…telegram-bot#4651)

docs/substitutions/global.rst

@@ -96,4 +96,6 @@
 
 .. |allow_paid_broadcast| replace:: Pass True to allow up to :tg-const:`telegram.constants.FloodLimit.PAID_MESSAGES_PER_SECOND` messages per second, ignoring `broadcasting limits <https://core.telegram.org/bots/faq#how-can-i-message-all-of-my-bot-39s-subscribers-at-once>`__ for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot's balance.
 
-.. |tz-naive-dtms| replace:: For timezone naive :obj:`datetime.datetime` objects, the default timezone of the bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used.
+.. |tz-naive-dtms| replace:: For timezone naive :obj:`datetime.datetime` objects, the default timezone of the bot will be used, which is UTC unless :attr:`telegram.ext.Defaults.tzinfo` is used.
+
+.. |time-period-input| replace:: :class:`datetime.timedelta` objects are accepted in addition to plain :obj:`int` values.

telegram/_bot.py

@@ -103,6 +103,7 @@
     JSONDict,
     ODVInput,
     ReplyMarkup,
+    TimePeriod,
 )
 from telegram._utils.warnings import warn
 from telegram._webhookinfo import WebhookInfo
@@ -1492,7 +1493,7 @@ async def send_audio(
         self,
         chat_id: Union[int, str],
         audio: Union[FileInput, "Audio"],
-        duration: Optional[int] = None,
+        duration: Optional[TimePeriod] = None,
         performer: Optional[str] = None,
         title: Optional[str] = None,
         caption: Optional[str] = None,
@@ -1554,7 +1555,11 @@ async def send_audio(
 
                 .. versionchanged:: 20.0
                     |sequenceargs|
-            duration (:obj:`int`, optional): Duration of sent audio in seconds.
+            duration (:obj:`int` | :class:`datetime.timedelta`, optional): Duration of sent audio
+                in seconds.
+
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
             performer (:obj:`str`, optional): Performer.
             title (:obj:`str`, optional): Track name.
             disable_notification (:obj:`bool`, optional): |disable_notification|
@@ -1932,7 +1937,7 @@ async def send_video(
         self,
         chat_id: Union[int, str],
         video: Union[FileInput, "Video"],
-        duration: Optional[int] = None,
+        duration: Optional[TimePeriod] = None,
         caption: Optional[str] = None,
         disable_notification: ODVInput[bool] = DEFAULT_NONE,
         reply_markup: Optional[ReplyMarkup] = None,
@@ -1990,7 +1995,11 @@ async def send_video(
                 .. versionchanged:: 20.0
                     File paths as input is also accepted for bots *not* running in
                     :paramref:`~telegram.Bot.local_mode`.
-            duration (:obj:`int`, optional): Duration of sent video in seconds.
+            duration (:obj:`int` | :class:`datetime.timedelta`, optional): Duration of sent video
+                in seconds.
+
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
             width (:obj:`int`, optional): Video width.
             height (:obj:`int`, optional): Video height.
             caption (:obj:`str`, optional): Video caption (may also be used when resending videos
@@ -2111,7 +2120,7 @@ async def send_video_note(
         self,
         chat_id: Union[int, str],
         video_note: Union[FileInput, "VideoNote"],
-        duration: Optional[int] = None,
+        duration: Optional[TimePeriod] = None,
         length: Optional[int] = None,
         disable_notification: ODVInput[bool] = DEFAULT_NONE,
         reply_markup: Optional[ReplyMarkup] = None,
@@ -2163,7 +2172,11 @@ async def send_video_note(
                 .. versionchanged:: 20.0
                     File paths as input is also accepted for bots *not* running in
                     :paramref:`~telegram.Bot.local_mode`.
-            duration (:obj:`int`, optional): Duration of sent video in seconds.
+            duration (:obj:`int` | :class:`datetime.timedelta`, optional): Duration of sent video
+                in seconds.
+
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
             length (:obj:`int`, optional): Video width and height, i.e. diameter of the video
                 message.
             disable_notification (:obj:`bool`, optional): |disable_notification|
@@ -2259,7 +2272,7 @@ async def send_animation(
         self,
         chat_id: Union[int, str],
         animation: Union[FileInput, "Animation"],
-        duration: Optional[int] = None,
+        duration: Optional[TimePeriod] = None,
         width: Optional[int] = None,
         height: Optional[int] = None,
         caption: Optional[str] = None,
@@ -2311,7 +2324,11 @@ async def send_animation(
 
                 .. versionchanged:: 13.2
                    Accept :obj:`bytes` as input.
-            duration (:obj:`int`, optional): Duration of sent animation in seconds.
+            duration (:obj:`int` | :class:`datetime.timedelta`, optional): Duration of sent
+                animation in seconds.
+
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
             width (:obj:`int`, optional): Animation width.
             height (:obj:`int`, optional): Animation height.
             caption (:obj:`str`, optional): Animation caption (may also be used when resending
@@ -2430,7 +2447,7 @@ async def send_voice(
         self,
         chat_id: Union[int, str],
         voice: Union[FileInput, "Voice"],
-        duration: Optional[int] = None,
+        duration: Optional[TimePeriod] = None,
         caption: Optional[str] = None,
         disable_notification: ODVInput[bool] = DEFAULT_NONE,
         reply_markup: Optional[ReplyMarkup] = None,
@@ -2491,7 +2508,11 @@ async def send_voice(
 
                 .. versionchanged:: 20.0
                     |sequenceargs|
-            duration (:obj:`int`, optional): Duration of the voice message in seconds.
+            duration (:obj:`int` | :class:`datetime.timedelta`, optional): Duration of the voice
+                message in seconds.
+
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
             disable_notification (:obj:`bool`, optional): |disable_notification|
             protect_content (:obj:`bool`, optional): |protect_content|
 
@@ -2763,7 +2784,7 @@ async def send_location(
         longitude: Optional[float] = None,
         disable_notification: ODVInput[bool] = DEFAULT_NONE,
         reply_markup: Optional[ReplyMarkup] = None,
-        live_period: Optional[int] = None,
+        live_period: Optional[TimePeriod] = None,
         horizontal_accuracy: Optional[float] = None,
         heading: Optional[int] = None,
         proximity_alert_radius: Optional[int] = None,
@@ -2796,12 +2817,16 @@ async def send_location(
             horizontal_accuracy (:obj:`int`, optional): The radius of uncertainty for the location,
                 measured in meters;
                 0-:tg-const:`telegram.constants.LocationLimit.HORIZONTAL_ACCURACY`.
-            live_period (:obj:`int`, optional): Period in seconds for which the location will be
+            live_period (:obj:`int` | :class:`datetime.timedelta`, optional): Period in seconds for
+                which the location will be
                 updated, should be between
                 :tg-const:`telegram.constants.LocationLimit.MIN_LIVE_PERIOD` and
                 :tg-const:`telegram.constants.LocationLimit.MAX_LIVE_PERIOD`, or
                 :tg-const:`telegram.constants.LocationLimit.LIVE_PERIOD_FOREVER` for live
                 locations that can be edited indefinitely.
+
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
             heading (:obj:`int`, optional): For live locations, a direction in which the user is
                 moving, in degrees. Must be between
                 :tg-const:`telegram.constants.LocationLimit.MIN_HEADING` and
@@ -2919,7 +2944,7 @@ async def edit_message_live_location(
         horizontal_accuracy: Optional[float] = None,
         heading: Optional[int] = None,
         proximity_alert_radius: Optional[int] = None,
-        live_period: Optional[int] = None,
+        live_period: Optional[TimePeriod] = None,
         business_connection_id: Optional[str] = None,
         *,
         location: Optional[Location] = None,
@@ -2959,7 +2984,8 @@ async def edit_message_live_location(
                 if specified.
             reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): An object for a new
                 inline keyboard.
-            live_period (:obj:`int`, optional): New period in seconds during which the location
+            live_period (:obj:`int` | :class:`datetime.timedelta`, optional): New period in seconds
+                during which the location
                 can be updated, starting from the message send date. If
                 :tg-const:`telegram.constants.LocationLimit.LIVE_PERIOD_FOREVER` is specified,
                 then the location can be updated forever. Otherwise, the new value must not exceed
@@ -2968,6 +2994,9 @@ async def edit_message_live_location(
                 remains unchanged
 
                 .. versionadded:: 21.2.
+
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
             business_connection_id (:obj:`str`, optional): |business_id_str_edit|
 
                 .. versionadded:: 21.4
@@ -3623,7 +3652,7 @@ async def answer_inline_query(
         results: Union[
             Sequence["InlineQueryResult"], Callable[[int], Optional[Sequence["InlineQueryResult"]]]
         ],
-        cache_time: Optional[int] = None,
+        cache_time: Optional[TimePeriod] = None,
         is_personal: Optional[bool] = None,
         next_offset: Optional[str] = None,
         button: Optional[InlineQueryResultsButton] = None,
@@ -3659,8 +3688,12 @@ async def answer_inline_query(
                 a callable that accepts the current page index starting from 0. It must return
                 either a list of :class:`telegram.InlineQueryResult` instances or :obj:`None` if
                 there are no more results.
-            cache_time (:obj:`int`, optional): The maximum amount of time in seconds that the
+            cache_time (:obj:`int` | :class:`datetime.timedelta`, optional): The maximum amount of
+                time in seconds that the
                 result of the inline query may be cached on the server. Defaults to ``300``.
+
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
             is_personal (:obj:`bool`, optional): Pass :obj:`True`, if results may be cached on
                 the server side only for the user that sent the query. By default,
                 results may be returned to any user who sends the same query.
@@ -4076,7 +4109,7 @@ async def answer_callback_query(
         text: Optional[str] = None,
         show_alert: Optional[bool] = None,
         url: Optional[str] = None,
-        cache_time: Optional[int] = None,
+        cache_time: Optional[TimePeriod] = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -4107,9 +4140,13 @@ async def answer_callback_query(
                 opens your game - note that this will only work if the query comes from a callback
                 game button. Otherwise, you may use links like t.me/your_bot?start=XXXX that open
                 your bot with a parameter.
-            cache_time (:obj:`int`, optional): The maximum amount of time in seconds that the
+            cache_time (:obj:`int` | :class:`datetime.timedelta`, optional): The maximum amount of
+                time in seconds that the
                 result of the callback query may be cached client-side. Defaults to 0.
 
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
+
         Returns:
             :obj:`bool` On success, :obj:`True` is returned.
 
@@ -7261,7 +7298,7 @@ async def send_poll(
         reply_markup: Optional[ReplyMarkup] = None,
         explanation: Optional[str] = None,
         explanation_parse_mode: ODVInput[str] = DEFAULT_NONE,
-        open_period: Optional[int] = None,
+        open_period: Optional[TimePeriod] = None,
         close_date: Optional[Union[int, dtm.datetime]] = None,
         explanation_entities: Optional[Sequence["MessageEntity"]] = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
@@ -7324,10 +7361,14 @@ async def send_poll(
 
                 .. versionchanged:: 20.0
                     |sequenceargs|
-            open_period (:obj:`int`, optional): Amount of time in seconds the poll will be active
+            open_period (:obj:`int` | :class:`datetime.timedelta`, optional): Amount of time in
+                seconds the poll will be active
                 after creation, :tg-const:`telegram.Poll.MIN_OPEN_PERIOD`-
                 :tg-const:`telegram.Poll.MAX_OPEN_PERIOD`. Can't be used together with
                 :paramref:`close_date`.
+
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
             close_date (:obj:`int` | :obj:`datetime.datetime`, optional): Point in time (Unix
                 timestamp) when the poll will be automatically closed. Must be at least
                 :tg-const:`telegram.Poll.MIN_OPEN_PERIOD` and no more than
@@ -8228,7 +8269,7 @@ async def create_invoice_link(
         send_phone_number_to_provider: Optional[bool] = None,
         send_email_to_provider: Optional[bool] = None,
         is_flexible: Optional[bool] = None,
-        subscription_period: Optional[Union[int, dtm.timedelta]] = None,
+        subscription_period: Optional[TimePeriod] = None,
         business_connection_id: Optional[str] = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -8349,11 +8390,7 @@ async def create_invoice_link(
             "is_flexible": is_flexible,
             "send_phone_number_to_provider": send_phone_number_to_provider,
             "send_email_to_provider": send_email_to_provider,
-            "subscription_period": (
-                subscription_period.total_seconds()
-                if isinstance(subscription_period, dtm.timedelta)
-                else subscription_period
-            ),
+            "subscription_period": subscription_period,
             "business_connection_id": business_connection_id,
         }
 
@@ -9644,7 +9681,7 @@ async def send_paid_media(
     async def create_chat_subscription_invite_link(
         self,
         chat_id: Union[str, int],
-        subscription_period: int,
+        subscription_period: TimePeriod,
         subscription_price: int,
         name: Optional[str] = None,
         *,
@@ -9665,9 +9702,13 @@ async def create_chat_subscription_invite_link(
 
         Args:
             chat_id (:obj:`int` | :obj:`str`): |chat_id_channel|
-            subscription_period (:obj:`int`): The number of seconds the subscription will be
+            subscription_period (:obj:`int` | :class:`datetime.timedelta`): The number of seconds
+                the subscription will be
                 active for before the next payment. Currently, it must always be
                 :tg-const:`telegram.constants.ChatSubscriptionLimit.SUBSCRIPTION_PERIOD` (30 days).
+
+                .. versionchanged:: NEXT.VERSION
+                    |time-period-input|
             subscription_price (:obj:`int`): The number of Telegram Stars a user must pay initially
                 and after each subsequent subscription period to be a member of the chat;
                 :tg-const:`telegram.constants.ChatSubscriptionLimit.MIN_PRICE`-

telegram/_callbackquery.py

@@ -28,7 +28,7 @@
 from telegram._user import User
 from telegram._utils.argumentparsing import de_json_optional
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import JSONDict, ODVInput, ReplyMarkup
+from telegram._utils.types import JSONDict, ODVInput, ReplyMarkup, TimePeriod
 
 if TYPE_CHECKING:
     from telegram import (
@@ -164,7 +164,7 @@ async def answer(
         text: Optional[str] = None,
         show_alert: Optional[bool] = None,
         url: Optional[str] = None,
-        cache_time: Optional[int] = None,
+        cache_time: Optional[TimePeriod] = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -471,7 +471,7 @@ async def edit_message_live_location(
         horizontal_accuracy: Optional[float] = None,
         heading: Optional[int] = None,
         proximity_alert_radius: Optional[int] = None,
-        live_period: Optional[int] = None,
+        live_period: Optional[TimePeriod] = None,
         *,
         location: Optional[Location] = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,