Merge pull request python-telegram-bot#127 from python-telegram-bot/chatclass

jh0ker · jh0ker · commit 37271e4a027e · 2015-12-16T16:32:19.000+01:00
API updates Oct and Nov
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,3 +1,10 @@
+**2015-12-16**
+
+*Released 3.1.0*
+
+- The ``chat``-field in ``Message`` is now of type ``Chat``. (API update Oct 8 2015)
+- ``Message`` now contains the optional fields ``supergroup_chat_created``, ``migrate_to_chat_id``, ``migrate_from_chat_id`` and ``channel_chat_created``. (API update Nov 2015)
+
 **2015-12-08**
 
 *Released 3.0.0*
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -58,9 +58,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '3.0'
+version = '3.1'
 # The full version, including alpha/beta/rc tags.
-release = '3.0.0'
+release = '3.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/source/telegram.chat.rst b/docs/source/telegram.chat.rst
@@ -1,7 +1,7 @@
-telegram.groupchat module
+telegram.chat module
 =========================
 
-.. automodule:: telegram.groupchat
+.. automodule:: telegram.chat
     :members:
     :undoc-members:
     :show-inheritance:
diff --git a/docs/source/telegram.dispatcher.rst b/docs/source/telegram.dispatcher.rst
@@ -0,0 +1,7 @@
+telegram.dispatcher module
+=========================
+
+.. automodule:: telegram.dispatcher
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/source/telegram.rst b/docs/source/telegram.rst
@@ -9,13 +9,15 @@ Submodules
    telegram.audio
    telegram.base
    telegram.bot
+   telegram.updater
+   telegram.dispatcher
    telegram.chataction
    telegram.contact
    telegram.document
    telegram.emoji
    telegram.error
    telegram.forcereply
-   telegram.groupchat
+   telegram.chat
    telegram.inputfile
    telegram.location
    telegram.message
diff --git a/docs/source/telegram.updater.rst b/docs/source/telegram.updater.rst
@@ -0,0 +1,7 @@
+telegram.updater module
+=========================
+
+.. automodule:: telegram.updater
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/setup.py b/setup.py
@@ -26,7 +26,7 @@ def requirements():
 
 setup(
     name='python-telegram-bot',
-    version='3.0.0',
+    version='3.1.0',
     author='Leandro Toledo',
     author_email='leandrotoledodesouza@gmail.com',
     license='LGPLv3',
diff --git a/telegram/__init__.py b/telegram/__init__.py
@@ -19,11 +19,11 @@
 """A library that provides a Python interface to the Telegram Bot API"""
 
 __author__ = 'leandrotoledodesouza@gmail.com'
-__version__ = '3.0.0'
+__version__ = '3.1.0'
 
 from .base import TelegramObject
 from .user import User
-from .groupchat import GroupChat
+from .chat import Chat
 from .photosize import PhotoSize
 from .audio import Audio
 from .voice import Voice
@@ -54,5 +54,5 @@
            'InputFile', 'ReplyMarkup', 'ForceReply', 'ReplyKeyboardHide',
            'ReplyKeyboardMarkup', 'UserProfilePhotos', 'ChatAction',
            'Location', 'Contact', 'Video', 'Sticker', 'Document', 'File',
-           'Audio', 'PhotoSize', 'GroupChat', 'Update', 'ParseMode', 'Message',
+           'Audio', 'PhotoSize', 'Chat', 'Update', 'ParseMode', 'Message',
            'User', 'TelegramObject', 'NullHandler', 'Voice']
