Documentation improvements + small style fixes

tsnoam · tsnoam · commit 59fa717023da · 2016-10-17T01:11:20.000+03:00
diff --git a/telegram/audio.py b/telegram/audio.py
@@ -35,13 +35,12 @@ class Audio(TelegramObject):
     Args:
         file_id (str):
         duration (int):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         performer (Optional[str]):
         title (Optional[str]):
         mime_type (Optional[str]):
         file_size (Optional[int]):
+        **kwargs: Arbitrary keyword arguments.
+
     """
 
     def __init__(self,
diff --git a/telegram/bot.py b/telegram/bot.py
diff --git a/telegram/chat.py b/telegram/chat.py
@@ -36,13 +36,14 @@ class Chat(TelegramObject):
     Args:
         id (int):
         type (str):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
-        type (Optional[str]):
+        title (Optional[str]):
+        username(Optional[str]):
+        first_name(Optional[str]):
+        last_name(Optional[str]):
         bot (Optional[Bot]): The Bot to use for instance methods
-    """
+        **kwargs (dict): Arbitrary keyword arguments.
 
+    """
     PRIVATE = 'private'
     GROUP = 'group'
     SUPERGROUP = 'supergroup'
diff --git a/telegram/chatmember.py b/telegram/chatmember.py
@@ -32,8 +32,9 @@ class ChatMember(TelegramObject):
     Args:
         user (:class:`telegram.User`):
         status (str):
-    """
+        **kwargs (dict): Arbitrary keyword arguments.
 
+    """
     CREATOR = 'creator'
     ADMINISTRATOR = 'administrator'
     MEMBER = 'member'
diff --git a/telegram/choseninlineresult.py b/telegram/choseninlineresult.py
@@ -33,11 +33,16 @@ class ChosenInlineResult(TelegramObject):
         result_id (str):
         from_user (:class:`telegram.User`):
         query (str):
+        location (:class:`telegram.Location`):
+        inline_message_id (str):
 
     Args:
         result_id (str):
         from_user (:class:`telegram.User`):
         query (str):
+        location (Optional[:class:`telegram.Location`]):
+        inline_message_id (Optional[str]):
+        **kwargs (dict): Arbitrary keyword arguments.
 
     """
 
diff --git a/telegram/contact.py b/telegram/contact.py
@@ -33,11 +33,10 @@ class Contact(TelegramObject):
     Args:
         phone_number (str):
         first_name (str):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         last_name (Optional[str]):
         user_id (Optional[int]):
+        **kwargs: Arbitrary keyword arguments.
+
     """
 
     def __init__(self, phone_number, first_name, last_name='', user_id=0, **kwargs):
diff --git a/telegram/document.py b/telegram/document.py
@@ -33,13 +33,12 @@ class Document(TelegramObject):
 
     Args:
         file_id (str):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         thumb (Optional[:class:`telegram.PhotoSize`]):
         file_name (Optional[str]):
         mime_type (Optional[str]):
         file_size (Optional[int]):
+        **kwargs (dict): Arbitrary keyword arguments.
+
     """
 
     def __init__(self, file_id, thumb=None, file_name='', mime_type='', file_size=0, **kwargs):
diff --git a/telegram/file.py b/telegram/file.py
@@ -34,11 +34,9 @@ class File(TelegramObject):
     Args:
         file_id (str):
         bot (telegram.Bot):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         file_size (Optional[int]):
         file_path (Optional[str]):
+        **kwargs (dict): Arbitrary keyword arguments.
 
     """
 
diff --git a/telegram/forcereply.py b/telegram/forcereply.py
@@ -30,10 +30,9 @@ class ForceReply(ReplyMarkup):
 
     Args:
         force_reply (bool):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         selective (Optional[bool]):
+        **kwargs (dict): Arbitrary keyword arguments.
+
     """
 
     def __init__(self, force_reply=True, selective=False, **kwargs):
diff --git a/telegram/inlinekeyboardbutton.py b/telegram/inlinekeyboardbutton.py
@@ -33,12 +33,10 @@ class InlineKeyboardButton(TelegramObject):
 
     Args:
         text (str):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         url (Optional[str]):
         callback_data (Optional[str]):
         switch_inline_query (Optional[str]):
+        **kwargs (dict): Arbitrary keyword arguments.
 
     """
 
diff --git a/telegram/inlinekeyboardmarkup.py b/telegram/inlinekeyboardmarkup.py
@@ -30,6 +30,7 @@ class InlineKeyboardMarkup(ReplyMarkup):
 
     Args:
         inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]):
+        **kwargs (dict): Arbitrary keyword arguments.
 
     """
 
@@ -46,6 +47,7 @@ def de_json(data, bot):
 
         Returns:
             telegram.InlineKeyboardMarkup:
