release 3.2 and update copyright notice to 2015-2016

JobQueue by @franciscod

.codeclimate.yml

@@ -0,0 +1,5 @@
+languages:
+  Python: true
+exclude_paths:
+- "telegram/emoji.py"
+- "tests/*"

.coveragerc

@@ -0,0 +1,5 @@
+[run]
+source = telegram
+
+[report]
+omit = tests/

.gitignore

@@ -43,6 +43,7 @@ htmlcov/
 nosetests.xml
 coverage.xml
 *,cover
+.coveralls.yml
 
 # Translations
 *.mo
@@ -57,3 +58,13 @@ docs/_build/
 # PyBuilder
 target/
 .idea/
+
+# Sublime Text 2
+*.sublime*
+
+# unitests files
+telegram.mp3
+telegram.mp4
+telegram.ogg
+telegram.png
+telegram.webp

.travis.yml

@@ -4,9 +4,15 @@ python:
   - "2.7"
   - "3.3"
   - "3.4"
+  - "pypy"
+  - "pypy3"
 install:
-  - pip install coveralls
+  - pip install pylint flake8 coveralls
+  - pip install -r requirements.txt
+  - 'if [[ $TRAVIS_PYTHON_VERSION == 2.6 ]]; then pip install unittest2; fi'
 script:
-  coverage run telegram_test.py
+  - nosetests --with-coverage --cover-package telegram/
+  - flake8 telegram
+  - 'if [[ $TRAVIS_PYTHON_VERSION != 2.6 ]]; then pylint -E telegram --disable=no-name-in-module,import-error; fi'
 after_success:
   coveralls

AUTHORS.rst

@@ -9,11 +9,18 @@ Contributors
 The following wonderful people contributed directly or indirectly to this project:
 
 - `Avanatiker <https://github.com/Avanatiker>`_
+- `Balduro <https://github.com/Balduro>`_
 - `bimmlerd <https://github.com/bimmlerd>`_
+- `ErgoZ Riftbit Vaper <https://github.com/ergoz>`_
 - `franciscod <https://github.com/franciscod>`_
 - `JASON0916 <https://github.com/JASON0916>`_
+- `jh0ker <https://github.com/jh0ker>`_
 - `JRoot3D <https://github.com/JRoot3D>`_
 - `macrojames <https://github.com/macrojames>`_
+- `naveenvhegde <https://github.com/naveenvhegde>`_
+- `njittam <https://github.com/njittam>`_
+- `Noam Meltzer <https://github.com/tsnoam>`_
+- `Rahiel Kasim <https://github.com/rahiel>`_
 - `sooyhwang <https://github.com/sooyhwang>`_
 - `wjt <https://github.com/wjt>`_
 

CHANGES

@@ -1,126 +0,0 @@
-2015-08-15
-  Released 2.6.1
-  Fixed parsing image header issue on < Python 2.7.3
-
-
-2015-08-14
-  Released 2.6.0
-  Depreciation of require_authentication and clearCredentials methods
-  Giving AUTHORS the proper credits for their contribution for this project
-  Message.date and Message.forward_date are now datetime objects
-
-
-2015-08-12
-  Released 2.5.3
-  telegram.Bot now supports to be unpickled
-
-
-2015-08-11
-  Released 2.5.2
-  New changes from Telegram Bot API have been applied
-  telegram.Bot now supports to be pickled
-  Return empty str instead None when message.text is empty
-
-
-2015-08-10
-  Released 2.5.1
-  Moved from GPLv2 to LGPLv3
-
-
-2015-08-09
-  Released 2.5
-  Fixes logging calls in API
-
-
-2015-08-08
-  Released 2.4
-  Fixes Emoji class for Python 3
-  PEP8 improvements
-
-
-2015-08-08
-  Released 2.3
-  Fixes ForceReply class
-  Remove logging.basicConfig from library
-
-
-2015-07-25
-  Released 2.2
-  Allows debug=True when initializing telegram.Bot
-
-
-2015-07-20
-  Released 2.1
-  Fix to_dict for Document and Video
-
-
-2015-07-19
-
-  Released 2.0
-  Fixes bugs
-  Improves __str__ over to_json()
-  Creates abstractclass TelegramObject
-
-
-2015-07-15
-
-  Released 1.9
-  Python 3 officially supported
-  PEP8 improvements
-
-
-2015-07-12
-
-  Released 1.8
-  Fixes crash when replying an unicode text message (special thanks to JRoot3D)
-
-
-2015-07-11
-
-  Released 1.7
-  Fixes crash when username is not defined on chat (special thanks to JRoot3D)
-
-
-2015-07-10
-
-  Released 1.6
-  Improvements for GAE support
-
-
-2015-07-10
-
-  Released 1.5
-  Fixes randomly unicode issues when using InputFile
-
-
-2015-07-10
-
-  Released 1.4
-  requests lib is no longer required
-  Google App Engine (GAE) is supported
-
-
-2015-07-10
-
-  Released 1.3
-  Added support to setWebhook (special thanks to macrojames)
-
-
-2015-07-09
-
-  Released 1.2
-  CustomKeyboard classes now available
-  Emojis available
-  PEP8 improvements
-
-
-2015-07-08
-
-  Released 1.1
-  PyPi package now available
-
-
-2015-07-08
-
-  Released 1.0
-  Initial checkin of python-telegram-bot

CHANGES.rst

@@ -0,0 +1,302 @@
+**2016-01-05**
+
+*Released 3.2.0*
+
+- Introducing ``JobQueue`` (original author: @franciscod)
+- Streamlining all exceptions to ``TelegramError`` (Special thanks to @tsnoam)
+- Proper locking of ``Updater`` and ``Dispatcher`` ``start`` and ``stop`` methods
+- Small bugfixes
+
+**2015-12-29**
+
+*Released 3.1.2*
+
+- Fix custom path for file downloads
+- Don't stop the dispatcher thread on uncaught errors in handlers
+
+**2015-12-21**
+
+*Released 3.1.1*
+
+- Fix a bug where asynchronous handlers could not have additional arguments
+- Add ``groups`` and ``groupdict`` as additional arguments for regex-based handlers
+
+**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*
+
+- Introducing the ``Updater`` and ``Dispatcher`` classes
+
+**2015-11-11**
+
+*Released 2.9.2*
+
+- Error handling on request timeouts has been improved
+
+**2015-11-10**
+
+*Released 2.9.1*
+
+- Add parameter ``network_delay`` to Bot.getUpdates for slow connections
+
+**2015-11-10**
+
+*Released 2.9*
+
+- Emoji class now uses ``bytes_to_native_str`` from ``future`` 3rd party lib
+- Make ``user_from`` optional to work with channels
+- Raise exception if Telegram times out on long-polling
+
+*Special thanks to @jh0ker for all hard work*
+
+
+**2015-10-08**
+
+*Released 2.8.7*
+
+- Type as optional for ``GroupChat`` class
+
+
+**2015-10-08**
+
+*Released 2.8.6*
+
+- Adds type to ``User`` and ``GroupChat`` classes (pre-release Telegram feature)
+
+
+**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
+- Add certificate to ``is_inputfile`` method
+
+
+**2015-09-05**
+
+*Released 2.8.1*
+
+- Fix regression on Telegram objects with thumb properties
+
+
+**2015-09-04**
+
+*Released 2.8*
+
+- TelegramError when ``chat_id`` is empty for send* methods
+- ``setWebhook`` now supports sending self-signed certificate
+- Huge redesign of existing Telegram classes
+- Added support for PyPy
+- Added docstring for existing classes
+
+
+**2015-08-19**
+
+*Released 2.7.1*
+
+- Fixed JSON serialization for ``message``
+
+
+**2015-08-17**
+
+*Released 2.7*
+
+- Added support for ``Voice`` object and ``sendVoice`` method
+- Due backward compatibility performer or/and title will be required for ``sendAudio``
+- Fixed JSON serialization when forwarded message
+
+
+**2015-08-15**
+
+*Released 2.6.1*
+
+- Fixed parsing image header issue on < Python 2.7.3
+
+
+**2015-08-14**
+
+*Released 2.6.0*
+
+- Depreciation of ``require_authentication`` and ``clearCredentials`` methods
+- Giving ``AUTHORS`` the proper credits for their contribution for this project
+- ``Message.date`` and ``Message.forward_date`` are now ``datetime`` objects
+
+
+**2015-08-12**
+
+*Released 2.5.3*
+
+- ``telegram.Bot`` now supports to be unpickled
+
+
+**2015-08-11**
+
+*Released 2.5.2*
+
+- New changes from Telegram Bot API have been applied
+- ``telegram.Bot`` now supports to be pickled
+- Return empty ``str`` instead ``None`` when ``message.text`` is empty
+
+
+**2015-08-10**
+
+*Released 2.5.1*
+
+- Moved from GPLv2 to LGPLv3
+
+
+**2015-08-09**
+
+*Released 2.5*
+
+- Fixes logging calls in API
+
+
+**2015-08-08**
+
+*Released 2.4*
+
+- Fixes ``Emoji`` class for Python 3
+- ``PEP8`` improvements
+
+
+**2015-08-08**
+
+*Released 2.3*
+
+- Fixes ``ForceReply`` class
+- Remove ``logging.basicConfig`` from library
+
+
+**2015-07-25**
+
+*Released 2.2*
+
+- Allows ``debug=True`` when initializing ``telegram.Bot``
+
+
+**2015-07-20**
+
+*Released 2.1*
+
+- Fix ``to_dict`` for ``Document`` and ``Video``
+
+
+**2015-07-19**
+
+*Released 2.0*
+
+- Fixes bugs
+- Improves ``__str__`` over ``to_json()``
+- Creates abstract class ``TelegramObject``
+
+
+**2015-07-15**
+
+*Released 1.9*
+
+- Python 3 officially supported
+- ``PEP8`` improvements
+
+
+**2015-07-12**
+
+*Released 1.8*
+
+- Fixes crash when replying an unicode text message (special thanks to JRoot3D)
+
+
+**2015-07-11**
+
+*Released 1.7*
+
+- Fixes crash when ``username`` is not defined on ``chat`` (special thanks to JRoot3D)
+
+
+**2015-07-10**
+
+*Released 1.6*
+
+- Improvements for GAE support
+
+
+**2015-07-10**
+
+*Released 1.5*
+
+- Fixes randomly unicode issues when using ``InputFile``
+
+
+**2015-07-10**
+
+*Released 1.4*
+
+- ``requests`` lib is no longer required
+- Google App Engine (GAE) is supported
+
+
+**2015-07-10**
+
+*Released 1.3*
+
+- Added support to ``setWebhook`` (special thanks to macrojames)
+
+
+**2015-07-09**
+
+*Released 1.2*
+
+- ``CustomKeyboard`` classes now available
+- Emojis available
+- ``PEP8`` improvements
+
+
+**2015-07-08**
+
+*Released 1.1*
+
+- PyPi package now available
+
+
+**2015-07-08**
+
+*Released 1.0*
+
+- Initial checkin of python-telegram-bot

CONTRIBUTING.rst

@@ -35,5 +35,5 @@ If you have any question or concerns, feel free to reach out to me.
 .. _`Code of Conduct`: https://www.python.org/psf/codeofconduct/
 .. _`Google Python Style Guide`: https://google-styleguide.googlecode.com/svn/trunk/pyguide.html
 .. _`Google Python Style Docstrings`: http://sphinx-doc.org/latest/ext/example_google.html
-.. _CHANGES: https://github.com/leandrotoledo/python-telegram-bot/blob/master/CHANGES
-.. _AUTHORS.rst: https://github.com/leandrotoledo/python-telegram-bot/blob/master/AUTHORS.rst
+.. _CHANGES: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/CHANGES
+.. _AUTHORS.rst: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/AUTHORS.rst

MANIFEST.in

@@ -1 +1 @@
-include LICENSE LICENSE.lesser Makefile
+include LICENSE LICENSE.lesser Makefile requirements.txt

Makefile

@@ -1,7 +1,4 @@
-help:
-	@echo "  clean		remove unwanted stuff"
-	@echo "  lint		check style with flake8"
-	@echo "  test		run tests"
+.PHONY: clean pep8 lint test install
 
 clean:
 	rm -fr build
@@ -10,8 +7,21 @@ clean:
 	find . -name '*.pyo' -exec rm -f {} \;
 	find . -name '*~' -exec rm -f {} \;
 
+pep8:
+	flake8 telegram
+
 lint:
-	flake8 --doctests --max-complexity 10 telegram
+	pylint -E telegram
 
 test:
-	python telegram_test.py
+	nosetests
+
+install:
+	pip install -r requirements.txt
+
+help:
+	@echo "Available targets:"
+	@echo "- clean       Clean up the source directory"
+	@echo "- pep8        Check style with flake8"
+	@echo "- lint        Check style with pylint"
+	@echo "- test        Run tests"

README.rst

@@ -1,35 +1,38 @@
-Python Telegram Bot
+.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-logo-text_768.png?raw=true
+   :align: center
+   :target: https://github.com/python-telegram-bot/logos
+   :alt: python-telegram-bot Logo
 
 A Python wrapper around the Telegram Bot API.
 
-By `Leandro Toledo <leandrotoledodesouza@gmail.com>`_
+*Stay tuned for library updates and new releases on our* `Telegram Channel <http://telegram.me/pythontelegrambotchannel>`_.
 
 .. image:: https://img.shields.io/pypi/v/python-telegram-bot.svg
    :target: https://pypi.python.org/pypi/python-telegram-bot
    :alt: PyPi Package Version
-    
+
 .. image:: https://img.shields.io/pypi/dm/python-telegram-bot.svg
    :target: https://pypi.python.org/pypi/python-telegram-bot
    :alt: PyPi Package Monthly Download
-   
+
 .. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=latest
    :target: https://readthedocs.org/projects/python-telegram-bot/?badge=latest
    :alt: Documentation Status
-   
-.. image:: https://img.shields.io/github/license/leandrotoledo/python-telegram-bot.svg
+
+.. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg
    :target: http://www.gnu.org/licenses/lgpl-3.0.html
    :alt: LGPLv3 License
 
-.. image:: https://travis-ci.org/leandrotoledo/python-telegram-bot.svg?branch=master
-   :target: https://travis-ci.org/leandrotoledo/python-telegram-bot
+.. image:: https://travis-ci.org/python-telegram-bot/python-telegram-bot.svg?branch=master
+   :target: https://travis-ci.org/python-telegram-bot/python-telegram-bot
    :alt: Travis CI Status
 
-.. image:: https://codeclimate.com/github/leandrotoledo/python-telegram-bot/badges/gpa.svg
-   :target: https://codeclimate.com/github/leandrotoledo/python-telegram-bot
+.. image:: https://codeclimate.com/github/python-telegram-bot/python-telegram-bot/badges/gpa.svg
+   :target: https://codeclimate.com/github/python-telegram-bot/python-telegram-bot
    :alt: Code Climate
-   
-.. image:: https://coveralls.io/repos/leandrotoledo/python-telegram-bot/badge.svg?branch=master&service=github
-   :target: https://coveralls.io/github/leandrotoledo/python-telegram-bot?branch=master
+
+.. image:: https://coveralls.io/repos/python-telegram-bot/python-telegram-bot/badge.svg?branch=master&service=github
+   :target: https://coveralls.io/github/python-telegram-bot/python-telegram-bot?branch=master
    :alt: Coveralls
 
 =================
@@ -50,13 +53,17 @@ Table of contents
 
 - `Getting started`_
 
-  1. `API`_
-
-  2. `Logging`_
-
-  3. `Examples`_
+  1. `The Updater class`_
   
-  4. `Documentation`_
+  2. `API`_
+  
+  3. `JobQueue`_
+
+  4. `Logging`_
+
+  5. `Examples`_
+
+  6. `Documentation`_
 
 - `License`_
 
@@ -94,6 +101,7 @@ sendLocation              Yes
 sendChatAction            Yes
 getUpdates                Yes
 getUserProfilePhotos      Yes
+getFile                   Yes
 setWebhook                Yes
 ========================= ============
 
@@ -108,6 +116,8 @@ Python Version *Supported?*
 2.7            Yes
 3.3            Yes
 3.4            Yes
+PyPy           Yes
+PyPy3          Yes
 ============== ============
 
 =============
@@ -126,11 +136,11 @@ Or upgrade to the latest version::
 _`Getting the code`
 ===================
 
-The code is hosted at https://github.com/leandrotoledo/python-telegram-bot
+The code is hosted at https://github.com/python-telegram-bot/python-telegram-bot
 
 Check out the latest development version anonymously with::
 
-    $ git clone https://github.com/leandrotoledo/python-telegram-bot
+    $ git clone https://github.com/python-telegram-bot/python-telegram-bot
     $ cd python-telegram-bot
 
 Run tests:
@@ -147,10 +157,72 @@ _`Getting started`
 
 View the last release API documentation at: https://core.telegram.org/bots/api
 
+--------------------
+_`The Updater class`
+--------------------
+
+The ``Updater`` class is the new way to create bots with ``python-telegram-bot``. It provides an easy-to-use interface to the ``telegram.Bot`` by caring about getting new updates from telegram and forwarding them to the ``Dispatcher`` class. We can register handler functions in the ``Dispatcher`` to make our bot react to Telegram commands, messages and even arbitrary updates.
+
+As with the old method, we'll need an Access Token. To generate an Access Token, we have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#botfather>`_).
+
+First, we create an ``Updater`` object::
+
+   >>> from telegram import Updater
+   >>> updater = Updater(token='token')
+
+For quicker access to the ``Dispatcher`` used by our ``Updater``, we can introduce it locally::
+
+   >>> dispatcher = updater.dispatcher
+
+Now, we need to define a function that should process a specific type of update::
+
+   >>> def start(bot, update):
+   ...   bot.sendMessage(chat_id=update.message.chat_id, text="I'm a bot, please talk to me!")
+
+We want this function to be called on a Telegram message that contains the ``/start`` command, so we need to register it in the dispatcher::
+
+   >>> dispatcher.addTelegramCommandHandler('start', start)
+   
+The last step is to tell the ``Updater`` to start working::
+
+   >>> updater.start_polling()
+
+Our bot is now up and running (go ahead and try it)! It's not doing anything yet, besides answering to the ``/start`` command. Let's add another handler function and register it::
+
+   >>> def echo(bot, update):
+   ...   bot.sendMessage(chat_id=update.message.chat_id, text=update.message.text)
+   ...
+   >>> dispatcher.addTelegramMessageHandler(echo)
+
+Our bot should now reply to all messages that are not a command with a message that has the same content.
+
+People might try to send commands to the bot that it doesn't understand, so we should get that covered as well::
+
+   >>> def unknown(bot, update):
+   ...   bot.sendMessage(chat_id=update.message.chat_id, text="Sorry, I didn't understand that command.")
+   ...
+   >>> dispatcher.addUnknownTelegramCommandHandler(unknown)
+
+Let's add some functionality to our bot. We want to add the ``/caps`` command, that will take some text as parameter and return it in all caps. We can get the arguments that were passed to the command in the handler function simply by adding it to the parameter list::
+
+   >>> def caps(bot, update, args):
+   ...   text_caps = ' '.join(args).upper()
+   ...   bot.sendMessage(chat_id=update.message.chat_id, text=text_caps)
+   ... 
+   >>> dispatcher.addTelegramCommandHandler('caps', caps)
+
+Now it's time to stop the bot::
+
+   >>> updater.stop()
+
+Check out more examples in the `examples folder <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples>`_!
+
 ------
 _`API`
 ------
 
+Note: Using the ``Bot`` class directly is the 'old' method, but some of this is still important information, even if you're using the ``Updater`` class!
+
 The API is exposed via the ``telegram.Bot`` class.
 
 To generate an Access Token you have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#botfather>`_).
@@ -187,6 +259,10 @@ To post a text message::
 
     >>> bot.sendMessage(chat_id=chat_id, text="I'm sorry Dave I'm afraid I can't do that.")
 
+To post a text message with markdown::
+
+    >>> bot.sendMessage(chat_id=chat_id, text="*bold* _italic_ [link](http://google.com).", parse_mode=telegram.ParseMode.MARKDOWN)
+
 To post an Emoji (special thanks to `Tim Whitlock <http://apps.timwhitlock.info/emoji/tables/unicode>`_)::
 
     >>> bot.sendMessage(chat_id=chat_id, text=telegram.Emoji.PILE_OF_POO)
@@ -214,14 +290,50 @@ 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
 
 -----------
-_`Logging`
+_`JobQueue`
 -----------
 
+The ``JobQueue`` allows you to perform tasks with a delay or even periodically. The ``Updater`` will create one for you::
+
+    >>> from telegram import Updater
+    >>> u = Updater('TOKEN')
+    >>> j = u.job_queue
+
+The job queue uses functions for tasks, so we define one and add it to the queue. Usually, when the first job is added to the queue, it wil start automatically. We can prevent this by setting ``prevent_autostart=True``::
+
+    >>> def job1(bot):
+    ...     bot.sendMessage(chat_id='@examplechannel', text='One message every minute')
+    >>> j.put(job1, 60, next_t=0, prevent_autostart=True)
+
+You can also have a job that will not be executed repeatedly::
+
+    >>> def job2(bot):
+    ...     bot.sendMessage(chat_id='@examplechannel', text='A single message with 30s delay')
+    >>> j.put(job2, 30, repeat=False)
+
+Now, because we didn't prevent the auto start this time, the queue will start ticking. It runs in a seperate thread, so it is non-blocking. When we stop the Updater, the related queue will be stopped as well::
+
+    >>> u.stop()
+
+We can also stop the job queue by itself::
+
+    >>> j.stop()
+
+----------
+_`Logging`
+----------
+
 You can get logs in your main application by calling `logging` and setting the log level you want::
 
     >>> import logging
@@ -238,14 +350,28 @@ _`Examples`
 
 Here follows some examples to help you to get your own Bot up to speed:
 
-- `echobot <https://github.com/leandrotoledo/python-telegram-bot/blob/master/examples/echobot.py>`_ replies back messages.
+- `echobot2 <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot2.py>`_ replies back messages.
 
-- `roboed <https://github.com/leandrotoledo/python-telegram-bot/blob/master/examples/roboed.py>`_ talks to `Robô Ed <http://www.ed.conpet.gov.br/br/converse.php>`_.
+- `clibot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/clibot.py>`_ has a command line interface.
+
+- `timerbot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/timerbot.py>`_ uses the ``JobQueue`` to send timed messages.
+
+- `Welcome Bot <https://github.com/jh0ker/welcomebot>`_ greets everyone who joins a group chat.
+
+Legacy examples (pre-3.0):
+
+- `echobot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/legacy/echobot.py>`_ replies back messages.
+
+- `roboed <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/legacy/roboed.py>`_ talks to `Robô Ed <http://www.ed.conpet.gov.br/br/converse.php>`_.
 
 - `Simple-Echo-Telegram-Bot <https://github.com/sooyhwang/Simple-Echo-Telegram-Bot>`_ simple Python Telegram bot that echoes your input with Flask microframework, setWebhook method, and Google App Engine (optional) - by @sooyhwang.
 
 - `DevOps Reaction Bot <https://github.com/leandrotoledo/gae-devops-reaction-telegram-bot>`_ sends latest or random posts from `DevOps Reaction <http://devopsreactions.tumblr.com/>`_. Running on `Google App Engine <https://cloud.google.com/appengine>`_ (billing has to be enabled for fully Socket API support).
 
+Other notable examples:
+
+- `TwitterForwarderBot <https://github.com/franciscod/telegram-twitter-forwarder-bot>`_ forwards you tweets from people that you have subscribed to.
+
 ================
 _`Documentation`
 ================
@@ -262,12 +388,10 @@ 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/00b9c0f802509b949c1563d56eb053b0>`_.
+Feel free to join to our `Telegram group <https://telegram.me/joinchat/ALnA-AJQm5R7Km9hdCgyng>`_.
 
 =======
 _`TODO`
 =======
 
