Doc fixes

docs/source/telegram.ext.dispatcherhandlerstop.rst

@@ -0,0 +1,6 @@
+telegram.ext.DispatcherHandlerStop
+==================================
+
+.. autoclass:: telegram.ext.DispatcherHandlerStop
+    :members:
+    :show-inheritance:

docs/source/telegram.ext.rst

@@ -5,6 +5,7 @@ telegram.ext package
 
     telegram.ext.updater
     telegram.ext.dispatcher
+    telegram.ext.dispatcherhandlerstop
     telegram.ext.filters
     telegram.ext.job
     telegram.ext.jobqueue

telegram/ext/dispatcher.py

@@ -397,7 +397,8 @@ def persist_update(update):
     def add_handler(self, handler, group=DEFAULT_GROUP):
         """Register a handler.
 
-        TL;DR: Order and priority counts. 0 or 1 handlers per group will be used.
+        TL;DR: Order and priority counts. 0 or 1 handlers per group will be used. End handling of
+        update with :class:`telegram.ext.DispatcherHandlerStop`.
 
         A handler must be an instance of a subclass of :class:`telegram.ext.Handler`. All handlers
         are organized in groups with a numeric value. The default group is 0. All groups will be

telegram/ext/jobqueue.py

@@ -113,9 +113,12 @@ def run_once(self, callback, when, context=None, name=None):
 
         Args:
             callback (:obj:`callable`): The callback function that should be executed by the new
-                job. It should take ``bot, job`` as parameters, where ``job`` is the
-                :class:`telegram.ext.Job` instance. It can be used to access its
-                ``job.context`` or change it to a repeating job.
+                job. Callback signature for context based API:
+
+                    ``def callback(CallbackContext)``
+
+                ``context.job`` is the :class:`telegram.ext.Job` instance. It can be used to access
+                its ``job.context`` or change it to a repeating job.
             when (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` |                         \
                   :obj:`datetime.datetime` | :obj:`datetime.time`):
                 Time in or at which the job should run. This parameter will be interpreted
@@ -150,9 +153,12 @@ def run_repeating(self, callback, interval, first=None, context=None, name=None)
 
         Args:
             callback (:obj:`callable`): The callback function that should be executed by the new
-                job. It should take ``bot, job`` as parameters, where ``job`` is the
-                :class:`telegram.ext.Job` instance. It can be used to access its
-                ``Job.context`` or change it to a repeating job.
+                job. Callback signature for context based API:
+
+                    ``def callback(CallbackContext)``
+
+                ``context.job`` is the :class:`telegram.ext.Job` instance. It can be used to access
+                its ``job.context`` or change it to a repeating job.
             interval (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta`): The interval in which
                 the job will run. If it is an :obj:`int` or a :obj:`float`, it will be interpreted
                 as seconds.
@@ -201,9 +207,12 @@ def run_daily(self, callback, time, days=Days.EVERY_DAY, context=None, name=None
 
         Args:
             callback (:obj:`callable`): The callback function that should be executed by the new
-                job. It should take ``bot, job`` as parameters, where ``job`` is the
-                :class:`telegram.ext.Job` instance. It can be used to access its ``Job.context``
-                or change it to a repeating job.
+                job. Callback signature for context based API:
+
+                    ``def callback(CallbackContext)``
+
+                ``context.job`` is the :class:`telegram.ext.Job` instance. It can be used to access
+                its ``job.context`` or change it to a repeating job.
             time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
                 (``time.tzinfo``) is ``None``, UTC will be assumed.
             days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should
@@ -358,9 +367,12 @@ class Job(object):
 
     Args:
         callback (:obj:`callable`): The callback function that should be executed by the new job.
-            It should take ``bot, job`` as parameters, where ``job`` is the
-            :class:`telegram.ext.Job` instance. It can be used to access it's :attr:`context`
-            or change it to a repeating job.
+            Callback signature for context based API:
+
+                ``def callback(CallbackContext)``
+
+            a ``context.job`` is the :class:`telegram.ext.Job` instance. It can be used to access
+            its ``job.context`` or change it to a repeating job.
         interval (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta`, optional): The time
             interval between executions of the job. If it is an :obj:`int` or a :obj:`float`,
             it will be interpreted as seconds. If you don't set this value, you must set

telegram/files/inputmedia.py

@@ -44,7 +44,7 @@ class InputMediaAnimation(InputMedia):
             Lastly you can pass an existing :class:`telegram.Animation` object to send.
         thumb (`filelike object`): Optional. Thumbnail of the
             file sent. The thumbnail should be in JPEG format and less than 200 kB in size.
-            A thumbnail's width and height should not exceed 90. Ignored if the file is not
+            A thumbnail's width and height should not exceed 320. Ignored if the file is not
             is passed as a string or file_id.
         caption (:obj:`str`): Optional. Caption of the animation to be sent, 0-1024 characters.
         parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
@@ -61,7 +61,7 @@ class InputMediaAnimation(InputMedia):
             Lastly you can pass an existing :class:`telegram.Animation` object to send.
         thumb (`filelike object`, optional): Thumbnail of the
             file sent. The thumbnail should be in JPEG format and less than 200 kB in size.
-            A thumbnail's width and height should not exceed 90. Ignored if the file is not
+            A thumbnail's width and height should not exceed 320. Ignored if the file is not
             is passed as a string or file_id.
         caption (:obj:`str`, optional): Caption of the animation to be sent, 0-1024 characters.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
@@ -170,7 +170,7 @@ class InputMediaVideo(InputMedia):
             for streaming.
         thumb (`filelike object`): Optional. Thumbnail of the
             file sent. The thumbnail should be in JPEG format and less than 200 kB in size.
-            A thumbnail's width and height should not exceed 90. Ignored if the file is not
+            A thumbnail's width and height should not exceed 320. Ignored if the file is not
             is passed as a string or file_id.
 
     Args:
@@ -188,7 +188,7 @@ class InputMediaVideo(InputMedia):
             for streaming.
         thumb (`filelike object`, optional): Thumbnail of the
             file sent. The thumbnail should be in JPEG format and less than 200 kB in size.
-            A thumbnail's width and height should not exceed 90. Ignored if the file is not
+            A thumbnail's width and height should not exceed 320. Ignored if the file is not
             is passed as a string or file_id.
 
     Note:
@@ -250,7 +250,7 @@ class InputMediaAudio(InputMedia):
         title (:obj:`str`): Optional. Title of the audio as defined by sender or by audio tags.
         thumb (`filelike object`): Optional. Thumbnail of the
             file sent. The thumbnail should be in JPEG format and less than 200 kB in size.
-            A thumbnail's width and height should not exceed 90. Ignored if the file is not
+            A thumbnail's width and height should not exceed 320. Ignored if the file is not
             is passed as a string or file_id.
 
     Args:
@@ -267,7 +267,7 @@ class InputMediaAudio(InputMedia):
         title (:obj:`str`, optional): Title of the audio as defined by sender or by audio tags.
         thumb (`filelike object`, optional): Thumbnail of the
             file sent. The thumbnail should be in JPEG format and less than 200 kB in size.
-            A thumbnail's width and height should not exceed 90. Ignored if the file is not
+            A thumbnail's width and height should not exceed 320. Ignored if the file is not
             is passed as a string or file_id.
 
     Note:
@@ -323,7 +323,7 @@ class InputMediaDocument(InputMedia):
             in :class:`telegram.ParseMode` for the available modes.
         thumb (`filelike object`): Optional. Thumbnail of the
             file sent. The thumbnail should be in JPEG format and less than 200 kB in size.
-            A thumbnail's width and height should not exceed 90. Ignored if the file is not
+            A thumbnail's width and height should not exceed 320. Ignored if the file is not
             is passed as a string or file_id.
 
     Args:
@@ -336,7 +336,7 @@ class InputMediaDocument(InputMedia):
             in :class:`telegram.ParseMode` for the available modes.
         thumb (`filelike object`, optional): Thumbnail of the
             file sent. The thumbnail should be in JPEG format and less than 200 kB in size.
-            A thumbnail's width and height should not exceed 90. Ignored if the file is not
+            A thumbnail's width and height should not exceed 320. Ignored if the file is not
             is passed as a string or file_id.
     """
 

