Doc Fixes (#1778)

* Update docs according to official docs

* Add note to Updater according to #1772

* Add note on ChatPermissions

* Fix rendering for arg type of conversation_timeout

telegram/bot.py

@@ -426,7 +426,7 @@ class Bot(TelegramObject):
                 Internet, or upload a new photo using multipart/form-data. Lastly you can pass
                 an existing :class:`telegram.PhotoSize` object to send.
             caption (:obj:`str`, optional): Photo caption (may also be used when resending photos
-                by file_id), 0-1024 characters.
+                by file_id), 0-1024 characters after entities parsing.
             parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
                 show bold, italic, fixed-width text or inline URLs in the media caption. See the
                 constants in :class:`telegram.ParseMode` for the available modes.
@@ -500,7 +500,8 @@ class Bot(TelegramObject):
                 (recommended), pass an HTTP URL as a String for Telegram to get an audio file from
                 the Internet, or upload a new one using multipart/form-data. Lastly you can pass
                 an existing :class:`telegram.Audio` object to send.
-            caption (:obj:`str`, optional): Audio caption, 0-1024 characters.
+            caption (:obj:`str`, optional): Audio caption, 0-1024 characters after entities
+                parsing.
             parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
                 show bold, italic, fixed-width text or inline URLs in the media caption. See the
                 constants in :class:`telegram.ParseMode` for the available modes.
@@ -586,7 +587,7 @@ class Bot(TelegramObject):
             filename (:obj:`str`, optional): File name that shows in telegram message (it is useful
                 when you send file generated by temp module, for example). Undocumented.
             caption (:obj:`str`, optional): Document caption (may also be used when resending
-                documents by file_id), 0-1024 characters.
+                documents by file_id), 0-1024 characters after entities parsing.
             parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
                 show bold, italic, fixed-width text or inline URLs in the media caption. See the
                 constants in :class:`telegram.ParseMode` for the available modes.
@@ -722,7 +723,7 @@ class Bot(TelegramObject):
             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
-                by file_id), 0-1024 characters.
+                by file_id), 0-1024 characters after entities parsing.
             parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
                 show bold, italic, fixed-width text or inline URLs in the media caption. See the
                 constants in :class:`telegram.ParseMode` for the available modes.
@@ -884,7 +885,7 @@ class Bot(TelegramObject):
                 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): Animation caption (may also be used when resending
-                animations by file_id), 0-1024 characters.
+                animations by file_id), 0-1024 characters after entities parsing.
             parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
                 show bold, italic, fixed-width text or inline URLs in the media caption. See the
                 constants in :class:`telegram.ParseMode` for the available modes.
@@ -962,7 +963,8 @@ class Bot(TelegramObject):
                 (recommended), pass an HTTP URL as a String for Telegram to get an voice file from
                 the Internet, or upload a new one using multipart/form-data. Lastly you can pass
                 an existing :class:`telegram.Voice` object to send.
-            caption (:obj:`str`, optional): Voice message caption, 0-1024 characters.
+            caption (:obj:`str`, optional): Voice message caption, 0-1024 characters after entities
+                parsing.
             parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
                 show bold, italic, fixed-width text or inline URLs in the media caption. See the
                 constants in :class:`telegram.ParseMode` for the available modes.
@@ -1802,7 +1804,7 @@ class Bot(TelegramObject):
                 Identifier of the sent message.
             inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
                 specified. Identifier of the inline message.
-            text (:obj:`str`): New text of the message.
+            text (:obj:`str`): New text of the message, 0-1024 characters after entities parsing.
             parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
                 show bold, italic, fixed-width text or inline URLs in your bot's message. See the
                 constants in :class:`telegram.ParseMode` for the available modes.

telegram/chatpermissions.py