+
         """
         data = super(InlineKeyboardMarkup, InlineKeyboardMarkup).de_json(data, bot)
 
diff --git a/telegram/inlinequery.py b/telegram/inlinequery.py
@@ -38,11 +38,10 @@ class InlineQuery(TelegramObject):
         from_user (:class:`telegram.User`):
         query (str):
         offset (str):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         location (optional[:class:`telegram.Location`]):
         bot (Optional[Bot]): The Bot to use for instance methods
+        **kwargs (dict): Arbitrary keyword arguments.
+
     """
 
     def __init__(self, id, from_user, query, offset, location=None, bot=None, **kwargs):
diff --git a/telegram/inlinequeryresult.py b/telegram/inlinequeryresult.py
@@ -26,12 +26,13 @@ class InlineQueryResult(TelegramObject):
     """This object represents a Telegram InlineQueryResult.
 
     Attributes:
-        type (str):
-        id (str):
+        type (str): Type of the result.
+        id (str): Unique identifier for this result, 1-64 Bytes
 
     Args:
-        type (str):
+        type (str): Type of the result.
         id (str): Unique identifier for this result, 1-64 Bytes
+        **kwargs (dict): Arbitrary keyword arguments.
 
     """
 
diff --git a/telegram/inlinequeryresultarticle.py b/telegram/inlinequeryresultarticle.py
@@ -42,21 +42,20 @@ class InlineQueryResultArticle(InlineQueryResult):
 
         parse_mode (str): Use :class:`InputTextMessageContent` instead.
 
-        disable_web_page_preview (bool): Use :class:`InputTextMessageContent`
-        instead.
+        disable_web_page_preview (bool): Use :class:`InputTextMessageContent` instead.
 
     Args:
         id (str): Unique identifier for this result, 1-64 Bytes
         title (str):
         reply_markup (:class:`telegram.ReplyMarkup`):
-
-    Keyword Args:
         url (Optional[str]):
         hide_url (Optional[bool]):
         description (Optional[str]):
         thumb_url (Optional[str]):
         thumb_width (Optional[int]):
         thumb_height (Optional[int]):