telegram/inline/inlinequery.py

@@ -35,15 +35,15 @@ class InlineQuery(TelegramObject):
         from_user (:class:`telegram.User`): Sender.
         location (:class:`telegram.Location`): Optional. Sender location, only for bots that
             request user location.
-        query (:obj:`str`): Text of the query (up to 512 characters).
+        query (:obj:`str`): Text of the query (up to 256 characters).
         offset (:obj:`str`): Offset of the results to be returned, can be controlled by the bot.
 
     Args:
         id (:obj:`str`): Unique identifier for this query.
         from_user (:class:`telegram.User`): Sender.
         location (:class:`telegram.Location`, optional): Sender location, only for bots that
             request user location.
-        query (:obj:`str`): Text of the query (up to 512 characters).
+        query (:obj:`str`): Text of the query (up to 256 characters).
         offset (:obj:`str`): Offset of the results to be returned, can be controlled by the bot.
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.

telegram/message.py

@@ -580,7 +580,7 @@ def reply_audio(self, *args, **kwargs):
             bot.send_audio(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
+            quote (:obj:`bool`, optional): If set to ``True``, the audio is sent as an actual reply
                 to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
                 will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
 
@@ -597,9 +597,10 @@ def reply_document(self, *args, **kwargs):
             bot.send_document(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
-                to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
-                will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
+            quote (:obj:`bool`, optional): If set to ``True``, the document is sent as an actual
+                reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
+                parameter will be ignored. Default: ``True`` in group chats and ``False`` in
+                private chats.
 
         Returns:
             :class:`telegram.Message`: On success, instance representing the message posted.
@@ -614,9 +615,10 @@ def reply_animation(self, *args, **kwargs):
             bot.send_animation(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
-                to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
-                will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
+            quote (:obj:`bool`, optional): If set to ``True``, the animation is sent as an actual
+                reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
+                parameter will be ignored. Default: ``True`` in group chats and ``False`` in
+                private chats.
 
         Returns:
             :class:`telegram.Message`: On success, instance representing the message posted.
@@ -631,9 +633,10 @@ def reply_sticker(self, *args, **kwargs):
             bot.send_sticker(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
-                to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
-                will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
+            quote (:obj:`bool`, optional): If set to ``True``, the sticker is sent as an actual
+                reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
+                parameter will be ignored. Default: ``True`` in group chats and ``False`` in
+                private chats.
 
         Returns:
             :class:`telegram.Message`: On success, instance representing the message posted.
@@ -648,9 +651,10 @@ def reply_video(self, *args, **kwargs):
             bot.send_video(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
-                to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
-                will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
+            quote (:obj:`bool`, optional): If set to ``True``, the video is sent as an actual
+                reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
+                parameter will be ignored. Default: ``True`` in group chats and ``False`` in
+                private chats.
 
         Returns:
             :class:`telegram.Message`: On success, instance representing the message posted.
@@ -665,9 +669,10 @@ def reply_video_note(self, *args, **kwargs):
             bot.send_video_note(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
-                to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
-                will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
+            quote (:obj:`bool`, optional): If set to ``True``, the video note is sent as an actual
+                reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
+                parameter will be ignored. Default: ``True`` in group chats and ``False`` in
+                private chats.
 
         Returns:
             :class:`telegram.Message`: On success, instance representing the message posted.
@@ -682,9 +687,10 @@ def reply_voice(self, *args, **kwargs):
             bot.send_voice(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
-                to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
-                will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
+            quote (:obj:`bool`, optional): If set to ``True``, the voice note is sent as an actual
+                reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
+                parameter will be ignored. Default: ``True`` in group chats and ``False`` in
+                private chats.
 
         Returns:
             :class:`telegram.Message`: On success, instance representing the message posted.
@@ -699,9 +705,10 @@ def reply_location(self, *args, **kwargs):
             bot.send_location(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
-                to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
-                will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
+            quote (:obj:`bool`, optional): If set to ``True``, the location is sent as an actual
+                reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
+                parameter will be ignored. Default: ``True`` in group chats and ``False`` in
+                private chats.
 
         Returns:
             :class:`telegram.Message`: On success, instance representing the message posted.
@@ -716,9 +723,10 @@ def reply_venue(self, *args, **kwargs):
             bot.send_venue(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
-                to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
-                will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
+            quote (:obj:`bool`, optional): If set to ``True``, the venue is sent as an actual
+                reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
+                parameter will be ignored. Default: ``True`` in group chats and ``False`` in
+                private chats.
 
         Returns:
             :class:`telegram.Message`: On success, instance representing the message posted.
@@ -733,9 +741,10 @@ def reply_contact(self, *args, **kwargs):
             bot.send_contact(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
-                to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
-                will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
+            quote (:obj:`bool`, optional): If set to ``True``, the contact is sent as an actual
+                reply to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this
+                parameter will be ignored. Default: ``True`` in group chats and ``False`` in
+                private chats.
 
         Returns:
             :class:`telegram.Message`: On success, instance representing the message posted.
@@ -750,7 +759,7 @@ def reply_poll(self, *args, **kwargs):
             bot.send_poll(update.message.chat_id, *args, **kwargs)
 
         Keyword Args:
-            quote (:obj:`bool`, optional): If set to ``True``, the photo is sent as an actual reply
+            quote (:obj:`bool`, optional): If set to ``True``, the poll is sent as an actual reply
                 to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
                 will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
 

telegram/utils/helpers.py

@@ -100,7 +100,7 @@ def to_float_timestamp(t, reference_timestamp=None):
     Converts a given time object to a float POSIX timestamp.
     Used to convert different time specifications to a common format. The time object
     can be relative (i.e. indicate a time increment, or a time of day) or absolute.
-    Any objects from the :module:`datetime` module that are timezone-naive will be assumed
+    Any objects from the :class:`datetime` module that are timezone-naive will be assumed
     to be in UTC.
 
     ``None`` s are left alone (i.e. ``to_float_timestamp(None)`` is ``None``).