diff --git a/telegram/bot.py b/telegram/bot.py
@@ -191,8 +191,7 @@ def sendMessage(self,
 
         Args:
           chat_id:
-            Unique identifier for the message recipient - telegram.User or
-            telegram.GroupChat id.
+            Unique identifier for the message recipient - telegram.Chat id.
           parse_mode:
             Send Markdown, if you want Telegram apps to show bold, italic and
             inline URLs in your bot's message. For the moment, only Telegram
@@ -234,10 +233,10 @@ def forwardMessage(self,
 
         Args:
           chat_id:
-            Unique identifier for the message recipient - User or GroupChat id.
+            Unique identifier for the message recipient - Chat id.
           from_chat_id:
             Unique identifier for the chat where the original message was sent
-            - User or GroupChat id.
+            - Chat id.
           message_id:
             Unique message identifier.
 
@@ -268,7 +267,7 @@ def sendPhoto(self,
 
         Args:
           chat_id:
-            Unique identifier for the message recipient - User or GroupChat id.
+            Unique identifier for the message recipient - Chat id.
           photo:
             Photo to send. You can either pass a file_id as String to resend a
             photo that is already on the Telegram servers, or upload a new
@@ -319,7 +318,7 @@ def sendAudio(self,
 
         Args:
           chat_id:
-            Unique identifier for the message recipient - User or GroupChat id.
+            Unique identifier for the message recipient - Chat id.
           audio:
             Audio file to send. You can either pass a file_id as String to
             resend an audio that is already on the Telegram servers, or upload
@@ -366,7 +365,7 @@ def sendDocument(self,
 
         Args:
           chat_id:
-            Unique identifier for the message recipient - User or GroupChat id.
+            Unique identifier for the message recipient - Chat id.
           document:
             File to send. You can either pass a file_id as String to resend a
             file that is already on the Telegram servers, or upload a new file
@@ -405,7 +404,7 @@ def sendSticker(self,
 
         Args:
           chat_id:
-            Unique identifier for the message recipient - User or GroupChat id.
+            Unique identifier for the message recipient - Chat id.
           sticker:
             Sticker to send. You can either pass a file_id as String to resend
             a sticker that is already on the Telegram servers, or upload a new
@@ -441,7 +440,7 @@ def sendVideo(self,
 
         Args:
           chat_id:
-            Unique identifier for the message recipient - User or GroupChat id.
+            Unique identifier for the message recipient - Chat id.
           video:
             Video to send. You can either pass a file_id as String to resend a
             video that is already on the Telegram servers, or upload a new
@@ -490,7 +489,7 @@ def sendVoice(self,
 
         Args:
           chat_id:
-            Unique identifier for the message recipient - User or GroupChat id.
+            Unique identifier for the message recipient - Chat id.
           voice:
             Audio file to send. You can either pass a file_id as String to
             resend an audio that is already on the Telegram servers, or upload
@@ -529,7 +528,7 @@ def sendLocation(self,
 
         Args:
           chat_id:
-            Unique identifier for the message recipient - User or GroupChat id.
+            Unique identifier for the message recipient - Chat id.
           latitude:
             Latitude of location.
           longitude:
@@ -565,7 +564,7 @@ def sendChatAction(self,
 
         Args:
           chat_id:
-            Unique identifier for the message recipient - User or GroupChat id.
+            Unique identifier for the message recipient - Chat id.
           action:
             Type of action to broadcast. Choose one, depending on what the user
             is about to receive:
diff --git a/telegram/chat.py b/telegram/chat.py
@@ -17,22 +17,25 @@
 # 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 a object that represents a Telegram GroupChat"""
+"""This module contains a object that represents a Telegram Chat"""
 
 from telegram import TelegramObject
 
 
-class GroupChat(TelegramObject):
-    """This object represents a Telegram GroupChat.
+class Chat(TelegramObject):
+    """This object represents a Telegram Chat.
 
     Attributes:
         id (int):
-        title (str):
-        type (str):
+        type (str): Can be 'private', 'group', 'supergroup' or 'channel'
+        title (str): Title, for channels and group chats
+        username (str): Username, for private chats and channels if available
+        first_name (str): First name of the other party in a private chat
+        last_name (str): Last name of the other party in a private chat
 
     Args:
         id (int):
-        title (str):
+        type (str):
         **kwargs: Arbitrary keyword arguments.
 
     Keyword Args:
@@ -41,24 +44,27 @@ class GroupChat(TelegramObject):
 
     def __init__(self,
                  id,
-                 title,
+                 type,
                  **kwargs):
         # Required
         self.id = int(id)
-        self.title = title
+        self.type = type
         # Optionals
-        self.type = kwargs.get('type', '')
+        self.title = kwargs.get('title', '')
+        self.username = kwargs.get('username', '')
+        self.first_name = kwargs.get('first_name', '')
+        self.last_name = kwargs.get('last_name', '')
 
     @staticmethod
     def de_json(data):
         """
         Args:
-            data (str):
+            data (dict):
 
         Returns:
-            telegram.GroupChat:
+            telegram.Chat:
         """
         if not data:
             return None
 
-        return GroupChat(**data)
+        return Chat(**data)
diff --git a/telegram/dispatcher.py b/telegram/dispatcher.py
@@ -61,22 +61,29 @@ def async_func(*args, **kwargs):
 class Dispatcher:
     """
     This class dispatches all kinds of updates to its registered handlers.
+    A handler is a function that usually takes the following parameters
 
-    A handler is a function that usually takes the following parameters:
-        bot: The telegram.Bot instance that received the message
-        update: The update that should be handled by the handler
+        bot:
+            The telegram.Bot instance that received the message
+        update:
+            The update that should be handled by the handler
 
-    Error handlers take an additional parameter:
-        error: The TelegramError instance that was raised during processing the
+    Error handlers take an additional parameter
+
+        error:
+            The TelegramError instance that was raised during processing the
             update
 
     All handlers, except error handlers, can also request more information by
     appending one or more of the following arguments in their argument list for
-    convenience:
-        update_queue: The Queue instance which contains all new updates and is
+    convenience
+
+        update_queue:
+            The Queue instance which contains all new updates and is
             processed by the Dispatcher. Be careful with this - you might
             create an infinite loop.
-        args: If the update is an instance str or telegram.Update, this will be
+        args:
+            If the update is an instance str or telegram.Update, this will be
             a list that contains the content of the message split on spaces,
             except the first word (usually the command).
             Example: '/add item1 item2 item3' -> ['item1', 'item2', 'item3']
diff --git a/telegram/message.py b/telegram/message.py
@@ -22,7 +22,7 @@
 from datetime import datetime
 from time import mktime
 
-from telegram import (Audio, Contact, Document, GroupChat, Location, PhotoSize,
+from telegram import (Audio, Contact, Document, Chat, Location, PhotoSize,
                       Sticker, TelegramObject, User, Video, Voice)
 
 
@@ -60,7 +60,7 @@ class Message(TelegramObject):
         message_id (int):
         from_user (:class:`telegram.User`):
         date (:class:`datetime.datetime`):
-        chat (:class:`telegram.User` or :class:`telegram.GroupChat`):
+        chat (:class:`telegram.User` or :class:`telegram.Chat`):
         **kwargs: Arbitrary keyword arguments.
 
     Keyword Args:
@@ -116,6 +116,12 @@ def __init__(self,
         self.new_chat_photo = kwargs.get('new_chat_photo')
         self.delete_chat_photo = bool(kwargs.get('delete_chat_photo', False))
         self.group_chat_created = bool(kwargs.get('group_chat_created', False))
+        self.supergroup_chat_created = bool(kwargs.get(
+            'supergroup_chat_created', False))
+        self.migrate_to_chat_id = int(kwargs.get('migrate_to_chat_id', 0))
+        self.migrate_from_chat_id = int(kwargs.get('migrate_from_chat_id', 0))
+        self.channel_chat_created = bool(kwargs.get('channel_chat_created',
+                                                    False))
 
     @property
     def chat_id(self):
@@ -126,7 +132,7 @@ def chat_id(self):
     def de_json(data):
         """
         Args:
-            data (str):
+            data (dict):
 
         Returns:
             telegram.Message:
@@ -136,10 +142,7 @@ def de_json(data):
 
         data['from_user'] = User.de_json(data.get('from'))
         data['date'] = datetime.fromtimestamp(data['date'])
-        if 'first_name' in data.get('chat', ''):
-            data['chat'] = User.de_json(data.get('chat'))
-        elif 'title' in data.get('chat', ''):
-            data['chat'] = GroupChat.de_json(data.get('chat'))
+        data['chat'] = Chat.de_json(data.get('chat'))
         data['forward_from'] = \
             User.de_json(data.get('forward_from'))
         data['forward_date'] = \
diff --git a/telegram/updater.py b/telegram/updater.py
@@ -249,7 +249,8 @@ def idle(self, stop_signals=(SIGINT, SIGTERM, SIGABRT)):
         Args:
             stop_signals: Iterable containing signals from the signal module
                 that should be subscribed to. Updater.stop() will be called on
-                receiving one of those signals.
+                receiving one of those signals. Defaults to (SIGINT, SIGTERM,
+                SIGABRT)
         """
         for sig in stop_signals:
             signal(sig, self.signal_handler)
diff --git a/tests/test_chat.py b/tests/test_chat.py
diff --git a/tests/test_update.py b/tests/test_update.py
diff --git a/tests/test_updater.py b/tests/test_updater.py
