Add type to User and GroupChat classes

Handles HTTP Bad Gateway error (503) on request module #63

CHANGES.rst

@@ -1,3 +1,27 @@
+2015-09-24
+  Released 2.8.5
+  Handles HTTP Bad Gateway (503) errors on request
+  Fixes regression on Audio and Document for unicode fields
+
+
+2015-09-20
+  Released 2.8.4
+  getFile and File.download is now fully supported
+
+
+2015-09-10
+  Released 2.8.3
+  Moved Bot._requestURL to its own class (telegram.utils.request)
+  Much better, such wow, Telegram Objects tests
+  Add consistency for str properties on Telegram Objects
+  Better design to test if chat_id is invalid
+  Add ability to set custom filename on Bot.sendDocument(..,filename='')
+  Fix Sticker as InputFile
+  Send JSON requests over urlencoded post data
+  Markdown support for Bot.sendMessage(..., parse_mode=ParseMode.MARKDOWN)
+  Refactor of TelegramError class (no more handling IOError or URLError)
+
+
 2015-09-05
   Released 2.8.2
   Fix regression on Telegram ReplyMarkup

README.rst

@@ -94,6 +94,7 @@ sendLocation              Yes
 sendChatAction            Yes
 getUpdates                Yes
 getUserProfilePhotos      Yes
+getFile                   Yes
 setWebhook                Yes
 ========================= ============
 
@@ -220,6 +221,12 @@ To hide `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_::
     >>> reply_markup = telegram.ReplyKeyboardHide()
     >>> bot.sendMessage(chat_id=chat_id, text="I'm back.", reply_markup=reply_markup)
 
+To download a file (you will need its file_id)::
+
+    >>> file_id = message.voice.file_id
+    >>> newFile = bot.getFile(file_id)
+    >>> newFile.download('voice.ogg')
+
 There are many more API methods, to read the full API documentation::
 
     $ pydoc telegram.Bot
@@ -268,7 +275,7 @@ You may copy, distribute and modify the software provided that modifications are
 _`Contact`
 ==========
 
-Feel free to join to our `Telegram group <https://telegram.me/joinchat/00b9c0f802509b946b2e8e98b73e19be>`_.
+Feel free to join to our `Telegram group <https://telegram.me/joinchat/ALnA-AJQm5SEwuAzar3nvw>`_.
 
 If you face trouble joining in the group please ping me `via Telegram <https://telegram.me/leandrotoledo>`_, I'll be glad to add you.
 

docs/source/conf.py

@@ -60,7 +60,7 @@ author = u'Leandro Toledo'
 # The short X.Y version.
 version = '2.8'
 # The full version, including alpha/beta/rc tags.
-release = '2.8.2'
+release = '2.8.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

setup.py

@@ -15,12 +15,12 @@ def read(*paths):
 
 setup(
     name='python-telegram-bot',
-    version='2.8.2',
+    version='2.8.5',
     author='Leandro Toledo',
     author_email='leandrotoledodesouza@gmail.com',
     license='LGPLv3',
     url='https://github.com/leandrotoledo/python-telegram-bot',
-    keywords='telegram bot api',
+    keywords='python telegram bot api wrapper',
     description='A Python wrapper around the Telegram Bot API',
     long_description=(read('README.rst')),
     packages=find_packages(exclude=['tests*']),

telegram/__init__.py

@@ -19,7 +19,7 @@
 """A library that provides a Python interface to the Telegram Bot API"""
 
 __author__ = 'leandrotoledodesouza@gmail.com'
-__version__ = '2.8.2'
+__version__ = '2.8.5'
 
 from .base import TelegramObject
 from .user import User
@@ -40,6 +40,7 @@ from .replykeyboardhide import ReplyKeyboardHide
 from .forcereply import ForceReply
 from .error import TelegramError
 from .inputfile import InputFile
+from .file import File
 from .nullhandler import NullHandler
 from .emoji import Emoji
 from .parsemode import ParseMode
@@ -50,6 +51,6 @@ from .bot import Bot
 __all__ = ['Bot', 'Emoji', 'TelegramError', 'InputFile', 'ReplyMarkup',
            'ForceReply', 'ReplyKeyboardHide', 'ReplyKeyboardMarkup',
            'UserProfilePhotos', 'ChatAction', 'Location', 'Contact',
-           'Video', 'Sticker', 'Document', 'Audio', 'PhotoSize', 'GroupChat',
-           'Update', 'ParseMode', 'Message', 'User', 'TelegramObject',
-           'NullHandler', 'Voice']
+           'Video', 'Sticker', 'Document', 'File', 'Audio', 'PhotoSize',
+           'GroupChat', 'Update', 'ParseMode', 'Message', 'User',
+           'TelegramObject', 'NullHandler', 'Voice']