-Patches and bug reports are `welcome <https://github.com/leandrotoledo/python-telegram-bot/issues/new>`_, just please keep the style consistent with the original source.
-
-- Add commands handler.
+Patches and bug reports are `welcome <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_, just please keep the style consistent with the original source.

docs/source/conf.py

@@ -50,7 +50,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Python Telegram Bot'
-copyright = u'2015, Leandro Toledo'
+copyright = u'2015-2016, Leandro Toledo'
 author = u'Leandro Toledo'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -58,9 +58,9 @@ author = u'Leandro Toledo'
 # built documents.
 #
 # The short X.Y version.
-version = '2.5'
+version = '3.2'
 # The full version, including alpha/beta/rc tags.
-release = '2.5.1'
+release = '3.2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

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:

docs/source/telegram.dispatcher.rst

@@ -0,0 +1,7 @@
+telegram.dispatcher module
+=========================
+
+.. automodule:: telegram.dispatcher
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/telegram.jobqueue.rst

@@ -0,0 +1,7 @@
+telegram.jobqueue module
+========================
+
+.. automodule:: telegram.jobqueue
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/telegram.rst

@@ -9,13 +9,16 @@ Submodules
    telegram.audio
    telegram.base
    telegram.bot
+   telegram.updater
+   telegram.dispatcher
+   telegram.jobqueue
    telegram.chataction
    telegram.contact
    telegram.document
    telegram.emoji
    telegram.error
    telegram.forcereply
-   telegram.groupchat
+   telegram.chat
    telegram.inputfile
    telegram.location
    telegram.message

docs/source/telegram.updater.rst

@@ -0,0 +1,7 @@
+telegram.updater module
+=========================
+
+.. automodule:: telegram.updater
+    :members:
+    :undoc-members:
+    :show-inheritance:

examples/LICENSE.txt

@@ -0,0 +1,116 @@
+CC0 1.0 Universal
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator and
+subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the
+purpose of contributing to a commons of creative, cultural and scientific
+works ("Commons") that the public can reliably and without fear of later
+claims of infringement build upon, modify, incorporate in other works, reuse
+and redistribute as freely as possible in any form whatsoever and for any
+purposes, including without limitation commercial purposes. These owners may
+contribute to the Commons to promote the ideal of a free culture and the
+further production of creative, cultural and scientific works, or to gain
+reputation or greater distribution for their Work in part through the use and
+efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation
+of additional consideration or compensation, the person associating CC0 with a
+Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
+and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
+and publicly distribute the Work under its terms, with knowledge of his or her
+Copyright and Related Rights in the Work and the meaning and intended legal
+effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display, communicate,
+  and translate a Work;
+
+  ii. moral rights retained by the original author(s) and/or performer(s);
+
+  iii. publicity and privacy rights pertaining to a person's image or likeness
+  depicted in a Work;
+
+  iv. rights protecting against unfair competition in regards to a Work,
+  subject to the limitations in paragraph 4(a), below;
+
+  v. rights protecting the extraction, dissemination, use and reuse of data in
+  a Work;
+
+  vi. database rights (such as those arising under Directive 96/9/EC of the
+  European Parliament and of the Council of 11 March 1996 on the legal
+  protection of databases, and under any national implementation thereof,
+  including any amended or successor version of such directive); and
+
+  vii. other similar, equivalent or corresponding rights throughout the world
+  based on applicable law or treaty, and any national implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention of,
+applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
+unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+and Related Rights and associated claims and causes of action, whether now
+known or unknown (including existing as well as future claims and causes of
+action), in the Work (i) in all territories worldwide, (ii) for the maximum
+duration provided by applicable law or treaty (including future time
+extensions), (iii) in any current or future medium and for any number of
+copies, and (iv) for any purpose whatsoever, including without limitation
+commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
+the Waiver for the benefit of each member of the public at large and to the
+detriment of Affirmer's heirs and successors, fully intending that such Waiver
+shall not be subject to revocation, rescission, cancellation, termination, or
+any other legal or equitable action to disrupt the quiet enjoyment of the Work
+by the public as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason be
+judged legally invalid or ineffective under applicable law, then the Waiver
+shall be preserved to the maximum extent permitted taking into account
+Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
+is so judged Affirmer hereby grants to each affected person a royalty-free,
+non transferable, non sublicensable, non exclusive, irrevocable and
+unconditional license to exercise Affirmer's Copyright and Related Rights in
+the Work (i) in all territories worldwide, (ii) for the maximum duration
+provided by applicable law or treaty (including future time extensions), (iii)
+in any current or future medium and for any number of copies, and (iv) for any
+purpose whatsoever, including without limitation commercial, advertising or
+promotional purposes (the "License"). The License shall be deemed effective as
+of the date CC0 was applied by Affirmer to the Work. Should any part of the
+License for any reason be judged legally invalid or ineffective under
+applicable law, such partial invalidity or ineffectiveness shall not
+invalidate the remainder of the License, and in such case Affirmer hereby
+affirms that he or she will not (i) exercise any of his or her remaining
+Copyright and Related Rights in the Work or (ii) assert any associated claims
+and causes of action with respect to the Work, in either case contrary to
+Affirmer's express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+  a. No trademark or patent rights held by Affirmer are waived, abandoned,
+  surrendered, licensed or otherwise affected by this document.
+
+  b. Affirmer offers the Work as-is and makes no representations or warranties
+  of any kind concerning the Work, express, implied, statutory or otherwise,
+  including without limitation warranties of title, merchantability, fitness
+  for a particular purpose, non infringement, or the absence of latent or
+  other defects, accuracy, or the present or absence of errors, whether or not
+  discoverable, all to the greatest extent permissible under applicable law.
+
+  c. Affirmer disclaims responsibility for clearing rights of other persons
+  that may apply to the Work or any use thereof, including without limitation
+  any person's Copyright and Related Rights in the Work. Further, Affirmer
+  disclaims responsibility for obtaining any necessary consents, permissions
+  or other rights required for any use of the Work.
+
+  d. Affirmer understands and acknowledges that Creative Commons is not a
+  party to this document and has no duty or obligation with respect to this
+  CC0 or use of the Work.
+
+For more information, please see
+<http://creativecommons.org/publicdomain/zero/1.0/>

examples/clibot.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Example Bot to show some of the functionality of the library
+# This program is dedicated to the public domain under the CC0 license.
+
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few handler functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and the CLI-Loop is entered, where all text inputs are
+inserted into the update queue for the bot to handle.
+
+Usage:
+Repeats messages with a delay.
+Reply to last chat from the command line by typing "/reply <text>"
+Type 'stop' on the command line to stop the bot.
+"""
+
+from telegram import Updater
+from telegram.dispatcher import run_async
+from time import sleep
+import logging
+
+# Enable Logging
+logging.basicConfig(
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+# We use this var to save the last chat id, so we can reply to it
+last_chat_id = 0
+
+
+# Define a few (command) handlers. These usually take the two arguments bot and
+# update. Error handlers also receive the raised TelegramError object in error.
+def start(bot, update):
+    """ Answer in Telegram """
+    bot.sendMessage(update.message.chat_id, text='Hi!')
+
+
+def help(bot, update):
+    """ Answer in Telegram """
+    bot.sendMessage(update.message.chat_id, text='Help!')
+
+
+def any_message(bot, update):
+    """ Print to console """
+
+    # Save last chat_id to use in reply handler
+    global last_chat_id
+    last_chat_id = update.message.chat_id
+
+    logger.info("New message\nFrom: %s\nchat_id: %d\nText: %s" %
+                (update.message.from_user,
+                 update.message.chat_id,
+                 update.message.text))
+
+
+def unknown_command(bot, update):
+    """ Answer in Telegram """
+    bot.sendMessage(update.message.chat_id, text='Command not recognized!')
+
+
+@run_async
+def message(bot, update, **kwargs):
+    """
+    Example for an asynchronous handler. It's not guaranteed that replies will
+    be in order when using @run_async. Also, you have to include **kwargs in
+    your parameter list. The kwargs contain all optional parameters that are
+    """
+
+    sleep(2)  # IO-heavy operation here
+    bot.sendMessage(update.message.chat_id, text='Echo: %s' %
+                                                 update.message.text)
+
+
+# These handlers are for updates of type str. We use them to react to inputs
+# on the command line interface
+def cli_reply(bot, update, args):
+    """
+    For any update of type telegram.Update or str that contains a command, you
+    can get the argument list by appending args to the function parameters.
+    Here, we reply to the last active chat with the text after the command.
+    """
+    if last_chat_id is not 0:
+        bot.sendMessage(chat_id=last_chat_id, text=' '.join(args))
+
+
+def cli_noncommand(bot, update, update_queue):
+    """
+    You can also get the update queue as an argument in any handler by
+    appending it to the argument list. Be careful with this though.
+    Here, we put the input string back into the queue, but as a command.
+
+    To learn more about those optional handler parameters, read:
+    http://python-telegram-bot.readthedocs.org/en/latest/telegram.dispatcher.html
+    """
+    update_queue.put('/%s' % update)
+
+
+def unknown_cli_command(bot, update):
+    logger.warn("Command not found: %s" % update)
+
+
+def error(bot, update, error):
+    """ Print error to console """
+    logger.warn('Update %s caused error %s' % (update, error))
+
+
+def main():
+    # Create the EventHandler and pass it your bot's token.
+    token = 'TOKEN'
+    updater = Updater(token, workers=10)
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # This is how we add handlers for Telegram messages
+    dp.addTelegramCommandHandler("start", start)
+    dp.addTelegramCommandHandler("help", help)
+    dp.addUnknownTelegramCommandHandler(unknown_command)
+    # Message handlers only receive updates that don't contain commands
+    dp.addTelegramMessageHandler(message)
+    # Regex handlers will receive all updates on which their regex matches
+    dp.addTelegramRegexHandler('.*', any_message)
+
+    # String handlers work pretty much the same
+    dp.addStringCommandHandler('reply', cli_reply)
+    dp.addUnknownStringCommandHandler(unknown_cli_command)
+    dp.addStringRegexHandler('[^/].*', cli_noncommand)
+
+    # All TelegramErrors are caught for you and delivered to the error
+    # handler(s). Other types of Errors are not caught.
+    dp.addErrorHandler(error)
+
+    # Start the Bot and store the update Queue, so we can insert updates
+    update_queue = updater.start_polling(poll_interval=0.1, timeout=10)
+
+    '''
+    # Alternatively, run with webhook:
+    updater.bot.setWebhook(webhook_url='https://example.com/%s' % token,
+                           certificate=open('cert.pem', 'rb'))
+
+    update_queue = updater.start_webhook('0.0.0.0',
+                                         443,
+                                         url_path=token,
+                                         cert='cert.pem',
+                                         key='key.key')
+
+    # Or, if SSL is handled by a reverse proxy, the webhook URL is already set
+    # and the reverse proxy is configured to deliver directly to port 6000:
+
+    update_queue = updater.start_webhook('0.0.0.0',
+                                         6000)
+    '''
+
+    # Start CLI-Loop
+    while True:
+        try:
+            text = raw_input()
+        except NameError:
+            text = input()
+
+        # Gracefully stop the event handler
+        if text == 'stop':
+            updater.stop()
+            break
+
+        # else, put the text into the update queue to be handled by our handlers
+        elif len(text) > 0:
+            update_queue.put(text)
+
+if __name__ == '__main__':
+    main()

examples/echobot.py

@@ -1,69 +0,0 @@
-#!/usr/bin/env python
-#
-# Simple Bot to reply Telegram messages
-# 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/].
-
-
-import logging
-import telegram
-import time
-
-
-LAST_UPDATE_ID = None
-
-
-def main():
-    global LAST_UPDATE_ID
-
-    logging.basicConfig(
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-
-    # Telegram Bot Authorization Token
-    bot = telegram.Bot('TOKEN')
-
-    # This will be our global variable to keep the latest update_id when requesting
-    # for updates. It starts with the latest update_id if available.
-    try:
-        LAST_UPDATE_ID = bot.getUpdates()[-1].update_id
-    except IndexError:
-        LAST_UPDATE_ID = None
-
-    while True:
-        echo(bot)
-        time.sleep(3)
-
-
-def echo(bot):
-    global LAST_UPDATE_ID
-
-    # Request updates from last updated_id
-    for update in bot.getUpdates(offset=LAST_UPDATE_ID):
-        if LAST_UPDATE_ID < update.update_id:
-            # chat_id is required to reply any message
-            chat_id = update.message.chat_id
-            message = update.message.text.encode('utf-8')
-
-            if (message):
-                # Reply the message
-                bot.sendMessage(chat_id=chat_id,
-                                text=message)
-
-                # Updates global offset to get the new updates
-                LAST_UPDATE_ID = update.update_id
-
-
-if __name__ == '__main__':
-    main()

examples/echobot2.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to reply to Telegram messages
+# This program is dedicated to the public domain under the CC0 license.
+
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few handler functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
+
+Usage:
+Basic Echobot example, repeats messages.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+from telegram import Updater
+import logging
+
+# Enable logging
+logging.basicConfig(
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+
+# Define a few command handlers. These usually take the two arguments bot and
+# update. Error handlers also receive the raised TelegramError object in error.
+def start(bot, update):
+    bot.sendMessage(update.message.chat_id, text='Hi!')
+
+
+def help(bot, update):
+    bot.sendMessage(update.message.chat_id, text='Help!')
+
+
+def echo(bot, update):
+    bot.sendMessage(update.message.chat_id, text=update.message.text)
+
+
+def error(bot, update, error):
+    logger.warn('Update "%s" caused error "%s"' % (update, error))
+
+
+def main():
+    # Create the EventHandler and pass it your bot's token.
+    updater = Updater("TOKEN")
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # on different commands - answer in Telegram
+    dp.addTelegramCommandHandler("start", start)
+    dp.addTelegramCommandHandler("help", help)
+
+    # on noncommand i.e message - echo the message on Telegram
+    dp.addTelegramMessageHandler(echo)
+
+    # log all errors
+    dp.addErrorHandler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Run the bot until the you presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+if __name__ == '__main__':
+    main()

examples/legacy/echobot.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to reply to Telegram messages
+# This program is dedicated to the public domain under the CC0 license.
+
+import logging
+import telegram
+from time import sleep
+
+try:
+    from urllib.error import URLError
+except ImportError:
+    from urllib2 import URLError  # python 2
+
+
+def main():
+    # Telegram Bot Authorization Token
+    bot = telegram.Bot('TOKEN')
+
+    # get the first pending update_id, this is so we can skip over it in case
+    # we get an "Unauthorized" exception.
+    try:
+        update_id = bot.getUpdates()[0].update_id
+    except IndexError:
+        update_id = None
+
+    logging.basicConfig(
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+
+    while True:
+        try:
+            update_id = echo(bot, update_id)
+        except telegram.TelegramError as e:
+            # These are network problems with Telegram.
+            if e.message in ("Bad Gateway", "Timed out"):
+                sleep(1)
+            elif e.message == "Unauthorized":
+                # The user has removed or blocked the bot.
+                update_id += 1
+            else:
+                raise e
+        except URLError as e:
+            # These are network problems on our end.
+            sleep(1)
+
+
+def echo(bot, update_id):
+
+    # Request updates after the last update_id
+    for update in bot.getUpdates(offset=update_id, timeout=10):
+        # chat_id is required to reply to any message
+        chat_id = update.message.chat_id
+        update_id = update.update_id + 1
+        message = update.message.text
+
+        if message:
+            # Reply to the message
+            bot.sendMessage(chat_id=chat_id,
+                            text=message)
+
+    return update_id
+
+
+if __name__ == '__main__':
+    main()

examples/legacy/roboed.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python
+# encoding: utf-8
+#
+# Robô Ed Telegram Bot
+# This program is dedicated to the public domain under the CC0 license.
+
+import logging
+import telegram
+import urllib
+
+
+def main():
+    logging.basicConfig(
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    bot = telegram.Bot('TOKEN')  # Telegram Bot Authorization Token
+
+    LAST_UPDATE_ID = bot.getUpdates()[-1].update_id  # Get lastest update
+
+    while True:
+        for update in bot.getUpdates(offset=LAST_UPDATE_ID, timeout=10):
+            text = update.message.text
+            chat_id = update.message.chat.id
+            update_id = update.update_id
+
+            if text:
+                roboed = ed(text)  # Ask something to Robô Ed
+                bot.sendMessage(chat_id=chat_id, text=roboed)
+                LAST_UPDATE_ID = update_id + 1
+
+
+def ed(text):
+    url = 'http://www.ed.conpet.gov.br/mod_perl/bot_gateway.cgi?server=0.0.0.0%3A8085&charset_post=utf-8&charset=utf-8&pure=1&js=0&tst=1&msg=' + text
+    data = urllib.urlopen(url).read()
+
+    return data.strip()
+
+if __name__ == '__main__':
+    main()

examples/roboed.py

@@ -1,56 +0,0 @@
-#!/usr/bin/env python
-# encoding: utf-8
-#
-# Robô Ed Telegram Bot
-# 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/].
-
-
-__author__ = 'leandrotoledodesouza@gmail.com'
-
-import logging
-import telegram
-import urllib
-
-
-def main():
-    logging.basicConfig(
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-    bot = telegram.Bot('TOKEN')  # Telegram Bot Authorization Token
-
-    LAST_UPDATE_ID = bot.getUpdates()[-1].update_id  # Get lastest update
-
-    while True:
-        for update in bot.getUpdates(offset=LAST_UPDATE_ID):
-            text = update.message.text
-            chat_id = update.message.chat.id
-            update_id = update.update_id
-
-            if LAST_UPDATE_ID < update_id:  # If newer than the initial
-                                            # LAST_UPDATE_ID
-                if text:
-                    roboed = ed(text)  # Ask something to Robô Ed
-                    bot.sendMessage(chat_id=chat_id, text=roboed)
-                    LAST_UPDATE_ID = update_id
-
-
-def ed(text):
-    url = 'http://www.ed.conpet.gov.br/mod_perl/bot_gateway.cgi?server=0.0.0.0%3A8085&charset_post=utf-8&charset=utf-8&pure=1&js=0&tst=1&msg=' + text
-    data = urllib.urlopen(url).read()
-
-    return data.strip()
-
-if __name__ == '__main__':
-    main()

examples/timerbot.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to send timed Telegram messages
+# This program is dedicated to the public domain under the CC0 license.
+
+"""
+This Bot uses the Updater class to handle the bot and the JobQueue to send
+timed messages.
+
+First, a few handler functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
+
+Usage:
+Basic Alarm Bot example, sends a message after a set time.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+from telegram import Updater
+import logging
+
+# Enable logging
+logging.basicConfig(
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+job_queue = None
+
+
+# Define a few command handlers. These usually take the two arguments bot and
+# update. Error handlers also receive the raised TelegramError object in error.
+def start(bot, update):
+    bot.sendMessage(update.message.chat_id, text='Hi! Use /set <seconds> to '
+                                                 'set a timer')
+
+
+def set(bot, update, args):
+    """ Adds a job to the queue """
+    chat_id = update.message.chat_id
+    try:
+        # args[0] should contain the time for the timer in seconds
+        due = int(args[0])
+
+        def alarm(bot):
+            """ Inner function to send the alarm message """
+            bot.sendMessage(chat_id, text='Beep!')
+
+        # Add job to queue
+        job_queue.put(alarm, due, repeat=False)
+        bot.sendMessage(chat_id, text='Timer successfully set!')
+
+    except IndexError:
+        bot.sendMessage(chat_id, text='Usage: /set <seconds>')
+    except ValueError:
+        bot.sendMessage(chat_id, text='Usage: /set <seconds>')
+
+
+def error(bot, update, error):
+    logger.warn('Update "%s" caused error "%s"' % (update, error))
+
+
+def main():
+    global job_queue
+
+    updater = Updater("148447715:AAFj2qskb3_sMMzlDhgTuoP7VAABNHpT0BU")
+    job_queue = updater.job_queue
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # on different commands - answer in Telegram
+    dp.addTelegramCommandHandler("start", start)
+    dp.addTelegramCommandHandler("help", start)
+    dp.addTelegramCommandHandler("set", set)
+
+    # log all errors
+    dp.addErrorHandler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Block until the you presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+if __name__ == '__main__':
+    main()

requirements.txt

@@ -0,0 +1 @@
+future

setup.py

@@ -13,17 +13,29 @@ def read(*paths):
         return f.read()
 
 
+def requirements():
+    """Build the requirements list for this project"""
+    requirements_list = []
+
+    with open('requirements.txt') as requirements:
+        for install in requirements:
+            requirements_list.append(install.strip())
+
+    return requirements_list
+
+
 setup(
     name='python-telegram-bot',
-    version='2.6.1',
+    version='3.2.0',
     author='Leandro Toledo',
-    author_email='leandrotoledodesouza@gmail.com',
+    author_email='devs@python-telegram-bot.org',
     license='LGPLv3',
-    url='https://github.com/leandrotoledo/python-telegram-bot',
-    keywords='telegram bot api',
+    url='https://github.com/python-telegram-bot/python-telegram-bot',
+    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*']),
+    install_requires=requirements(),
     include_package_data=True,
     classifiers=[
         'Development Status :: 5 - Production/Stable',

telegram/__init__.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,15 +17,14 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 
+"""A library that provides a Python interface to the Telegram Bot API"""
 
-__author__ = 'leandrotoledodesouza@gmail.com'
-__version__ = '2.6.1'
+__author__ = 'devs@python-telegram-bot.org'
+__version__ = '3.2.0'
 
 from .base import TelegramObject
 from .user import User
-from .message import Message
-from .update import Update
-from .groupchat import GroupChat
+from .chat import Chat
 from .photosize import PhotoSize
 from .audio import Audio
 from .voice import Voice
@@ -39,15 +39,22 @@ from .replymarkup import ReplyMarkup
 from .replykeyboardmarkup import ReplyKeyboardMarkup
 from .replykeyboardhide import ReplyKeyboardHide
 from .forcereply import ForceReply
-from .inputfile import InputFile
 from .error import TelegramError
+from .inputfile import InputFile
+from .file import File
 from .nullhandler import NullHandler
 from .emoji import Emoji
+from .parsemode import ParseMode
+from .message import Message
+from .update import Update
 from .bot import Bot
+from .dispatcher import Dispatcher
+from .jobqueue import JobQueue
+from .updater import Updater
 
-__all__ = ['Bot', 'Emoji', 'TelegramError', 'InputFile', 'ReplyMarkup',
-           'ForceReply', 'ReplyKeyboardHide', 'ReplyKeyboardMarkup',
-           'UserProfilePhotos', 'ChatAction', 'Location', 'Contact',
-           'Video', 'Sticker', 'Document', 'Audio', 'PhotoSize', 'GroupChat',
-           'Update', 'Message', 'User', 'TelegramObject', 'NullHandler',
-           'Voice']
+__all__ = ['Bot', 'Updater', 'Dispatcher', 'Emoji', 'TelegramError',
+           'InputFile', 'ReplyMarkup', 'ForceReply', 'ReplyKeyboardHide',
+           'ReplyKeyboardMarkup', 'UserProfilePhotos', 'ChatAction',
+           'Location', 'Contact', 'Video', 'Sticker', 'Document', 'File',
+           'Audio', 'PhotoSize', 'Chat', 'Update', 'ParseMode', 'Message',
+           'User', 'TelegramObject', 'NullHandler', 'Voice', 'JobQueue']

telegram/audio.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,43 +17,57 @@
 # 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 Audio"""
 
 from telegram import TelegramObject
 
 
 class Audio(TelegramObject):
+    """This object represents a Telegram Audio.
+
+    Attributes:
+        file_id (str):
+        duration (int):
+        performer (str):
+        title (str):
+        mime_type (str):
+        file_size (int):
+
+    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]):
+    """
+
     def __init__(self,
                  file_id,
                  duration,
-                 performer=None,
-                 title=None,
-                 mime_type=None,
-                 file_size=None):
-        self.file_id = file_id
-        self.duration = duration
-        self.performer = performer
-        self.title = title
-        self.mime_type = mime_type
-        self.file_size = file_size
+                 **kwargs):
+        # Required
+        self.file_id = str(file_id)
+        self.duration = int(duration)
+        # Optionals
+        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))
 
     @staticmethod
     def de_json(data):
-        return Audio(file_id=data.get('file_id', None),
-                     duration=data.get('duration', None),
-                     performer=data.get('performer', None),
-                     title=data.get('title', None),
-                     mime_type=data.get('mime_type', None),
-                     file_size=data.get('file_size', None))
+        """
+        Args:
+            data (str):
 
-    def to_dict(self):
-        data = {'file_id': self.file_id,
-                'duration': self.duration}
-        if self.performer:
-            data['performer'] = self.performer
-        if self.title:
-            data['title'] = self.title
-        if self.mime_type:
-            data['mime_type'] = self.mime_type
-        if self.file_size:
-            data['file_size'] = self.file_size
-        return data
+        Returns:
+            telegram.Audio:
+        """
+        if not data:
+            return None
+
+        return Audio(**data)

telegram/base.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,13 +17,14 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 
+"""Base class for Telegram Objects"""
 
 import json
-from abc import ABCMeta, abstractmethod
+from abc import ABCMeta
 
 
 class TelegramObject(object):
-    """Base class for most telegram object"""
+    """Base class for most telegram objects"""
 
     __metaclass__ = ABCMeta
 
@@ -34,11 +36,34 @@ class TelegramObject(object):
 
     @staticmethod
     def de_json(data):
+        """
+        Args:
+            data (str):
+
+        Returns:
+            telegram.TelegramObject:
+        """
         raise NotImplementedError
 
     def to_json(self):
+        """
+        Returns:
+            str:
+        """
         return json.dumps(self.to_dict())
 
-    @abstractmethod
     def to_dict(self):
-        return
+        """
+        Returns:
+            dict:
+        """
+        data = dict()
+
+        for key, value in self.__dict__.items():
+            if value:
+                if hasattr(value, 'to_dict'):
+                    data[key] = value.to_dict()
+                else:
+                    data[key] = value
+
+        return data

telegram/bot.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python
+# pylint: disable=E0611,E0213,E1102,C0103,E1101,W0613,R0913,R0904
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,45 +18,63 @@
 # 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 Bot"""
 
-import json
-try:
-    from urllib.parse import urlencode
-    from urllib.request import urlopen, Request
-    from urllib.error import HTTPError, URLError
-except ImportError:
-    from urllib import urlencode
-    from urllib2 import urlopen, Request
-    from urllib2 import HTTPError, URLError
 import functools
 import logging
 
-from telegram import (User, Message, Update, UserProfilePhotos, TelegramError,
-                      ReplyMarkup, InputFile, TelegramObject, NullHandler)
+from telegram import (User, Message, Update, UserProfilePhotos, File,
+                      TelegramError, ReplyMarkup, TelegramObject, NullHandler)
+from telegram.utils import request
 
-h = NullHandler()
-logging.getLogger(__name__).addHandler(h)
+H = NullHandler()
+logging.getLogger(__name__).addHandler(H)
 
 
 class Bot(TelegramObject):
 
+    """This object represents a Telegram Bot.
+
+    Attributes:
+        id (int):
+        first_name (str):
+        last_name (str):
+        username (str):
+        name (str):
+
+    Args:
+        token (str):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        base_url (Optional[str]):
+    """
+
     def __init__(self,
                  token,
                  base_url=None):
-        self.token = token
+        self.token = self._valid_token(token)
 
         if base_url is None:
             self.base_url = 'https://api.telegram.org/bot%s' % self.token
         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.log = logging.getLogger(__name__)
+        self.logger = logging.getLogger(__name__)
 
     def info(func):
+        """
+        Returns:
+        """
         @functools.wraps(func)
         def decorator(self, *args, **kwargs):
+            """
+            decorator
+            """
             if not self.bot:
                 self.getMe()
 
@@ -65,36 +85,48 @@ class Bot(TelegramObject):
     @property
     @info
     def id(self):
+        """int: """
         return self.bot.id
 
     @property
     @info
     def first_name(self):
+        """str: """
         return self.bot.first_name
 
     @property
     @info
     def last_name(self):
+        """str: """
         return self.bot.last_name
 
     @property
     @info
     def username(self):
+        """str: """
         return self.bot.username
 
     @property
     def name(self):
+        """str: """
         return '@%s' % self.username
 
     def log(func):
+        """
+        Returns:
+          A telegram.Message instance representing the message posted.
+        """
         logger = logging.getLogger(func.__module__)
 
         @functools.wraps(func)
         def decorator(self, *args, **kwargs):
-            logger.debug('Entering: %s' % func.__name__)
+            """
+            decorator
+            """
+            logger.debug('Entering: %s', func.__name__)
             result = func(self, *args, **kwargs)
             logger.debug(result)
-            logger.debug('Exiting: %s' % func.__name__)
+            logger.debug('Exiting: %s', func.__name__)
             return result
         return decorator
 
@@ -105,8 +137,14 @@ class Bot(TelegramObject):
         """
         @functools.wraps(func)
         def decorator(self, *args, **kwargs):
+            """
+            decorator
+            """
             url, data = func(self, *args, **kwargs)
 
+            if not data.get('chat_id'):
+                raise TelegramError('Invalid chat_id')
+
             if kwargs.get('reply_to_message_id'):
                 reply_to_message_id = kwargs.get('reply_to_message_id')
                 data['reply_to_message_id'] = reply_to_message_id
@@ -118,13 +156,12 @@ class Bot(TelegramObject):
                 else:
                     data['reply_markup'] = reply_markup
 
-            json_data = self._requestUrl(url, 'POST', data=data)
-            data = self._parseAndCheckTelegram(json_data)
+            result = request.post(url, data)
 
-            if data is True:
-                return data
+            if result is True:
+                return result
 
-            return Message.de_json(data)
+            return Message.de_json(result)
         return decorator
 
     @log
@@ -137,10 +174,9 @@ class Bot(TelegramObject):
         """
         url = '%s/getMe' % self.base_url
 
-        json_data = self._requestUrl(url, 'GET')
-        data = self._parseAndCheckTelegram(json_data)
+        result = request.get(url)
 
-        self.bot = User.de_json(data)
+        self.bot = User.de_json(result)
 
         return self.bot
 
@@ -149,15 +185,18 @@ class Bot(TelegramObject):
     def sendMessage(self,
                     chat_id,
                     text,
+                    parse_mode=None,
                     disable_web_page_preview=None,
-                    reply_to_message_id=None,
-                    reply_markup=None):
+                    **kwargs):
         """Use this method to send text messages.
 
         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
+            for Android supports this. [Optional]
           text:
             Text of the message to be sent.
           disable_web_page_preview:
@@ -178,6 +217,8 @@ class Bot(TelegramObject):
         data = {'chat_id': chat_id,
                 'text': text}
 
+        if parse_mode:
+            data['parse_mode'] = parse_mode
         if disable_web_page_preview:
             data['disable_web_page_preview'] = disable_web_page_preview
 
@@ -193,10 +234,10 @@ class Bot(TelegramObject):
 
         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.
 
@@ -222,13 +263,12 @@ class Bot(TelegramObject):
                   chat_id,
                   photo,
                   caption=None,
-                  reply_to_message_id=None,
-                  reply_markup=None):
+                  **kwargs):
         """Use this method to send photos.
 
         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
@@ -265,8 +305,7 @@ class Bot(TelegramObject):
                   duration=None,
                   performer=None,
                   title=None,
-                  reply_to_message_id=None,
-                  reply_markup=None):
+                  **kwargs):
         """Use this method to send audio files, if you want Telegram clients to
         display them in the music player. Your audio must be in an .mp3 format.
         On success, the sent Message is returned. Bots can currently send audio
@@ -280,7 +319,7 @@ class Bot(TelegramObject):
 
         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
@@ -321,17 +360,20 @@ class Bot(TelegramObject):
     def sendDocument(self,
                      chat_id,
                      document,
-                     reply_to_message_id=None,
-                     reply_markup=None):
+                     filename=None,
+                     **kwargs):
         """Use this method to send general files.
 
         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
             using multipart/form-data.
+          filename:
+            File name that shows in telegram message (it is usefull when you
+            send file generated by temp module, for example). [Optional]
           reply_to_message_id:
             If the message is a reply, ID of the original message. [Optional]
           reply_markup:
@@ -348,6 +390,9 @@ class Bot(TelegramObject):
         data = {'chat_id': chat_id,
                 'document': document}
 
+        if filename:
+            data['filename'] = filename
+
         return url, data
 
     @log
@@ -355,13 +400,12 @@ class Bot(TelegramObject):
     def sendSticker(self,
                     chat_id,
                     sticker,
-                    reply_to_message_id=None,
-                    reply_markup=None):
+                    **kwargs):
         """Use this method to send .webp stickers.
 
         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
@@ -391,14 +435,13 @@ class Bot(TelegramObject):
                   video,
                   duration=None,
                   caption=None,
-                  reply_to_message_id=None,
-                  reply_markup=None):
+                  **kwargs):
         """Use this method to send video files, Telegram clients support mp4
         videos (other formats may be sent as telegram.Document).
 
         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
@@ -437,8 +480,7 @@ class Bot(TelegramObject):
                   chat_id,
                   voice,
                   duration=None,
-                  reply_to_message_id=None,
-                  reply_markup=None):
+                  **kwargs):
         """Use this method to send audio files, if you want Telegram clients to
         display the file as a playable voice message. For this to work, your
         audio must be in an .ogg file encoded with OPUS (other formats may be
@@ -448,7 +490,7 @@ class Bot(TelegramObject):
 
         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
@@ -482,13 +524,12 @@ class Bot(TelegramObject):
                      chat_id,
                      latitude,
                      longitude,
-                     reply_to_message_id=None,
-                     reply_markup=None):
+                     **kwargs):
         """Use this method to send point on the map.
 
         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:
@@ -524,14 +565,14 @@ class Bot(TelegramObject):
 
         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:
             - ChatAction.TYPING for text messages,
             - ChatAction.UPLOAD_PHOTO for photos,
-            - ChatAction.UPLOAD_VIDEO or upload_video for videos,
-            - ChatAction.UPLOAD_AUDIO or upload_audio for audio files,
+            - ChatAction.UPLOAD_VIDEO for videos,
+            - ChatAction.UPLOAD_AUDIO for audio files,
             - ChatAction.UPLOAD_DOCUMENT for general files,
             - ChatAction.FIND_LOCATION for location data.
         """
@@ -573,16 +614,43 @@ class Bot(TelegramObject):
         if limit:
             data['limit'] = limit
 
-        json_data = self._requestUrl(url, 'POST', data=data)
-        data = self._parseAndCheckTelegram(json_data)
+        result = request.post(url, data)
 
-        return UserProfilePhotos.de_json(data)
+        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,
                    limit=100,
-                   timeout=0):
+                   timeout=0,
+                   network_delay=2.):
         """Use this method to receive incoming updates using long polling.
 
         Args:
@@ -598,6 +666,11 @@ class Bot(TelegramObject):
           timeout:
             Timeout in seconds for long polling. Defaults to 0, i.e. usual
             short polling.
+          network_delay:
+            Additional timeout in seconds to allow the response from Telegram
+            to take some time when using long polling. Defaults to 2, which
+            should be enough for most connections. Increase it if it takes very
+            long for data to be transmitted from and to the Telegram servers.
 
         Returns:
           A list of telegram.Update objects are returned.
@@ -613,20 +686,20 @@ class Bot(TelegramObject):
         if timeout:
             data['timeout'] = timeout
 
-        json_data = self._requestUrl(url, 'POST', data=data)
-        data = self._parseAndCheckTelegram(json_data)
+        result = request.post(url, data, network_delay=network_delay)
 
-        if data:
-            self.log.info(
-                'Getting updates: %s' % [u['update_id'] for u in data])
+        if result:
+            self.logger.info(
+                'Getting updates: %s', [u['update_id'] for u in result])
         else:
-            self.log.info('No new updates found.')
+            self.logger.info('No new updates found.')
 
-        return [Update.de_json(x) for x in data]
+        return [Update.de_json(x) for x in result]
 
     @log
     def setWebhook(self,
-                   webhook_url):
+                   webhook_url=None,
+                   certificate=None):
         """Use this method to specify a url and receive incoming updates via an
         outgoing webhook. Whenever there is an update for the bot, we will send
         an HTTPS POST request to the specified url, containing a
@@ -643,89 +716,25 @@ class Bot(TelegramObject):
         """
         url = '%s/setWebhook' % self.base_url
 
-        data = {'url': webhook_url}
+        data = {}
+        if webhook_url:
+            data['url'] = webhook_url
+        if certificate:
+            data['certificate'] = certificate
 
-        json_data = self._requestUrl(url, 'POST', data=data)
-        data = self._parseAndCheckTelegram(json_data)
+        result = request.post(url, data)
 
-        return True
+        return result
 
-    def _requestUrl(self,
-                    url,
-                    method,
-                    data=None):
-        """Request an URL.
-
-        Args:
-          url:
-            The web location we want to retrieve.
-          method:
-            Either POST or GET.
-          data:
-            A dict of (str, unicode) key/value pairs.
-
-        Returns:
-          A JSON object.
-        """
-        if method not in ('POST', 'GET'):
-            raise ValueError(
-                "Method '%s' is neither 'POST' nor 'GET'" % method)
-
-        if method == 'POST':
-            try:
-                if InputFile.is_inputfile(data):
-                    data = InputFile(data)
-
-                    request = Request(
-                        url,
-                        data=data.to_form(),
-                        headers=data.headers
-                    )
-
-                    return urlopen(request).read()
-                else:
-                    return urlopen(
-                        url,
-                        urlencode(data).encode()
-                    ).read()
-            except IOError as e:
-                raise TelegramError(str(e))
-            except HTTPError as e:
-                raise TelegramError(str(e))
-            except URLError as e:
-                raise TelegramError(str(e))
-
-        if method == 'GET':
-            try:
-                return urlopen(url).read()
-            except URLError as e:
-                raise TelegramError(str(e))
-
-    def _parseAndCheckTelegram(self,
-                               json_data):
-        """Try and parse the JSON returned from Telegram and return an empty
-        dictionary if there is any error.
-
-        Args:
-          json_data:
-            JSON results from Telegram Bot API.
-
-        Returns:
-          A JSON parsed as Python dict with results.
-        """
-
-        try:
-            data = json.loads(json_data.decode())
-            if not data['ok']:
-                raise TelegramError(data['description'])
-        except ValueError:
-            if '<title>403 Forbidden</title>' in json_data:
-                raise TelegramError({'message': 'API must be authenticated'})
-            raise TelegramError({'message': 'JSON decoding'})
-
-        return data['result']
+    @staticmethod
+    def de_json(data):
+        pass
 
     def to_dict(self):
+        """
+        Returns:
+            dict:
+        """
         data = {'id': self.id,
                 'username': self.username,
                 'first_name': self.username}
@@ -736,3 +745,11 @@ class Bot(TelegramObject):
     def __reduce__(self):
         return (self.__class__, (self.token,
                                  self.base_url.replace(self.token, '')))
+
+    @staticmethod
+    def _valid_token(token):
+        """a very basic validation on token"""
+        left, sep, _right = token.partition(':')
+        if (not sep) or (not left.isdigit()) or (len(left) < 3):
+            raise TelegramError('Invalid token')
+        return token

telegram/chat.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+# pylint: disable=C0103,W0622
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Chat"""
+
+from telegram import TelegramObject
+
+
+class Chat(TelegramObject):
+    """This object represents a Telegram Chat.
+
+    Attributes:
+        id (int):
+        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):
+        type (str):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        type (Optional[str]):
+    """
+
+    def __init__(self,
+                 id,
+                 type,
+                 **kwargs):
+        # Required
+        self.id = int(id)
+        self.type = type
+        # Optionals
+        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 (dict):
+
+        Returns:
+            telegram.Chat:
+        """
+        if not data:
+            return None
+
+        return Chat(**data)

telegram/chataction.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python
+# pylint: disable=R0903
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,11 +18,17 @@
 # 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 ChatAction"""
+
 
 class ChatAction(object):
+    """This object represents a Telegram ChatAction."""
+
     TYPING = 'typing'
     UPLOAD_PHOTO = 'upload_photo'
-    RECORD_VIDEO = 'upload_video'
-    RECORD_AUDIO = 'upload_audio'
+    RECORD_VIDEO = 'record_video'
+    UPLOAD_VIDEO = 'upload_video'
+    RECORD_AUDIO = 'record_audio'
+    UPLOAD_AUDIO = 'upload_audio'
     UPLOAD_DOCUMENT = 'upload_document'
     FIND_LOCATION = 'find_location'

telegram/contact.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,33 +17,51 @@
 # 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 Contact"""
 
 from telegram import TelegramObject
 
 
 class Contact(TelegramObject):
+    """This object represents a Telegram Contact.
+
+    Attributes:
+        phone_number (str):
+        first_name (str):
+        last_name (str):
+        user_id (int):
+
+    Args:
+        phone_number (str):
+        first_name (str):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        last_name (Optional[str]):
+        user_id (Optional[int]):
+    """
+
     def __init__(self,
                  phone_number,
                  first_name,
-                 last_name=None,
-                 user_id=None):
-        self.phone_number = phone_number
+                 **kwargs):
+        # Required
+        self.phone_number = str(phone_number)
         self.first_name = first_name
-        self.last_name = last_name
-        self.user_id = user_id
+        # Optionals
+        self.last_name = kwargs.get('last_name', '')
+        self.user_id = int(kwargs.get('user_id', 0))
 
     @staticmethod
     def de_json(data):
-        return Contact(phone_number=data.get('phone_number', None),
-                       first_name=data.get('first_name', None),
-                       last_name=data.get('last_name', None),
-                       user_id=data.get('user_id', None))
+        """
+        Args:
+            data (str):
 
-    def to_dict(self):
-        data = {'phone_number': self.phone_number,
-                'first_name': self.first_name}
-        if self.last_name:
-            data['last_name'] = self.last_name
-        if self.user_id:
-            data['user_id'] = self.user_id
-        return data
+        Returns:
+            telegram.Contact:
+        """
+        if not data:
+            return None
+
+        return Contact(**data)

telegram/dispatcher.py

@@ -0,0 +1,637 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 the Dispatcher class.
+"""
+import logging
+from functools import wraps
+from inspect import getargspec
+from threading import Thread, BoundedSemaphore, Lock
+from re import match
+
+from telegram import (TelegramError, Update, NullHandler)
+
+H = NullHandler()
+logging.getLogger(__name__).addHandler(H)
+
+semaphore = None
+running_async = 0
+async_lock = Lock()
+
+
+def run_async(func):
+    """
+    Function decorator that will run the function in a new thread. A function
+    decorated with this will have to include **kwargs in their parameter list,
+    which will contain all optional parameters.
+
+    Args:
+        func (function): The function to run in the thread.
+
+    Returns:
+        function:
+    """
+
+    @wraps(func)
+    def pooled(*pargs, **kwargs):
+        """
+        A wrapper to run a thread in a thread pool
+        """
+        global running_async, async_lock
+        result = func(*pargs, **kwargs)
+        semaphore.release()
+        with async_lock:
+            running_async -= 1
+        return result
+
+    @wraps(func)
+    def async_func(*pargs, **kwargs):
+        """
+        A wrapper to run a function in a thread
+        """
+        global running_async, async_lock
+        thread = Thread(target=pooled, args=pargs, kwargs=kwargs)
+        semaphore.acquire()
+        with async_lock:
+            running_async += 1
+        thread.start()
+        return thread
+
+    return async_func
+
+
+class Dispatcher:
+    """
+    This class dispatches all kinds of updates to its registered handlers.
+    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
+
+    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
+            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
+            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']
+            For other updates, args will be None
+
+    For regex-based handlers, you can also request information about the match.
+    For all other handlers, these will be None
+
+        groups:
+            A tuple that contains the result of
+            re.match(matcher, ...).groups()
+        groupdict:
+            A dictionary that contains the result of
+            re.match(matcher, ...).groupdict()
+
+    Args:
+        bot (telegram.Bot): The bot object that should be passed to the
+            handlers
+        update_queue (queue.Queue): The synchronized queue that will
+            contain the updates.
+    """
+    def __init__(self, bot, update_queue, workers=4):
+        self.bot = bot
+        self.update_queue = update_queue
+        self.telegram_message_handlers = []
+        self.telegram_command_handlers = {}
+        self.telegram_regex_handlers = {}
+        self.string_regex_handlers = {}
+        self.string_command_handlers = {}
+        self.type_handlers = {}
+        self.unknown_telegram_command_handlers = []
+        self.unknown_string_command_handlers = []
+        self.error_handlers = []
+        self.logger = logging.getLogger(__name__)
+        self.running = False
+        self.__lock = Lock()
+
+        global semaphore
+        if not semaphore:
+            semaphore = BoundedSemaphore(value=workers)
+        else:
+            self.logger.info("Semaphore already initialized, skipping.")
+
+    class _Stop(object):
+        """
+        A class which objects can be passed into the update queue to stop the
+        thread
+        """
+        pass
+
+    def start(self):
+        """
+        Thread target of thread 'dispatcher'. Runs in background and processes
+        the update queue.
+        """
+
+        self.__lock.acquire()
+        if not self.running:
+            self.running = True
+            self.__lock.release()
+            self.logger.info('Dispatcher thread started')
+
+            while True:
+                update = None
+
+                try:
+                    # Pop update from update queue.
+                    # Blocks if no updates are available.
+                    update = self.update_queue.get()
+
+                    if type(update) is self._Stop:
+                        break
+
+                    self.processUpdate(update)
+                    self.logger.debug('Processed Update: %s' % update)
+
+                # Dispatch any errors
+                except TelegramError as te:
+                    self.logger.warn("Error was raised while processing "
+                                     "Update.")
+                    self.dispatchError(update, te)
+
+                # All other errors should not stop the thread, just print them
+                except:
+                    self.logger.exception("An uncaught error was raised while "
+                                          "processing an update")
+        else:
+            self.__lock.release()
+        self.logger.info('Dispatcher thread stopped')
+
+    def stop(self):
+        """
+        Stops the thread
+        """
+        with self.__lock:
+            if self.running:
+                self.running = False
+                self.update_queue.put(self._Stop())
+
+    def processUpdate(self, update):
+        """
+        Processes a single update.
+
+        Args:
+            update (any):
+        """
+
+        handled = False
+
+        # Custom type handlers
+        for t in self.type_handlers:
+            if isinstance(update, t):
+                self.dispatchType(update)
+                handled = True
+
+        # string update
+        if type(update) is str and update.startswith('/'):
+            self.dispatchStringCommand(update)
+            handled = True
+        elif type(update) is str:
+            self.dispatchRegex(update)
+            handled = True
+
+        # An error happened while polling
+        if isinstance(update, TelegramError):
+            self.dispatchError(None, update)
+            handled = True
+
+        # Telegram update (regex)
+        if isinstance(update, Update):
+            self.dispatchRegex(update)
+            handled = True
+
+        # Telegram update (command)
+        if isinstance(update, Update) \
+                and update.message.text.startswith('/'):
+            self.dispatchTelegramCommand(update)
+            handled = True
+
+        # Telegram update (message)
+        elif isinstance(update, Update):
+            self.dispatchTelegramMessage(update)
+            handled = True
+
+        # Update not recognized
+        if not handled:
+            self.dispatchError(update, TelegramError(
+                "Received update of unknown type %s" % type(update)))
+
+    # Add Handlers
+    def addTelegramMessageHandler(self, handler):
+        """
+        Registers a message handler in the Dispatcher.
+
+        Args:
+            handler (function): A function that takes (Bot, Update, *args) as
+                arguments.
+        """
+
+        self.telegram_message_handlers.append(handler)
+
+    def addTelegramCommandHandler(self, command, handler):
+        """
+        Registers a command handler in the Dispatcher.
+
+        Args:
+            command (str): The command keyword that this handler should be
+                listening to.
+            handler (function): A function that takes (Bot, Update, *args) as
+                arguments.
+        """
+
+        if command not in self.telegram_command_handlers:
+            self.telegram_command_handlers[command] = []
+
+        self.telegram_command_handlers[command].append(handler)
+
+    def addTelegramRegexHandler(self, matcher, handler):
+        """
+        Registers a regex handler in the Dispatcher. If handlers will be
+        called if re.match(matcher, update.message.text) is True.
+
+        Args:
+            matcher (str/__Regex): A regex string or compiled regex object that
+                matches on messages that handler should be listening to
+            handler (function): A function that takes (Bot, Update, *args) as
+                arguments.
+        """
+
+        if matcher not in self.telegram_regex_handlers:
+            self.telegram_regex_handlers[matcher] = []
+
+        self.telegram_regex_handlers[matcher].append(handler)
+
+    def addStringCommandHandler(self, command, handler):
+        """
+        Registers a string-command handler in the Dispatcher.
+
+        Args:
+            command (str): The command keyword that this handler should be
+                listening to.
+            handler (function): A function that takes (Bot, str, *args) as
+                arguments.
+        """
+
+        if command not in self.string_command_handlers:
+            self.string_command_handlers[command] = []
+
+        self.string_command_handlers[command].append(handler)
+
+    def addStringRegexHandler(self, matcher, handler):
+        """
+        Registers a regex handler in the Dispatcher. If handlers will be
+        called if re.match(matcher, string) is True.
+
+        Args:
+            matcher (str/__Regex): A regex string or compiled regex object that
+                matches on the string input that handler should be listening to
+            handler (function): A function that takes (Bot, Update, *args) as
+                arguments.
+        """
+
+        if matcher not in self.string_regex_handlers:
+            self.string_regex_handlers[matcher] = []
+
+        self.string_regex_handlers[matcher].append(handler)
+
+    def addUnknownTelegramCommandHandler(self, handler):
+        """
+        Registers a command handler in the Dispatcher, that will receive all
+        commands that have no associated handler.
+
+        Args:
+            handler (function): A function that takes (Bot, Update, *args) as
+                arguments.
+        """
+
+        self.unknown_telegram_command_handlers.append(handler)
+
+    def addUnknownStringCommandHandler(self, handler):
+        """
+        Registers a string-command handler in the Dispatcher, that will
+        receive all commands that have no associated handler.
+
+        Args:
+            handler (function): A function that takes (Bot, str, *args) as
+                arguments.
+        """
+
+        self.unknown_string_command_handlers.append(handler)
+
+    def addErrorHandler(self, handler):
+        """
+        Registers an error handler in the Dispatcher.
+
+        Args:
+            handler (function): A function that takes (Bot, TelegramError) as
+                arguments.
+        """
+
+        self.error_handlers.append(handler)
+
+    def addTypeHandler(self, the_type, handler):
+        """
+        Registers a type handler in the Dispatcher. This allows you to send
+        any type of object into the update queue.
+
+        Args:
+            the_type (type): The type this handler should listen to
+            handler (function): A function that takes (Bot, type, *args) as
+                arguments.
+        """
+
+        if the_type not in self.type_handlers:
+            self.type_handlers[the_type] = []
+
+        self.type_handlers[the_type].append(handler)
+
+    # Remove Handlers
+    def removeTelegramMessageHandler(self, handler):
+        """
+        De-registers a message handler.
+
+        Args:
+            handler (any):
+        """
+
+        if handler in self.telegram_message_handlers:
+            self.telegram_message_handlers.remove(handler)
+
+    def removeTelegramCommandHandler(self, command, handler):
+        """
+        De-registers a command handler.
+
+        Args:
+            command (str): The command
+            handler (any):
+        """
+
+        if command in self.telegram_command_handlers \
+                and handler in self.telegram_command_handlers[command]:
+            self.telegram_command_handlers[command].remove(handler)
+
+    def removeTelegramRegexHandler(self, matcher, handler):
+        """
+        De-registers a regex handler.
+
+        Args:
+            matcher (str/__Regex): The regex matcher object or string
+            handler (any):
+        """
+
+        if matcher in self.telegram_regex_handlers \
+                and handler in self.telegram_regex_handlers[matcher]:
+            self.telegram_regex_handlers[matcher].remove(handler)
+
+    def removeStringCommandHandler(self, command, handler):
+        """
+        De-registers a string-command handler.
+
+        Args:
+            command (str): The command
+            handler (any):
+        """
+
+        if command in self.string_command_handlers \
+                and handler in self.string_command_handlers[command]:
+            self.string_command_handlers[command].remove(handler)
+
+    def removeStringRegexHandler(self, matcher, handler):
+        """
+        De-registers a regex handler.
+
+        Args:
+            matcher (str/__Regex): The regex matcher object or string
+            handler (any):
+        """
+
+        if matcher in self.string_regex_handlers \
+                and handler in self.string_regex_handlers[matcher]:
+            self.string_regex_handlers[matcher].remove(handler)
+
+    def removeUnknownTelegramCommandHandler(self, handler):
+        """
+        De-registers an unknown-command handler.
+
+        Args:
+            handler (any):
+        """
+
+        if handler in self.unknown_telegram_command_handlers:
+            self.unknown_telegram_command_handlers.remove(handler)
+
+    def removeUnknownStringCommandHandler(self, handler):
+        """
+        De-registers an unknown-command handler.
+
+        Args:
+            handler (any):
+        """
+
+        if handler in self.unknown_string_command_handlers:
+            self.unknown_string_command_handlers.remove(handler)
+
+    def removeErrorHandler(self, handler):
+        """
+        De-registers an error handler.
+
+        Args:
+            handler (any):
+        """
+
+        if handler in self.error_handlers:
+            self.error_handlers.remove(handler)
+
+    def removeTypeHandler(self, the_type, handler):
+        """
+        De-registers a type handler.
+
+        Args:
+            handler (any):
+        """
+
+        if the_type in self.type_handlers \
+                and handler in self.type_handlers[the_type]:
+            self.type_handlers[the_type].remove(handler)
+
+    def dispatchTelegramCommand(self, update):
+        """
+        Dispatches an update that contains a command.
+
+        Args:
+            command (str): The command keyword
+            update (telegram.Update): The Telegram update that contains the
+                command
+        """
+
+        command = update.message.text.split(' ')[0][1:].split('@')[0]
+
+        if command in self.telegram_command_handlers:
+            self.dispatchTo(self.telegram_command_handlers[command], update)
+        else:
+            self.dispatchTo(self.unknown_telegram_command_handlers, update)
+
+    def dispatchRegex(self, update):
+        """
+        Dispatches an update to all string or telegram regex handlers that
+        match the string/message content.
+
+        Args:
+            update (str, Update): The update that should be checked for matches
+        """
+
+        if isinstance(update, Update):
+            handlers = self.telegram_regex_handlers
+            to_match = update.message.text
+        elif isinstance(update, str):
+            handlers = self.string_regex_handlers
+            to_match = update
+
+        for matcher in handlers:
+            m = match(matcher, to_match)
+            if m:
+                for handler in handlers[matcher]:
+                    self.call_handler(handler,
+                                      update,
+                                      groups=m.groups(),
+                                      groupdict=m.groupdict())
+
+    def dispatchStringCommand(self, update):
+        """
+        Dispatches a string-update that contains a command.
+
+        Args:
+            update (str): The string input
+        """
+
+        command = update.split(' ')[0][1:]
+
+        if command in self.string_command_handlers:
+            self.dispatchTo(self.string_command_handlers[command], update)
+        else:
+            self.dispatchTo(self.unknown_string_command_handlers, update)
+
+    def dispatchType(self, update):
+        """
+        Dispatches an update of any type.
+
+        Args:
+            update (any): The update
+        """
+
+        for t in self.type_handlers:
+            if isinstance(update, t):
+                self.dispatchTo(self.type_handlers[t], update)
+
+    def dispatchTelegramMessage(self, update):
+        """
+        Dispatches an update that contains a regular message.
+
+        Args:
+            update (telegram.Update): The Telegram update that contains the
+                message.
+        """
+
+        self.dispatchTo(self.telegram_message_handlers, update)
+
+    def dispatchError(self, update, error):
+        """
+        Dispatches an error.
+
+        Args:
+            update (any): The pdate that caused the error
+            error (telegram.TelegramError): The Telegram error that was raised.
+        """
+
+        for handler in self.error_handlers:
+            handler(self.bot, update, error)
+
+    def dispatchTo(self, handlers, update, **kwargs):
+        """
+        Dispatches an update to a list of handlers.
+
+        Args:
+            handlers (list): A list of handler-functions.
+            update (any): The update to be dispatched
+        """
+
+        for handler in handlers:
+            self.call_handler(handler, update, **kwargs)
+
+    def call_handler(self, handler, update, **kwargs):
+        """
+        Calls an update handler. Checks the handler for keyword arguments and
+        fills them, if possible.
+
+        Args:
+            handler (function): An update handler function
+            update (any): An update
+        """
+
+        target_kwargs = {}
+        fargs = getargspec(handler).args
+
+        '''
+        async handlers will receive all optional arguments, since we can't
+        their argument list.
+        '''
+
+        is_async = 'pargs' == getargspec(handler).varargs
+
+        if is_async or 'update_queue' in fargs:
+            target_kwargs['update_queue'] = self.update_queue
+
+        if is_async or 'args' in fargs:
+            if isinstance(update, Update):
+                args = update.message.text.split(' ')[1:]
+            elif isinstance(update, str):
+                args = update.split(' ')[1:]
+            else:
+                args = None
+
+            target_kwargs['args'] = args
+
+        if is_async or 'groups' in fargs:
+            target_kwargs['groups'] = kwargs.get('groups', None)
+
+        if is_async or 'groupdict' in fargs:
+            target_kwargs['groupdict'] = kwargs.get('groupdict', None)
+
+        handler(self.bot, update, **target_kwargs)

telegram/document.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,45 +17,55 @@
 # 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 Document"""
 
-from telegram import TelegramObject
+from telegram import PhotoSize, TelegramObject
 
 
 class Document(TelegramObject):
+    """This object represents a Telegram Document.
+
+    Attributes:
+        file_id (str):
+        thumb (:class:`telegram.PhotoSize`):
+        file_name (str):
+        mime_type (str):
+        file_size (int):
+
+    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]):
+    """
+
     def __init__(self,
                  file_id,
-                 thumb=None,
-                 file_name=None,
-                 mime_type=None,
-                 file_size=None):
-        self.file_id = file_id
-        self.thumb = thumb
-        self.file_name = file_name
-        self.mime_type = mime_type
-        self.file_size = file_size
+                 **kwargs):
+        # Required
+        self.file_id = str(file_id)
+        # Optionals
+        self.thumb = kwargs.get('thumb')
+        self.file_name = kwargs.get('file_name', '')
+        self.mime_type = str(kwargs.get('mime_type', ''))
+        self.file_size = int(kwargs.get('file_size', 0))
 
     @staticmethod
     def de_json(data):
-        if 'thumb' in data:
-            from telegram import PhotoSize
-            thumb = PhotoSize.de_json(data['thumb'])
-        else:
-            thumb = None
+        """
+        Args:
+            data (str):
 
-        return Document(file_id=data.get('file_id', None),
-                        thumb=thumb,
-                        file_name=data.get('file_name', None),
-                        mime_type=data.get('mime_type', None),
-                        file_size=data.get('file_size', None))
+        Returns:
+            telegram.Document:
+        """
+        if not data:
+            return None
 
-    def to_dict(self):
-        data = {'file_id': self.file_id}
-        if self.thumb:
-            data['thumb'] = self.thumb.to_dict()
-        if self.file_name:
-            data['file_name'] = self.file_name
-        if self.mime_type:
-            data['mime_type'] = self.mime_type
-        if self.file_size:
-            data['file_size'] = self.file_size
-        return data
+        data['thumb'] = PhotoSize.de_json(data.get('thumb'))
+
+        return Document(**data)

telegram/error.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,11 +17,45 @@
 # 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 Error"""
+
+
+def _lstrip_str(in_s, lstr):
+    """
+    Args:
+        in_s (str): in string
+        lstr (str): substr to strip from left side
+
+    Returns:
+        str:
+
+    """
+    if in_s.startswith(lstr):
+        res = in_s[len(lstr):]
+    else:
+        res = in_s
+    return res
+
 
 class TelegramError(Exception):
-    """Base class for Telegram errors."""
+    """This object represents a Telegram Error."""
 
-    @property
-    def message(self):
-        '''Returns the first argument used to construct this error.'''
-        return self.args[0]
+    def __init__(self, message):
+        """
+        Args:
+            message (str):
+
+        Returns:
+
+        """
+        super(TelegramError, self).__init__()
+
+        msg = _lstrip_str(message, 'Error: ')
+        msg = _lstrip_str(msg, '[Error]: ')
+        if msg != message:
+            # api_error - capitalize the msg...
+            msg = msg.capitalize()
+        self.message = msg
+
+    def __str__(self):
+        return '%s' % (self.message)

telegram/file.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 = custom_path
+        else:
+            filename = basename(url)
+
+        _download(url, filename)

telegram/forcereply.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,24 +17,44 @@
 # 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 ForceReply"""
 
 from telegram import ReplyMarkup
 
 
 class ForceReply(ReplyMarkup):
+    """This object represents a Telegram ForceReply.
+
+    Attributes:
+        force_reply (bool):
+        selective (bool):
+
+    Args:
+        force_reply (bool):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        selective (Optional[bool]):
+    """
+
     def __init__(self,
                  force_reply=True,
-                 selective=None):
-        self.force_reply = force_reply
-        self.selective = selective
+                 **kwargs):
+        # Required
+        self.force_reply = bool(force_reply)
+        # Optionals
+        self.selective = bool(kwargs.get('selective', False))
 
     @staticmethod
     def de_json(data):
-        return ForceReply(force_reply=data.get('force_reply', None),
-                          selective=data.get('selective', None))
+        """
+        Args:
+            data (str):
 
-    def to_dict(self):
-        data = {'force_reply': self.force_reply}
-        if self.selective:
-            data['selective'] = self.selective
-        return data
+        Returns:
+            telegram.ForceReply:
+        """
+        if not data:
+            return None
+
+        return ForceReply(**data)

telegram/groupchat.py

@@ -1,38 +0,0 @@
-#!/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/].
-
-
-from telegram import TelegramObject
-
-
-class GroupChat(TelegramObject):
-    def __init__(self,
-                 id,
-                 title):
-        self.id = id
-        self.title = title
-
-    @staticmethod
-    def de_json(data):
-        return GroupChat(id=data.get('id', None),
-                         title=data.get('title', None))
-
-    def to_dict(self):
-        data = {'id': self.id,
-                'title': self.title}
-        return data

telegram/inputfile.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python
+# pylint: disable=W0622,E0611
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,6 +18,7 @@
 # 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 InputFile"""
 
 try:
     from email.generator import _make_boundary as choose_boundary
@@ -29,14 +32,16 @@ import os
 import sys
 import imghdr
 
-from .error import TelegramError
+from telegram import TelegramError
 
 DEFAULT_MIME_TYPE = 'application/octet-stream'
 USER_AGENT = 'Python Telegram Bot' \
-             ' (https://github.com/leandrotoledo/python-telegram-bot)'
+             ' (https://github.com/python-telegram-bot/python-telegram-bot)'
 
 
 class InputFile(object):
+    """This object represents a Telegram InputFile."""
+
     def __init__(self,
                  data):
         self.data = data
@@ -51,16 +56,25 @@ class InputFile(object):
         if 'photo' in data:
             self.input_name = 'photo'
             self.input_file = data.pop('photo')
+        if 'sticker' in data:
+            self.input_name = 'sticker'
+            self.input_file = data.pop('sticker')
         if 'video' in data:
             self.input_name = 'video'
             self.input_file = data.pop('video')
         if 'voice' in data:
             self.input_name = 'voice'
             self.input_file = data.pop('voice')
+        if 'certificate' in data:
+            self.input_name = 'certificate'
+            self.input_file = data.pop('certificate')
 
         if isinstance(self.input_file, file):
             self.input_file_content = self.input_file.read()
-            self.filename = os.path.basename(self.input_file.name)
+            if 'filename' in data:
+                self.filename = self.data.pop('filename')
+            else:
+                self.filename = os.path.basename(self.input_file.name)
             self.mimetype = mimetypes.guess_type(self.filename)[0] or \
                 DEFAULT_MIME_TYPE
 
@@ -71,14 +85,26 @@ class InputFile(object):
 
     @property
     def headers(self):
+        """
+        Returns:
+            str:
+        """
         return {'User-agent': USER_AGENT,
                 'Content-type': self.content_type}
 
     @property
     def content_type(self):
+        """
+        Returns:
+            str:
+        """
         return 'multipart/form-data; boundary=%s' % self.boundary
 
     def to_form(self):
+        """
+        Returns:
+            str:
+        """
         form = []
         form_boundary = '--' + self.boundary
 
@@ -105,9 +131,14 @@ class InputFile(object):
         form.append('--' + self.boundary + '--')
         form.append('')
 
-        return self._parse(form)
+        return InputFile._parse(form)
 
-    def _parse(self, form):
+    @staticmethod
+    def _parse(form):
+        """
+        Returns:
+            str:
+        """
         if sys.version_info > (3,):
             # on Python 3 form needs to be byte encoded
             encoded_form = []
@@ -125,31 +156,30 @@ class InputFile(object):
         """Check if the content file is an image by analyzing its headers.
 
         Args:
-          stream:
-            A str representing the content of a file.
+            stream (str): A str representing the content of a file.
 
         Returns:
-          The str mimetype of an image.
+            str: The str mimetype of an image.
         """
         image = imghdr.what(None, stream)
         if image:
             return 'image/%s' % image
 
-        raise TelegramError({'message': 'Could not parse file content'})
+        raise TelegramError('Could not parse file content')
 
     @staticmethod
     def is_inputfile(data):
         """Check if the request is a file request.
 
         Args:
-          data:
-            A dict of (str, unicode) key/value pairs
+            data (str): A dict of (str, unicode) key/value pairs
 
         Returns:
             bool
         """
         if data:
-            file_types = ['audio', 'document', 'photo', 'video', 'voice']
+            file_types = ['audio', 'document', 'photo', 'sticker', 'video',
+                          'voice', 'certificate']
             file_type = [i for i in list(data.keys()) if i in file_types]
 
             if file_type:

telegram/jobqueue.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 the class JobQueue
+"""
+
+import logging
+import time
+from threading import Thread, Lock
+
+try:
+    from queue import PriorityQueue
+except ImportError:
+    from Queue import PriorityQueue
+
+
+class JobQueue(object):
+    """
+    This class allows you to periodically perform tasks with the bot.
+
+    Attributes:
+        tick_interval (float):
+        queue (PriorityQueue):
+        bot (Bot):
+        running (bool):
+
+    Args:
+        bot (Bot): The bot instance that should be passed to the jobs
+
+    Keyword Args:
+        tick_interval (Optional[float]): The interval this queue should check
+            the newest task in seconds. Defaults to 1.0
+    """
+
+    def __init__(self, bot, tick_interval=1.0):
+        self.tick_interval = tick_interval
+        self.queue = PriorityQueue()
+        self.bot = bot
+        self.logger = logging.getLogger(__name__)
+        self.__lock = Lock()
+        self.running = False
+
+    def put(self,
+            run,
+            interval,
+            repeat=True,
+            next_t=None,
+            prevent_autostart=False):
+        """
+        Queue a new job. If the JobQueue is not running, it will be started.
+
+        Args:
+            run (function): A function that takes the parameter `bot`
+            interval (float): The interval in seconds in which `run` should be
+                executed
+            repeat (Optional[bool]): If `False`, job will only be executed once
+            next_t (Optional[float]): Time in seconds in which run should be
+                executed first. Defaults to `interval`
+            prevent_autostart (Optional[bool]): If `True`, the job queue will
+                not be started automatically if it is not running.
+        """
+        name = run.__name__
+
+        job = JobQueue.Job()
+        job.run = run
+        job.interval = interval
+        job.name = name
+        job.repeat = repeat
+
+        if next_t is None:
+            next_t = interval
+
+        next_t += time.time()
+
+        self.logger.debug("Putting a %s with t=%f" % (job.name, next_t))
+        self.queue.put((next_t, job))
+
+        if not self.running and not prevent_autostart:
+            self.logger.info("Auto-starting JobQueue")
+            self.start()
+
+    def tick(self):
+        """
+        Run all jobs that are due and re-enqueue them with their interval
+        """
+        now = time.time()
+
+        self.logger.debug("Ticking jobs with t=%f" % now)
+        while not self.queue.empty():
+            t, j = self.queue.queue[0]
+            self.logger.debug("Peeked at %s with t=%f" % (j.name, t))
+
+            if t < now:
+                self.queue.get()
+                self.logger.info("Running job %s" % j.name)
+                try:
+                    j.run(self.bot)
+                except:
+                    self.logger.exception("An uncaught error was raised while "
+                                          "executing job %s" % j.name)
+                if j.repeat:
+                    self.put(j.run, j.interval)
+                continue
+
+            self.logger.debug("Next task isn't due yet. Finished!")
+            break
+
+    def start(self):
+        """
+        Starts the job_queue thread.
+        """
+        self.__lock.acquire()
+        if not self.running:
+            self.running = True
+            self.__lock.release()
+            job_queue_thread = Thread(target=self._start,
+                                      name="job_queue")
+            job_queue_thread.start()
+            self.logger.info('Job Queue thread started')
+        else:
+            self.__lock.release()
+
+    def _start(self):
+        """
+        Thread target of thread 'job_queue'. Runs in background and performs
+        ticks on the job queue.
+        """
+        while self.running:
+            self.tick()
+            time.sleep(self.tick_interval)
+
+        self.logger.info('Job Queue thread stopped')
+
+    def stop(self):
+        """
+        Stops the thread
+        """
+        with self.__lock:
+            self.running = False
+
+    class Job(object):
+        """ Inner class that represents a job """
+        interval = None
+        name = None
+        repeat = None
+
+        def run(self):
+            pass
+
+        def __lt__(self, other):
+            return False

telegram/location.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,23 +17,40 @@
 # 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 Location"""
 
 from telegram import TelegramObject
 
 
 class Location(TelegramObject):
+    """This object represents a Telegram Sticker.
+
+    Attributes:
+        longitude (float):
+        latitude (float):
+
+    Args:
+        longitude (float):
+        latitude (float):
+    """
+
     def __init__(self,
                  longitude,
                  latitude):
-        self.longitude = longitude
-        self.latitude = latitude
+        # Required
+        self.longitude = float(longitude)
+        self.latitude = float(latitude)
 
     @staticmethod
     def de_json(data):
-        return Location(longitude=data.get('longitude', None),
-                        latitude=data.get('latitude', None))
+        """
+        Args:
+            data (str):
 
-    def to_dict(self):
-        data = {'longitude': self.longitude,
-                'latitude': self.latitude}
-        return data
+        Returns:
+            telegram.Location:
+        """
+        if not data:
+            return None
+
+        return Location(**data)

telegram/message.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python
+# pylint: disable=R0902,R0912,R0913
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,243 +18,218 @@
 # 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 Message"""
 
-from telegram import TelegramObject
 from datetime import datetime
 from time import mktime
 
+from telegram import (Audio, Contact, Document, Chat, Location, PhotoSize,
+                      Sticker, TelegramObject, User, Video, Voice)
+
 
 class Message(TelegramObject):
+    """This object represents a Telegram Message.
+
+    Note:
+        * In Python `from` is a reserved word, use `from_user` instead.
+
+    Attributes:
+        message_id (int):
+        from_user (:class:`telegram.User`):
+        date (:class:`datetime.datetime`):
+        forward_from (:class:`telegram.User`):
+        forward_date (:class:`datetime.datetime`):
+        reply_to_message (:class:`telegram.Message`):
+        text (str):
+        audio (:class:`telegram.Audio`):
+        document (:class:`telegram.Document`):
+        photo (List[:class:`telegram.PhotoSize`]):
+        sticker (:class:`telegram.Sticker`):
+        video (:class:`telegram.Video`):
+        voice (:class:`telegram.Voice`):
+        caption (str):
+        contact (:class:`telegram.Contact`):
+        location (:class:`telegram.Location`):
+        new_chat_participant (:class:`telegram.User`):
+        left_chat_participant (:class:`telegram.User`):
+        new_chat_title (str):
+        new_chat_photo (List[:class:`telegram.PhotoSize`]):
+        delete_chat_photo (bool):
+        group_chat_created (bool):
+
+    Args:
+        message_id (int):
+        from_user (:class:`telegram.User`):
+        date (:class:`datetime.datetime`):
+        chat (:class:`telegram.Chat`):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        forward_from (Optional[:class:`telegram.User`]):
+        forward_date (Optional[:class:`datetime.datetime`]):
+        reply_to_message (Optional[:class:`telegram.Message`]):
+        text (Optional[str]):
+        audio (Optional[:class:`telegram.Audio`]):
+        document (Optional[:class:`telegram.Document`]):
+        photo (Optional[List[:class:`telegram.PhotoSize`]]):
+        sticker (Optional[:class:`telegram.Sticker`]):
+        video (Optional[:class:`telegram.Video`]):
+        voice (Optional[:class:`telegram.Voice`]):
+        caption (Optional[str]):
+        contact (Optional[:class:`telegram.Contact`]):
+        location (Optional[:class:`telegram.Location`]):
+        new_chat_participant (Optional[:class:`telegram.User`]):
+        left_chat_participant (Optional[:class:`telegram.User`]):
+        new_chat_title (Optional[str]):
+        new_chat_photo (Optional[List[:class:`telegram.PhotoSize`]):
+        delete_chat_photo (Optional[bool]):
+        group_chat_created (Optional[bool]):
+    """
+
     def __init__(self,
                  message_id,
                  from_user,
                  date,
                  chat,
-                 forward_from=None,
-                 forward_date=None,
-                 reply_to_message=None,
-                 text=None,
-                 audio=None,
-                 document=None,
-                 photo=None,
-                 sticker=None,
-                 video=None,
-                 voice=None,
-                 caption=None,
-                 contact=None,
-                 location=None,
-                 new_chat_participant=None,
-                 left_chat_participant=None,
-                 new_chat_title=None,
-                 new_chat_photo=None,
-                 delete_chat_photo=None,
-                 group_chat_created=None):
-        self.message_id = message_id
+                 **kwargs):
+        # Required
+        self.message_id = int(message_id)
         self.from_user = from_user
         self.date = date
         self.chat = chat
-        self.forward_from = forward_from
-        self.forward_date = forward_date
-        self.reply_to_message = reply_to_message
-        self.text = text
-        self.audio = audio
-        self.document = document
-        self.photo = photo
-        self.sticker = sticker
-        self.video = video
-        self.voice = voice
-        self.caption = caption
-        self.contact = contact
-        self.location = location
-        self.new_chat_participant = new_chat_participant
-        self.left_chat_participant = left_chat_participant
-        self.new_chat_title = new_chat_title
-        self.new_chat_photo = new_chat_photo
-        self.delete_chat_photo = delete_chat_photo
-        self.group_chat_created = group_chat_created
+        # Optionals
+        self.forward_from = kwargs.get('forward_from')
+        self.forward_date = kwargs.get('forward_date')
+        self.reply_to_message = kwargs.get('reply_to_message')
+        self.text = kwargs.get('text', '')
+        self.audio = kwargs.get('audio')
+        self.document = kwargs.get('document')
+        self.photo = kwargs.get('photo')
+        self.sticker = kwargs.get('sticker')
+        self.video = kwargs.get('video')
+        self.voice = kwargs.get('voice')
+        self.caption = kwargs.get('caption', '')
+        self.contact = kwargs.get('contact')
+        self.location = kwargs.get('location')
+        self.new_chat_participant = kwargs.get('new_chat_participant')
+        self.left_chat_participant = kwargs.get('left_chat_participant')
+        self.new_chat_title = kwargs.get('new_chat_title', '')
+        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):
+        """int: Short for :attr:`Message.chat.id`"""
         return self.chat.id
 
     @staticmethod
     def de_json(data):
-        if 'from' in data:  # from is a reserved word, use from_user instead.
-            from telegram import User
-            from_user = User.de_json(data['from'])
-        else:
-            from_user = None
+        """
+        Args:
+            data (dict):
 
-        if 'date' in data:
-            date = datetime.fromtimestamp(data['date'])
-        else:
-            date = None
+        Returns:
+            telegram.Message:
+        """
+        if not data:
+            return None
 
-        if 'chat' in data:
-            if 'first_name' in data['chat']:
-                from telegram import User
-                chat = User.de_json(data['chat'])
-            if 'title' in data['chat']:
-                from telegram import GroupChat
-                chat = GroupChat.de_json(data['chat'])
-        else:
-            chat = None
+        data['from_user'] = User.de_json(data.get('from'))
+        data['date'] = datetime.fromtimestamp(data['date'])
+        data['chat'] = Chat.de_json(data.get('chat'))
+        data['forward_from'] = \
+            User.de_json(data.get('forward_from'))
+        data['forward_date'] = \
+            Message._fromtimestamp(data.get('forward_date'))
+        data['reply_to_message'] = \
+            Message.de_json(data.get('reply_to_message'))
+        data['audio'] = \
+            Audio.de_json(data.get('audio'))
+        data['document'] = \
+            Document.de_json(data.get('document'))
+        data['photo'] = \
+            PhotoSize.de_list(data.get('photo'))
+        data['sticker'] = \
+            Sticker.de_json(data.get('sticker'))
+        data['video'] = \
+            Video.de_json(data.get('video'))
+        data['voice'] = \
+            Voice.de_json(data.get('voice'))
+        data['contact'] = \
+            Contact.de_json(data.get('contact'))
+        data['location'] = \
+            Location.de_json(data.get('location'))
+        data['new_chat_participant'] = \
+            User.de_json(data.get('new_chat_participant'))
+        data['left_chat_participant'] = \
+            User.de_json(data.get('left_chat_participant'))
+        data['new_chat_photo'] = \
+            PhotoSize.de_list(data.get('new_chat_photo'))
 
-        if 'forward_from' in data:
-            from telegram import User
-            forward_from = User.de_json(data['forward_from'])
-        else:
-            forward_from = None
+        return Message(**data)
 
-        if 'forward_date' in data:
-            forward_date = datetime.fromtimestamp(data['forward_date'])
-        else:
-            forward_date = None
-
-        if 'reply_to_message' in data:
-            reply_to_message = Message.de_json(data['reply_to_message'])
-        else:
-            reply_to_message = None
-
-        if 'audio' in data:
-            from telegram import Audio
-            audio = Audio.de_json(data['audio'])
-        else:
-            audio = None
-
-        if 'document' in data:
-            from telegram import Document
-            document = Document.de_json(data['document'])
-        else:
-            document = None
-
-        if 'photo' in data:
-            from telegram import PhotoSize
-            photo = [PhotoSize.de_json(x) for x in data['photo']]
-        else:
-            photo = None
-
-        if 'sticker' in data:
-            from telegram import Sticker
-            sticker = Sticker.de_json(data['sticker'])
-        else:
-            sticker = None
-
-        if 'video' in data:
-            from telegram import Video
-            video = Video.de_json(data['video'])
-        else:
-            video = None
-
-        if 'voice' in data:
-            from telegram import Voice
-            voice = Voice.de_json(data['voice'])
-        else:
-            voice = None
-
-        if 'contact' in data:
-            from telegram import Contact
-            contact = Contact.de_json(data['contact'])
-        else:
-            contact = None
-
-        if 'location' in data:
-            from telegram import Location
-            location = Location.de_json(data['location'])
-        else:
-            location = None
-
-        if 'new_chat_participant' in data:
-            from telegram import User
-            new_chat_participant = User.de_json(data['new_chat_participant'])
-        else:
-            new_chat_participant = None
-
-        if 'left_chat_participant' in data:
-            from telegram import User
-            left_chat_participant = User.de_json(data['left_chat_participant'])
-        else:
-            left_chat_participant = None
-
-        return Message(message_id=data.get('message_id', None),
-                       from_user=from_user,
-                       date=date,
-                       chat=chat,
-                       forward_from=forward_from,
-                       forward_date=forward_date,
-                       reply_to_message=reply_to_message,
-                       text=data.get('text', ''),
-                       audio=audio,
-                       document=document,
-                       photo=photo,
-                       sticker=sticker,
-                       video=video,
-                       voice=voice,
-                       caption=data.get('caption', ''),
-                       contact=contact,
-                       location=location,
-                       new_chat_participant=new_chat_participant,
-                       left_chat_participant=left_chat_participant,
-                       new_chat_title=data.get('new_chat_title', None),
-                       new_chat_photo=data.get('new_chat_photo', None),
-                       delete_chat_photo=data.get('delete_chat_photo', None),
-                       group_chat_created=data.get('group_chat_created', None))
+    def __getitem__(self, item):
+        if item in self.__dict__.keys():
+            return self.__dict__[item]
+        elif item == 'chat_id':
+            return self.chat.id
 
     def to_dict(self):
-        data = {'message_id': self.message_id,
-                'from': self.from_user.to_dict(),
-                'chat': self.chat.to_dict()}
-        try:
-            # Python 3.3+ supports .timestamp()
-            data['date'] = int(self.date.timestamp())
+        """
+        Returns:
+            dict:
+        """
+        data = super(Message, self).to_dict()
 
-            if self.forward_date:
-                data['forward_date'] = int(self.forward_date.timestamp())
-        except AttributeError:
-            # _totimestamp() for Python 3 (< 3.3) and Python 2
-            data['date'] = self._totimestamp(self.date)
-
-            if self.forward_date:
-                data['forward_date'] = self._totimestamp(self.forward_date)
-
-        if self.forward_from:
-            data['forward_from'] = self.forward_from.to_dict()
-        if self.reply_to_message:
-            data['reply_to_message'] = self.reply_to_message
-        if self.text:
-            data['text'] = self.text
-        if self.audio:
-            data['audio'] = self.audio.to_dict()
-        if self.document:
-            data['document'] = self.document.to_dict()
+        # Required
+        data['from'] = data.pop('from_user', None)
+        data['date'] = self._totimestamp(self.date)
+        # Optionals
+        if self.forward_date:
+            data['forward_date'] = self._totimestamp(self.forward_date)
         if self.photo:
             data['photo'] = [p.to_dict() for p in self.photo]
-        if self.sticker:
-            data['sticker'] = self.sticker.to_dict()
-        if self.video:
-            data['video'] = self.video.to_dict()
-        if self.voice:
-            data['voice'] = self.voice.to_dict()
-        if self.caption:
-            data['caption'] = self.caption
-        if self.contact:
-            data['contact'] = self.contact.to_dict()
-        if self.location:
-            data['location'] = self.location.to_dict()
-        if self.new_chat_participant:
-            data['new_chat_participant'] = self.new_chat_participant
-        if self.left_chat_participant:
-            data['left_chat_participant'] = self.left_chat_participant
-        if self.new_chat_title:
-            data['new_chat_title'] = self.new_chat_title
         if self.new_chat_photo:
-            data['new_chat_photo'] = self.new_chat_photo
-        if self.delete_chat_photo:
-            data['delete_chat_photo'] = self.delete_chat_photo
-        if self.group_chat_created:
-            data['group_chat_created'] = self.group_chat_created
+            data['new_chat_photo'] = [p.to_dict() for p in self.new_chat_photo]
+
         return data
 
     @staticmethod
-    def _totimestamp(dt):
-        return int(mktime(dt.timetuple()))
+    def _fromtimestamp(unixtime):
+        """
+        Args:
+            unixtime (int):
+
+        Returns:
+            datetime.datetime:
+        """
+        if not unixtime:
+            return None
+
+        return datetime.fromtimestamp(unixtime)
+
+    @staticmethod
+    def _totimestamp(dt_obj):
+        """
+        Args:
+            dt_obj (:class:`datetime.datetime`):
+
+        Returns:
+            int:
+        """
+        if not dt_obj:
+            return None
+
+        try:
+            # Python 3.3+
+            return int(dt_obj.timestamp())
+        except AttributeError:
+            # Python 3 (< 3.3) and Python 2
+            return int(mktime(dt_obj.timetuple()))

telegram/nullhandler.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,10 +17,17 @@
 # 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 logging NullHandler"""
 
 import logging
 
 
 class NullHandler(logging.Handler):
+    """This object represents a logging NullHandler."""
+
     def emit(self, record):
+        """
+        Args:
+            record (str):
+        """
         pass

telegram/parsemode.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python
+# pylint: disable=R0903
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,15 +18,11 @@
 # 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
+Message Parse Modes"""
 
-import logging
-import unittest
-from tests.test_bot import BotTest
 
-if __name__ == '__main__':
-    logging.basicConfig(
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-    logger = logging.getLogger()
-    logger.setLevel(logging.DEBUG)
-    testsuite = unittest.TestLoader().loadTestsFromTestCase(BotTest)
-    unittest.TextTestRunner(verbosity=1).run(testsuite)
+class ParseMode(object):
+    """This object represents a Telegram Message Parse Modes."""
+
+    MARKDOWN = 'Markdown'

telegram/photosize.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,32 +17,70 @@
 # 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 PhotoSize"""
 
 from telegram import TelegramObject
 
 
 class PhotoSize(TelegramObject):
+    """This object represents a Telegram PhotoSize.
+
+    Attributes:
+        file_id (str):
+        width (int):
+        height (int):
+        file_size (int):
+
+    Args:
+        file_id (str):
+        width (int):
+        height (int):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        file_size (Optional[int]):
+    """
+
     def __init__(self,
                  file_id,
                  width,
                  height,
-                 file_size=None):
+                 **kwargs):
+        # Required
         self.file_id = file_id
-        self.width = width
-        self.height = height
-        self.file_size = file_size
+        self.width = int(width)
+        self.height = int(height)
+        # Optionals
+        self.file_size = int(kwargs.get('file_size', 0))
 
     @staticmethod
     def de_json(data):
-        return PhotoSize(file_id=data.get('file_id', None),
-                         width=data.get('width', None),
-                         height=data.get('height', None),
-                         file_size=data.get('file_size', None))
+        """
+        Args:
+            data (str):
 
-    def to_dict(self):
-        data = {'file_id': self.file_id,
-                'width': self.width,
-                'height': self.height}
-        if self.file_size:
-            data['file_size'] = self.file_size
-        return data
+        Returns:
+            telegram.PhotoSize:
+        """
+        if not data:
+            return None
+
+        return PhotoSize(**data)
+
+    @staticmethod
+    def de_list(data):
+        """
+        Args:
+            data (list):
+
+        Returns:
+            List<telegram.PhotoSize>:
+        """
+        if not data:
+            return []
+
+        photos = list()
+        for photo in data:
+            photos.append(PhotoSize.de_json(photo))
+
+        return photos

telegram/replykeyboardhide.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,24 +17,45 @@
 # 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
+ReplyKeyboardHide"""
 
 from telegram import ReplyMarkup
 
 
 class ReplyKeyboardHide(ReplyMarkup):
+    """This object represents a Telegram ReplyKeyboardHide.
+
+    Attributes:
+        hide_keyboard (bool):
+        selective (bool):
+
+    Args:
+        hide_keyboard (bool):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        selective (Optional[bool]):
+    """
+
     def __init__(self,
                  hide_keyboard=True,
-                 selective=None):
-        self.hide_keyboard = hide_keyboard
-        self.selective = selective
+                 **kwargs):
+        # Required
+        self.hide_keyboard = bool(hide_keyboard)
+        # Optionals
+        self.selective = bool(kwargs.get('selective', False))
 
     @staticmethod
     def de_json(data):
-        return ReplyKeyboardHide(hide_keyboard=data.get('hide_keyboard', None),
-                                 selective=data.get('selective', None))
+        """
+        Args:
+            data (str):
 
-    def to_dict(self):
-        data = {'hide_keyboard': self.hide_keyboard}
-        if self.selective:
-            data['selective'] = self.selective
-        return data
+        Returns:
+            telegram.ReplyKeyboardHide:
+        """
+        if not data:
+            return None
+
+        return ReplyKeyboardHide(**data)

telegram/replykeyboardmarkup.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,38 +17,51 @@
 # 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
+ReplyKeyboardMarkup"""
 
 from telegram import ReplyMarkup
 
 
 class ReplyKeyboardMarkup(ReplyMarkup):
+    """This object represents a Telegram ReplyKeyboardMarkup.
+
+    Attributes:
+        keyboard (List[List[str]]):
+        resize_keyboard (bool):
+        one_time_keyboard (bool):
+        selective (bool):
+
+    Args:
+        keyboard (List[List[str]]):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        resize_keyboard (Optional[bool]):
+        one_time_keyboard (Optional[bool]):
+        selective (Optional[bool]):
+    """
+
     def __init__(self,
                  keyboard,
-                 resize_keyboard=None,
-                 one_time_keyboard=None,
-                 selective=None):
+                 **kwargs):
+        # Required
         self.keyboard = keyboard
-        self.resize_keyboard = resize_keyboard
-        self.one_time_keyboard = one_time_keyboard
-        self.selective = selective
+        # Optionals
+        self.resize_keyboard = bool(kwargs.get('resize_keyboard', False))
+        self.one_time_keyboard = bool(kwargs.get('one_time_keyboard', False))
+        self.selective = bool(kwargs.get('selective', False))
 
     @staticmethod
     def de_json(data):
-        return ReplyKeyboardMarkup(keyboard=data.get('keyboard', None),
-                                   resize_keyboard=data.get(
-                                       'resize_keyboard', None
-                                       ),
-                                   one_time_keyboard=data.get(
-                                       'one_time_keyboard', None
-                                       ),
-                                   selective=data.get('selective', None))
+        """
+        Args:
+            data (str):
 
-    def to_dict(self):
-        data = {'keyboard': self.keyboard}
-        if self.resize_keyboard:
-            data['resize_keyboard'] = self.resize_keyboard
-        if self.one_time_keyboard:
-            data['one_time_keyboard'] = self.one_time_keyboard
-        if self.selective:
-            data['selective'] = self.selective
-        return data
+        Returns:
+            telegram.ReplyKeyboardMarkup:
+        """
+        if not data:
+            return None
+
+        return ReplyKeyboardMarkup(**data)

telegram/replymarkup.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,9 +17,14 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 
+"""Base class for Telegram ReplyMarkup Objects"""
 
 from telegram import TelegramObject
 
 
 class ReplyMarkup(TelegramObject):
-    pass
+    """Base class for Telegram ReplyMarkup Objects"""
+
+    @staticmethod
+    def de_json(data):
+        pass

telegram/sticker.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,42 +17,57 @@
 # 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 Sticker"""
 
-from telegram import TelegramObject
+from telegram import PhotoSize, TelegramObject
 
 
 class Sticker(TelegramObject):
+    """This object represents a Telegram Sticker.
+
+    Attributes:
+        file_id (str):
+        width (int):
+        height (int):
+        thumb (:class:`telegram.PhotoSize`):
+        file_size (int):
+
+    Args:
+        file_id (str):
+        width (int):
+        height (int):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        thumb (Optional[:class:`telegram.PhotoSize`]):
+        file_size (Optional[int]):
+    """
+
     def __init__(self,
                  file_id,
                  width,
                  height,
-                 thumb=None,
-                 file_size=None):
-        self.file_id = file_id
-        self.width = width
-        self.height = height
-        self.thumb = thumb
-        self.file_size = file_size
+                 **kwargs):
+        # Required
+        self.file_id = str(file_id)
+        self.width = int(width)
+        self.height = int(height)
+        # Optionals
+        self.thumb = kwargs.get('thumb')
+        self.file_size = int(kwargs.get('file_size', 0))
 
     @staticmethod
     def de_json(data):
-        if 'thumb' in data:
-            from telegram import PhotoSize
-            thumb = PhotoSize.de_json(data['thumb'])
-        else:
-            thumb = None
+        """
+        Args:
+            data (str):
 
-        return Sticker(file_id=data.get('file_id', None),
-                       width=data.get('width', None),
-                       height=data.get('height', None),
-                       thumb=thumb,
-                       file_size=data.get('file_size', None))
+        Returns:
+            telegram.Sticker:
+        """
+        if not data:
+            return None
 
-    def to_dict(self):
-        data = {'file_id': self.file_id,
-                'width': self.width,
-                'height': self.height,
-                'thumb': self.thumb.to_dict()}
-        if self.file_size:
-            data['file_size'] = self.file_size
-        return data
+        data['thumb'] = PhotoSize.de_json(data.get('thumb'))
+
+        return Sticker(**data)

telegram/update.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,30 +17,45 @@
 # 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 Update"""
 
-from telegram import TelegramObject
+from telegram import Message, TelegramObject
 
 
 class Update(TelegramObject):
+    """This object represents a Telegram Update.
+
+    Attributes:
+        update_id (int):
+        message (:class:`telegram.Message`):
+
+    Args:
+        update_id (int):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        message (Optional[:class:`telegram.Message`]):
+    """
     def __init__(self,
                  update_id,
-                 message=None):
-        self.update_id = update_id
-        self.message = message
+                 **kwargs):
+        # Required
+        self.update_id = int(update_id)
+        # Optionals
+        self.message = kwargs.get('message')
 
     @staticmethod
     def de_json(data):
-        if 'message' in data:
-            from telegram import Message
-            message = Message.de_json(data['message'])
-        else:
-            message = None
+        """
+        Args:
+            data (str):
 
-        return Update(update_id=data.get('update_id', None),
-                      message=message)
+        Returns:
+            telegram.Update:
+        """
+        if not data:
+            return None
 
-    def to_dict(self):
-        data = {'update_id': self.update_id}
-        if self.message:
-            data['message'] = self.message.to_dict()
-        return data
+        data['message'] = Message.de_json(data['message'])
+
+        return Update(**data)

telegram/updater.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 the class Updater, which tries to make creating Telegram
+Bots intuitive!
+"""
+import logging
+import os
+import ssl
+from threading import Thread, Lock
+from time import sleep
+import subprocess
+from signal import signal, SIGINT, SIGTERM, SIGABRT
+from telegram import (Bot, TelegramError, dispatcher, Dispatcher,
+                      NullHandler, JobQueue)
+from telegram.utils.webhookhandler import (WebhookServer, WebhookHandler)
+
+# Adjust for differences in Python versions
+try:
+    from Queue import Queue
+except ImportError:
+    from queue import Queue
+
+try:
+    from urllib2 import URLError
+except ImportError:
+    from urllib.error import URLError
+
+H = NullHandler()
+logging.getLogger(__name__).addHandler(H)
+
+
+class Updater:
+    """
+    This class, which employs the Dispatcher class, provides a frontend to
+    telegram.Bot to the programmer, so they can focus on coding the bot. It's
+    purpose is to receive the updates from Telegram and to deliver them to said
+    dispatcher. It also runs in a separate thread, so the user can interact
+    with the bot, for example on the command line. The dispatcher supports
+    handlers for different kinds of data: Updates from Telegram, basic text
+    commands and even arbitrary types.
+    The updater can be started as a polling service or, for production, use a
+    webhook to receive updates. This is achieved using the WebhookServer and
+    WebhookHandler classes.
+
+
+    Attributes:
+
+    Args:
+        token (Optional[str]): The bot's token given by the @BotFather
+        base_url (Optional[str]):
+        workers (Optional[int]): Amount of threads in the thread pool for
+            functions decorated with @run_async
+        bot (Optional[Bot]):
+
+    Raises:
+        ValueError: If both `token` and `bot` are passed or none of them.
+    """
+
+    def __init__(self,
+                 token=None,
+                 base_url=None,
+                 workers=4,
+                 bot=None,
+                 job_queue_tick_interval=1.0):
+        if (token is None) and (bot is None):
+            raise ValueError('`token` or `bot` must be passed')
+        if (token is not None) and (bot is not None):
+            raise ValueError('`token` and `bot` are mutually exclusive')
+
+        if bot is not None:
+            self.bot = bot
+        else:
+            self.bot = Bot(token, base_url)
+        self.update_queue = Queue()
+        self.job_queue = JobQueue(self.bot, job_queue_tick_interval)
+        self.dispatcher = Dispatcher(self.bot, self.update_queue,
+                                     workers=workers)
+        self.last_update_id = 0
+        self.logger = logging.getLogger(__name__)
+        self.running = False
+        self.is_idle = False
+        self.httpd = None
+        self.__lock = Lock()
+
+    def start_polling(self, poll_interval=0.0, timeout=10, network_delay=2):
+        """
+        Starts polling updates from Telegram.
+
+        Args:
+            poll_interval (Optional[float]): Time to wait between polling
+                updates from Telegram in seconds. Default is 0.0
+            timeout (Optional[float]): Passed to Bot.getUpdates
+            network_delay (Optional[float]): Passed to Bot.getUpdates
+
+        Returns:
+            Queue: The update queue that can be filled from the main thread
+        """
+
+        with self.__lock:
+            if not self.running:
+                self.running = True
+
+                # Create Thread objects
+                dispatcher_thread = Thread(target=self.dispatcher.start,
+                                           name="dispatcher")
+                updater_thread = Thread(target=self._start_polling,
+                                        name="updater",
+                                        args=(poll_interval,
+                                              timeout,
+                                              network_delay))
+
+                # Start threads
+                dispatcher_thread.start()
+                updater_thread.start()
+
+                # Return the update queue so the main thread can insert updates
+                return self.update_queue
+
+    def start_webhook(self,
+                      listen='127.0.0.1',
+                      port=80,
+                      url_path='',
+                      cert=None,
+                      key=None):
+        """
+        Starts a small http server to listen for updates via webhook. If cert
+        and key are not provided, the webhook will be started directly on
+        http://listen:port/url_path, so SSL can be handled by another
+        application. Else, the webhook will be started on
+        https://listen:port/url_path
+
+        Args:
+            listen (Optional[str]): IP-Address to listen on
+            port (Optional[int]): Port the bot should be listening on
+            url_path (Optional[str]): Path inside url
+            cert (Optional[str]): Path to the SSL certificate file
+            key (Optional[str]): Path to the SSL key file
+
+        Returns:
+            Queue: The update queue that can be filled from the main thread
+        """
+
+        with self.__lock:
+            if not self.running:
+                self.running = True
+
+                # Create Thread objects
+                dispatcher_thread = Thread(target=self.dispatcher.start,
+                                           name="dispatcher")
+                updater_thread = Thread(target=self._start_webhook,
+                                        name="updater",
+                                        args=(listen,
+                                              port,
+                                              url_path,
+                                              cert,
+                                              key))
+
+                # Start threads
+                dispatcher_thread.start()
+                updater_thread.start()
+
+                # Return the update queue so the main thread can insert updates
+                return self.update_queue
+
+    def _start_polling(self, poll_interval, timeout, network_delay):
+        """
+        Thread target of thread 'updater'. Runs in background, pulls
+        updates from Telegram and inserts them in the update queue of the
+        Dispatcher.
+        """
+
+        current_interval = poll_interval
+        self.logger.info('Updater thread started')
+
+        # Remove webhook
+        self.bot.setWebhook(webhook_url=None)
+
+        while self.running:
+            try:
+                updates = self.bot.getUpdates(self.last_update_id,
+                                              timeout=timeout,
+                                              network_delay=network_delay)
+                if not self.running:
+                    if len(updates) > 0:
+                        self.logger.info('Updates ignored and will be pulled '
+                                         'again on restart.')
+                    break
+
+                for update in updates:
+                    self.update_queue.put(update)
+                    self.last_update_id = update.update_id + 1
+                    current_interval = poll_interval
+
+                sleep(current_interval)
+            except TelegramError as te:
+                # Put the error into the update queue and let the Dispatcher
+                # broadcast it
+                self.update_queue.put(te)
+                sleep(current_interval)
+
+            except URLError as e:
+                self.logger.error("Error while getting Updates: %s" % e)
+                # increase waiting times on subsequent errors up to 30secs
+                if current_interval == 0:
+                    current_interval = 1
+                elif current_interval < 30:
+                    current_interval += current_interval / 2
+                elif current_interval > 30:
+                    current_interval = 30
+
+        self.logger.info('Updater thread stopped')
+
+    def _start_webhook(self, listen, port, url_path, cert, key):
+        self.logger.info('Updater thread started')
+        use_ssl = cert is not None and key is not None
+        url_path = "/%s" % url_path
+
+        # Create and start server
+        self.httpd = WebhookServer((listen, port), WebhookHandler,
+                                   self.update_queue, url_path)
+
+        if use_ssl:
+            # Check SSL-Certificate with openssl, if possible
+            try:
+                exit_code = subprocess.call(["openssl", "x509", "-text",
+                                             "-noout", "-in", cert],
+                                            stdout=open(os.devnull, 'wb'),
+                                            stderr=subprocess.STDOUT)
+            except OSError:
+                exit_code = 0
+
+            if exit_code is 0:
+                try:
+                    self.httpd.socket = ssl.wrap_socket(self.httpd.socket,
+                                                        certfile=cert,
+                                                        keyfile=key,
+                                                        server_side=True)
+                except ssl.SSLError as error:
+                    raise TelegramError(str(error))
+            else:
+                raise TelegramError('SSL Certificate invalid')
+
+        self.httpd.serve_forever(poll_interval=1)
+        self.logger.info('Updater thread stopped')
+
+    def stop(self):
+        """
+        Stops the polling/webhook thread, the dispatcher and the job queue
+        """
+
+        self.job_queue.stop()
+        with self.__lock:
+            if self.running:
+                self.running = False
+                self.logger.info('Stopping Updater and Dispatcher...')
+                self.logger.debug('This might take a long time if you set a '
+                                  'high value as polling timeout.')
+
+                if self.httpd:
+                    self.logger.info(
+                        'Waiting for current webhook connection to be '
+                        'closed... Send a Telegram message to the bot to exit '
+                        'immediately.')
+                    self.httpd.shutdown()
+                    self.httpd = None
+
+                self.logger.debug("Requesting Dispatcher to stop...")
+                self.dispatcher.stop()
+                while dispatcher.running_async > 0:
+                    sleep(1)
+
+                self.logger.debug("Dispatcher stopped.")
+
+    def signal_handler(self, signum, frame):
+        self.is_idle = False
+        self.stop()
+
+    def idle(self, stop_signals=(SIGINT, SIGTERM, SIGABRT)):
+        """
+        Blocks until one of the signals are received and stops the updater
+
+        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. Defaults to (SIGINT, SIGTERM,
+                SIGABRT)
+        """
+        for sig in stop_signals:
+            signal(sig, self.signal_handler)
+
+        self.is_idle = True
+
+        while self.is_idle:
+            sleep(1)

telegram/user.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python
+# pylint: disable=C0103,W0622
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,23 +18,47 @@
 # 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 User"""
 
 from telegram import TelegramObject
 
 
 class User(TelegramObject):
+    """This object represents a Telegram User.
+
+    Attributes:
+        id (int):
+        first_name (str):
+        last_name (str):
+        username (str):
+        type (str):
+
+    Args:
+        id (int):
+        first_name (str):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        type (Optional[str]):
+        last_name (Optional[str]):
+        username (Optional[str]):
+    """
+
     def __init__(self,
                  id,
                  first_name,
-                 last_name=None,
-                 username=None):
-        self.id = id
+                 **kwargs):
+        # Required
+        self.id = int(id)
         self.first_name = first_name
-        self.last_name = last_name
-        self.username = username
+        # Optionals
+        self.type = kwargs.get('type', '')
+        self.last_name = kwargs.get('last_name', '')
+        self.username = kwargs.get('username', '')
 
     @property
     def name(self):
+        """str: """
         if self.username:
             return '@%s' % self.username
         if self.last_name:
@@ -41,16 +67,14 @@ class User(TelegramObject):
 
     @staticmethod
     def de_json(data):
-        return User(id=data.get('id', None),
-                    first_name=data.get('first_name', None),
-                    last_name=data.get('last_name', None),
-                    username=data.get('username', None))
+        """
+        Args:
+            data (str):
 
-    def to_dict(self):
-        data = {'id': self.id,
-                'first_name': self.first_name}
-        if self.last_name:
-            data['last_name'] = self.last_name
-        if self.username:
-            data['username'] = self.username
-        return data
+        Returns:
+            telegram.User:
+        """
+        if not data:
+            return None
+
+        return User(**data)

telegram/userprofilephotos.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,36 +17,56 @@
 # 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
+UserProfilePhotos"""
 
-from telegram import TelegramObject
+from telegram import PhotoSize, TelegramObject
 
 
 class UserProfilePhotos(TelegramObject):
+    """This object represents a Telegram UserProfilePhotos.
+
+    Attributes:
+        total_count (int):
+        photos (List[List[:class:`telegram.PhotoSize`]]):
+
+    Args:
+        total_count (int):
+        photos (List[List[:class:`telegram.PhotoSize`]]):
+    """
+
     def __init__(self,
                  total_count,
                  photos):
-        self.total_count = total_count
+        # Required
+        self.total_count = int(total_count)
         self.photos = photos
 
     @staticmethod
     def de_json(data):
-        if 'photos' in data:
-            from telegram import PhotoSize
-            photos = []
-            for photo in data['photos']:
-                photos.append([PhotoSize.de_json(x) for x in photo])
-        else:
-            photos = None
+        """
+        Args:
+            data (str):
 
-        return UserProfilePhotos(total_count=data.get('total_count', None),
-                                 photos=photos)
+        Returns:
+            telegram.UserProfilePhotos:
+        """
+        if not data:
+            return None
+
+        data['photos'] = [PhotoSize.de_list(photo) for photo in data['photos']]
+
+        return UserProfilePhotos(**data)
 
     def to_dict(self):
-        data = {}
-        if self.total_count:
-            data['total_count'] = self.total_count
-        if self.photos:
-            data['photos'] = []
-            for photo in self.photos:
-                data['photos'].append([x.to_dict() for x in photo])
+        """
+        Returns:
+            dict:
+        """
+        data = super(UserProfilePhotos, self).to_dict()
+
+        data['photos'] = []
+        for photo in self.photos:
+            data['photos'].append([x.to_dict() for x in photo])
+
         return data

telegram/utils/request.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python
+# pylint: disable=no-name-in-module,unused-import
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 methods to make POST and GET requests"""
+
+import functools
+import json
+import socket
+from ssl import SSLError
+
+try:
+    from urllib.request import urlopen, urlretrieve, Request
+    from urllib.error import HTTPError
+except ImportError:
+    from urllib import urlretrieve
+    from urllib2 import urlopen, Request
+    from urllib2 import HTTPError
+
+from telegram import (InputFile, TelegramError)
+
+
+def _parse(json_data):
+    """Try and parse the JSON returned from Telegram and return an empty
+    dictionary if there is any error.
+
+    Args:
+      url:
+        urllib.urlopen object
+
+    Returns:
+      A JSON parsed as Python dict with results.
+    """
+    decoded_s = json_data.decode('utf-8')
+    try:
+        data = json.loads(decoded_s)
+    except ValueError:
+        raise TelegramError('Invalid server response')
+
+    if not data.get('ok') and data.get('description'):
+        return data['description']
+
+    return data['result']
+
+
+def _try_except_req(func):
+    """Decorator for requests to handle known exceptions"""
+    @functools.wraps(func)
+    def decorator(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except HTTPError as error:
+            if error.getcode() == 403:
+                raise TelegramError('Unauthorized')
+            if error.getcode() == 502:
+                raise TelegramError('Bad Gateway')
+
+            try:
+                message = _parse(error.read())
+            except ValueError:
+                message = 'Unknown HTTPError {0}'.format(error.getcode())
+
+            raise TelegramError(message)
+        except (SSLError, socket.timeout) as error:
+            if "operation timed out" in str(error):
+                raise TelegramError("Timed out")
+
+            raise TelegramError(str(error))
+
+    return decorator
+
+
+@_try_except_req
+def get(url):
+    """Request an URL.
+    Args:
+      url:
+        The web location we want to retrieve.
+
+    Returns:
+      A JSON object.
+    """
+    result = urlopen(url).read()
+
+    return _parse(result)
+
+
+@_try_except_req
+def post(url,
+         data,
+         network_delay=2.):
+    """Request an URL.
+    Args:
+      url:
+        The web location we want to retrieve.
+      data:
+        A dict of (str, unicode) key/value pairs.
+      network_delay:
+        Additional timeout in seconds to allow the response from Telegram to
+        take some time.
+
+    Returns:
+      A JSON object.
+    """
+
+    # Add time to the timeout of urlopen to allow data to be transferred over
+    # the network.
+    if 'timeout' in data:
+        timeout = data['timeout'] + network_delay
+    else:
+        timeout = None
+
+    if InputFile.is_inputfile(data):
+        data = InputFile(data)
+        request = Request(url,
+                          data=data.to_form(),
+                          headers=data.headers)
+    else:
+        data = json.dumps(data)
+        request = Request(url,
+                          data=data.encode(),
+                          headers={'Content-Type': 'application/json'})
+
+    result = urlopen(request, timeout=timeout).read()
+    return _parse(result)
+
+
+@_try_except_req
+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)

telegram/utils/webhookhandler.py

@@ -0,0 +1,85 @@
+import logging
+
+from telegram import Update, NullHandler
+from future.utils import bytes_to_native_str as n
+from threading import Lock
+import json
+try:
+    import BaseHTTPServer
+except ImportError:
+    import http.server as BaseHTTPServer
+
+
+H = NullHandler()
+logging.getLogger(__name__).addHandler(H)
+
+
+class WebhookServer(BaseHTTPServer.HTTPServer, object):
+    def __init__(self, server_address, RequestHandlerClass, update_queue,
+                 webhook_path):
+        super(WebhookServer, self).__init__(server_address,
+                                            RequestHandlerClass)
+        self.logger = logging.getLogger(__name__)
+        self.update_queue = update_queue
+        self.webhook_path = webhook_path
+        self.is_running = False
+        self.server_lock = Lock()
+        self.shutdown_lock = Lock()
+
+    def serve_forever(self, poll_interval=0.5):
+        with self.server_lock:
+            self.is_running = True
+            self.logger.info("Webhook Server started.")
+            super(WebhookServer, self).serve_forever(poll_interval)
+            self.logger.info("Webhook Server stopped.")
+
+    def shutdown(self):
+        with self.shutdown_lock:
+            if not self.is_running:
+                self.logger.warn("Webhook Server already stopped.")
+                return
+            else:
+                super(WebhookServer, self).shutdown()
+                self.is_running = False
+
+
+# WebhookHandler, process webhook calls
+# Based on: https://github.com/eternnoir/pyTelegramBotAPI/blob/master/
+# examples/webhook_examples/webhook_cpython_echo_bot.py
+class WebhookHandler(BaseHTTPServer.BaseHTTPRequestHandler, object):
+    server_version = "WebhookHandler/1.0"
+
+    def __init__(self, request, client_address, server):
+        self.logger = logging.getLogger(__name__)
+        super(WebhookHandler, self).__init__(request, client_address, server)
+
+    def do_HEAD(self):
+        self.send_response(200)
+        self.end_headers()
+
+    def do_GET(self):
+        self.send_response(200)
+        self.end_headers()
+
+    def do_POST(self):
+        self.logger.debug("Webhook triggered")
+        if self.path == self.server.webhook_path and \
+           'content-type' in self.headers and \
+           'content-length' in self.headers and \
+           self.headers['content-type'] == 'application/json':
+            json_string = \
+                n(self.rfile.read(int(self.headers['content-length'])))
+
+            self.send_response(200)
+            self.end_headers()
+
+            self.logger.debug("Webhook received data: " + json_string)
+
+            update = Update.de_json(json.loads(json_string))
+            self.logger.info("Received Update with ID %d on Webhook" %
+                             update.update_id)
+            self.server.update_queue.put(update)
+
+        else:
+            self.send_error(403)
+            self.end_headers()

telegram/video.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,52 +17,64 @@
 # 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 Video"""
 
-from telegram import TelegramObject
+from telegram import PhotoSize, TelegramObject
 
 
 class Video(TelegramObject):
+    """This object represents a Telegram Video.
+
+    Attributes:
+        file_id (str):
+        width (int):
+        height (int):
+        duration (int):
+        thumb (:class:`telegram.PhotoSize`):
+        mime_type (str):
+        file_size (int):
+
+    Args:
+        file_id (str):
+        width (int):
+        height (int):
+        duration (int):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        thumb (Optional[:class:`telegram.PhotoSize`]):
+        mime_type (Optional[str]):
+        file_size (Optional[int]):
+    """
+
     def __init__(self,
                  file_id,
                  width,
                  height,
                  duration,
-                 thumb=None,
-                 mime_type=None,
-                 file_size=None):
-        self.file_id = file_id
-        self.width = width
-        self.height = height
-        self.duration = duration
-        self.thumb = thumb
-        self.mime_type = mime_type
-        self.file_size = file_size
+                 **kwargs):
+        # Required
+        self.file_id = str(file_id)
+        self.width = int(width)
+        self.height = int(height)
+        self.duration = int(duration)
+        # Optionals
+        self.thumb = kwargs.get('thumb')
+        self.mime_type = str(kwargs.get('mime_type', ''))
+        self.file_size = int(kwargs.get('file_size', 0))
 
     @staticmethod
     def de_json(data):
-        if 'thumb' in data:
-            from telegram import PhotoSize
-            thumb = PhotoSize.de_json(data['thumb'])
-        else:
-            thumb = None
+        """
+        Args:
+            data (str):
 
-        return Video(file_id=data.get('file_id', None),
-                     width=data.get('width', None),
-                     height=data.get('height', None),
-                     duration=data.get('duration', None),
-                     thumb=thumb,
-                     mime_type=data.get('mime_type', None),
-                     file_size=data.get('file_size', None))
+        Returns:
+            telegram.Video:
+        """
+        if not data:
+            return None
 
-    def to_dict(self):
-        data = {'file_id': self.file_id,
-                'width': self.width,
-                'height': self.height,
-                'duration': self.duration}
-        if self.thumb:
-            data['thumb'] = self.thumb.to_dict()
-        if self.mime_type:
-            data['mime_type'] = self.mime_type
-        if self.file_size:
-            data['file_size'] = self.file_size
-        return data
+        data['thumb'] = PhotoSize.de_json(data.get('thumb'))
+
+        return Video(**data)

telegram/voice.py

@@ -1,7 +1,8 @@
 #!/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>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -16,34 +17,50 @@
 # 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 Voice"""
 
 from telegram import TelegramObject
 
 
 class Voice(TelegramObject):
+    """This object represents a Telegram Voice.
+
+    Attributes:
+        file_id (str):
+        duration (int):
+        mime_type (str):
+        file_size (int):
+
+    Args:
+        file_id (str):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        duration (Optional[int]):
+        mime_type (Optional[str]):
+        file_size (Optional[int]):
+    """
+
     def __init__(self,
                  file_id,
-                 duration=None,
-                 mime_type=None,
-                 file_size=None):
-        self.file_id = file_id
-        self.duration = duration
-        self.mime_type = mime_type
-        self.file_size = file_size
+                 **kwargs):
+        # Required
+        self.file_id = str(file_id)
+        # Optionals
+        self.duration = int(kwargs.get('duration', 0))
+        self.mime_type = str(kwargs.get('mime_type', ''))
+        self.file_size = int(kwargs.get('file_size', 0))
 
     @staticmethod
     def de_json(data):
-        return Voice(file_id=data.get('file_id', None),
-                     duration=data.get('duration', None),
-                     mime_type=data.get('mime_type', None),
-                     file_size=data.get('file_size', None))
+        """
+        Args:
+            data (str):
 
-    def to_dict(self):
-        data = {'file_id': self.file_id}
-        if self.duration:
-            data['duration'] = self.duration
-        if self.mime_type:
-            data['mime_type'] = self.mime_type
-        if self.file_size:
-            data['file_size'] = self.file_size
-        return data
+        Returns:
+            telegram.Voice:
+        """
+        if not data:
+            return None
+
+        return Voice(**data)

tests/base.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 a Base class for tests"""
+
+import os
+import sys
+sys.path.append('.')
+
+import json
+import telegram
+
+
+class BaseTest(object):
+    """This object represents a Base test and its sets of functions."""
+
+    def __init__(self, *args, **kwargs):
+        super(BaseTest, self).__init__(*args, **kwargs)
+
+        bot = telegram.Bot(os.environ.get('TOKEN'))
+        chat_id = os.environ.get('CHAT_ID')
+
+        self._bot = bot
+        self._chat_id = chat_id
+
+    @staticmethod
+    def is_json(string):
+        try:
+            json.loads(string)
+        except ValueError:
+            return False
+
+        return True
+
+    @staticmethod
+    def is_dict(dictionary):
+        if isinstance(dictionary, dict):
+            return True
+
+        return False

tests/test_audio.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Audio"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class AudioTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Audio."""
+
+    def setUp(self):
+        self.audio_file = open('tests/data/telegram.mp3', 'rb')
+        self.audio_file_id = 'BQADAQADDwADHyP1B6PSPq2HjX8kAg'
+        self.duration = 4
+        self.performer = 'Leandro Toledo'
+        self.title = 'Teste'
+        self.mime_type = 'audio/mpeg'
+        self.file_size = 28232
+
+        self.json_dict = {
+            'file_id': self.audio_file_id,
+            'duration': self.duration,
+            'performer': self.performer,
+            'title': self.title,
+            'mime_type': self.mime_type,
+            'file_size': self.file_size
+        }
+
+    def test_send_audio_required_args_only(self):
+        """Test telegram.Bot sendAudio method"""
+        print('Testing bot.sendAudio - With required arguments only')
+
+        message = self._bot.sendAudio(self._chat_id,
+                                      self.audio_file)
+
+        audio = message.audio
+
+        self.assertTrue(isinstance(audio.file_id, str))
+        self.assertNotEqual(audio.file_id, '')
+        self.assertEqual(audio.duration, 4)
+        self.assertEqual(audio.performer, '')
+        self.assertEqual(audio.title, '')
+        self.assertEqual(audio.mime_type, self.mime_type)
+        self.assertEqual(audio.file_size, self.file_size)
+
+    def test_send_audio_all_args(self):
+        """Test telegram.Bot sendAudio method"""
+        print('Testing bot.sendAudio - With all arguments')
+
+        message = self._bot.sendAudio(self._chat_id,
+                                      self.audio_file,
+                                      duration=self.duration,
+                                      performer=self.performer,
+                                      title=self.title,
+                                      mime_type=self.mime_type,
+                                      file_size=self.file_size)
+
+        audio = message.audio
+
+        self.assertTrue(isinstance(audio.file_id, str))
+        self.assertNotEqual(audio.file_id, '')
+        self.assertEqual(audio.duration, self.duration)
+        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_send_audio_mp3_file(self):
+        """Test telegram.Bot sendAudio method"""
+        print('Testing bot.sendAudio - MP3 File')
+
+        message = self._bot.sendAudio(chat_id=self._chat_id,
+                                      audio=self.audio_file,
+                                      duration=self.duration,
+                                      performer=self.performer,
+                                      title=self.title)
+
+        audio = message.audio
+
+        self.assertTrue(isinstance(audio.file_id, str))
+        self.assertNotEqual(audio.file_id, '')
+        self.assertEqual(audio.duration, self.duration)
+        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_send_audio_mp3_file_custom_filename(self):
+        """Test telegram.Bot sendAudio method"""
+        print('Testing bot.sendAudio - MP3 File with custom filename')
+
+        message = self._bot.sendAudio(chat_id=self._chat_id,
+                                      audio=self.audio_file,
+                                      duration=self.duration,
+                                      performer=self.performer,
+                                      title=self.title,
+                                      filename='telegram_custom.mp3')
+
+        audio = message.audio
+
+        self.assertTrue(isinstance(audio.file_id, str))
+        self.assertNotEqual(audio.file_id, '')
+        self.assertEqual(audio.duration, self.duration)
+        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_send_audio_resend(self):
+        """Test telegram.Bot sendAudio method"""
+        print('Testing bot.sendAudio - Resend by file_id')
+
+        message = self._bot.sendAudio(chat_id=self._chat_id,
+                                      audio=self.audio_file_id,
+                                      duration=self.duration,
+                                      performer=self.performer,
+                                      title=self.title)
+
+        audio = message.audio
+
+        self.assertEqual(audio.file_id, self.audio_file_id)
+        self.assertEqual(audio.duration, self.duration)
+        self.assertEqual(audio.performer, self.performer)
+        self.assertEqual(audio.title, self.title)
+        self.assertEqual(audio.mime_type, self.mime_type)
+
+    def test_audio_de_json(self):
+        """Test Audio.de_json() method"""
+        print('Testing Audio.de_json()')
+
+        audio = telegram.Audio.de_json(self.json_dict)
+
+        self.assertEqual(audio.file_id, self.audio_file_id)
+        self.assertEqual(audio.duration, self.duration)
+        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_to_json(self):
+        """Test Audio.to_json() method"""
+        print('Testing Audio.to_json()')
+
+        audio = telegram.Audio.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(audio.to_json()))
+
+    def test_audio_to_dict(self):
+        """Test Audio.to_dict() method"""
+        print('Testing Audio.to_dict()')
+
+        audio = telegram.Audio.de_json(self.json_dict)
+
+        self.assertTrue(self.is_dict(audio.to_dict()))
+        self.assertEqual(audio['file_id'], self.audio_file_id)
+        self.assertEqual(audio['duration'], self.duration)
+        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_error_send_audio_empty_file(self):
+        print('Testing bot.sendAudio - Null file')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        json_dict['audio'] = open(os.devnull, 'rb')
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendAudio(chat_id=self._chat_id,
+                                                      **json_dict))
+
+    def test_error_send_audio_empty_file_id(self):
+        print('Testing bot.sendAudio - Empty file_id')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        json_dict['audio'] = ''
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendAudio(chat_id=self._chat_id,
+                                                      **json_dict))
+
+    def test_error_audio_without_required_args(self):
+        print('Testing bot.sendAudio - Without required arguments')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        del(json_dict['duration'])
+
+        self.assertRaises(TypeError,
+                          lambda: self._bot.sendAudio(chat_id=self._chat_id,
+                                                      **json_dict))
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_bot.py

@@ -2,7 +2,8 @@
 # encoding: utf-8
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # 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
@@ -17,214 +18,158 @@
 # 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 Bot"""
 
 import os
-import json
-import telegram
-import unittest
 from datetime import datetime
+import sys
+
+if sys.version_info[0:2] == (2, 6):
+    import unittest2 as unittest
+else:
+    import unittest
+
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
 
 
-class BotTest(unittest.TestCase):
-    @staticmethod
-    def is_json(string):
-        try:
-            json.loads(string)
-        except ValueError:
-            return False
-        return True
-
-    def setUp(self):
-        bot = telegram.Bot(token=os.environ.get('TOKEN'))
-        self._bot = bot
-        print('Testing the Bot API class')
+class BotTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Bot."""
 
     def testGetMe(self):
         '''Test the telegram.Bot getMe method'''
         print('Testing getMe')
         bot = self._bot.getMe()
+
         self.assertTrue(self.is_json(bot.to_json()))
-        self.assertEqual(120405045, bot.id)
-        self.assertEqual('Toledo\'s Palace Bot', bot.first_name)
-        self.assertEqual(None, bot.last_name)
-        self.assertEqual('ToledosPalaceBot', bot.username)
+        self.assertEqual(bot.id, 133505823)
+        self.assertEqual(bot.first_name, 'PythonTelegramBot')
+        self.assertEqual(bot.last_name, '')
+        self.assertEqual(bot.username, 'PythonTelegramBot')
+        self.assertEqual(bot.name, '@PythonTelegramBot')
 
     def testSendMessage(self):
         '''Test the telegram.Bot sendMessage method'''
         print('Testing sendMessage')
-        message = self._bot.sendMessage(chat_id=12173560,
+        message = self._bot.sendMessage(chat_id=self._chat_id,
                                         text='Моё судно на воздушной подушке полно угрей')
+
         self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(u'Моё судно на воздушной подушке полно угрей', message.text)
-        self.assertIsInstance(message.date, datetime)
+        self.assertEqual(message.text, u'Моё судно на воздушной подушке полно угрей')
+        self.assertTrue(isinstance(message.date, datetime))
 
     def testGetUpdates(self):
         '''Test the telegram.Bot getUpdates method'''
         print('Testing getUpdates')
         updates = self._bot.getUpdates()
-        self.assertTrue(self.is_json(updates[0].to_json()))
-        self.assertIsInstance(updates[0], telegram.Update)
+
+        if updates:
+            self.assertTrue(self.is_json(updates[0].to_json()))
+            self.assertTrue(isinstance(updates[0], telegram.Update))
 
     def testForwardMessage(self):
         '''Test the telegram.Bot forwardMessage method'''
         print('Testing forwardMessage')
-        message = self._bot.forwardMessage(chat_id=12173560,
-                                           from_chat_id=12173560,
-                                           message_id=138)
+        message = self._bot.forwardMessage(chat_id=self._chat_id,
+                                           from_chat_id=self._chat_id,
+                                           message_id=2398)
+
         self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual('Oi', message.text)
-        self.assertEqual('leandrotoledo', message.forward_from.username)
-        self.assertIsInstance(message.forward_date, datetime)
+        self.assertEqual(message.text, 'teste')
+        self.assertEqual(message.forward_from.username, 'leandrotoledo')
+        self.assertTrue(isinstance(message.forward_date, datetime))
 
     def testSendPhoto(self):
         '''Test the telegram.Bot sendPhoto method'''
         print('Testing sendPhoto - File')
-        message = self._bot.sendPhoto(photo=open('tests/telegram.png', 'rb'),
+        message = self._bot.sendPhoto(photo=open('tests/data/telegram.png', 'rb'),
                                       caption='testSendPhoto',
-                                      chat_id=12173560)
+                                      chat_id=self._chat_id)
+
         self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(1451, message.photo[0].file_size)
-        self.assertEqual('testSendPhoto', message.caption)
+        self.assertEqual(message.photo[0].file_size, 1451)
+        self.assertEqual(message.caption, 'testSendPhoto')
 
     def testResendPhoto(self):
         '''Test the telegram.Bot sendPhoto method'''
         print('Testing sendPhoto - Resend')
-        message = self._bot.sendPhoto(photo='AgADAQADr6cxGzU8LQe6q0dMJD2rHYkP2ykABFymiQqJgjxRGGMAAgI',
-                                      chat_id=12173560)
+        message = self._bot.sendPhoto(photo='AgADAQADyKcxGx8j9Qdp6d-gpUsw4Gja1i8ABEVJsVqQk8LfJ3wAAgI',
+                                      chat_id=self._chat_id)
+
         self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual('AgADAQADr6cxGzU8LQe6q0dMJD2rHYkP2ykABFymiQqJgjxRGGMAAgI', message.photo[0].file_id)
+        self.assertEqual(message.photo[0].file_id, 'AgADAQADyKcxGx8j9Qdp6d-gpUsw4Gja1i8ABEVJsVqQk8LfJ3wAAgI')
 
     def testSendJPGURLPhoto(self):
         '''Test the telegram.Bot sendPhoto method'''
         print('Testing testSendJPGURLPhoto - URL')
         message = self._bot.sendPhoto(photo='http://dummyimage.com/600x400/000/fff.jpg&text=telegram',
-                                      chat_id=12173560)
+                                      chat_id=self._chat_id)
+
         self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(822, message.photo[0].file_size)
+        self.assertEqual(message.photo[0].file_size, 822)
 
     def testSendPNGURLPhoto(self):
         '''Test the telegram.Bot sendPhoto method'''
         print('Testing testSendPNGURLPhoto - URL')
         message = self._bot.sendPhoto(photo='http://dummyimage.com/600x400/000/fff.png&text=telegram',
-                                      chat_id=12173560)
+                                      chat_id=self._chat_id)
+
         self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(684, message.photo[0].file_size)
+        self.assertEqual(message.photo[0].file_size, 684)
 
     def testSendGIFURLPhoto(self):
         '''Test the telegram.Bot sendPhoto method'''
         print('Testing testSendGIFURLPhoto - URL')
         message = self._bot.sendPhoto(photo='http://dummyimage.com/600x400/000/fff.gif&text=telegram',
-                                      chat_id=12173560)
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(684, message.photo[0].file_size)
+                                      chat_id=self._chat_id)
 
-    def testSendAudio(self):
-        '''Test the telegram.Bot sendAudio method'''
-        print('Testing sendAudio - File')
-        message = self._bot.sendAudio(audio=open('tests/telegram.mp3', 'rb'),
-                                      chat_id=12173560,
-                                      performer='Leandro Toledo',
-                                      title='Teste')
         self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(28232, message.audio.file_size)
-        self.assertEqual('Leandro Toledo', message.audio.performer)
-        self.assertEqual('Teste', message.audio.title)
-
-    def testResendAudio(self):
-        '''Test the telegram.Bot sendAudio method'''
-        print('Testing sendAudio - Resend')
-        message = self._bot.sendAudio(audio='BQADAQADwwcAAjU8LQdBRsl3_qD2TAI',
-                                      chat_id=12173560,
-                                      performer='Leandro Toledo',   # Bug #39
-                                      title='Teste')                # Bug #39
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual('BQADAQADwwcAAjU8LQdBRsl3_qD2TAI', message.audio.file_id)
-
-    def testSendVoice(self):
-        '''Test the telegram.Bot sendVoice method'''
-        print('Testing sendVoice - File')
-        message = self._bot.sendVoice(voice=open('tests/telegram.ogg', 'rb'),
-                                      chat_id=12173560)
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(9199, message.voice.file_size)
-
-    def testResendVoice(self):
-        '''Test the telegram.Bot sendVoice method'''
-        print('Testing sendVoice - Resend')
-        message = self._bot.sendVoice(voice='AwADAQADIQEAAvjAuQABSAXg_GhkhZcC',
-                                      chat_id=12173560)
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual('AwADAQADIQEAAvjAuQABSAXg_GhkhZcC', message.voice.file_id)
-
-    def testSendDocument(self):
-        '''Test the telegram.Bot sendDocument method'''
-        print('Testing sendDocument - File')
-        message = self._bot.sendDocument(document=open('tests/telegram.png', 'rb'),
-                                         chat_id=12173560)
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(12948, message.document.file_size)
-
-    def testSendGIFURLDocument(self):
-        '''Test the telegram.Bot sendDocument method'''
-        print('Testing sendDocument - File')
-        message = self._bot.sendPhoto(photo='http://dummyimage.com/600x400/000/fff.gif&text=telegram',
-                                      chat_id=12173560)
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(684, message.photo[0].file_size)
-
-    def testResendDocument(self):
-        '''Test the telegram.Bot sendDocument method'''
-        print('Testing sendDocument - Resend')
-        message = self._bot.sendDocument(document='BQADAQADHAADNTwtBxZxUGKyxYbYAg',
-                                         chat_id=12173560)
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual('BQADAQADHAADNTwtBxZxUGKyxYbYAg', message.document.file_id)
-
-    def testSendVideo(self):
-        '''Test the telegram.Bot sendVideo method'''
-        print('Testing sendVideo - File')
-        message = self._bot.sendVideo(video=open('tests/telegram.mp4', 'rb'),
-                                      caption='testSendVideo',
-                                      chat_id=12173560)
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(326534, message.video.file_size)
-        self.assertEqual('testSendVideo', message.caption)
-
-    def testResendVideo(self):
-        '''Test the telegram.Bot sendVideo method'''
-        print('Testing sendVideo - Resend')
-        message = self._bot.sendVideo(video='BAADAQADIgEAAvjAuQABOuTB937fPTgC',
-                                      chat_id=12173560)
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(4, message.video.duration)
-
-    def testResendSticker(self):
-        '''Test the telegram.Bot sendSticker method'''
-        print('Testing sendSticker - Resend')
-        message = self._bot.sendSticker(sticker='BQADAQADHAADyIsGAAFZfq1bphjqlgI',
-                                        chat_id=12173560)
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(39518, message.sticker.file_size)
-
-    def testSendLocation(self):
-        '''Test the telegram.Bot sendLocation method'''
-        print('Testing sendLocation')
-        message = self._bot.sendLocation(latitude=-23.558873,
-                                         longitude=-46.659732,
-                                         chat_id=12173560)
-        self.assertTrue(self.is_json(message.to_json()))
-        self.assertEqual(-23.558873, message.location.latitude)
-        self.assertEqual(-46.659732, message.location.longitude)
+        self.assertEqual(message.photo[0].file_size, 684)
 
     def testSendChatAction(self):
         '''Test the telegram.Bot sendChatAction method'''
         print('Testing sendChatAction - ChatAction.TYPING')
+
         self._bot.sendChatAction(action=telegram.ChatAction.TYPING,
-                                 chat_id=12173560)
+                                 chat_id=self._chat_id)
 
     def testGetUserProfilePhotos(self):
         '''Test the telegram.Bot getUserProfilePhotos method'''
         print('Testing getUserProfilePhotos')
-        upf = self._bot.getUserProfilePhotos(user_id=12173560)
+        upf = self._bot.getUserProfilePhotos(user_id=self._chat_id)
+
         self.assertTrue(self.is_json(upf.to_json()))
-        self.assertEqual(6547, upf.photos[0][0].file_size)
+        self.assertEqual(upf.photos[0][0].file_size, 12421)
+
+    def _test_invalid_token(self, token):
+        print('Testing invalid token: {0}'.format(token))
+        self.assertRaisesRegexp(telegram.TelegramError, 'Invalid token', telegram.Bot, token)
+
+    def testInvalidToken1(self):
+        self._test_invalid_token('123')
+
+    def testInvalidToken2(self):
+        self._test_invalid_token('12a:')
+
+    def testInvalidToken3(self):
+        self._test_invalid_token('12:')
+
+    def testUnauthToken(self):
+        print('Testing unauthorized token')
+        with self.assertRaisesRegexp(telegram.TelegramError, 'Unauthorized'):
+            bot = telegram.Bot('1234:abcd1234')
+            bot.getMe()
+
+    def testInvalidSrvResp(self):
+        print('Testing invalid server response')
+        with self.assertRaisesRegexp(telegram.TelegramError, 'Invalid server response'):
+            # bypass the valid token check
+            bot_cls = type('bot_cls', (telegram.Bot, ), {'_valid_token': lambda self, token: token})
+            bot = bot_cls('12')
+            bot.getMe()
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_chat.py

@@ -0,0 +1,83 @@
+  #!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Chat"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class ChatTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Chat."""
+
+    def setUp(self):
+        self.id = -28767330
+        self.title = 'ToledosPalaceBot - Group'
+        self.type = 'group'
+
+        self.json_dict = {
+            'id': self.id,
+            'title': self.title,
+            'type': self.type
+        }
+
+    def test_group_chat_de_json_empty_json(self):
+        """Test Chat.de_json() method"""
+        print('Testing Chat.de_json() - Empty JSON')
+
+        group_chat = telegram.Chat.de_json({})
+
+        self.assertEqual(group_chat, None)
+
+    def test_group_chat_de_json(self):
+        """Test Chat.de_json() method"""
+        print('Testing Chat.de_json()')
+
+        group_chat = telegram.Chat.de_json(self.json_dict)
+
+        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 Chat.to_json() method"""
+        print('Testing Chat.to_json()')
+
+        group_chat = telegram.Chat.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(group_chat.to_json()))
+
+    def test_group_chat_to_dict(self):
+        """Test Chat.to_dict() method"""
+        print('Testing Chat.to_dict()')
+
+        group_chat = telegram.Chat.de_json(self.json_dict)
+
+        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_contact.py

@@ -0,0 +1,79 @@
+  #!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Contact"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class ContactTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Contact."""
+
+    def setUp(self):
+        self.phone_number = '+11234567890'
+        self.first_name = 'Leandro Toledo'
+        self.last_name = ''
+        self.user_id = 0
+
+        self.json_dict = {
+            'phone_number': self.phone_number,
+            'first_name': self.first_name,
+            'last_name': self.last_name,
+            'user_id': self.user_id
+        }
+
+    def test_contact_de_json(self):
+        """Test Contact.de_json() method"""
+        print('Testing Contact.de_json()')
+
+        contact = telegram.Contact.de_json(self.json_dict)
+
+        self.assertEqual(contact.phone_number, self.phone_number)
+        self.assertEqual(contact.first_name, self.first_name)
+        self.assertEqual(contact.last_name, self.last_name)
+        self.assertEqual(contact.user_id, self.user_id)
+
+    def test_contact_to_json(self):
+        """Test Contact.to_json() method"""
+        print('Testing Contact.to_json()')
+
+        contact = telegram.Contact.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(contact.to_json()))
+
+    def test_contact_to_dict(self):
+        """Test Contact.to_dict() method"""
+        print('Testing Contact.to_dict()')
+
+        contact = telegram.Contact.de_json(self.json_dict)
+
+        self.assertTrue(self.is_dict(contact.to_dict()))
+        self.assertEqual(contact['phone_number'], self.phone_number)
+        self.assertEqual(contact['first_name'], self.first_name)
+        self.assertEqual(contact['last_name'], self.last_name)
+        self.assertEqual(contact['user_id'], self.user_id)
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_document.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Document"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class DocumentTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Document."""
+
+    def setUp(self):
+        self.document_file = open('tests/data/telegram.png', 'rb')
+        self.document_file_id = 'BQADAQADpAADHyP1B04ipZxJTe2BAg'
+        self.document_file_url = 'http://dummyimage.com/600x400/000/fff.gif&text=telegram'
+        self.thumb = {'width': 90,
+                      'height': 90,
+                      'file_id': 'BQADAQADoQADHyP1B0mzJMVyzcB0Ag',
+                      'file_size': 2364}
+        self.file_name = 'telegram.png'
+        self.mime_type = 'image/png'
+        self.file_size = 12948
+
+        self.json_dict = {
+            'file_id': self.document_file_id,
+            'thumb': self.thumb,
+            'file_name': self.file_name,
+            'mime_type': self.mime_type,
+            'file_size': self.file_size
+        }
+
+    def test_send_document_png_file(self):
+        """Test telegram.Bot sendDocument method"""
+        print('Testing bot.sendDocument - PNG File')
+
+        message = self._bot.sendDocument(self._chat_id,
+                                         self.document_file)
+
+        document = message.document
+
+        self.assertTrue(isinstance(document.file_id, str))
+        self.assertNotEqual(document.file_id, '')
+        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_send_document_png_file_with_custom_file_name(self):
+        """Test telegram.Bot sendDocument method"""
+        print('Testing bot.sendDocument - PNG File with custom filename')
+
+        message = self._bot.sendDocument(self._chat_id,
+                                         self.document_file,
+                                         filename='telegram_custom.png')
+
+        document = message.document
+
+        self.assertTrue(isinstance(document.file_id, str))
+        self.assertNotEqual(document.file_id, '')
+        self.assertTrue(isinstance(document.thumb, telegram.PhotoSize))
+        self.assertEqual(document.file_name, 'telegram_custom.png')
+        self.assertEqual(document.mime_type, self.mime_type)
+        self.assertEqual(document.file_size, self.file_size)
+
+    def test_send_document_url_gif_file(self):
+        """Test telegram.Bot sendDocument method"""
+        print('Testing bot.sendDocument - GIF File by URL')
+
+        message = self._bot.sendDocument(self._chat_id,
+                                         self.document_file_url)
+
+        document = message.document
+
+        self.assertTrue(isinstance(document.file_id, str))
+        self.assertNotEqual(document.file_id, '')
+        self.assertTrue(isinstance(document.thumb, telegram.PhotoSize))
+        self.assertEqual(document.file_name, 'image.gif')
+        self.assertEqual(document.mime_type, 'image/gif')
+        self.assertEqual(document.file_size, 3878)
+
+    def test_send_document_resend(self):
+        """Test telegram.Bot sendDocument method"""
+        print('Testing bot.sendDocument - Resend by file_id')
+
+        message = self._bot.sendDocument(chat_id=self._chat_id,
+                                         document=self.document_file_id)
+
+        document = message.document
+
+        self.assertEqual(document.file_id, self.document_file_id)
+        self.assertTrue(isinstance(document.thumb, telegram.PhotoSize))
+        self.assertEqual(document.file_name, self.file_name)
+        self.assertEqual(document.mime_type, self.mime_type)
+
+    def test_document_de_json(self):
+        """Test Document.de_json() method"""
+        print('Testing Document.de_json()')
+
+        document = telegram.Document.de_json(self.json_dict)
+
+        self.assertEqual(document.file_id, self.document_file_id)
+        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_to_json(self):
+        """Test Document.to_json() method"""
+        print('Testing Document.to_json()')
+
+        document = telegram.Document.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(document.to_json()))
+
+    def test_document_to_dict(self):
+        """Test Document.to_dict() method"""
+        print('Testing Document.to_dict()')
+
+        document = telegram.Document.de_json(self.json_dict)
+
+        self.assertTrue(self.is_dict(document.to_dict()))
+        self.assertEqual(document['file_id'], self.document_file_id)
+        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_error_send_document_empty_file(self):
+        print('Testing bot.sendDocument - Null file')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        json_dict['document'] = open(os.devnull, 'rb')
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendDocument(chat_id=self._chat_id,
+                                                         **json_dict))
+
+    def test_error_send_document_empty_file_id(self):
+        print('Testing bot.sendDocument - Empty file_id')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        json_dict['document'] = ''
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendDocument(chat_id=self._chat_id,
+                                                         **json_dict))
+
+    def test_error_document_without_required_args(self):
+        print('Testing bot.sendDocument - Without required arguments')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+
+        self.assertRaises(TypeError,
+                          lambda: self._bot.sendDocument(chat_id=self._chat_id,
+                                                         **json_dict))
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_emoji.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Emoji"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from telegram.emoji import Emoji
+from tests.base import BaseTest
+
+
+class EmojiTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Emoji."""
+
+    def test_emoji(self):
+        """Test Emoji class"""
+        print('Testing Emoji class')
+        
+        for attr in dir(Emoji):
+            if attr[0] != '_':  # TODO: dirty way to filter out functions
+                self.assertTrue(type(getattr(Emoji, attr)) is str)
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_file.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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_jobqueue.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python
+# encoding: utf-8
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 JobQueue
+"""
+import logging
+import sys
+from time import sleep
+
+if sys.version_info[0:2] == (2, 6):
+    import unittest2 as unittest
+else:
+    import unittest
+
+try:
+    from urllib2 import urlopen, Request
+except ImportError:
+    from urllib.request import Request, urlopen
+
+sys.path.append('.')
+
+from telegram import JobQueue, Updater
+from tests.base import BaseTest
+
+# Enable logging
+root = logging.getLogger()
+root.setLevel(logging.INFO)
+
+ch = logging.StreamHandler(sys.stdout)
+ch.setLevel(logging.WARN)
+formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+ch.setFormatter(formatter)
+root.addHandler(ch)
+
+
+class JobQueueTest(BaseTest, unittest.TestCase):
+    """
+    This object represents Tests for Updater, Dispatcher, WebhookServer and
+    WebhookHandler
+    """
+
+    def setUp(self):
+        self.jq = JobQueue("Bot", tick_interval=0.005)
+        self.result = 0
+
+    def tearDown(self):
+        if self.jq is not None:
+            self.jq.stop()
+
+    def job1(self, bot):
+        self.result += 1
+
+    def job2(self, bot):
+        raise Exception("Test Error")
+
+    def test_basic(self):
+        print('Testing basic job queue function')
+        self.jq.put(self.job1, 0.1)
+        sleep(1.5)
+        self.assertGreaterEqual(self.result, 10)
+
+    def test_noRepeat(self):
+        print('Testing job queue without repeat')
+        self.jq.put(self.job1, 0.1, repeat=False)
+        sleep(0.5)
+        self.assertEqual(1, self.result)
+
+    def test_nextT(self):
+        print('Testing job queue with a set next_t value')
+        self.jq.put(self.job1, 0.1, next_t=0.5)
+        sleep(0.45)
+        self.assertEqual(0, self.result)
+        sleep(0.1)
+        self.assertEqual(1, self.result)
+
+    def test_multiple(self):
+        print('Testing job queue with multiple jobs')
+        self.jq.put(self.job1, 0.1, repeat=False)
+        self.jq.put(self.job1, 0.2, repeat=False)
+        self.jq.put(self.job1, 0.4)
+        sleep(1)
+        self.assertEqual(4, self.result)
+
+    def test_error(self):
+        print('Testing job queue starting twice with an erroneous job')
+        self.jq.put(self.job2, 0.1)
+        self.jq.put(self.job1, 0.2)
+        self.jq.start()
+        sleep(0.4)
+        self.assertEqual(1, self.result)
+
+    def test_inUpdater(self):
+        print('Testing job queue created by updater')
+        u = Updater(bot="MockBot", job_queue_tick_interval=0.005)
+        u.job_queue.put(self.job1, 0.1)
+        sleep(0.15)
+        self.assertEqual(1, self.result)
+        u.stop()
+        sleep(0.4)
+        self.assertEqual(1, self.result)
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_location.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Location"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class LocationTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Location."""
+
+    def setUp(self):
+        self.latitude = -23.691288
+        self.longitude = -46.788279
+
+        self.json_dict = {
+            'latitude': self.latitude,
+            'longitude': self.longitude
+        }
+
+    def test_send_location_implicit_args(self):
+        """Test telegram.Bot sendLocation method"""
+        print('Testing bot.sendLocation - Implicit arguments')
+
+        message = self._bot.sendLocation(self._chat_id,
+                                         self.latitude,
+                                         self.longitude)
+
+        location = message.location
+
+        self.assertEqual(location.latitude, self.latitude)
+        self.assertEqual(location.longitude, self.longitude)
+
+    def test_send_location_explicit_args(self):
+        """Test telegram.Bot sendLocation method"""
+        print('Testing bot.sendLocation - Explicit arguments')
+
+        message = self._bot.sendLocation(chat_id=self._chat_id,
+                                         latitude=self.latitude,
+                                         longitude=self.longitude)
+
+        location = message.location
+
+        self.assertEqual(location.latitude, self.latitude)
+        self.assertEqual(location.longitude, self.longitude)
+
+    def test_location_de_json(self):
+        """Test Location.de_json() method"""
+        print('Testing Location.de_json()')
+
+        location = telegram.Location.de_json(self.json_dict)
+
+        self.assertEqual(location.latitude, self.latitude)
+        self.assertEqual(location.longitude, self.longitude)
+
+    def test_location_to_json(self):
+        """Test Location.to_json() method"""
+        print('Testing Location.to_json()')
+
+        location = telegram.Location.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(location.to_json()))
+
+    def test_location_to_dict(self):
+        """Test Location.to_dict() method"""
+        print('Testing Location.to_dict()')
+
+        location = telegram.Location.de_json(self.json_dict)
+
+        self.assertEqual(location['latitude'], self.latitude)
+        self.assertEqual(location['longitude'], self.longitude)
+
+    def test_error_send_location_empty_args(self):
+        print('Testing bot.sendLocation - Empty arguments')
+
+        json_dict = self.json_dict
+
+        json_dict['latitude'] = ''
+        json_dict['longitude'] = ''
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendLocation(chat_id=self._chat_id,
+                                                         **json_dict))
+
+    def test_error_location_without_required_args(self):
+        print('Testing bot.sendLocation - Without required arguments')
+
+        json_dict = self.json_dict
+
+        del(json_dict['latitude'])
+        del(json_dict['longitude'])
+
+        self.assertRaises(TypeError,
+                          lambda: self._bot.sendLocation(chat_id=self._chat_id,
+                                                         **json_dict))
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_sticker.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Sticker"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class StickerTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Sticker."""
+
+    def setUp(self):
+        self.sticker_file_id = 'BQADAQADHAADyIsGAAFZfq1bphjqlgI'
+        self.width = 510
+        self.height = 512
+        self.thumb = {'width': 90,
+                      'height': 90,
+                      'file_id': 'BQADAQADoQADHyP1B0mzJMVyzcB0Ag',
+                      'file_size': 2364}
+        self.file_size = 39518
+
+        self.json_dict = {
+            'file_id': self.sticker_file_id,
+            'width': self.width,
+            'height': self.height,
+            'thumb': self.thumb,
+            'file_size': self.file_size
+        }
+
+    def test_send_sticker_file(self):
+        pass
+
+    def test_send_sticker_resend(self):
+        """Test telegram.Bot sendSticker method"""
+        print('Testing bot.sendSticker - Resend by file_id')
+
+        message = self._bot.sendSticker(chat_id=self._chat_id,
+                                         sticker=self.sticker_file_id)
+
+        sticker = message.sticker
+
+        self.assertEqual(sticker.file_id, self.sticker_file_id)
+        self.assertEqual(sticker.width, self.width)
+        self.assertEqual(sticker.height, self.height)
+        self.assertTrue(isinstance(sticker.thumb, telegram.PhotoSize))
+        self.assertEqual(sticker.file_size, self.file_size)
+
+    def test_sticker_de_json(self):
+        """Test Sticker.de_json() method"""
+        print('Testing Sticker.de_json()')
+
+        sticker = telegram.Sticker.de_json(self.json_dict)
+
+        self.assertEqual(sticker.file_id, self.sticker_file_id)
+        self.assertEqual(sticker.width, self.width)
+        self.assertEqual(sticker.height, self.height)
+        self.assertTrue(isinstance(sticker.thumb, telegram.PhotoSize))
+        self.assertEqual(sticker.file_size, self.file_size)
+
+    def test_sticker_to_json(self):
+        """Test Sticker.to_json() method"""
+        print('Testing Sticker.to_json()')
+
+        sticker = telegram.Sticker.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(sticker.to_json()))
+
+    def test_sticker_to_dict(self):
+        """Test Sticker.to_dict() method"""
+        print('Testing Sticker.to_dict()')
+
+        sticker = telegram.Sticker.de_json(self.json_dict)
+
+        self.assertEqual(sticker['file_id'], self.sticker_file_id)
+        self.assertEqual(sticker['width'], self.width)
+        self.assertEqual(sticker['height'], self.height)
+        self.assertTrue(isinstance(sticker['thumb'], telegram.PhotoSize))
+        self.assertEqual(sticker['file_size'], self.file_size)
+
+    def test_error_send_sticker_empty_file(self):
+        print('Testing bot.sendSticker - Null file')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        json_dict['sticker'] = open(os.devnull, 'rb')
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendSticker(chat_id=self._chat_id,
+                                                        **json_dict))
+
+    def test_error_send_sticker_empty_file_id(self):
+        print('Testing bot.sendSticker - Empty file_id')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        json_dict['sticker'] = ''
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendSticker(chat_id=self._chat_id,
+                                                         **json_dict))
+
+    def test_error_sticker_without_required_args(self):
+        print('Testing bot.sendSticker - Without required arguments')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+
+        self.assertRaises(TypeError,
+                          lambda: self._bot.sendSticker(chat_id=self._chat_id,
+                                                         **json_dict))
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_update.py

@@ -0,0 +1,82 @@
+  #!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Update"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class UpdateTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Update."""
+
+    def setUp(self):
+        self.update_id = 868573637
+        self.message = {'message_id': 319,
+                        'from': {'id': 12173560,
+                                 'first_name': "Leandro",
+                                 'last_name': "S.",
+                                 'username': "leandrotoledo"},
+                        'chat': {'id': 12173560,
+                                 'type': 'private',
+                                 'first_name': "Leandro",
+                                 'last_name': "S.",
+                                 'username': "leandrotoledo"},
+                        'date': 1441644592,
+                        'text': "Update Test"}
+
+        self.json_dict = {
+            'update_id': self.update_id,
+            'message': self.message
+        }
+
+    def test_update_de_json(self):
+        """Test Update.de_json() method"""
+        print('Testing Update.de_json()')
+
+        update = telegram.Update.de_json(self.json_dict)
+
+        self.assertEqual(update.update_id, self.update_id)
+        self.assertTrue(isinstance(update.message, telegram.Message))
+
+    def test_update_to_json(self):
+        """Test Update.to_json() method"""
+        print('Testing Update.to_json()')
+
+        update = telegram.Update.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(update.to_json()))
+
+    def test_update_to_dict(self):
+        """Test Update.to_dict() method"""
+        print('Testing Update.to_dict()')
+
+        update = telegram.Update.de_json(self.json_dict)
+
+        self.assertTrue(self.is_dict(update.to_dict()))
+        self.assertEqual(update['update_id'], self.update_id)
+        self.assertTrue(isinstance(update['message'], telegram.Message))
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_updater.py

@@ -0,0 +1,539 @@
+#!/usr/bin/env python
+# encoding: utf-8
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Updater, Dispatcher,
+WebhookServer and WebhookHandler
+"""
+import logging
+import sys
+import re
+import os
+import signal
+from random import randrange
+from time import sleep
+from datetime import datetime
+
+if sys.version_info[0:2] == (2, 6):
+    import unittest2 as unittest
+else:
+    import unittest
+
+try:
+    from urllib2 import urlopen, Request
+except ImportError:
+    from urllib.request import Request, urlopen
+
+sys.path.append('.')
+
+from telegram import Update, Message, TelegramError, User, Chat, Updater, Bot
+from telegram.dispatcher import run_async
+from tests.base import BaseTest
+from threading import Lock, Thread
+
+# Enable logging
+root = logging.getLogger()
+root.setLevel(logging.INFO)
+
+ch = logging.StreamHandler(sys.stdout)
+ch.setLevel(logging.WARN)
+formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+ch.setFormatter(formatter)
+root.addHandler(ch)
+
+
+class UpdaterTest(BaseTest, unittest.TestCase):
+    """
+    This object represents Tests for Updater, Dispatcher, WebhookServer and
+    WebhookHandler
+    """
+
+    def setUp(self):
+        self.updater = None
+        self.received_message = None
+        self.message_count = 0
+        self.lock = Lock()
+
+    def _setup_updater(self, *args, **kwargs):
+        bot = MockBot(*args, **kwargs)
+        self.updater = Updater(workers=2, bot=bot)
+
+    def tearDown(self):
+        if self.updater is not None:
+            self.updater.stop()
+
+    def reset(self):
+        self.message_count = 0
+        self.received_message = None
+
+    def telegramHandlerTest(self, bot, update):
+        self.received_message = update.message.text
+        self.message_count += 1
+
+    @run_async
+    def asyncHandlerTest(self, bot, update, **kwargs):
+        sleep(1)
+        with self.lock:
+            self.received_message = update.message.text
+            self.message_count += 1
+
+    def stringHandlerTest(self, bot, update):
+        self.received_message = update
+        self.message_count += 1
+
+    def regexGroupHandlerTest(self, bot, update, groups=None, groupdict=None):
+        self.received_message = (groups, groupdict)
+        self.message_count += 1
+
+    def additionalArgsTest(self, bot, update, update_queue, args):
+        self.received_message = update
+        self.message_count += 1
+        if args[0] == 'resend':
+            update_queue.put('/test5 noresend')
+        elif args[0] == 'noresend':
+            pass
+
+    @run_async
+    def asyncAdditionalHandlerTest(self, bot, update, update_queue=None,
+                                   **kwargs):
+        sleep(1)
+        with self.lock:
+            if update_queue is not None:
+                self.received_message = update.message.text
+                self.message_count += 1
+
+    def errorRaisingHandlerTest(self, bot, update):
+        raise TelegramError(update)
+
+    def errorHandlerTest(self, bot, update, error):
+        self.received_message = error.message
+        self.message_count += 1
+
+    def test_addRemoveTelegramMessageHandler(self):
+        print('Testing add/removeTelegramMessageHandler')
+        self._setup_updater('Test')
+        d = self.updater.dispatcher
+        d.addTelegramMessageHandler(
+            self.telegramHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(.1)
+        self.assertEqual(self.received_message, 'Test')
+
+        # Remove handler
+        d.removeTelegramMessageHandler(self.telegramHandlerTest)
+        self.reset()
+
+        self.updater.bot.send_messages = 1
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addTelegramMessageHandlerMultipleMessages(self):
+        print('Testing addTelegramMessageHandler and send 100 messages...')
+        self._setup_updater('Multiple', 100)
+        self.updater.dispatcher.addTelegramMessageHandler(
+            self.telegramHandlerTest)
+        self.updater.start_polling(0.0)
+        sleep(2)
+        self.assertEqual(self.received_message, 'Multiple')
+        self.assertEqual(self.message_count, 100)
+
+    def test_addRemoveTelegramRegexHandler(self):
+        print('Testing add/removeStringRegexHandler')
+        self._setup_updater('Test2')
+        d = self.updater.dispatcher
+        regobj = re.compile('Te.*')
+        self.updater.dispatcher.addTelegramRegexHandler(regobj,
+                                                        self.telegramHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(.1)
+        self.assertEqual(self.received_message, 'Test2')
+
+        # Remove handler
+        d.removeTelegramRegexHandler(regobj, self.telegramHandlerTest)
+        self.reset()
+
+        self.updater.bot.send_messages = 1
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveTelegramCommandHandler(self):
+        print('Testing add/removeTelegramCommandHandler')
+        self._setup_updater('/test')
+        d = self.updater.dispatcher
+        self.updater.dispatcher.addTelegramCommandHandler(
+            'test', self.telegramHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(.1)
+        self.assertEqual(self.received_message, '/test')
+
+        # Remove handler
+        d.removeTelegramCommandHandler('test', self.telegramHandlerTest)
+        self.reset()
+
+        self.updater.bot.send_messages = 1
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveUnknownTelegramCommandHandler(self):
+        print('Testing add/removeUnknownTelegramCommandHandler')
+        self._setup_updater('/test2')
+        d = self.updater.dispatcher
+        self.updater.dispatcher.addUnknownTelegramCommandHandler(
+            self.telegramHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(.1)
+        self.assertEqual(self.received_message, '/test2')
+
+        # Remove handler
+        d.removeUnknownTelegramCommandHandler(self.telegramHandlerTest)
+        self.reset()
+
+        self.updater.bot.send_messages = 1
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveStringRegexHandler(self):
+        print('Testing add/removeStringRegexHandler')
+        self._setup_updater('', messages=0)
+        d = self.updater.dispatcher
+        d.addStringRegexHandler('Te.*', self.stringHandlerTest)
+        queue = self.updater.start_polling(0.01)
+        queue.put('Test3')
+        sleep(.1)
+        self.assertEqual(self.received_message, 'Test3')
+
+        # Remove handler
+        d.removeStringRegexHandler('Te.*', self.stringHandlerTest)
+        self.reset()
+
+        queue.put('Test3')
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveStringCommandHandler(self):
+        print('Testing add/removeStringCommandHandler')
+        self._setup_updater('', messages=0)
+        d = self.updater.dispatcher
+        d.addStringCommandHandler(
+            'test3', self.stringHandlerTest)
+
+        queue = self.updater.start_polling(0.01)
+        queue.put('/test3')
+        sleep(.1)
+        self.assertEqual(self.received_message, '/test3')
+
+        # Remove handler
+        d.removeStringCommandHandler('test3', self.stringHandlerTest)
+        self.reset()
+
+        queue.put('/test3')
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveUnknownStringCommandHandler(self):
+        print('Testing add/removeUnknownStringCommandHandler')
+        self._setup_updater('/test')
+        d = self.updater.dispatcher
+        d.addUnknownStringCommandHandler(
+            self.stringHandlerTest)
+        queue = self.updater.start_polling(0.01)
+        queue.put('/test4')
+        sleep(.1)
+        self.assertEqual(self.received_message, '/test4')
+
+        # Remove handler
+        d.removeUnknownStringCommandHandler(self.stringHandlerTest)
+        self.reset()
+
+        self.updater.bot.send_messages = 1
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveErrorHandler(self):
+        print('Testing add/removeErrorHandler')
+        self._setup_updater('', messages=0)
+        d = self.updater.dispatcher
+        d.addErrorHandler(self.errorHandlerTest)
+        queue = self.updater.start_polling(0.01)
+        error = TelegramError("Unauthorized.")
+        queue.put(error)
+        sleep(.1)
+        self.assertEqual(self.received_message, "Unauthorized.")
+
+        # Remove handler
+        d.removeErrorHandler(self.errorHandlerTest)
+        self.reset()
+
+        queue.put(error)
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_errorInHandler(self):
+        print('Testing error in Handler')
+        self._setup_updater('', messages=0)
+        d = self.updater.dispatcher
+        d.addStringRegexHandler('.*',
+                                                self.errorRaisingHandlerTest)
+        self.updater.dispatcher.addErrorHandler(self.errorHandlerTest)
+        queue = self.updater.start_polling(0.01)
+
+        queue.put('Test Error 1')
+        sleep(.1)
+        self.assertEqual(self.received_message, 'Test Error 1')
+
+    def test_errorOnGetUpdates(self):
+        print('Testing error on getUpdates')
+        self._setup_updater('', raise_error=True)
+        d = self.updater.dispatcher
+        d.addErrorHandler(self.errorHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(.1)
+        self.assertEqual(self.received_message, "Test Error 2")
+
+    def test_addRemoveTypeHandler(self):
+        print('Testing add/removeTypeHandler')
+        self._setup_updater('', messages=0)
+        d = self.updater.dispatcher
+        d.addTypeHandler(dict, self.stringHandlerTest)
+        queue = self.updater.start_polling(0.01)
+        payload = {"Test": 42}
+        queue.put(payload)
+        sleep(.1)
+        self.assertEqual(self.received_message, payload)
+
+        # Remove handler
+        d.removeTypeHandler(dict, self.stringHandlerTest)
+        self.reset()
+
+        queue.put(payload)
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_runAsync(self):
+        print('Testing @run_async')
+        self._setup_updater('Test5', messages=2)
+        d = self.updater.dispatcher
+        d.addTelegramMessageHandler(
+            self.asyncHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(1.2)
+        self.assertEqual(self.received_message, 'Test5')
+        self.assertEqual(self.message_count, 2)
+
+    def test_additionalArgs(self):
+        print('Testing additional arguments for handlers')
+        self._setup_updater('', messages=0)
+        self.updater.dispatcher.addStringCommandHandler(
+            'test5', self.additionalArgsTest)
+
+        queue = self.updater.start_polling(0.01)
+        queue.put('/test5 resend')
+        sleep(.1)
+        self.assertEqual(self.received_message, '/test5 noresend')
+        self.assertEqual(self.message_count, 2)
+
+    def test_regexGroupHandler(self):
+        print('Testing optional groups and groupdict parameters')
+        self._setup_updater('', messages=0)
+        d = self.updater.dispatcher
+        d.addStringRegexHandler('^(This).*?(?P<testgroup>regex group).*',
+                                self.regexGroupHandlerTest)
+        queue = self.updater.start_polling(0.01)
+        queue.put('This is a test message for regex group matching.')
+        sleep(.1)
+        self.assertEqual(self.received_message, (('This', 'regex group'),
+                                                 {'testgroup': 'regex group'}))
+
+
+    def test_runAsyncWithAdditionalArgs(self):
+        print('Testing @run_async with additional parameters')
+        self._setup_updater('Test6', messages=2)
+        d = self.updater.dispatcher
+        d.addTelegramMessageHandler(
+            self.asyncAdditionalHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(1.2)
+        self.assertEqual(self.received_message, 'Test6')
+        self.assertEqual(self.message_count, 2)
+
+    def test_webhook(self):
+        print('Testing Webhook')
+        self._setup_updater('', messages=0)
+        d = self.updater.dispatcher
+        d.addTelegramMessageHandler(
+            self.telegramHandlerTest)
+
+        # Select random port for travis
+        port = randrange(1024, 49152)
+        self.updater.start_webhook('127.0.0.1', port,
+                                   url_path='TOKEN',
+                                   cert='./tests/test_updater.py',
+                                   key='./tests/test_updater.py')
+        sleep(0.5)
+        # SSL-Wrapping will fail, so we start the server without SSL
+        Thread(target=self.updater.httpd.serve_forever).start()
+
+        # Now, we send an update to the server via urlopen
+        message = Message(1, User(1, "Tester"), datetime.now(),
+                          Chat(1, "group", title="Test Group"))
+
+        message.text = "Webhook Test"
+        update = Update(1)
+        update.message = message
+
+        try:
+            payload = bytes(update.to_json(), encoding='utf-8')
+        except TypeError:
+            payload = bytes(update.to_json())
+
+        header = {
+            'content-type': 'application/json',
+            'content-length': str(len(payload))
+        }
+
+        r = Request('http://127.0.0.1:%d/TOKEN' % port,
+                    data=payload,
+                    headers=header)
+
+        urlopen(r)
+
+        sleep(1)
+        self.assertEqual(self.received_message, 'Webhook Test')
+
+        print("Test other webhook server functionalities...")
+        request = Request('http://localhost:%d/webookhandler.py' % port)
+        response = urlopen(request)
+        self.assertEqual(b'', response.read())
+        self.assertEqual(200, response.code)
+
+        request.get_method = lambda: 'HEAD'
+
+        response = urlopen(request)
+        self.assertEqual(b'', response.read())
+        self.assertEqual(200, response.code)
+
+        # Test multiple shutdown() calls
+        self.updater.httpd.shutdown()
+        self.updater.httpd.shutdown()
+        self.assertTrue(True)
+
+    def test_webhook_no_ssl(self):
+        print('Testing Webhook without SSL')
+        self._setup_updater('', messages=0)
+        d = self.updater.dispatcher
+        d.addTelegramMessageHandler(
+            self.telegramHandlerTest)
+
+        # Select random port for travis
+        port = randrange(1024, 49152)
+        self.updater.start_webhook('127.0.0.1', port)
+        sleep(0.5)
+
+        # Now, we send an update to the server via urlopen
+        message = Message(1, User(1, "Tester 2"), datetime.now(),
+                          Chat(1, 'group', title="Test Group 2"))
+
+        message.text = "Webhook Test 2"
+        update = Update(1)
+        update.message = message
+
+        try:
+            payload = bytes(update.to_json(), encoding='utf-8')
+        except TypeError:
+            payload = bytes(update.to_json())
+
+        header = {
+            'content-type': 'application/json',
+            'content-length': str(len(payload))
+        }
+
+        r = Request('http://127.0.0.1:%d/' % port,
+                    data=payload,
+                    headers=header)
+
+        urlopen(r)
+        sleep(1)
+        self.assertEqual(self.received_message, 'Webhook Test 2')
+
+    def signalsender(self):
+        sleep(0.5)
+        os.kill(os.getpid(), signal.SIGTERM)
+
+    def test_idle(self):
+        print('Testing idle')
+        self._setup_updater('Test6', messages=0)
+        self.updater.start_polling(poll_interval=0.01)
+        Thread(target=self.signalsender).start()
+        self.updater.idle()
+        # If we get this far, idle() ran through
+        sleep(1)
+        self.updater.running = False
+
+    def test_createBot(self):
+        updater = Updater('123:abcd')
+        self.assertIsNotNone(updater.bot)
+
+    def test_mutualExclusiveTokenBot(self):
+        bot = Bot('123:zyxw')
+        self.assertRaises(ValueError, Updater, token='123:abcd', bot=bot)
+
+    def test_noTokenOrBot(self):
+        self.assertRaises(ValueError, Updater)
+
+
+class MockBot:
+
+    def __init__(self, text, messages=1, raise_error=False):
+        self.text = text
+        self.send_messages = messages
+        self.raise_error = raise_error
+        self.token = "TOKEN"
+        pass
+
+    @staticmethod
+    def mockUpdate(text):
+        message = Message(0, None, None, None)
+        message.text = text
+        update = Update(0)
+        update.message = message
+        return update
+
+    def setWebhook(self, webhook_url=None, certificate=None):
+        pass
+
+    def getUpdates(self,
+                   offset=None,
+                   limit=100,
+                   timeout=0,
+                   network_delay=2.):
+
+        if self.raise_error:
+            raise TelegramError('Test Error 2')
+        elif self.send_messages >= 2:
+            self.send_messages -= 2
+            return self.mockUpdate(self.text), self.mockUpdate(self.text)
+        elif self.send_messages == 1:
+            self.send_messages -= 1
+            return self.mockUpdate(self.text),
+        else:
+            return []
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_user.py

@@ -0,0 +1,119 @@
+  #!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 User"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class UserTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram User."""
+
+    def setUp(self):
+        self.id = 12173560
+        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,
+            'type': self.type
+        }
+
+    def test_user_de_json(self):
+        """Test User.de_json() method"""
+        print('Testing User.de_json()')
+
+        user = telegram.User.de_json(self.json_dict)
+
+        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.username, self.username)
+        self.assertEqual(user.type, self.type)
+
+        self.assertEqual(user.name, '@leandrotoledo')
+
+    def test_user_de_json_without_username(self):
+        """Test User.de_json() method"""
+        print('Testing User.de_json() - Without username')
+
+        json_dict = self.json_dict
+
+        del(json_dict['username'])
+
+        user = telegram.User.de_json(self.json_dict)
+
+        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))
+
+
+    def test_user_de_json_without_username_and_lastname(self):
+        """Test User.de_json() method"""
+        print('Testing User.de_json() - Without username and last_name')
+
+        json_dict = self.json_dict
+
+        del(json_dict['username'])
+        del(json_dict['last_name'])
+
+        user = telegram.User.de_json(self.json_dict)
+
+        self.assertEqual(user.id, self.id)
+        self.assertEqual(user.first_name, self.first_name)
+
+        self.assertEqual(user.name, self.first_name)
+
+    def test_user_to_json(self):
+        """Test User.to_json() method"""
+        print('Testing User.to_json()')
+
+        user = telegram.User.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(user.to_json()))
+
+    def test_user_to_dict(self):
+        """Test User.to_dict() method"""
+        print('Testing User.to_dict()')
+
+        user = telegram.User.de_json(self.json_dict)
+
+        self.assertTrue(self.is_dict(user.to_dict()))
+        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['username'], self.username)
+        self.assertEqual(user['type'], self.type)
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_video.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Video"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class VideoTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Video."""
+
+    def setUp(self):
+        self.video_file = open('tests/data/telegram.mp4', 'rb')
+        self.video_file_id = 'BAADAQADXwADHyP1BwJFTcmY2RYCAg'
+        self.width = 360
+        self.height = 640
+        self.duration = 4
+        self.thumb = telegram.PhotoSize.de_json({})
+        self.mime_type = 'video/mp4'
+        self.file_size = 326534
+
+        # caption is part of sendVideo method but not Video object
+        self.caption = u'VideoTest - Caption'
+
+        self.json_dict = {
+            'file_id': self.video_file_id,
+            'width': self.width,
+            'height': self.height,
+            'duration': self.duration,
+            'thumb': self.thumb,
+            'mime_type': self.mime_type,
+            'file_size': self.file_size
+        }
+
+    def test_send_video_required_args_only(self):
+        """Test telegram.Bot sendVideo method"""
+        print('Testing bot.sendVideo - With required arguments only')
+
+        message = self._bot.sendVideo(self._chat_id,
+                                      self.video_file)
+
+        video = message.video
+
+        self.assertTrue(isinstance(video.file_id, str))
+        self.assertNotEqual(video.file_id, '')
+        self.assertEqual(video.width, 0)
+        self.assertEqual(video.height, 0)
+        self.assertEqual(video.duration, 0)
+        self.assertEqual(video.thumb, None)
+        self.assertEqual(video.mime_type, '')
+        self.assertEqual(video.file_size, self.file_size)
+
+    def test_send_video_all_args(self):
+        """Test telegram.Bot sendAudio method"""
+        print('Testing bot.sendVideo - With all arguments')
+
+        message = self._bot.sendVideo(self._chat_id,
+                                      self.video_file,
+                                      duration=self.duration,
+                                      caption=self.caption)
+
+        video = message.video
+
+        self.assertTrue(isinstance(video.file_id, str))
+        self.assertNotEqual(video.file_id, '')
+        self.assertEqual(video.width, 0)
+        self.assertEqual(video.height, 0)
+        self.assertEqual(video.duration, self.duration)
+        self.assertEqual(video.thumb, None)
+        self.assertEqual(video.mime_type, '')
+        self.assertEqual(video.file_size, self.file_size)
+
+        self.assertEqual(message.caption, self.caption)
+
+    def test_send_video_mp4_file(self):
+        """Test telegram.Bot sendVideo method"""
+        print('Testing bot.sendVideo - MP4 File')
+
+        message = self._bot.sendVideo(chat_id=self._chat_id,
+                                      video=self.video_file,
+                                      duration=self.duration,
+                                      caption=self.caption)
+
+        video = message.video
+
+        self.assertTrue(isinstance(video.file_id, str))
+        self.assertNotEqual(video.file_id, '')
+        self.assertEqual(video.width, 0)
+        self.assertEqual(video.height, 0)
+        self.assertEqual(video.duration, self.duration)
+        self.assertEqual(video.thumb, None)
+        self.assertEqual(video.mime_type, '')
+        self.assertEqual(video.file_size, self.file_size)
+
+        self.assertEqual(message.caption, self.caption)
+
+    def test_send_video_mp4_file_with_custom_filename(self):
+        """Test telegram.Bot sendVideo method"""
+        print('Testing bot.sendVideo - MP4 File with custom filename')
+
+        message = self._bot.sendVideo(chat_id=self._chat_id,
+                                      video=self.video_file,
+                                      duration=self.duration,
+                                      caption=self.caption,
+                                      filename='telegram_custom.mp4')
+
+        video = message.video
+
+        self.assertTrue(isinstance(video.file_id, str))
+        self.assertNotEqual(video.file_id, '')
+        self.assertEqual(video.width, 0)
+        self.assertEqual(video.height, 0)
+        self.assertEqual(video.duration, self.duration)
+        self.assertEqual(video.thumb, None)
+        self.assertEqual(video.mime_type, '')
+        self.assertEqual(video.file_size, self.file_size)
+
+        self.assertEqual(message.caption, self.caption)
+
+    def test_send_video_resend(self):
+        """Test telegram.Bot sendVideo method"""
+        print('Testing bot.sendVideo - Resend by file_id')
+
+        message = self._bot.sendVideo(chat_id=self._chat_id,
+                                      video=self.video_file_id,
+                                      duration=self.duration,
+                                      caption=self.caption)
+
+        video = message.video
+
+        self.assertEqual(video.file_id, self.video_file_id)
+        self.assertEqual(video.duration, 0)
+        self.assertEqual(video.thumb, None)
+        self.assertEqual(video.mime_type, '')
+
+        self.assertEqual(message.caption, self.caption)
+
+    def test_video_de_json(self):
+        """Test Video.de_json() method"""
+        print('Testing Video.de_json()')
+
+        video = telegram.Video.de_json(self.json_dict)
+
+        self.assertEqual(video.file_id, self.video_file_id)
+        self.assertEqual(video.width, self.width)
+        self.assertEqual(video.height, self.height)
+        self.assertEqual(video.duration, self.duration)
+        self.assertEqual(video.thumb, None)
+        self.assertEqual(video.mime_type, self.mime_type)
+        self.assertEqual(video.file_size, self.file_size)
+
+    def test_video_to_json(self):
+        """Test Video.to_json() method"""
+        print('Testing Video.to_json()')
+
+        video = telegram.Video.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(video.to_json()))
+
+    def test_video_to_dict(self):
+        """Test Video.to_dict() method"""
+        print('Testing Video.to_dict()')
+
+        video = telegram.Video.de_json(self.json_dict)
+
+        self.assertTrue(self.is_dict(video.to_dict()))
+        self.assertEqual(video['file_id'], self.video_file_id)
+        self.assertEqual(video['width'], self.width)
+        self.assertEqual(video['height'], self.height)
+        self.assertEqual(video['duration'], self.duration)
+        self.assertEqual(video['mime_type'], self.mime_type)
+        self.assertEqual(video['file_size'], self.file_size)
+
+    def test_error_send_video_empty_file(self):
+        print('Testing bot.sendVideo - Null file')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        json_dict['video'] = open(os.devnull, 'rb')
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendVideo(chat_id=self._chat_id,
+                                                      **json_dict))
+
+    def test_error_send_video_empty_file_id(self):
+        print('Testing bot.sendVideo - Empty file_id')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        json_dict['video'] = ''
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendVideo(chat_id=self._chat_id,
+                                                      **json_dict))
+
+    def test_error_video_without_required_args(self):
+        print('Testing bot.sendVideo - Without required arguments')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        del(json_dict['duration'])
+
+        self.assertRaises(TypeError,
+                          lambda: self._bot.sendVideo(chat_id=self._chat_id,
+                                                      **json_dict))
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_voice.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# 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 Voice"""
+
+import os
+import unittest
+import sys
+sys.path.append('.')
+
+import telegram
+from tests.base import BaseTest
+
+
+class VoiceTest(BaseTest, unittest.TestCase):
+    """This object represents Tests for Telegram Voice."""
+
+    def setUp(self):
+        self.voice_file = open('tests/data/telegram.ogg', 'rb')
+        self.voice_file_id = 'AwADAQADTgADHyP1B_mbw34svXPHAg'
+        self.duration = 0
+        self.mime_type = 'audio/ogg'
+        self.file_size = 9199
+
+        self.json_dict = {
+            'file_id': self.voice_file_id,
+            'duration': self.duration,
+            'mime_type': self.mime_type,
+            'file_size': self.file_size
+        }
+
+    def test_send_voice_required_args_only(self):
+        """Test telegram.Bot sendVoice method"""
+        print('Testing bot.sendVoice - With required arguments only')
+
+        message = self._bot.sendVoice(self._chat_id,
+                                      self.voice_file)
+
+        voice = message.voice
+
+        self.assertTrue(isinstance(voice.file_id, str))
+        self.assertNotEqual(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_send_voice_all_args(self):
+        """Test telegram.Bot sendAudio method"""
+        print('Testing bot.sendVoice - With all arguments')
+
+        message = self._bot.sendVoice(self._chat_id,
+                                      self.voice_file,
+                                      self.duration,
+                                      mime_type=self.mime_type,
+                                      file_size=self.file_size)
+
+        voice = message.voice
+
+        self.assertTrue(isinstance(voice.file_id, str))
+        self.assertNotEqual(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_send_voice_ogg_file(self):
+        """Test telegram.Bot sendVoice method"""
+        print('Testing bot.sendVoice - Ogg File')
+
+        message = self._bot.sendVoice(chat_id=self._chat_id,
+                                      voice=self.voice_file,
+                                      duration=self.duration)
+
+        voice = message.voice
+
+        self.assertTrue(isinstance(voice.file_id, str))
+        self.assertNotEqual(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_send_voice_ogg_file_with_custom_filename(self):
+        """Test telegram.Bot sendVoice method"""
+        print('Testing bot.sendVoice - Ogg File with custom filename')
+
+        message = self._bot.sendVoice(chat_id=self._chat_id,
+                                      voice=self.voice_file,
+                                      duration=self.duration,
+                                      filename='telegram_custom.ogg')
+
+        voice = message.voice
+
+        self.assertTrue(isinstance(voice.file_id, str))
+        self.assertNotEqual(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_send_voice_resend(self):
+        """Test telegram.Bot sendVoice method"""
+        print('Testing bot.sendVoice - Resend by file_id')
+
+        message = self._bot.sendVoice(chat_id=self._chat_id,
+                                      voice=self.voice_file_id,
+                                      duration=self.duration)
+
+        voice = message.voice
+
+        self.assertEqual(voice.file_id, self.voice_file_id)
+        self.assertEqual(voice.duration, self.duration)
+        self.assertEqual(voice.mime_type, self.mime_type)
+
+    def test_voice_de_json(self):
+        """Test Voice.de_json() method"""
+        print('Testing Voice.de_json()')
+
+        voice = telegram.Voice.de_json(self.json_dict)
+
+        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_to_json(self):
+        """Test Voice.to_json() method"""
+        print('Testing Voice.to_json()')
+
+        voice = telegram.Voice.de_json(self.json_dict)
+
+        self.assertTrue(self.is_json(voice.to_json()))
+
+    def test_voice_to_dict(self):
+        """Test Voice.to_dict() method"""
+        print('Testing Voice.to_dict()')
+
+        voice = telegram.Voice.de_json(self.json_dict)
+
+        self.assertTrue(self.is_dict(voice.to_dict()))
+        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_error_send_voice_empty_file(self):
+        print('Testing bot.sendVoice - Null file')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        json_dict['voice'] = open(os.devnull, 'rb')
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendVoice(chat_id=self._chat_id,
+                                                      **json_dict))
+
+    def test_error_send_voice_empty_file_id(self):
+        print('Testing bot.sendVoice - Empty file_id')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        json_dict['voice'] = ''
+
+        self.assertRaises(telegram.TelegramError,
+                          lambda: self._bot.sendVoice(chat_id=self._chat_id,
+                                                      **json_dict))
+
+    def test_error_voice_without_required_args(self):
+        print('Testing bot.sendVoice - Without required arguments')
+
+        json_dict = self.json_dict
+
+        del(json_dict['file_id'])
+        del(json_dict['duration'])
+
+        self.assertRaises(TypeError,
+                          lambda: self._bot.sendVoice(chat_id=self._chat_id,
+                                                      **json_dict))
+
+if __name__ == '__main__':
+    unittest.main()