+        **kwargs (dict): Arbitrary keyword arguments.
+
     """
 
     def __init__(self,
diff --git a/telegram/inlinequeryresultaudio.py b/telegram/inlinequeryresultaudio.py
@@ -34,28 +34,24 @@ class InlineQueryResultAudio(InlineQueryResult):
         performer (Optional[str]):
         audio_duration (Optional[str]):
         reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
-        input_message_content (Optional[
-            :class:`telegram.input_message_content`]):
+        input_message_content (Optional[:class:`telegram.input_message_content`]):
 
     Deprecated: 4.0
         message_text (str): Use :class:`InputTextMessageContent` instead.
 
         parse_mode (str): Use :class:`InputTextMessageContent` instead.
 
-        disable_web_page_preview (bool): Use :class:`InputTextMessageContent`
-        instead.
+        disable_web_page_preview (bool): Use :class:`InputTextMessageContent` instead.
 
     Args:
         audio_url (str):
         title (str):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         performer (Optional[str]):
         audio_duration (Optional[str]):
         reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
-        input_message_content (Optional[
-            :class:`telegram.input_message_content`]):
+        input_message_content (Optional[:class:`telegram.input_message_content`]):
+        **kwargs (dict): Arbitrary keyword arguments.
+
     """
 
     def __init__(self,
diff --git a/telegram/inlinequeryresultcachedaudio.py b/telegram/inlinequeryresultcachedaudio.py
@@ -23,34 +23,29 @@
 
 
 class InlineQueryResultCachedAudio(InlineQueryResult):
-    """Represents a link to an mp3 audio file stored on the Telegram
-    servers. By default, this audio file will be sent by the user.
-    Alternatively, you can use input_message_content to send a message with
-    the specified content instead of the audio.
+    """Represents a link to an mp3 audio file stored on the Telegram servers. By default, this
+    audio file will be sent by the user. Alternatively, you can use input_message_content to send a
+    message with the specified content instead of the audio.
 
     Attributes:
         id (str):
         audio_file_id (str):
         reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
-        input_message_content (Optional[
-            :class:`telegram.input_message_content`]):
+        input_message_content (Optional[:class:`telegram.input_message_content`]):
 
     Deprecated: 4.0
         message_text (str): Use :class:`InputTextMessageContent` instead.
 
         parse_mode (str): Use :class:`InputTextMessageContent` instead.
 
-        disable_web_page_preview (bool): Use :class:`InputTextMessageContent`
-        instead.
+        disable_web_page_preview (bool): Use :class:`InputTextMessageContent` instead.
 
     Args:
         audio_file_id (str):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
-        input_message_content (Optional[
-            :class:`telegram.input_message_content`]):
+        input_message_content (Optional[:class:`telegram.input_message_content`]):
+        **kwargs (dict): Arbitrary keyword arguments.
+
     """
 
     def __init__(self, id, audio_file_id, reply_markup=None, input_message_content=None, **kwargs):
diff --git a/telegram/inlinequeryresultcacheddocument.py b/telegram/inlinequeryresultcacheddocument.py
@@ -16,13 +16,38 @@
 #
 # 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 classes that represent Telegram
-InlineQueryResultCachedDocument"""
+"""This module contains the classes that represent Telegram InlineQueryResultCachedDocument"""
 
 from telegram import InlineQueryResult, InlineKeyboardMarkup, InputMessageContent
 
 
 class InlineQueryResultCachedDocument(InlineQueryResult):
+    """Represents a link to a file stored on the Telegram servers. By default, this file will be
+    sent by the user with an optional caption. Alternatively, you can use input_message_content to
+    send a message with the specified content instead of the file. Currently, only pdf-files and
+    zip archives can be sent using this method.
+
+    Attributes:
+        title (str): Title for the result.
+        document_file_id (str): A valid file identifier for the file.
+        description (Optional[str]): Short description of the result.
+        caption	(Optional[str]): Caption of the document to be sent, 0-200 characters.
+        reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]): Inline keyboard attached
+            to the message.
+        input_message_content (Optional[:class:`telegram.InputMessageContent`]): Content of the
+            message to be sent instead of the file.
+
+    Args:
+        id (str):
+        title (str):
+        document_file_id (str):
+        description (Optional[str]):
+        caption	(Optional[str]):
+        reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
+        input_message_content (Optional[:class:`telegram.InputMessageContent`]):
+        **kwargs (dict): Arbitrary keyword arguments.
+
+        """
 
     def __init__(self,
                  id,
diff --git a/telegram/inlinequeryresultcachedgif.py b/telegram/inlinequeryresultcachedgif.py
@@ -23,6 +23,29 @@
 
 
 class InlineQueryResultCachedGif(InlineQueryResult):
+    """Represents a link to an animated GIF file stored on the Telegram servers. By default, this
+    animated GIF file will be sent by the user with an optional caption. Alternatively, you can use
+    input_message_content to send a message with specified content instead of the animation.
+
+    Attributes:
+        gif_file_id (str): A valid file identifier for the GIF file.
+        title (Optional[str]): Title for the result.
+        caption (Optional[str]): Caption of the GIF file to be sent, 0-200 characters.
+        reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]): Inline keyboard attached
+            to the message.
+        input_message_content (Optional[:class:`telegram.InputMessageContent`]): Content of the
+            message to be sent instead of the GIF animation.
+
+    Args:
+        id (str):
+        gif_file_id (str):
+        title (Optional[str]):
+        caption (Optional[str]):
+        reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
+        input_message_content (Optional[:class:`telegram.InputMessageContent`]):
+        **kwargs (dict): Arbitrary keyword arguments.
+
+    """
 
     def __init__(self,
                  id,
diff --git a/telegram/inlinequeryresultcachedmpeg4gif.py b/telegram/inlinequeryresultcachedmpeg4gif.py
@@ -23,6 +23,30 @@
 
 
 class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
+    """Represents a link to a video animation (H.264/MPEG-4 AVC video without sound) stored on the
+    Telegram servers. By default, this animated MPEG-4 file will be sent by the user with an
+    optional caption. Alternatively, you can use input_message_content to send a message with the
+    specified content instead of the animation.
+
+    Attributes:
+        mpeg4_file_id (str): A valid file identifier for the MP4 file.
+        title (Optional[str]): Title for the result.
+        caption	(Optional[str]): Caption of the MPEG-4 file to be sent, 0-200 characters.
+        reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]): Inline keyboard attached
+            to the message.
+        input_message_content (Optional[:class:`telegram.InputMessageContent`]): Content of the
+            message to be sent instead of the video animation
+
+    Args:
+        id (str):
+        mpeg4_file_id (str):
+        title (Optional[str]):
+        caption	(Optional[str]):
+        reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
+        input_message_content (Optional[:class:`telegram.InputMessageContent`]):
+         **kwargs (dict): Arbitrary keyword arguments.
+
+    """
 
     def __init__(self,
                  id,
diff --git a/telegram/message.py b/telegram/message.py
@@ -153,9 +153,7 @@ def __init__(self,
         self.reply_to_message = reply_to_message
         self.edit_date = edit_date
         self.text = text
-        if entities is None:
-            entities = list()
-        self.entities = entities
+        self.entities = entities or list()
         self.audio = audio
         self.document = document
         self.photo = photo