telegram/audio.py

@@ -52,8 +52,8 @@ class Audio(TelegramObject):
         self.file_id = str(file_id)
         self.duration = int(duration)
         # Optionals
-        self.performer = str(kwargs.get('performer', ''))
-        self.title = str(kwargs.get('title', ''))
+        self.performer = kwargs.get('performer', '')
+        self.title = kwargs.get('title', '')
         self.mime_type = str(kwargs.get('mime_type', ''))
         self.file_size = int(kwargs.get('file_size', 0))
 

telegram/bot.py

@@ -22,8 +22,8 @@
 import functools
 import logging
 
-from telegram import (User, Message, Update, UserProfilePhotos, TelegramError,
-                      ReplyMarkup, TelegramObject, NullHandler)
+from telegram import (User, Message, Update, UserProfilePhotos, File,
+                      TelegramError, ReplyMarkup, TelegramObject, NullHandler)
 from telegram.utils import request
 
 H = NullHandler()
@@ -31,6 +31,7 @@ logging.getLogger(__name__).addHandler(H)
 
 
 class Bot(TelegramObject):
+
     """This object represents a Telegram Bot.
 
     Attributes:
@@ -58,6 +59,8 @@ class Bot(TelegramObject):
         else:
             self.base_url = base_url + self.token
 
+        self.base_file_url = 'https://api.telegram.org/file/bot%s' % self.token
+
         self.bot = None
 
         self.logger = logging.getLogger(__name__)
@@ -615,6 +618,33 @@ class Bot(TelegramObject):
 
         return UserProfilePhotos.de_json(result)
 
+    @log
+    def getFile(self,
+                file_id):
+        """Use this method to get basic info about a file and prepare it for
+        downloading. For the moment, bots can download files of up to 20MB in
+        size.
+
+        Args:
+          file_id:
+            File identifier to get info about.
+
+        Returns:
+          Returns a telegram.File object
+        """
+
+        url = '%s/getFile' % self.base_url
+
+        data = {'file_id': file_id}
+
+        result = request.post(url, data)
+
+        if result.get('file_path'):
+            result['file_path'] = '%s/%s' % (self.base_file_url,
+                                             result['file_path'])
+
+        return File.de_json(result)
+
     @log
     def getUpdates(self,
                    offset=None,

telegram/document.py

@@ -49,7 +49,7 @@ class Document(TelegramObject):
         self.file_id = str(file_id)
         # Optionals
         self.thumb = kwargs.get('thumb')
-        self.file_name = str(kwargs.get('file_name', ''))
+        self.file_name = kwargs.get('file_name', '')
         self.mime_type = str(kwargs.get('mime_type', ''))
         self.file_size = int(kwargs.get('file_size', 0))
 

telegram/file.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# 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 File"""
+
+from os.path import basename
+
+from telegram import TelegramObject
+from telegram.utils.request import download as _download
+
+
+class File(TelegramObject):
+
+    """This object represents a Telegram File.
+
+    Attributes:
+        file_id (str):
+        file_size (str):
+        file_path (str):
+
+    Args:
+        file_id (str):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        file_size (Optional[int]):
+        file_path (Optional[str]):
+    """
+
+    def __init__(self,
+                 file_id,
+                 **kwargs):
+        # Required
+        self.file_id = str(file_id)
+        # Optionals
+        self.file_size = int(kwargs.get('file_size', 0))
+        self.file_path = str(kwargs.get('file_path', ''))
+
+    @staticmethod
+    def de_json(data):
+        """
+        Args:
+            data (str):
+
+        Returns:
+            telegram.File:
+        """
+        if not data:
+            return None
+
+        return File(**data)
+
+    def download(self,
+                 custom_path=None):
+        """
+        Args:
+            custom_path (str):
+        """
+        url = self.file_path
+
+        if custom_path:
+            filename = basename(custom_path)
+        else:
+            filename = basename(url)
+
+        _download(url, filename)