@@ -24,6 +24,11 @@ from telegram import TelegramObject
 class ChatPermissions(TelegramObject):
     """Describes actions that a non-administrator user is allowed to take in a chat.
 
+    Note:
+        Though not stated explicitly in the offical docs, Telegram changes not only the permissions
+        that are set, but also sets all the others to :obj:`False`. However, since not documented,
+        this behaviour may change unbeknown to PTB.
+
     Attributes:
         can_send_messages (:obj:`bool`): Optional. True, if the user is allowed to send text
             messages, contacts, locations and venues.

telegram/ext/conversationhandler.py

@@ -93,10 +93,10 @@ class ConversationHandler(Handler):
         per_user (:obj:`bool`): If the conversationkey should contain the User's ID.
         per_message (:obj:`bool`): If the conversationkey should contain the Message's
             ID.
-        conversation_timeout (:obj:`float`|:obj:`datetime.timedelta`): Optional. When this handler
+        conversation_timeout (:obj:`float` | :obj:`datetime.timedelta`): Optional. When this
-            is inactive more than this timeout (in seconds), it will be automatically ended. If
+            handler is inactive more than this timeout (in seconds), it will be automatically
-            this value is 0 (default), there will be no timeout. When it's triggered, the last
+            ended. If this value is 0 (default), there will be no timeout. When it's triggered, the
-            received update will be handled by ALL the handler's who's `check_update` method
+            last received update will be handled by ALL the handler's who's `check_update` method
             returns True that are in the state :attr:`ConversationHandler.TIMEOUT`.
         name (:obj:`str`): Optional. The name for this conversationhandler. Required for
             persistence

telegram/ext/updater.py

@@ -91,7 +91,9 @@ class Updater(object):
             be used if not set explicitly in the bot methods.
 
     Note:
-        You must supply either a :attr:`bot` or a :attr:`token` argument.
+        * You must supply either a :attr:`bot` or a :attr:`token` argument.
+        * If you supply a :attr:`bot`, you will need to pass :attr:`defaults` to *both* the bot and
+          the :class:`telegram.ext.Updater`.
 
     Raises:
         ValueError: If both :attr:`token` and :attr:`bot` are passed or none of them.

telegram/files/inputmedia.py

@@ -47,7 +47,8 @@ class InputMediaAnimation(InputMedia):
             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 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.
+        caption (:obj:`str`): Optional. Caption of the animation to be sent, 0-1024 characters
+            after entities parsing.
         parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -64,7 +65,8 @@ class InputMediaAnimation(InputMedia):
             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 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.
+        caption (:obj:`str`, optional): Caption of the animation to be sent, 0-1024 characters
+            after entities parsing.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -124,7 +126,8 @@ class InputMediaPhoto(InputMedia):
             (recommended), pass an HTTP URL as a String for Telegram to get a photo from the
             Internet, or upload a new photo using multipart/form-data. Lastly you can pass
             an existing :class:`telegram.PhotoSize` object to send.
-        caption (:obj:`str`): Optional. Caption of the photo to be sent, 0-1024 characters.
+        caption (:obj:`str`): Optional. Caption of the photo to be sent, 0-1024 characters after
+            entities parsing.
         parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -133,7 +136,8 @@ class InputMediaPhoto(InputMedia):
         media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the
             Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the
             Internet. Lastly you can pass an existing :class:`telegram.PhotoSize` object to send.
-        caption (:obj:`str`, optional ): Caption of the photo to be sent, 0-1024 characters.
+        caption (:obj:`str`, optional ): Caption of the photo to be sent, 0-1024 characters after
+            entities parsing.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -164,7 +168,8 @@ class InputMediaVideo(InputMedia):
             (recommended), pass an HTTP URL as a String for Telegram to get an video file from
             the Internet, or upload a new one using multipart/form-data. Lastly you can pass
             an existing :class:`telegram.Video` object to send.
-        caption (:obj:`str`): Optional. Caption of the video to be sent, 0-1024 characters.
+        caption (:obj:`str`): Optional. Caption of the video to be sent, 0-1024 characters after
+            entities parsing.
         parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -182,7 +187,8 @@ class InputMediaVideo(InputMedia):
         media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
             servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
             Lastly you can pass an existing :class:`telegram.Video` object to send.
-        caption (:obj:`str`, optional): Caption of the video to be sent, 0-1024 characters.
+        caption (:obj:`str`, optional): Caption of the video to be sent, 0-1024 characters after
+            entities parsing.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -244,7 +250,8 @@ class InputMediaAudio(InputMedia):
             (recommended), pass an HTTP URL as a String for Telegram to get an audio file from
             the Internet, or upload a new one using multipart/form-data. Lastly you can pass
             an existing :class:`telegram.Audio` object to send.
-        caption (:obj:`str`): Optional. Caption of the audio to be sent, 0-1024 characters.
+        caption (:obj:`str`): Optional. Caption of the audio to be sent, 0-1024 characters after
+            entities parsing.
         parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -261,7 +268,8 @@ class InputMediaAudio(InputMedia):
         media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
             servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
             Lastly you can pass an existing :class:`telegram.Document` object to send.
-        caption (:obj:`str`, optional): Caption of the audio to be sent, 0-1024 characters.
+        caption (:obj:`str`, optional): Caption of the audio to be sent, 0-1024 characters after
+            entities parsing.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -320,7 +328,8 @@ class InputMediaDocument(InputMedia):
             (recommended), pass an HTTP URL as a String for Telegram to get a file from the
             Internet, or upload a new one using multipart/form-data. Lastly you can pass
             an existing :class:`telegram.Document` object to send.
-        caption (:obj:`str`): Optional. Caption of the document to be sent, 0-1024 characters.
+        caption (:obj:`str`): Optional. Caption of the document to be sent, 0-1024 characters after
+            entities parsing.
         parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -333,7 +342,8 @@ class InputMediaDocument(InputMedia):
         media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
             servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
             Lastly you can pass an existing :class:`telegram.Document` object to send.
-        caption (:obj:`str`, optional): Caption of the document to be sent, 0-1024 characters.
+        caption (:obj:`str`, optional): Caption of the document to be sent, 0-1024 characters after
+            entities parsing.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.

telegram/inline/inlinequeryresultcachedvideo.py

@@ -35,7 +35,7 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
         video_file_id (:obj:`str`): A valid file identifier for the video file.
         title (:obj:`str`): Title for the result.
         description (:obj:`str`): Optional. Short description of the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters.
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters after entities parsing.
         parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -49,7 +49,7 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
         video_file_id (:obj:`str`): A valid file identifier for the video file.
         title (:obj:`str`): Title for the result.
         description (:obj:`str`, optional): Short description of the result.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters.
+        caption (:obj:`str`, optional): Caption, 0-1024 characters after entities parsing.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.

telegram/inline/inlinequeryresultcachedvoice.py

@@ -33,7 +33,7 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         voice_file_id (:obj:`str`): A valid file identifier for the voice message.
         title (:obj:`str`): Voice message title.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters.
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters after entities parsing.
         parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -46,7 +46,7 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         voice_file_id (:obj:`str`): A valid file identifier for the voice message.
         title (:obj:`str`): Voice message title.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters.
+        caption (:obj:`str`, optional): Caption, 0-1024 characters after entities parsing.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.

telegram/inline/inlinequeryresultvideo.py

@@ -55,7 +55,7 @@ class InlineQueryResultVideo(InlineQueryResult):
         mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4".
         thumb_url (:obj:`str`): URL of the thumbnail (jpeg only) for the video.
         title (:obj:`str`): Title for the result.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters.
+        caption (:obj:`str`, optional): Caption, 0-1024 characters after entities parsing.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.

telegram/inline/inlinequeryresultvoice.py

@@ -34,7 +34,7 @@ class InlineQueryResultVoice(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         voice_url (:obj:`str`): A valid URL for the voice recording.
         title (:obj:`str`): Voice message title.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters.
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters after entities parsing.
         parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
             in :class:`telegram.ParseMode` for the available modes.
@@ -48,7 +48,7 @@ class InlineQueryResultVoice(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         voice_url (:obj:`str`): A valid URL for the voice recording.
         title (:obj:`str`): Voice message title.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters.
+        caption (:obj:`str`, optional): Caption, 0-1024 characters after entities parsing.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
             in :class:`telegram.ParseMode` for the available modes.

telegram/inline/inputtextmessagecontent.py

@@ -27,15 +27,16 @@ class InputTextMessageContent(InputMessageContent):
     Represents the content of a text message to be sent as the result of an inline query.
 
     Attributes:
-        message_text (:obj:`str`): Text of the message to be sent, 1-4096 characters.
+        message_text (:obj:`str`): Text of the message to be sent, 1-4096 characters after entities
+            parsing.
         parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in your bot's message.
         disable_web_page_preview (:obj:`bool`): Optional. Disables link previews for links in the
             sent message.
 
     Args:
-        message_text (:obj:`str`): Text of the message to be sent, 1-4096 characters.  Also found
+        message_text (:obj:`str`): Text of the message to be sent, 1-4096 characters after entities
-            as :attr:`telegram.constants.MAX_MESSAGE_LENGTH`.
+            parsing. Also found as :attr:`telegram.constants.MAX_MESSAGE_LENGTH`.
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or inline URLs in your bot's message.
         disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in the