telegram/groupchat.py

@@ -28,18 +28,22 @@ class GroupChat(TelegramObject):
     Attributes:
         id (int):
         title (str):
+        type (str):
 
     Args:
         id (int):
         title (str):
+        type (str):
     """
 
     def __init__(self,
                  id,
-                 title):
+                 title,
+                 type):
         # Required
         self.id = int(id)
         self.title = title
+        self.type = type
 
     @staticmethod
     def de_json(data):

telegram/parsemode.py

@@ -17,10 +17,10 @@
 # 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 Parse Modes"""
+"""This module contains a object that represents a Telegram Message Parse Modes"""
 
 
 class ParseMode(object):
-    """This object represents a Telegram Parse Modes."""
+    """This object represents a Telegram Message Parse Modes."""
 
     MARKDOWN = 'Markdown'

telegram/user.py

@@ -23,13 +23,14 @@ from telegram import TelegramObject
 
 
 class User(TelegramObject):
-    """This object represents a Telegram Sticker.
+    """This object represents a Telegram User.
 
     Attributes:
         id (int):
         first_name (str):
         last_name (str):
         username (str):
+        type (str):
 
     Args:
         id (int):
@@ -37,6 +38,7 @@ class User(TelegramObject):
         **kwargs: Arbitrary keyword arguments.
 
     Keyword Args:
+        type (Optional[str]):
         last_name (Optional[str]):
         username (Optional[str]):
     """
@@ -49,6 +51,7 @@ class User(TelegramObject):
         self.id = int(id)
         self.first_name = first_name
         # Optionals
+        self.type = kwargs.get('type', '')
         self.last_name = kwargs.get('last_name', '')
         self.username = kwargs.get('username', '')
 

telegram/utils/request.py

@@ -22,11 +22,13 @@
 import json
 
 try:
-    from urllib.request import urlopen, Request
-    from urllib.error import HTTPError
+    from urllib.parse import urlencode
+    from urllib.request import urlopen, urlretrieve, Request
+    from urllib.error import HTTPError, URLError
 except ImportError:
+    from urllib import urlencode, urlretrieve
     from urllib2 import urlopen, Request
-    from urllib2 import HTTPError
+    from urllib2 import HTTPError, URLError
 
 from telegram import (InputFile, TelegramError)
 
@@ -92,8 +94,24 @@ def post(url,
     except HTTPError as error:
         if error.getcode() == 403:
             raise TelegramError('Unauthorized')
+        if error.getcode() == 502:
+            raise TelegramError('Bad Gateway')
 
         message = _parse(error.read())
         raise TelegramError(message)
 
     return _parse(result)
+
+
+def download(url,
+             filename):
+    """Download a file by its URL.
+    Args:
+      url:
+        The web location we want to retrieve.
+
+      filename:
+        The filename wihtin the path to download the file.
+    """
+
+    urlretrieve(url, filename)

tests/test_audio.py

@@ -145,7 +145,6 @@ class AudioTest(BaseTest, unittest.TestCase):
         self.assertEqual(audio.performer, self.performer)
         self.assertEqual(audio.title, self.title)
         self.assertEqual(audio.mime_type, self.mime_type)
-        self.assertEqual(audio.file_size, self.file_size)
 
     def test_audio_de_json(self):
         """Test Audio.de_json() method"""

tests/test_document.py

@@ -112,7 +112,6 @@ class DocumentTest(BaseTest, unittest.TestCase):
         self.assertTrue(isinstance(document.thumb, telegram.PhotoSize))
         self.assertEqual(document.file_name, self.file_name)
         self.assertEqual(document.mime_type, self.mime_type)
-        self.assertEqual(document.file_size, self.file_size)
 
     def test_document_de_json(self):
         """Test Document.de_json() method"""

tests/test_file.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+
+"""This module contains a object that represents Tests for Telegram File"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class FileTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram File."""
+
+    def setUp(self):
+        self.audio_file_id = 'BQADAQADDwADHyP1B6PSPq2HjX8kAg'
+        self.document_file_id = 'BQADAQADpAADHyP1B04ipZxJTe2BAg'
+        self.sticker_file_id = 'BQADAQADHAADyIsGAAFZfq1bphjqlgI'
+        self.video_file_id = 'BAADAQADXwADHyP1BwJFTcmY2RYCAg'
+        self.voice_file_id = 'AwADAQADTgADHyP1B_mbw34svXPHAg'
+
+
+        self.json_dict = {
+            'file_id': self.audio_file_id,
+            'file_path': 'https://api.telegram.org/file/bot133505823:AAHZFMHno3mzVLErU5b5jJvaeG--qUyLyG0/document/file_3',
+            'file_size': 28232
+        }
+
+    def test_get_and_download_file_audio(self):
+        """Test telegram.Bot getFile method - Audio"""
+        print('Testing bot.getFile - With Audio.file_id')
+
+        newFile = self._bot.getFile(self.audio_file_id)
+
+        self.assertEqual(newFile.file_size, 28232)
+        self.assertEqual(newFile.file_id, self.audio_file_id)
+        self.assertTrue(newFile.file_path.startswith('https://'))
+
+        newFile.download('telegram.mp3')
+
+        self.assertTrue(os.path.isfile('telegram.mp3'))
+
+    def test_get_and_download_file_document(self):
+        """Test telegram.Bot getFile method - Document"""
+        print('Testing bot.getFile - With Document.file_id')
+
+        newFile = self._bot.getFile(self.document_file_id)
+
+        self.assertEqual(newFile.file_size, 12948)
+        self.assertEqual(newFile.file_id, self.document_file_id)
+        self.assertTrue(newFile.file_path.startswith('https://'))
+
+        newFile.download('telegram.png')
+
+        self.assertTrue(os.path.isfile('telegram.png'))
+
+    def test_get_and_download_file_sticker(self):
+        """Test telegram.Bot getFile method - Sticker"""
+        print('Testing bot.getFile - With Sticker.file_id')
+
+        newFile = self._bot.getFile(self.sticker_file_id)
+
+        self.assertEqual(newFile.file_size, 39518)
+        self.assertEqual(newFile.file_id, self.sticker_file_id)
+        self.assertTrue(newFile.file_path.startswith('https://'))
+
+        newFile.download('telegram.webp')
+
+        self.assertTrue(os.path.isfile('telegram.webp'))
+
+    def test_get_and_download_file_video(self):
+        """Test telegram.Bot getFile method - Video"""
+        print('Testing bot.getFile - With Video.file_id')
+
+        newFile = self._bot.getFile(self.video_file_id)
+
+        self.assertEqual(newFile.file_size, 326534)
+        self.assertEqual(newFile.file_id, self.video_file_id)
+        self.assertTrue(newFile.file_path.startswith('https://'))
+
+        newFile.download('telegram.mp4')
+
+        self.assertTrue(os.path.isfile('telegram.mp4'))
+
+    def test_get_and_download_file_voice(self):
+        """Test telegram.Bot getFile method - Voice"""
+        print('Testing bot.getFile - With Voice.file_id')
+
+        newFile = self._bot.getFile(self.voice_file_id)
+
+        self.assertEqual(newFile.file_size, 9199)
+        self.assertEqual(newFile.file_id, self.voice_file_id)
+        self.assertTrue(newFile.file_path.startswith('https://'))
+
+        newFile.download('telegram.ogg')
+
+        self.assertTrue(os.path.isfile('telegram.ogg'))
+
+    def test_file_de_json(self):
+        """Test File.de_json() method"""
+        print('Testing File.de_json()')
+
+        newFile = telegram.File.de_json(self.json_dict)
+
+        self.assertEqual(newFile.file_id, self.json_dict['file_id'])
+        self.assertEqual(newFile.file_path, self.json_dict['file_path'])
+        self.assertEqual(newFile.file_size, self.json_dict['file_size'])
+
+    def test_file_to_json(self):
+        """Test File.to_json() method"""
+        print('Testing File.to_json()')
+
+        newFile = telegram.File.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(newFile.to_json()))
+
+    def test_file_to_dict(self):
+        """Test File.to_dict() method"""
+        print('Testing File.to_dict()')
+
+        newFile = telegram.File.de_json(self.json_dict)
+
+        self.assertTrue(self.is_dict(newFile.to_dict()))
+        self.assertEqual(newFile['file_id'], self.json_dict['file_id'])
+        self.assertEqual(newFile['file_path'], self.json_dict['file_path'])
+        self.assertEqual(newFile['file_size'], self.json_dict['file_size'])
+
+    def test_error_get_empty_file_id(self):
+        print('Testing bot.getFile - Null file_id')
+
+        json_dict = self.json_dict
+
+        json_dict['file_id'] = ''
+        del(json_dict['file_path'])
+        del(json_dict['file_size'])
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.getFile(**json_dict))
+
+    def test_error_file_without_required_args(self):
+        print('Testing bot.getFile - Without required arguments')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        del(json_dict['file_path'])
+        del(json_dict['file_size'])
+
+        self.assertRaises(TypeError,
+                          lambda: self._bot.getFile(**json_dict))
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_groupchat.py

@@ -33,10 +33,12 @@ class GroupChatTest(BaseTest, unittest.TestCase):
     def setUp(self):
         self.id = -28767330
         self.title = 'ToledosPalaceBot - Group'
+        self.type = 'group'
 
         self.json_dict = {
             'id': self.id,
-            'title': self.title
+            'title': self.title,
+            'type': self.type
         }
 
     def test_group_chat_de_json_empty_json(self):
@@ -55,6 +57,7 @@ class GroupChatTest(BaseTest, unittest.TestCase):
 
         self.assertEqual(group_chat.id, self.id)
         self.assertEqual(group_chat.title, self.title)
+        self.assertEqual(group_chat.type, self.type)
 
     def test_group_chat_to_json(self):
         """Test GroupChat.to_json() method"""
@@ -73,6 +76,7 @@ class GroupChatTest(BaseTest, unittest.TestCase):
         self.assertTrue(self.is_dict(group_chat.to_dict()))
         self.assertEqual(group_chat['id'], self.id)
         self.assertEqual(group_chat['title'], self.title)
+        self.assertEqual(group_chat['type'], self.type)
 
 if __name__ == '__main__':
     unittest.main()

tests/test_user.py

@@ -35,12 +35,14 @@ class UserTest(BaseTest, unittest.TestCase):
         self.first_name = "Leandro"
         self.last_name = "S."
         self.username = "leandrotoledo"
+        self.type = "private"
 
         self.json_dict = {
             'id': self.id,
             'first_name': self.first_name,
             'last_name': self.last_name,
-            'username': self.username
+            'username': self.username,
+            'type': self.type
         }
 
     def test_user_de_json(self):
@@ -53,6 +55,7 @@ class UserTest(BaseTest, unittest.TestCase):
         self.assertEqual(user.first_name, self.first_name)
         self.assertEqual(user.last_name, self.last_name)
         self.assertEqual(user.username, self.username)
+        self.assertEqual(user.type, self.type)
 
         self.assertEqual(user.name, '@leandrotoledo')
 
@@ -69,6 +72,7 @@ class UserTest(BaseTest, unittest.TestCase):
         self.assertEqual(user.id, self.id)
         self.assertEqual(user.first_name, self.first_name)
         self.assertEqual(user.last_name, self.last_name)
+        self.assertEqual(user.type, self.type)
 
         self.assertEqual(user.name, '%s %s' % (self.first_name, self.last_name))
 
@@ -108,6 +112,7 @@ class UserTest(BaseTest, unittest.TestCase):
         self.assertEqual(user['first_name'], self.first_name)
         self.assertEqual(user['last_name'], self.last_name)
         self.assertEqual(user['username'], self.username)
+        self.assertEqual(user['type'], self.type)
 
 if __name__ == '__main__':
     unittest.main()

tests/test_video.py

@@ -153,7 +153,6 @@ class VideoTest(BaseTest, unittest.TestCase):
         self.assertEqual(video.duration, 0)
         self.assertEqual(video.thumb, None)
         self.assertEqual(video.mime_type, '')
-        self.assertEqual(video.file_size, self.file_size)
 
         self.assertEqual(message.caption, self.caption)
 

tests/test_voice.py

@@ -123,7 +123,6 @@ class VoiceTest(BaseTest, unittest.TestCase):
         self.assertEqual(voice.file_id, self.voice_file_id)
         self.assertEqual(voice.duration, self.duration)
         self.assertEqual(voice.mime_type, self.mime_type)
-        self.assertEqual(voice.file_size, self.file_size)
 
     def test_voice_de_json(self):
         """Test Voice.de_json() method"""