Bump version to v6.0.1

* add support for User.language_code

* Add language filter

Useful is you wanna do something like restrict your shop to a single or a few locales or something like that.

.coveragerc

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

.github/CONTRIBUTING.rst

@@ -85,6 +85,12 @@ Here's how to make a one-off code change.
 
         $ make test
 
+     If you don't have ``make``, do:
+
+     .. code-block::
+
+        $ nosetests -v
+
    - To actually make the commit (this will trigger tests for yapf, lint and pep8 automatically):
 
      .. code-block:: bash
@@ -184,11 +190,11 @@ break the API classes. For example:
 .. code-block:: python
 
     # GOOD
-    def __init__(self, id, name, **kwargs):
-       self.last_name = kwargs.get('last_name', '')
+    def __init__(self, id, name, last_name=None, **kwargs):
+       self.last_name = last_name
 
     # BAD
-    def __init__(self, id, name, last_name=''):
+    def __init__(self, id, name, last_name=None):
        self.last_name = last_name
 
 

.github/ISSUE_TEMPLATE.md

@@ -1,6 +1,10 @@
 <!--
 Thanks for reporting issues of python-telegram-bot!
 To make it easier for us to help you please enter detailed information below.
+
+Please note, we only support the latest version of python-telegram-bot and
+master branch. Please make sure to upgrade & recreate the issue on the latest
+version prior to opening an issue.
 -->
 ### Steps to reproduce
 1.
@@ -19,13 +23,9 @@ Tell us what happens instead
 **Operating System:**
 
 
-**Version of Python:**
+**Version of Python, python-telegram-bot & dependencies:**
 
-``$ python -V``
-
-**Version of python-telegram-bot:**
-
-``$ python -c 'import telegram; print(telegram.__version__)'``
+``$ python -m telegram``
 
 ### Logs
 Insert logs here (if necessary)

.gitignore

@@ -68,3 +68,9 @@ telegram.mp4
 telegram.ogg
 telegram.png
 telegram.webp
+
+# original files from merges
+*.orig
+
+# Exclude .exrc file for Vim
+.exrc

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "telegram/vendor/urllib3"]
+	path = telegram/vendor/urllib3
+	url = https://github.com/python-telegram-bot/urllib3.git
+	branch = ptb

.pre-commit-config.yaml

@@ -1,15 +1,15 @@
--   repo: git://github.com/pre-commit/mirrors-yapf
-    sha: 316b795b2f32cbe80047aff7e842b72368d5a2c1
+-   repo: git://github.com/python-telegram-bot/mirrors-yapf
+    sha: v0.12.2
     hooks:
     -   id: yapf
         files: ^(telegram|tests)/.*\.py$
 -   repo: git://github.com/pre-commit/pre-commit-hooks
-    sha: 3fa02652357ff0dbb42b5bc78c673b7bc105fcf3
+    sha: 18d7035de5388cc7775be57f529c154bf541aab9
     hooks:
     -   id: flake8
         files: ^telegram/.*\.py$
 -   repo: git://github.com/pre-commit/mirrors-pylint
-    sha: 4de6c8dfadef1a271a814561ce05b8bc1c446d22
+    sha: v1.5.5
     hooks:
     -   id: pylint
         files: ^telegram/.*\.py$

.travis.yml

@@ -1,18 +1,22 @@
 language: python
 python:
-  - "2.6"
   - "2.7"
   - "3.3"
   - "3.4"
   - "3.5"
+  - "3.6"
   - "pypy"
   - "pypy3"
+branches:
+  only:
+    - master
 install:
   - pip install coveralls
   - pip install -r requirements.txt
   - pip install -r requirements-dev.txt
+  - if [[ $TRAVIS_PYTHON_VERSION != 'pypy'* ]]; then pip install ujson; fi
 script:
-  - nosetests -v --with-flaky --no-flaky-report --with-coverage --cover-package=telegram/
-  - 'if [ $TRAVIS_PYTHON_VERSION != 2.6 ] && [ $TRAVIS_PYTHON_VERSION != 3.3 ] && [ $TRAVIS_PYTHON_VERSION != pypy3 ]; then pre-commit run --all-files; fi'
+  - nosetests -v --with-flaky --no-flaky-report --with-coverage --cover-package=telegram/ tests
+  - if [[ $TRAVIS_PYTHON_VERSION == 3.5 ]]; then pre-commit run --all-files; fi
 after_success:
   coveralls

AUTHORS.rst

@@ -1,7 +1,14 @@
 Credits
 =======
 
-``python-telegram-bot`` is written and maintained by `Leandro Toledo <https://github.com/leandrotoledo>`_.
+``python-telegram-bot`` was originally created by
+`Leandro Toledo <https://github.com/leandrotoledo>`_ and is now maintained by
+`Jannes Höke <https://github.com/jh0ker>`_ (`@jh0ker <https://t.me/jh0ker>`_ on Telegram) and
+`Noam Meltzer <https://github.com/tsnoam>`_.
+
+We're vendoring urllib3 as part of ``python-telegram-bot`` which is distributed under the MIT
+license. For more info, full credits & license terms, the sources can be found here:
+`https://github.com/python-telegram-bot/urllib3`.
 
 Contributors
 ------------
@@ -9,23 +16,43 @@ Contributors
 The following wonderful people contributed directly or indirectly to this project:
 
 - `Avanatiker <https://github.com/Avanatiker>`_
+- `Anton Tagunov <https://github.com/anton-tagunov>`_
 - `Balduro <https://github.com/Balduro>`_
 - `bimmlerd <https://github.com/bimmlerd>`_
+- `d-qoi <https://github.com/d-qoi>`_
+- `daimajia <https://github.com/daimajia>`_
+- `Eli Gao <https://github.com/eligao>`_
 - `ErgoZ Riftbit Vaper <https://github.com/ergoz>`_
+- `Eugene Lisitsky <https://github.com/lisitsky>`_
+- `evgfilim1 <https://github.com/evgfilim1>`_
 - `franciscod <https://github.com/franciscod>`_
+- `Hugo Damer <https://github.com/HakimusGIT>`_
+- `Jacob Bom <https://github.com/bomjacob>`_
 - `JASON0916 <https://github.com/JASON0916>`_
 - `jh0ker <https://github.com/jh0ker>`_
+- `John Yong <https://github.com/whipermr5>`_
+- `jossalgon <https://github.com/jossalgon>`_
 - `JRoot3D <https://github.com/JRoot3D>`_
 - `jlmadurga <https://github.com/jlmadurga>`_
+- `Kjwon15 <https://github.com/kjwon15>`_
+- `Li-aung Yip <https://github.com/LiaungYip>`_
 - `macrojames <https://github.com/macrojames>`_
+- `Michael Elovskikh <https://github.com/wronglink>`_
 - `naveenvhegde <https://github.com/naveenvhegde>`_
+- `neurrone <https://github.com/neurrone>`_
 - `njittam <https://github.com/njittam>`_
 - `Noam Meltzer <https://github.com/tsnoam>`_
 - `Oleg Shlyazhko <https://github.com/ollmer>`_
+- `overquota <https://github.com/overquota>`_
+- `Patrick Hofmann <https://github.com/PH89>`_
+- `Pieter Schutz <https://github.com/eldinnie>`_
 - `Rahiel Kasim <https://github.com/rahiel>`_
+- `Joscha Götzer <https://github.com/Rostgnom>`_
 - `Shelomentsev D <https://github.com/shelomentsevd>`_
 - `sooyhwang <https://github.com/sooyhwang>`_
+- `thodnev <https://github.com/thodnev>`_
 - `Valentijn <https://github.com/Faalentijn>`_
+- `voider1 <https://github.com/voider1>`_
 - `wjt <https://github.com/wjt>`_
 
 Please add yourself here alphabetically when you submit your first pull request.

CHANGES.rst

@@ -2,6 +2,78 @@
 Changes
 =======
 
+**2017-05-21**
+
+*Released 6.0.1*
+
+- Add support for ``User.language_code``
+- Fix ``Message.text_html`` and ``Message.text_markdown`` for messages with emoji
+
+**2017-05-19**
+
+*Released 6.0.0*
+
+- Add support for Bot API 2.3.1
+- Add support for ``deleteMessage`` API method
+- New, simpler API for ``JobQueue`` - https://github.com/python-telegram-bot/python-telegram-bot/pull/484
+- Download files into file-like objects - https://github.com/python-telegram-bot/python-telegram-bot/pull/459
+- Use vendor ``urllib3`` to address issues with timeouts
+  - The default timeout for messages is now 5 seconds. For sending media, the default timeout is now 20 seconds.
+- String attributes that are not set are now ``None`` by default, instead of empty strings
+- Add ``text_markdown`` and ``text_html`` properties to ``Message`` - https://github.com/python-telegram-bot/python-telegram-bot/pull/507
+- Add support for Socks5 proxy - https://github.com/python-telegram-bot/python-telegram-bot/pull/518
+- Add support for filters in ``CommandHandler`` - https://github.com/python-telegram-bot/python-telegram-bot/pull/536
+- Add the ability to invert (not) filters - https://github.com/python-telegram-bot/python-telegram-bot/pull/552
+- Add ``Filters.group`` and ``Filters.private``
+- Compatibility with GAE via ``urllib3.contrib`` package - https://github.com/python-telegram-bot/python-telegram-bot/pull/583
+- Add equality rich comparision operators to telegram objects - https://github.com/python-telegram-bot/python-telegram-bot/pull/604
+- Several bugfixes and other improvements
+- Remove some deprecated code
+
+**2017-04-17**
+
+*Released 5.3.1*
+
+- Hotfix release due to bug introduced by urllib3 version 1.21
+
+**2016-12-11**
+
+*Released 5.3*
+
+- Implement API changes of November 21st (Bot API 2.3)
+- ``JobQueue`` now supports ``datetime.timedelta`` in addition to seconds
+- ``JobQueue`` now supports running jobs only on certain days
+- New ``Filters.reply`` filter
+- Bugfix for ``Message.edit_reply_markup``
+- Other bugfixes
+
+**2016-10-25**
+
+*Released 5.2*
+
+- Implement API changes of October 3rd (games update)
+- Add ``Message.edit_*`` methods
+- Filters for the ``MessageHandler`` can now be combined using bitwise operators (``& and |``)
+- Add a way to save user- and chat-related data temporarily
+- Other bugfixes and improvements
+
+**2016-09-24**
+
+*Released 5.1*
+
+- Drop Python 2.6 support
+- Deprecate ``telegram.Emoji``
+
+- Use ``ujson`` if available
+- Add instance methods to ``Message``, ``Chat``, ``User``, ``InlineQuery`` and ``CallbackQuery``
+- RegEx filtering for ``CallbackQueryHandler`` and ``InlineQueryHandler``
+- New ``MessageHandler`` filters: ``forwarded`` and ``entity``
+- Add ``Message.get_entity`` to correctly handle UTF-16 codepoints and ``MessageEntity`` offsets
+- Fix bug in ``ConversationHandler`` when first handler ends the conversation
+- Allow multiple ``Dispatcher`` instances
+- Add ``ChatMigrated`` Exception
+- Properly split and handle arguments in ``CommandHandler``
+
 **2016-07-15**
 
 *Released 5.0*

README.rst

@@ -1,9 +1,9 @@
 .. 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
+   :target: https://python-telegram-bot.org
    :alt: python-telegram-bot Logo
 
-Not **just** a Python wrapper around the Telegram Bot API
+We have made you a wrapper you can't refuse
 
 *Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_.
 
@@ -16,7 +16,7 @@ Not **just** a Python wrapper around the Telegram Bot API
    :alt: Supported python versions
 
 .. image:: https://img.shields.io/badge/docs-latest-af1a97.svg
-   :target: https://pythonhosted.org/python-telegram-bot/
+   :target: https://python-telegram-bot.readthedocs.io/
    :alt: Documentation Status
 
 .. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg
@@ -37,7 +37,7 @@ Not **just** a Python wrapper around the Telegram Bot API
    
 .. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
    :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
-   :alt: Average time to resolve an issue
+   :alt: Median time to resolve an issue
 
 .. image:: https://img.shields.io/badge/Telegram-Group-blue.svg
    :target: https://telegram.me/pythontelegrambotgroup
@@ -73,8 +73,7 @@ Introduction
 
 This library provides a pure Python interface for the
 `Telegram Bot API <https://core.telegram.org/bots/api>`_.
-It works with Python versions from 2.6+ (**Note:** Support for 2.6 will be dropped at some point
-this year. 2.7 will still be supported).
+It's compatible with Python versions 2.7, 3.3+ and `PyPy <http://pypy.org/>`_.
 It also works with `Google App Engine <https://cloud.google.com/appengine>`_.
 
 In addition to the pure API implementation, this library features a number of high-level classes to
@@ -85,7 +84,7 @@ make the development of bots easy and straightforward. These classes are contain
 Telegram API support
 ====================
 
-As of **28. May 2016**, all types and methods of the Telegram Bot API are supported.
+As of **4. Dec 2016**, all types and methods of the Telegram Bot API are supported.
 
 ==========
 Installing
@@ -97,6 +96,20 @@ You can install or upgrade python-telegram-bot with:
 
     $ pip install python-telegram-bot --upgrade
 
+Or you can install from source with:
+
+.. code:: shell
+
+    $ git clone https://github.com/python-telegram-bot/python-telegram-bot --recursive
+    $ cd python-telegram-bot
+    $ python setup.py install
+    
+In case you have a previously cloned local repository already, you should initialize the added urllib3 submodule before installing with:
+
+.. code:: shell
+
+    $ git submodule update --init --recursive
+
 ===============
 Getting started
 ===============
@@ -109,7 +122,7 @@ Our Wiki contains a lot of resources to get you started with ``python-telegram-b
 Other references:
 
 - `Telegram API documentation <https://core.telegram.org/bots/api>`_
-- `python-telegram-bot documentation <https://pythonhosted.org/python-telegram-bot/>`_
+- `python-telegram-bot documentation <https://python-telegram-bot.readthedocs.io/>`_
 
 -------------------
 Learning by example
@@ -117,21 +130,11 @@ Learning by example
 
 We believe that the best way to learn and understand this simple package is by example. So here
 are some examples for you to review. Even if it's not your approach for learning, please take a
-look at ``echobot2`` (below), it is de facto the base for most of the bots out there. Best of all,
+look at ``echobot2``, it is de facto the base for most of the bots out there. Best of all,
 the code for these examples are released to the public domain, so you can start by grabbing the
 code and building on top of it.
 
-- `echobot2 <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot2.py>`_ replies back messages.
-
-- `inlinebot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinebot.py>`_ basic example of an `inline bot <https://core.telegram.org/bots/inline>`_.
-
-- `state machine bot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/state_machine_bot.py>`_ keeps the state for individual users, useful for multipart conversations.
-
-- `timerbot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/timerbot.py>`_ uses the ``JobQueue`` to send timed messages.
-
-- `echobot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/legacy/echobot.py>`_ uses only the pure API to echo messages.
-
-Look at the examples on the `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Examples>`_ to see other bots the community has built.
+Visit `this page <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ to discover the official examples or look at the examples on the `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Examples>`_ to see other bots the community has built.
 
 -------
 Logging
@@ -165,7 +168,7 @@ If you want DEBUG logs instead:
 Documentation
 =============
 
-``python-telegram-bot``'s documentation lives at `pythonhosted.org <https://pythonhosted.org/python-telegram-bot/>`_.
+``python-telegram-bot``'s documentation lives at `readthedocs.io <https://python-telegram-bot.readthedocs.io/>`_.
 
 ============
 Getting help

docs/source/conf.py

@@ -15,7 +15,7 @@
 import sys
 import os
 import shlex
-import telegram
+# import telegram
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -51,7 +51,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Python Telegram Bot'
-copyright = u'2015-2016, Leandro Toledo'
+copyright = u'2015-2017, Leandro Toledo'
 author = u'Leandro Toledo'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -59,9 +59,9 @@ author = u'Leandro Toledo'
 # built documents.
 #
 # The short X.Y version.
-version = telegram.__version__[:3]
+version = '6.0'  # telegram.__version__[:3]
 # The full version, including alpha/beta/rc tags.
-release = telegram.__version__
+release = '6.0.1'  # telegram.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -131,7 +131,7 @@ html_theme = 'sphinx_rtd_theme'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = 'ptb-logo-orange.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -209,14 +209,17 @@ htmlhelp_basename = 'PythonTelegramBotdoc'
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
+
 # The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+    'papersize': 'a4paper',
 
 # The font size ('10pt', '11pt' or '12pt').
 #'pointsize': '10pt',
 
 # Additional stuff for the LaTeX preamble.
-#'preamble': '',
+    'preamble': r'''\setcounter{tocdepth}{2}
+\usepackage{enumitem}
+\setlistdepth{99}''',
 
 # Latex figure (float) alignment
 #'figure_align': 'htbp',
@@ -227,12 +230,12 @@ latex_elements = {
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
   (master_doc, 'PythonTelegramBot.tex', u'Python Telegram Bot Documentation',
-   u'Leandro Toledo', 'manual'),
+   author, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-#latex_logo = None
+latex_logo = 'ptb-logo_1024.png'
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
@@ -271,7 +274,7 @@ man_pages = [
 #  dir menu entry, description, category)
 texinfo_documents = [
   (master_doc, 'PythonTelegramBot', u'Python Telegram Bot Documentation',
-   author, 'PythonTelegramBot', 'Not just a Python wrapper around the Telegram Bot API',
+   author, 'PythonTelegramBot', "We have made you a wrapper you can't refuse",
    'Miscellaneous'),
 ]
 

docs/source/index.rst

@@ -6,12 +6,8 @@
 Welcome to Python Telegram Bot's documentation!
 ===============================================
 
-Contents:
-   telegram
-
 .. toctree::
-   :maxdepth: 2
-
+   telegram
 
 
 Indices and tables

docs/source/modules.rst

@@ -1,7 +0,0 @@
-telegram
-========
-
-.. toctree::
-   :maxdepth: 4
-
-   telegram

docs/source/telegram.animation.rst

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

docs/source/telegram.callbackgame.rst

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

docs/source/telegram.callbackquery.rst

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

docs/source/telegram.chatmember.rst

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

docs/source/telegram.contrib.rst

@@ -0,0 +1,17 @@
+telegram.contrib package
+========================
+
+Submodules
+----------
+
+.. toctree::
+
+    telegram.contrib.botan
+
+Module contents
+---------------
+
+.. automodule:: telegram.contrib
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/telegram.ext.filters.rst

@@ -1,7 +1,7 @@
-telegram.nullhandler module
+telegram.ext.filters module
 ===========================
 
-.. automodule:: telegram.nullhandler
+.. automodule:: telegram.ext.filters
     :members:
     :undoc-members:
     :show-inheritance:

docs/source/telegram.ext.messagequeue.rst

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

docs/source/telegram.ext.rst

@@ -10,11 +10,14 @@ Submodules
     telegram.ext.dispatcher
     telegram.ext.jobqueue
     telegram.ext.handler
+    telegram.ext.callbackqueryhandler
     telegram.ext.choseninlineresulthandler
     telegram.ext.conversationhandler
     telegram.ext.commandhandler
     telegram.ext.inlinequeryhandler
     telegram.ext.messagehandler
+    telegram.ext.messagequeue
+    telegram.ext.filters
     telegram.ext.regexhandler
     telegram.ext.stringcommandhandler
     telegram.ext.stringregexhandler

docs/source/telegram.file.rst

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

docs/source/telegram.game.rst

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

docs/source/telegram.gamehighscore.rst

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

docs/source/telegram.inlinekeyboardbutton.rst

@@ -1,5 +1,5 @@
 telegram.inlinekeyboardbutton module
-===========================
+====================================
 
 .. automodule:: telegram.inlinekeyboardbutton
     :members:

docs/source/telegram.inlinekeyboardmarkup.rst

@@ -1,5 +1,5 @@
 telegram.inlinekeyboardmarkup module
-==========================
+====================================
 
 .. automodule:: telegram.inlinekeyboardmarkup
     :members:

docs/source/telegram.inlinequeryresultarticle.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultarticle module
-=================================
+========================================
 
 .. automodule:: telegram.inlinequeryresultarticle
     :members:

docs/source/telegram.inlinequeryresultaudio.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultaudio module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultaudio
     :members:

docs/source/telegram.inlinequeryresultcachedaudio.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedaudio module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedaudio
     :members:

docs/source/telegram.inlinequeryresultcacheddocument.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcacheddocument module
-=================================
+===============================================
 
 .. automodule:: telegram.inlinequeryresultcacheddocument
     :members:

docs/source/telegram.inlinequeryresultcachedgif.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedgif module
-=================================
+==========================================
 
 .. automodule:: telegram.inlinequeryresultcachedgif
     :members:

docs/source/telegram.inlinequeryresultcachedmpeg4gif.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedmpeg4gif module
-=================================
+===============================================
 
 .. automodule:: telegram.inlinequeryresultcachedmpeg4gif
     :members:

docs/source/telegram.inlinequeryresultcachedphoto.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedphoto module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedphoto
     :members:

docs/source/telegram.inlinequeryresultcachedsticker.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedsticker module
-=================================
+==============================================
 
 .. automodule:: telegram.inlinequeryresultcachedsticker
     :members:

docs/source/telegram.inlinequeryresultcachedvideo.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedvideo module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedvideo
     :members:

docs/source/telegram.inlinequeryresultcachedvoice.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcachedvoice module
-=================================
+============================================
 
 .. automodule:: telegram.inlinequeryresultcachedvoice
     :members:

docs/source/telegram.inlinequeryresultcontact.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultcontact module
-=================================
+========================================
 
 .. automodule:: telegram.inlinequeryresultcontact
     :members:

docs/source/telegram.inlinequeryresultdocument.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultdocument module
-=================================
+=========================================
 
 .. automodule:: telegram.inlinequeryresultdocument
     :members:

docs/source/telegram.inlinequeryresultgame.rst

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

docs/source/telegram.inlinequeryresultgif.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultgif module
-=================================
+====================================
 
 .. automodule:: telegram.inlinequeryresultgif
     :members:

docs/source/telegram.inlinequeryresultlocation.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultlocation module
-=================================
+=========================================
 
 .. automodule:: telegram.inlinequeryresultlocation
     :members:

docs/source/telegram.inlinequeryresultmpeg4gif.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultmpeg4gif module
-=================================
+=========================================
 
 .. automodule:: telegram.inlinequeryresultmpeg4gif
     :members:

docs/source/telegram.inlinequeryresultphoto.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultphoto module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultphoto
     :members:

docs/source/telegram.inlinequeryresultvenue.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultvenue module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultvenue
     :members:

docs/source/telegram.inlinequeryresultvideo.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultvideo module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultvideo
     :members:

docs/source/telegram.inlinequeryresultvoice.rst

@@ -1,5 +1,5 @@
 telegram.inlinequeryresultvoice module
-=================================
+======================================
 
 .. automodule:: telegram.inlinequeryresultvoice
     :members:

docs/source/telegram.inputcontactmessagecontent.rst

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

docs/source/telegram.inputlocationmessagecontent.rst

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

docs/source/telegram.inputmessagecontent.rst

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

docs/source/telegram.inputtextmessagecontent.rst

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

docs/source/telegram.inputvenuemessagecontent.rst

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

docs/source/telegram.keyboardbutton.rst

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

docs/source/telegram.messageentity.rst

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

docs/source/telegram.parsemode.rst

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

docs/source/telegram.replykeyboardhide.rst

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

docs/source/telegram.replykeyboardremove.rst

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

docs/source/telegram.rst

@@ -6,14 +6,30 @@ Submodules
 
 .. toctree::
 
+   telegram.contrib
+   telegram.ext
+   telegram.animation
    telegram.audio
    telegram.base
    telegram.bot
-   telegram.ext
-   telegram.inlinequery
-   telegram.inlinequeryresult
+   telegram.callbackgame
+   telegram.callbackquery
+   telegram.chat
+   telegram.chataction
+   telegram.chatmember
+   telegram.choseninlineresult
+   telegram.constants
+   telegram.contact
+   telegram.document
+   telegram.error
+   telegram.file
+   telegram.forcereply
+   telegram.game
+   telegram.gamehighscore
    telegram.inlinekeyboardbutton
    telegram.inlinekeyboardmarkup
+   telegram.inlinequery
+   telegram.inlinequeryresult
    telegram.inlinequeryresultarticle
    telegram.inlinequeryresultaudio
    telegram.inlinequeryresultcachedaudio
@@ -26,6 +42,7 @@ Submodules
    telegram.inlinequeryresultcachedvoice
    telegram.inlinequeryresultcontact
    telegram.inlinequeryresultdocument
+   telegram.inlinequeryresultgame
    telegram.inlinequeryresultgif
    telegram.inlinequeryresultlocation
    telegram.inlinequeryresultmpeg4gif
@@ -33,28 +50,29 @@ Submodules
    telegram.inlinequeryresultvenue
    telegram.inlinequeryresultvideo
    telegram.inlinequeryresultvoice
-   telegram.choseninlineresult
-   telegram.chataction
-   telegram.contact
-   telegram.document
-   telegram.emoji
-   telegram.error
-   telegram.forcereply
-   telegram.chat
+   telegram.inputcontactmessagecontent
    telegram.inputfile
+   telegram.inputlocationmessagecontent
+   telegram.inputmessagecontent
+   telegram.inputtextmessagecontent
+   telegram.inputvenuemessagecontent
+   telegram.keyboardbutton
    telegram.location
    telegram.message
-   telegram.nullhandler
+   telegram.messageentity
+   telegram.parsemode
    telegram.photosize
-   telegram.replykeyboardhide
+   telegram.replykeyboardremove
    telegram.replykeyboardmarkup
    telegram.replymarkup
    telegram.sticker
    telegram.update
    telegram.user
    telegram.userprofilephotos
+   telegram.venue
    telegram.video
    telegram.voice
+   telegram.webhookinfo
 
 Module contents
 ---------------

docs/source/telegram.venue.rst

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

docs/source/telegram.webhookinfo.rst

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

examples/README.md

@@ -0,0 +1,26 @@
+# Examples
+
+The examples in this folder are small bots meant to show you how a bot that is written with `python-telegram-bot` looks like. Some bots focus on one specific aspect of the Telegram Bot API while others focus on one of the mechanics of this library. Except for the `echobot.py` example, they all use the high-level framework this library provides with the `telegram.ext` submodule.
+
+All examples are licensed under the [CC0 License](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt) and are therefore fully dedicated to the public domain. You can use them as the base for your own bots without worrying about copyrights.
+
+### [`echobot2.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot2.py) 
+This is probably the base for most of the bots made with `python-telegram-bot`. It simply replies to each text message with a message that contains the same text.
+
+### [`timerbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/timerbot.py) 
+This bot uses the [`JobQueue`](https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.jobqueue.html) class to send timed messages. The user sets a timer by using `/set` command with a specific time, for example `/set 30`. The bot then sets up a job to send a message to that user after 30 seconds. The user can also cancel the timer by sending `/unset`. To learn more about the `JobQueue`, read [this wiki article](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue).
+
+### [`conversationbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot.py)
+A common task for a bot is to ask information from the user. In v5.0 of this library, we introduced the [`ConversationHandler`](https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.conversationhandler.html) for that exact purpose. This example uses it to retrieve user-information in a conversation-like style. To get a better understanding, take a look at the [state diagram](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot.png).
+
+### [`conversationbot2.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot2.py)
+A more complex example of a bot that uses the `ConversationHandler`. It is also more confusing. Good thing there is a [fancy state diagram](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot2.png) for this one, too!
+
+### [`inlinekeyboard.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinekeyboard.py)
+This example sheds some light on inline keyboards, callback queries and message editing.
+
+### [`inlinebot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinebot.py)
+A basic example of an [inline bot](https://core.telegram.org/bots/inline). Don't forget to enable inline mode with [@BotFather](https://telegram.me/BotFather).
+
+## Pure API
+The [`echobot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot.py) example uses only the pure, "bare-metal" API wrapper. 

examples/conversationbot.py

@@ -17,7 +17,7 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """
 
-from telegram import (ReplyKeyboardMarkup)
+from telegram import (ReplyKeyboardMarkup, ReplyKeyboardRemove)
 from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters, RegexHandler,
                           ConversationHandler)
 
@@ -35,11 +35,11 @@ GENDER, PHOTO, LOCATION, BIO = range(4)
 def start(bot, update):
     reply_keyboard = [['Boy', 'Girl', 'Other']]
 
-    bot.sendMessage(update.message.chat_id,
-                    text='Hi! My name is Professor Bot. I will hold a conversation with you. '
-                         'Send /cancel to stop talking to me.\n\n'
-                         'Are you a boy or a girl?',
-                    reply_markup=ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True))
+    update.message.reply_text(
+        'Hi! My name is Professor Bot. I will hold a conversation with you. '
+        'Send /cancel to stop talking to me.\n\n'
+        'Are you a boy or a girl?',
+        reply_markup=ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True))
 
     return GENDER
 
@@ -47,20 +47,20 @@ def start(bot, update):
 def gender(bot, update):
     user = update.message.from_user
     logger.info("Gender of %s: %s" % (user.first_name, update.message.text))
-    bot.sendMessage(update.message.chat_id,
-                    text='I see! Please send me a photo of yourself, '
-                         'so I know what you look like, or send /skip if you don\'t want to.')
+    update.message.reply_text('I see! Please send me a photo of yourself, '
+                              'so I know what you look like, or send /skip if you don\'t want to.',
+                              reply_markup=ReplyKeyboardRemove())
 
     return PHOTO
 
 
 def photo(bot, update):
     user = update.message.from_user
-    photo_file = bot.getFile(update.message.photo[-1].file_id)
+    photo_file = bot.get_file(update.message.photo[-1].file_id)
     photo_file.download('user_photo.jpg')
     logger.info("Photo of %s: %s" % (user.first_name, 'user_photo.jpg'))
-    bot.sendMessage(update.message.chat_id, text='Gorgeous! Now, send me your location please, '
-                                                 'or send /skip if you don\'t want to.')
+    update.message.reply_text('Gorgeous! Now, send me your location please, '
+                              'or send /skip if you don\'t want to.')
 
     return LOCATION
 
@@ -68,8 +68,8 @@ def photo(bot, update):
 def skip_photo(bot, update):
     user = update.message.from_user
     logger.info("User %s did not send a photo." % user.first_name)
-    bot.sendMessage(update.message.chat_id, text='I bet you look great! Now, send me your '
-                                                 'location please, or send /skip.')
+    update.message.reply_text('I bet you look great! Now, send me your location please, '
+                              'or send /skip.')
 
     return LOCATION
 
@@ -79,8 +79,8 @@ def location(bot, update):
     user_location = update.message.location
     logger.info("Location of %s: %f / %f"
                 % (user.first_name, user_location.latitude, user_location.longitude))
-    bot.sendMessage(update.message.chat_id, text='Maybe I can visit you sometime! '
-                                                 'At last, tell me something about yourself.')
+    update.message.reply_text('Maybe I can visit you sometime! '
+                              'At last, tell me something about yourself.')
 
     return BIO
 
@@ -88,8 +88,8 @@ def location(bot, update):
 def skip_location(bot, update):
     user = update.message.from_user
     logger.info("User %s did not send a location." % user.first_name)
-    bot.sendMessage(update.message.chat_id, text='You seem a bit paranoid! '
-                                                 'At last, tell me something about yourself.')
+    update.message.reply_text('You seem a bit paranoid! '
+                              'At last, tell me something about yourself.')
 
     return BIO
 
@@ -97,8 +97,7 @@ def skip_location(bot, update):
 def bio(bot, update):
     user = update.message.from_user
     logger.info("Bio of %s: %s" % (user.first_name, update.message.text))
-    bot.sendMessage(update.message.chat_id,
-                    text='Thank you! I hope we can talk again some day.')
+    update.message.reply_text('Thank you! I hope we can talk again some day.')
 
     return ConversationHandler.END
 
@@ -106,8 +105,8 @@ def bio(bot, update):
 def cancel(bot, update):
     user = update.message.from_user
     logger.info("User %s canceled the conversation." % user.first_name)
-    bot.sendMessage(update.message.chat_id,
-                    text='Bye! I hope we can talk again some day.')
+    update.message.reply_text('Bye! I hope we can talk again some day.',
+                              reply_markup=ReplyKeyboardRemove())
 
     return ConversationHandler.END
 
@@ -130,13 +129,13 @@ def main():
         states={
             GENDER: [RegexHandler('^(Boy|Girl|Other)$', gender)],
 
-            PHOTO: [MessageHandler([Filters.photo], photo),
+            PHOTO: [MessageHandler(Filters.photo, photo),
                     CommandHandler('skip', skip_photo)],
 
-            LOCATION: [MessageHandler([Filters.location], location),
+            LOCATION: [MessageHandler(Filters.location, location),
                        CommandHandler('skip', skip_location)],
 
-            BIO: [MessageHandler([Filters.text], bio)]
+            BIO: [MessageHandler(Filters.text, bio)]
         },
 
         fallbacks=[CommandHandler('cancel', cancel)]
@@ -150,7 +149,7 @@ def main():
     # Start the Bot
     updater.start_polling()
 
-    # Run the bot until the you presses Ctrl-C or the process receives SIGINT,
+    # Run the bot until you press 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()

examples/conversationbot2.py

@@ -0,0 +1,152 @@
+#!/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 callback 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:
+Example of a bot-user conversation using ConversationHandler.
+Send /start to initiate the conversation.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+from telegram import ReplyKeyboardMarkup
+from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters, RegexHandler,
+                          ConversationHandler)
+
+import logging
+
+# Enable logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+CHOOSING, TYPING_REPLY, TYPING_CHOICE = range(3)
+
+reply_keyboard = [['Age', 'Favourite colour'],
+                  ['Number of siblings', 'Something else...'],
+                  ['Done']]
+markup = ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True)
+
+
+def facts_to_str(user_data):
+    facts = list()
+
+    for key, value in user_data.items():
+        facts.append('%s - %s' % (key, value))
+
+    return "\n".join(facts).join(['\n', '\n'])
+
+
+def start(bot, update):
+    update.message.reply_text(
+        "Hi! My name is Doctor Botter. I will hold a more complex conversation with you. "
+        "Why don't you tell me something about yourself?",
+        reply_markup=markup)
+
+    return CHOOSING
+
+
+def regular_choice(bot, update, user_data):
+    text = update.message.text
+    user_data['choice'] = text
+    update.message.reply_text('Your %s? Yes, I would love to hear about that!' % text.lower())
+
+    return TYPING_REPLY
+
+
+def custom_choice(bot, update):
+    update.message.reply_text('Alright, please send me the category first, '
+                              'for example "Most impressive skill"')
+
+    return TYPING_CHOICE
+
+
+def received_information(bot, update, user_data):
+    text = update.message.text
+    category = user_data['choice']
+    user_data[category] = text
+    del user_data['choice']
+
+    update.message.reply_text("Neat! Just so you know, this is what you already told me:"
+                              "%s"
+                              "You can tell me more, or change your opinion on something."
+                              % facts_to_str(user_data),
+                              reply_markup=markup)
+
+    return CHOOSING
+
+
+def done(bot, update, user_data):
+    if 'choice' in user_data:
+        del user_data['choice']
+
+    update.message.reply_text("I learned these facts about you:"
+                              "%s"
+                              "Until next time!" % facts_to_str(user_data))
+
+    user_data.clear()
+    return ConversationHandler.END
+
+
+def error(bot, update, error):
+    logger.warn('Update "%s" caused error "%s"' % (update, error))
+
+
+def main():
+    # Create the Updater and pass it your bot's token.
+    updater = Updater("TOKEN")
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # Add conversation handler with the states GENDER, PHOTO, LOCATION and BIO
+    conv_handler = ConversationHandler(
+        entry_points=[CommandHandler('start', start)],
+
+        states={
+            CHOOSING: [RegexHandler('^(Age|Favourite colour|Number of siblings)$',
+                                    regular_choice,
+                                    pass_user_data=True),
+                       RegexHandler('^Something else...$',
+                                    custom_choice),
+                       ],
+
+            TYPING_CHOICE: [MessageHandler(Filters.text,
+                                           regular_choice,
+                                           pass_user_data=True),
+                            ],
+
+            TYPING_REPLY: [MessageHandler(Filters.text,
+                                          received_information,
+                                          pass_user_data=True),
+                           ],
+        },
+
+        fallbacks=[RegexHandler('^Done$', done, pass_user_data=True)]
+    )
+
+    dp.add_handler(conv_handler)
+
+    # log all errors
+    dp.add_error_handler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Run the bot until you press 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/echobot.py

@@ -20,7 +20,7 @@ def main():
     # 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
+        update_id = bot.get_updates()[0].update_id
     except IndexError:
         update_id = None
 
@@ -39,14 +39,12 @@ def main():
 def echo(bot):
     global 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
+    for update in bot.get_updates(offset=update_id, timeout=10):
         update_id = update.update_id + 1
 
         if update.message:  # your bot can receive updates without messages
             # Reply to the message
-            bot.sendMessage(chat_id=chat_id, text=update.message.text)
+            update.message.reply_text(update.message.text)
 
 
 if __name__ == '__main__':

examples/echobot2.py

@@ -29,15 +29,15 @@ 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!')
+    update.message.reply_text('Hi!')
 
 
 def help(bot, update):
-    bot.sendMessage(update.message.chat_id, text='Help!')
+    update.message.reply_text('Help!')
 
 
 def echo(bot, update):
-    bot.sendMessage(update.message.chat_id, text=update.message.text)
+    update.message.reply_text(update.message.text)
 
 
 def error(bot, update, error):
@@ -56,7 +56,7 @@ def main():
     dp.add_handler(CommandHandler("help", help))
 
     # on noncommand i.e message - echo the message on Telegram
-    dp.add_handler(MessageHandler([Filters.text], echo))
+    dp.add_handler(MessageHandler(Filters.text, echo))
 
     # log all errors
     dp.add_error_handler(error)
@@ -64,7 +64,7 @@ def main():
     # Start the Bot
     updater.start_polling()
 
-    # Run the bot until the you presses Ctrl-C or the process receives SIGINT,
+    # Run the bot until you press 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()

examples/inlinebot.py

@@ -34,11 +34,11 @@ 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!')
+    update.message.reply_text('Hi!')
 
 
 def help(bot, update):
-    bot.sendMessage(update.message.chat_id, text='Help!')
+    update.message.reply_text('Help!')
 
 
 def escape_markdown(text):
@@ -68,11 +68,11 @@ def inlinequery(bot, update):
                                                 "_%s_" % escape_markdown(query),
                                                 parse_mode=ParseMode.MARKDOWN)))
 
-    bot.answerInlineQuery(update.inline_query.id, results=results)
+    update.inline_query.answer(results)
 
 
 def error(bot, update, error):
-    logger.warn('Update "%s" caused error "%s"' % (update, error))
+    logger.warning('Update "%s" caused error "%s"' % (update, error))
 
 
 def main():

examples/inlinekeyboard.py

@@ -1,108 +1,49 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-# Basic example for a bot that awaits an answer from the user. It's built upon
-# the state_machine_bot.py example
+# Basic example for a bot that uses inline keyboards.
 # This program is dedicated to the public domain under the CC0 license.
 
 import logging
-from telegram import Emoji, ForceReply, InlineKeyboardButton, \
-    InlineKeyboardMarkup
-from telegram.ext import Updater, CommandHandler, MessageHandler, \
-    CallbackQueryHandler, Filters
+from telegram import InlineKeyboardButton, InlineKeyboardMarkup
+from telegram.ext import Updater, CommandHandler, CallbackQueryHandler
 
 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.DEBUG)
-
-# Define the different states a chat can be in
-MENU, AWAIT_CONFIRMATION, AWAIT_INPUT = range(3)
-
-# Python 2 and 3 unicode differences
-try:
-    YES, NO = (Emoji.THUMBS_UP_SIGN.decode('utf-8'), Emoji.THUMBS_DOWN_SIGN.decode('utf-8'))
-except AttributeError:
-    YES, NO = (Emoji.THUMBS_UP_SIGN, Emoji.THUMBS_DOWN_SIGN)
-
-# States are saved in a dict that maps chat_id -> state
-state = dict()
-# Sometimes you need to save data temporarily
-context = dict()
-# This dict is used to store the settings value for the chat.
-# Usually, you'd use persistence for this (e.g. sqlite).
-values = dict()
+                    level=logging.INFO)
 
 
-# Example handler. Will be called on the /set command and on regular messages
-def set_value(bot, update):
-    chat_id = update.message.chat_id
-    user_id = update.message.from_user.id
-    user_state = state.get(chat_id, MENU)
+def start(bot, update):
+    keyboard = [[InlineKeyboardButton("Option 1", callback_data='1'),
+                 InlineKeyboardButton("Option 2", callback_data='2')],
 
-    if user_state == MENU:
-        state[user_id] = AWAIT_INPUT  # set the state
-        bot.sendMessage(chat_id,
-                        text="Please enter your settings value",
-                        reply_markup=ForceReply())
+                [InlineKeyboardButton("Option 3", callback_data='3')]]
+
+    reply_markup = InlineKeyboardMarkup(keyboard)
+
+    update.message.reply_text('Please choose:', reply_markup=reply_markup)
 
 
-def entered_value(bot, update):
-    chat_id = update.message.chat_id
-    user_id = update.message.from_user.id
-    chat_state = state.get(user_id, MENU)
-
-    # Check if we are waiting for input
-    if chat_state == AWAIT_INPUT:
-        state[user_id] = AWAIT_CONFIRMATION
-
-        # Save the user id and the answer to context
-        context[user_id] = update.message.text
-        reply_markup = InlineKeyboardMarkup([[InlineKeyboardButton(YES, callback_data=YES),
-                                              InlineKeyboardButton(NO, callback_data=NO)]])
-        bot.sendMessage(chat_id, text="Are you sure?", reply_markup=reply_markup)
-
-
-def confirm_value(bot, update):
+def button(bot, update):
     query = update.callback_query
-    chat_id = query.message.chat_id
-    user_id = query.from_user.id
-    text = query.data
-    user_state = state.get(user_id, MENU)
-    user_context = context.get(user_id, None)
 
-    # Check if we are waiting for confirmation and the right user answered
-    if user_state == AWAIT_CONFIRMATION:
-        del state[user_id]
-        del context[user_id]
-        bot.answerCallbackQuery(query.id, text="Ok!")
-        if text == YES:
-            values[user_id] = user_context
-            bot.editMessageText(text="Changed value to %s." % values[user_id],
-                                chat_id=chat_id,
-                                message_id=query.message.message_id)
-        else:
-            bot.editMessageText(text="Alright, value is still %s." %
-                                values.get(user_id, 'not set'),
-                                chat_id=chat_id,
-                                message_id=query.message.message_id)
+    bot.edit_message_text(text="Selected option: %s" % query.data,
+                          chat_id=query.message.chat_id,
+                          message_id=query.message.message_id)
 
 
 def help(bot, update):
-    bot.sendMessage(update.message.chat_id, text="Use /set to test this bot.")
+    update.message.reply_text("Use /start to test this bot.")
 
 
 def error(bot, update, error):
     logging.warning('Update "%s" caused error "%s"' % (update, error))
 
+
 # Create the Updater and pass it your bot's token.
 updater = Updater("TOKEN")
 
-# The command
-updater.dispatcher.add_handler(CommandHandler('set', set_value))
-# The answer
-updater.dispatcher.add_handler(MessageHandler([Filters.text], entered_value))
-# The confirmation
-updater.dispatcher.add_handler(CallbackQueryHandler(confirm_value))
-updater.dispatcher.add_handler(CommandHandler('start', help))
+updater.dispatcher.add_handler(CommandHandler('start', start))
+updater.dispatcher.add_handler(CallbackQueryHandler(button))
 updater.dispatcher.add_handler(CommandHandler('help', help))
 updater.dispatcher.add_error_handler(error)
 

examples/timerbot.py

@@ -22,60 +22,58 @@ import logging
 
 # Enable logging
 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.DEBUG)
+                    level=logging.INFO)
 
 logger = logging.getLogger(__name__)
-timers = dict()
 
 
 # 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')
+    update.message.reply_text('Hi! Use /set <seconds> to set a timer')
 
 
 def alarm(bot, job):
     """Function to send the alarm message"""
-    bot.sendMessage(job.context, text='Beep!')
+    bot.send_message(job.context, text='Beep!')
 
 
-def set(bot, update, args, job_queue):
+def set(bot, update, args, job_queue, chat_data):
     """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])
         if due < 0:
-            bot.sendMessage(chat_id, text='Sorry we can not go back to future!')
+            update.message.reply_text('Sorry we can not go back to future!')
+            return
 
         # Add job to queue
-        job = Job(alarm, due, repeat=False, context=chat_id)
-        timers[chat_id] = job
-        job_queue.put(job)
+        job = job_queue.run_once(alarm, due, context=chat_id)
+        chat_data['job'] = job
 
-        bot.sendMessage(chat_id, text='Timer successfully set!')
+        update.message.reply_text('Timer successfully set!')
 
     except (IndexError, ValueError):
-        bot.sendMessage(chat_id, text='Usage: /set <seconds>')
+        update.message.reply_text('Usage: /set <seconds>')
 
 
-def unset(bot, update):
+def unset(bot, update, chat_data):
     """Removes the job if the user changed their mind"""
-    chat_id = update.message.chat_id
 
-    if chat_id not in timers:
-        bot.sendMessage(chat_id, text='You have no active timer')
+    if 'job' not in chat_data:
+        update.message.reply_text('You have no active timer')
         return
 
-    job = timers[chat_id]
+    job = chat_data['job']
     job.schedule_removal()
-    del timers[chat_id]
+    del chat_data['job']
 
-    bot.sendMessage(chat_id, text='Timer successfully unset!')
+    update.message.reply_text('Timer successfully unset!')
 
 
 def error(bot, update, error):
-    logger.warn('Update "%s" caused error "%s"' % (update, error))
+    logger.warning('Update "%s" caused error "%s"' % (update, error))
 
 
 def main():
@@ -87,8 +85,11 @@ def main():
     # on different commands - answer in Telegram
     dp.add_handler(CommandHandler("start", start))
     dp.add_handler(CommandHandler("help", start))
-    dp.add_handler(CommandHandler("set", set, pass_args=True, pass_job_queue=True))
-    dp.add_handler(CommandHandler("unset", unset))
+    dp.add_handler(CommandHandler("set", set,
+                                  pass_args=True,
+                                  pass_job_queue=True,
+                                  pass_chat_data=True))
+    dp.add_handler(CommandHandler("unset", unset, pass_chat_data=True))
 
     # log all errors
     dp.add_error_handler(error)
@@ -96,9 +97,9 @@ def main():
     # 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.
+    # Block until you press 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()
 
 

requirements-dev.txt

@@ -2,7 +2,6 @@ flake8
 nose
 pep257
 pylint
-unittest2
 flaky
 yapf
 pre-commit

requirements.txt

@@ -1,3 +1,2 @@
 future>=0.15.2
-urllib3>=1.10
 certifi

setup.py

@@ -2,7 +2,7 @@
 """The setup and build script for the python-telegram-bot library."""
 
 import codecs
-import telegram
+import os
 from setuptools import setup, find_packages
 
 
@@ -16,18 +16,35 @@ def requirements():
 
     return requirements_list
 
+
+packages = find_packages(exclude=['tests*'])
+packages.extend(['telegram.vendor.urllib3.urllib3',
+                'telegram.vendor.urllib3.urllib3.packages', 'telegram.vendor.urllib3.urllib3.packages.ssl_match_hostname',
+                'telegram.vendor.urllib3.urllib3.packages.backports', 'telegram.vendor.urllib3.urllib3.contrib',
+                'telegram.vendor.urllib3.urllib3.util',
+                ])
+
 with codecs.open('README.rst', 'r', 'utf-8') as fd:
+    fn = os.path.join('telegram', 'version.py')
+    with open(fn) as fh:
+        code = compile(fh.read(), fn, 'exec')
+        exec(code)
+
     setup(name='python-telegram-bot',
-          version=telegram.__version__,
+          version=__version__,
           author='Leandro Toledo',
           author_email='devs@python-telegram-bot.org',
           license='LGPLv3',
-          url='https://github.com/python-telegram-bot/python-telegram-bot',
+          url='https://python-telegram-bot.org/',
           keywords='python telegram bot api wrapper',
-          description='Not just a Python wrapper around the Telegram Bot API',
+          description="We have made you a wrapper you can't refuse",
           long_description=fd.read(),
-          packages=find_packages(exclude=['tests*']),
+          packages=packages,
           install_requires=requirements(),
+          extras_require={
+              'json': 'ujson',
+              'socks': 'PySocks'
+          },
           include_package_data=True,
           classifiers=[
               'Development Status :: 5 - Production/Stable',
@@ -39,10 +56,10 @@ with codecs.open('README.rst', 'r', 'utf-8') as fd:
               'Topic :: Internet',
               'Programming Language :: Python',
               'Programming Language :: Python :: 2',
-              'Programming Language :: Python :: 2.6',
               'Programming Language :: Python :: 2.7',
               'Programming Language :: Python :: 3',
               'Programming Language :: Python :: 3.3',
               'Programming Language :: Python :: 3.4',
               'Programming Language :: Python :: 3.5',
+              'Programming Language :: Python :: 3.6'
           ],)

telegram/__init__.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,6 +19,10 @@
 """A library that provides a Python interface to the Telegram Bot API"""
 
 from sys import version_info
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'vendor', 'urllib3'))
 
 from .base import TelegramObject
 from .user import User
@@ -38,15 +42,16 @@ from .userprofilephotos import UserProfilePhotos
 from .keyboardbutton import KeyboardButton
 from .replymarkup import ReplyMarkup
 from .replykeyboardmarkup import ReplyKeyboardMarkup
-from .replykeyboardhide import ReplyKeyboardHide
+from .replykeyboardremove import ReplyKeyboardRemove, ReplyKeyboardHide
 from .forcereply import ForceReply
 from .error import TelegramError
 from .inputfile import InputFile
 from .file import File
-from .nullhandler import NullHandler
 from .emoji import Emoji
 from .parsemode import ParseMode
 from .messageentity import MessageEntity
+from .animation import Animation
+from .game import Game
 from .message import Message
 from .inputmessagecontent import InputMessageContent
 from .callbackquery import CallbackQuery
@@ -74,40 +79,41 @@ from .inlinequeryresultphoto import InlineQueryResultPhoto
 from .inlinequeryresultvenue import InlineQueryResultVenue
 from .inlinequeryresultvideo import InlineQueryResultVideo
 from .inlinequeryresultvoice import InlineQueryResultVoice
+from .inlinequeryresultgame import InlineQueryResultGame
 from .inputtextmessagecontent import InputTextMessageContent
 from .inputlocationmessagecontent import InputLocationMessageContent
 from .inputvenuemessagecontent import InputVenueMessageContent
 from .inputcontactmessagecontent import InputContactMessageContent
+from .webhookinfo import WebhookInfo
+from .gamehighscore import GameHighScore
 from .update import Update
 from .bot import Bot
 from .constants import (MAX_MESSAGE_LENGTH, MAX_CAPTION_LENGTH, SUPPORTED_WEBHOOK_PORTS,
                         MAX_FILESIZE_DOWNLOAD, MAX_FILESIZE_UPLOAD,
                         MAX_MESSAGES_PER_SECOND_PER_CHAT, MAX_MESSAGES_PER_SECOND,
                         MAX_MESSAGES_PER_MINUTE_PER_GROUP)
+from .version import __version__  # flake8: noqa
 
 __author__ = 'devs@python-telegram-bot.org'
-__version__ = '5.0.0'
-__all__ = ['Audio', 'Bot', 'Chat', 'ChatMember', 'ChatAction', 'ChosenInlineResult',
-           'CallbackQuery', 'Contact', 'Document', 'Emoji', 'File', 'ForceReply',
-           'InlineKeyboardButton', 'InlineKeyboardMarkup', 'InlineQuery', 'InlineQueryResult',
-           'InlineQueryResult', 'InlineQueryResultArticle', 'InlineQueryResultAudio',
-           'InlineQueryResultCachedAudio', 'InlineQueryResultCachedDocument',
-           'InlineQueryResultCachedGif', 'InlineQueryResultCachedMpeg4Gif',
-           'InlineQueryResultCachedPhoto', 'InlineQueryResultCachedSticker',
-           'InlineQueryResultCachedVideo', 'InlineQueryResultCachedVoice',
-           'InlineQueryResultContact', 'InlineQueryResultDocument', 'InlineQueryResultGif',
-           'InlineQueryResultLocation', 'InlineQueryResultMpeg4Gif', 'InlineQueryResultPhoto',
-           'InlineQueryResultVenue', 'InlineQueryResultVideo', 'InlineQueryResultVoice',
-           'InputContactMessageContent', 'InputFile', 'InputLocationMessageContent',
-           'InputMessageContent', 'InputTextMessageContent', 'InputVenueMessageContent',
-           'KeyboardButton', 'Location', 'Message', 'MessageEntity', 'NullHandler', 'ParseMode',
-           'PhotoSize', 'ReplyKeyboardHide', 'ReplyKeyboardMarkup', 'ReplyMarkup', 'Sticker',
-           'TelegramError', 'TelegramObject', 'Update', 'User', 'UserProfilePhotos', 'Venue',
-           'Video', 'Voice', 'MAX_MESSAGE_LENGTH', 'MAX_CAPTION_LENGTH', 'SUPPORTED_WEBHOOK_PORTS',
-           'MAX_FILESIZE_DOWNLOAD', 'MAX_FILESIZE_UPLOAD', 'MAX_MESSAGES_PER_SECOND_PER_CHAT',
-           'MAX_MESSAGES_PER_SECOND', 'MAX_MESSAGES_PER_MINUTE_PER_GROUP']
 
-if version_info < (2, 7):
-    from warnings import warn
-    warn("python-telegram-bot will stop supporting Python 2.6 in a future release. "
-         "Please upgrade your Python version to at least Python 2.7!")
+__all__ = [
+    'Audio', 'Bot', 'Chat', 'ChatMember', 'ChatAction', 'ChosenInlineResult', 'CallbackQuery',
+    'Contact', 'Document', 'Emoji', 'File', 'ForceReply', 'InlineKeyboardButton',
+    'InlineKeyboardMarkup', 'InlineQuery', 'InlineQueryResult', 'InlineQueryResult',
+    'InlineQueryResultArticle', 'InlineQueryResultAudio', 'InlineQueryResultCachedAudio',
+    'InlineQueryResultCachedDocument', 'InlineQueryResultCachedGif',
+    'InlineQueryResultCachedMpeg4Gif', 'InlineQueryResultCachedPhoto',
+    'InlineQueryResultCachedSticker', 'InlineQueryResultCachedVideo',
+    'InlineQueryResultCachedVoice', 'InlineQueryResultContact', 'InlineQueryResultDocument',
+    'InlineQueryResultGif', 'InlineQueryResultLocation', 'InlineQueryResultMpeg4Gif',
+    'InlineQueryResultPhoto', 'InlineQueryResultVenue', 'InlineQueryResultVideo',
+    'InlineQueryResultVoice', 'InlineQueryResultGame', 'InputContactMessageContent', 'InputFile',
+    'InputLocationMessageContent', 'InputMessageContent', 'InputTextMessageContent',
+    'InputVenueMessageContent', 'KeyboardButton', 'Location', 'Message', 'MessageEntity',
+    'ParseMode', 'PhotoSize', 'ReplyKeyboardRemove', 'ReplyKeyboardMarkup', 'ReplyMarkup',
+    'Sticker', 'TelegramError', 'TelegramObject', 'Update', 'User', 'UserProfilePhotos', 'Venue',
+    'Video', 'Voice', 'MAX_MESSAGE_LENGTH', 'MAX_CAPTION_LENGTH', 'SUPPORTED_WEBHOOK_PORTS',
+    'MAX_FILESIZE_DOWNLOAD', 'MAX_FILESIZE_UPLOAD', 'MAX_MESSAGES_PER_SECOND_PER_CHAT',
+    'MAX_MESSAGES_PER_SECOND', 'MAX_MESSAGES_PER_MINUTE_PER_GROUP', 'WebhookInfo', 'Animation',
+    'Game', 'GameHighScore'
+]

telegram/__main__.py

@@ -14,5 +14,10 @@ def print_ver_info():
     print('future {0}'.format(future.__version__))
     print('Python {0}'.format(sys.version.replace('\n', ' ')))
 
-# main
-print_ver_info()
+
+def main():
+    print_ver_info()
+
+
+if __name__ == '__main__':
+    main()

telegram/animation.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2017
+# 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 an object that represents a Telegram Animation."""
+from telegram import PhotoSize
+from telegram import TelegramObject
+
+
+class Animation(TelegramObject):
+    """This object represents a Telegram Animation.
+
+    Attributes:
+        file_id (str): Unique file identifier.
+
+    Keyword Args:
+        thumb (Optional[:class:`telegram.PhotoSize`]): Animation thumbnail as defined by sender.
+        file_name (Optional[str]): Original animation filename as defined by sender.
+        mime_type (Optional[str]): MIME type of the file as defined by sender.
+        file_size (Optional[int]): File size.
+
+    """
+
+    def __init__(self,
+                 file_id,
+                 thumb=None,
+                 file_name=None,
+                 mime_type=None,
+                 file_size=None,
+                 **kwargs):
+        self.file_id = file_id
+        self.thumb = thumb
+        self.file_name = file_name
+        self.mime_type = mime_type
+        self.file_size = file_size
+
+        self._id_attrs = (self.file_id,)
+
+    @staticmethod
+    def de_json(data, bot):
+        """
+        Args:
+            data (dict):
+            bot (telegram.Bot):
+
+        Returns:
+            telegram.Game:
+        """
+        if not data:
+            return None
+
+        data = super(Animation, Animation).de_json(data, bot)
+
+        data['thumb'] = PhotoSize.de_json(data.get('thumb'), bot)
+
+        return Animation(**data)

telegram/audio.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,7 +16,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 Audio."""
+"""This module contains an object that represents a Telegram Audio."""
 
 from telegram import TelegramObject
 
@@ -35,30 +35,39 @@ class Audio(TelegramObject):
     Args:
         file_id (str):
         duration (int):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         performer (Optional[str]):
         title (Optional[str]):
         mime_type (Optional[str]):
         file_size (Optional[int]):
+        **kwargs: Arbitrary keyword arguments.
+
     """
 
-    def __init__(self, file_id, duration, **kwargs):
+    def __init__(self,
+                 file_id,
+                 duration,
+                 performer=None,
+                 title=None,
+                 mime_type=None,
+                 file_size=None,
+                 **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))
+        self.performer = performer
+        self.title = title
+        self.mime_type = mime_type
+        self.file_size = file_size
+
+        self._id_attrs = (self.file_id,)
 
     @staticmethod
-    def de_json(data):
+    def de_json(data, bot):
         """
         Args:
-            data (str):
+            data (dict):
+            bot (telegram.Bot):
 
         Returns:
             telegram.Audio:

telegram/base.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,14 +18,18 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """Base class for Telegram Objects."""
 
-import json
+try:
+    import ujson as json
+except ImportError:
+    import json
+
 from abc import ABCMeta
 
 
 class TelegramObject(object):
     """Base class for most telegram objects."""
-
     __metaclass__ = ABCMeta
+    _id_attrs = ()
 
     def __str__(self):
         return str(self.to_dict())
@@ -34,13 +38,14 @@ class TelegramObject(object):
         return self.__dict__[item]
 
     @staticmethod
-    def de_json(data):
+    def de_json(data, bot):
         """
         Args:
-            data (str):
+            data (dict):
+            bot (telegram.Bot):
 
         Returns:
-            telegram.TelegramObject:
+            dict:
         """
         if not data:
             return None
@@ -64,6 +69,9 @@ class TelegramObject(object):
         data = dict()
 
         for key in iter(self.__dict__):
+            if key in ('bot', '_id_attrs'):
+                continue
+
             value = self.__dict__[key]
             if value is not None:
                 if hasattr(value, 'to_dict'):
@@ -72,3 +80,13 @@ class TelegramObject(object):
                     data[key] = value
 
         return data
+
+    def __eq__(self, other):
+        if isinstance(other, self.__class__):
+            return self._id_attrs == other._id_attrs
+        return super(TelegramObject, self).__eq__(other)
+
+    def __hash__(self):
+        if self._id_attrs:
+            return hash((self.__class__, self._id_attrs))
+        return super(TelegramObject, self).__hash__()

telegram/callbackgame.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,17 +16,10 @@
 #
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
-"""This module contains a object that represents a logging NullHandler."""
+"""This module contains an object that represents a Telegram CallbackGame."""
 
-import logging
+from telegram import TelegramObject
 
 
-class NullHandler(logging.Handler):
-    """This object represents a logging NullHandler."""
-
-    def emit(self, record):
-        """
-        Args:
-            record (str):
-        """
-        pass
+class CallbackGame(TelegramObject):
+    """A placeholder, currently holds no information. Use BotFather to set up your game."""

telegram/callbackquery.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,8 +16,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
-CallbackQuery"""
+"""This module contains an object that represents a Telegram CallbackQuery"""
 
 from telegram import TelegramObject, Message, User
 
@@ -25,24 +24,48 @@ from telegram import TelegramObject, Message, User
 class CallbackQuery(TelegramObject):
     """This object represents a Telegram CallbackQuery."""
 
-    def __init__(self, id, from_user, data, **kwargs):
+    def __init__(self,
+                 id,
+                 from_user,
+                 chat_instance,
+                 message=None,
+                 data=None,
+                 inline_message_id=None,
+                 game_short_name=None,
+                 bot=None,
+                 **kwargs):
         # Required
         self.id = id
         self.from_user = from_user
-        self.data = data
+        self.chat_instance = chat_instance
         # Optionals
-        self.message = kwargs.get('message')
-        self.inline_message_id = kwargs.get('inline_message_id', '')
+        self.message = message
+        self.data = data
+        self.inline_message_id = inline_message_id
+        self.game_short_name = game_short_name
+
+        self.bot = bot
 
     @staticmethod
-    def de_json(data):
+    def de_json(data, bot):
+        """
+        Args:
+            data (dict):
+            bot (telegram.Bot):
+
+        Returns:
+            telegram.CallbackQuery:
+        """
+
         if not data:
             return None
 
-        data['from_user'] = User.de_json(data.get('from'))
-        data['message'] = Message.de_json(data.get('message'))
+        data = super(CallbackQuery, CallbackQuery).de_json(data, bot)
 
-        return CallbackQuery(**data)
+        data['from_user'] = User.de_json(data.get('from'), bot)
+        data['message'] = Message.de_json(data.get('message'), bot)
+
+        return CallbackQuery(bot=bot, **data)
 
     def to_dict(self):
         """
@@ -54,3 +77,56 @@ class CallbackQuery(TelegramObject):
         # Required
         data['from'] = data.pop('from_user', None)
         return data
+
+    def answer(self, *args, **kwargs):
+        """Shortcut for ``bot.answerCallbackQuery(update.callback_query.id, *args, **kwargs)``"""
+        return self.bot.answerCallbackQuery(self.id, *args, **kwargs)
+
+    def edit_message_text(self, *args, **kwargs):
+        """
+        Shortcut for either ``bot.editMessageText(chat_id=update.callback_query.message.chat_id, \
+message_id=update.callback_query.message.message_id, \
+*args, **kwargs)``
+        or ``bot.editMessageText(inline_message_id=update.callback_query.inline_message_id, \
+*args, **kwargs)``
+        """
+        if self.inline_message_id:
+            return self.bot.edit_message_text(
+                inline_message_id=self.inline_message_id, *args, **kwargs)
+        else:
+            return self.bot.edit_message_text(
+                chat_id=self.message.chat_id, message_id=self.message.message_id, *args, **kwargs)
+
+    def edit_message_caption(self, *args, **kwargs):
+        """
+        Shortcut for either
+        ``bot.editMessageCaption(chat_id=update.callback_query.message.chat_id, \
+message_id=update.callback_query.message.message_id, \
+*args, **kwargs)``
+        or
+        ``bot.editMessageCaption(inline_message_id=update.callback_query.inline_message_id, \
+*args, **kwargs)``
+        """
+        if self.inline_message_id:
+            return self.bot.edit_message_caption(
+                inline_message_id=self.inline_message_id, *args, **kwargs)
+        else:
+            return self.bot.edit_message_caption(
+                chat_id=self.message.chat_id, message_id=self.message.message_id, *args, **kwargs)
+
+    def edit_message_reply_markup(self, *args, **kwargs):
+        """
+        Shortcut for either
+        ``bot.editMessageReplyMarkup(chat_id=update.callback_query.message.chat_id, \
+message_id=update.callback_query.message.message_id, \
+*args, **kwargs)``
+        or
+        ``bot.editMessageReplyMarkup(inline_message_id=update.callback_query.inline_message_id, \
+*args, **kwargs)``
+        """
+        if self.inline_message_id:
+            return self.bot.edit_message_reply_markup(
+                inline_message_id=self.inline_message_id, *args, **kwargs)
+        else:
+            return self.bot.edit_message_reply_markup(
+                chat_id=self.message.chat_id, message_id=self.message.message_id, *args, **kwargs)

telegram/chat.py

@@ -2,7 +2,7 @@
 # pylint: disable=C0103,W0622
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,7 +17,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 Chat."""
+"""This module contains an object that represents a Telegram Chat."""
 
 from telegram import TelegramObject
 
@@ -32,36 +32,53 @@ class Chat(TelegramObject):
         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
+        all_members_are_administrators (bool): True if group has 'All Members Are Administrators'
 
     Args:
         id (int):
         type (str):
-        **kwargs: Arbitrary keyword arguments.
+        title (Optional[str]):
+        username(Optional[str]):
+        first_name(Optional[str]):
+        last_name(Optional[str]):
+        bot (Optional[Bot]): The Bot to use for instance methods
+        **kwargs (dict): Arbitrary keyword arguments.
 
-    Keyword Args:
-        type (Optional[str]):
     """
-
     PRIVATE = 'private'
     GROUP = 'group'
     SUPERGROUP = 'supergroup'
     CHANNEL = 'channel'
 
-    def __init__(self, id, type, **kwargs):
+    def __init__(self,
+                 id,
+                 type,
+                 title=None,
+                 username=None,
+                 first_name=None,
+                 last_name=None,
+                 all_members_are_administrators=None,
+                 bot=None,
+                 **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', '')
+        self.title = title
+        self.username = username
+        self.first_name = first_name
+        self.last_name = last_name
+        self.all_members_are_administrators = all_members_are_administrators
+
+        self.bot = bot
+        self._id_attrs = (self.id,)
 
     @staticmethod
-    def de_json(data):
+    def de_json(data, bot):
         """
         Args:
             data (dict):
+            bot (telegram.Bot):
 
         Returns:
             telegram.Chat:
@@ -69,4 +86,32 @@ class Chat(TelegramObject):
         if not data:
             return None
 
-        return Chat(**data)
+        return Chat(bot=bot, **data)
+
+    def send_action(self, *args, **kwargs):
+        """Shortcut for ``bot.sendChatAction(update.message.chat.id, *args, **kwargs)``"""
+        return self.bot.sendChatAction(self.id, *args, **kwargs)
+
+    def leave(self, *args, **kwargs):
+        """Shortcut for ``bot.leaveChat(update.message.chat.id, *args, **kwargs)``"""
+        return self.bot.leaveChat(self.id, *args, **kwargs)
+
+    def get_administrators(self, *args, **kwargs):
+        """Shortcut for ``bot.getChatAdministrators(update.message.chat.id, *args, **kwargs)``"""
+        return self.bot.getChatAdministrators(self.id, *args, **kwargs)
+
+    def get_members_count(self, *args, **kwargs):
+        """Shortcut for ``bot.getChatMembersCount(update.message.chat.id, *args, **kwargs)``"""
+        return self.bot.getChatMembersCount(self.id, *args, **kwargs)
+
+    def get_member(self, *args, **kwargs):
+        """Shortcut for ``bot.getChatMember(update.message.chat.id, *args, **kwargs)``"""
+        return self.bot.getChatMember(self.id, *args, **kwargs)
+
+    def kick_member(self, *args, **kwargs):
+        """Shortcut for ``bot.kickChatMember(update.message.chat.id, *args, **kwargs)``"""
+        return self.bot.kickChatMember(self.id, *args, **kwargs)
+
+    def unban_member(self, *args, **kwargs):
+        """Shortcut for ``bot.unbanChatMember(update.message.chat.id, *args, **kwargs)``"""
+        return self.bot.unbanChatMember(self.id, *args, **kwargs)

telegram/chataction.py

@@ -2,7 +2,7 @@
 # pylint: disable=R0903
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,7 +17,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 ChatAction."""
+"""This module contains an object that represents a Telegram ChatAction."""
 
 
 class ChatAction(object):

telegram/chatmember.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,7 +16,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 ChatMember."""
+"""This module contains an object that represents a Telegram ChatMember."""
 
 from telegram import User, TelegramObject
 
@@ -32,8 +32,9 @@ class ChatMember(TelegramObject):
     Args:
         user (:class:`telegram.User`):
         status (str):
-    """
+        **kwargs (dict): Arbitrary keyword arguments.
 
+    """
     CREATOR = 'creator'
     ADMINISTRATOR = 'administrator'
     MEMBER = 'member'
@@ -45,11 +46,14 @@ class ChatMember(TelegramObject):
         self.user = user
         self.status = status
 
+        self._id_attrs = (self.user, self.status)
+
     @staticmethod
-    def de_json(data):
+    def de_json(data, bot):
         """
         Args:
             data (dict):
+            bot (telegram.Bot):
 
         Returns:
             telegram.ChatMember:
@@ -57,6 +61,8 @@ class ChatMember(TelegramObject):
         if not data:
             return None
 
-        data['user'] = User.de_json(data.get('user'))
+        data = super(ChatMember, ChatMember).de_json(data, bot)
+
+        data['user'] = User.de_json(data.get('user'), bot)
 
         return ChatMember(**data)

telegram/choseninlineresult.py

@@ -2,7 +2,8 @@
 # pylint: disable=R0902,R0912,R0913
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015 Leandro Toledo de Souza <devs@python-telegram-bot.org>
+# Copyright (C) 2015-2017
+# 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
@@ -17,7 +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 ChosenInlineResult
+This module contains an object that represents a Telegram ChosenInlineResult
 """
 
 from telegram import TelegramObject, User, Location
@@ -33,11 +34,16 @@ class ChosenInlineResult(TelegramObject):
         result_id (str):
         from_user (:class:`telegram.User`):
         query (str):
+        location (:class:`telegram.Location`):
+        inline_message_id (str):
 
     Args:
         result_id (str):
         from_user (:class:`telegram.User`):
         query (str):
+        location (Optional[:class:`telegram.Location`]):
+        inline_message_id (Optional[str]):
+        **kwargs (dict): Arbitrary keyword arguments.
 
     """
 
@@ -56,11 +62,14 @@ class ChosenInlineResult(TelegramObject):
         self.location = location
         self.inline_message_id = inline_message_id
 
+        self._id_attrs = (self.result_id,)
+
     @staticmethod
-    def de_json(data):
+    def de_json(data, bot):
         """
         Args:
             data (dict):
+            bot (telegram.Bot):
 
         Returns:
             telegram.ChosenInlineResult:
@@ -68,10 +77,11 @@ class ChosenInlineResult(TelegramObject):
         if not data:
             return None
 
+        data = super(ChosenInlineResult, ChosenInlineResult).de_json(data, bot)
         # Required
-        data['from_user'] = User.de_json(data.pop('from'))
+        data['from_user'] = User.de_json(data.pop('from'), bot)
         # Optionals
-        data['location'] = Location.de_json(data.get('location'))
+        data['location'] = Location.de_json(data.get('location'), bot)
 
         return ChosenInlineResult(**data)
 

telegram/constants.py

@@ -1,5 +1,5 @@
 # python-telegram-bot - a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # by the python-telegram-bot contributors <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -32,6 +32,13 @@ Attributes:
         limit, but eventually you'll begin receiving 429 errors.
     MAX_MESSAGES_PER_SECOND (int)
     MAX_MESSAGES_PER_MINUTE_PER_GROUP (int)
+    MAX_INLINE_QUERY_RESULTS (int)
+
+The following constant have been found by experimentation:
+
+Attributes:
+    MAX_MESSAGE_ENTITIES (int): Max number of entities that can be in a message.
+        (Beyond this cap telegram will simply ignore further formatting styles)
 """
 
 MAX_MESSAGE_LENGTH = 4096
@@ -45,3 +52,5 @@ MAX_FILESIZE_UPLOAD = int(50E6)  # (50MB)
 MAX_MESSAGES_PER_SECOND_PER_CHAT = 1
 MAX_MESSAGES_PER_SECOND = 30
 MAX_MESSAGES_PER_MINUTE_PER_GROUP = 20
+MAX_MESSAGE_ENTITIES = 100
+MAX_INLINE_QUERY_RESULTS = 50

telegram/contact.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,7 +16,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 Contact."""
+"""This module contains an object that represents a Telegram Contact."""
 
 from telegram import TelegramObject
 
@@ -33,26 +33,28 @@ class Contact(TelegramObject):
     Args:
         phone_number (str):
         first_name (str):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         last_name (Optional[str]):
         user_id (Optional[int]):
+        **kwargs: Arbitrary keyword arguments.
+
     """
 
-    def __init__(self, phone_number, first_name, **kwargs):
+    def __init__(self, phone_number, first_name, last_name=None, user_id=None, **kwargs):
         # Required
         self.phone_number = str(phone_number)
         self.first_name = first_name
         # Optionals
-        self.last_name = kwargs.get('last_name', '')
-        self.user_id = int(kwargs.get('user_id', 0))
+        self.last_name = last_name
+        self.user_id = user_id
+
+        self._id_attrs = (self.phone_number,)
 
     @staticmethod
-    def de_json(data):
+    def de_json(data, bot):
         """
         Args:
-            data (str):
+            data (dict):
+            bot (telegram.Bot):
 
         Returns:
             telegram.Contact:

telegram/contrib/botan.py

@@ -1,11 +1,10 @@
 import logging
-from telegram import NullHandler
 
 from future.moves.urllib.parse import quote
 from future.moves.urllib.error import HTTPError, URLError
 from future.moves.urllib.request import urlopen, Request
 
-logging.getLogger(__name__).addHandler(NullHandler())
+logging.getLogger(__name__).addHandler(logging.NullHandler())
 
 
 class Botan(object):
@@ -29,12 +28,10 @@ class Botan(object):
             return False
         data = message.to_json()
         try:
-            url = self.url_template.format(token=str(self.token),
-                                           uid=str(uid),
-                                           name=quote(event_name))
-            request = Request(url,
-                              data=data.encode(),
-                              headers={'Content-Type': 'application/json'})
+            url = self.url_template.format(
+                token=str(self.token), uid=str(uid), name=quote(event_name))
+            request = Request(
+                url, data=data.encode(), headers={'Content-Type': 'application/json'})
             urlopen(request)
             return True
         except HTTPError as error:

telegram/document.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,7 +16,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 Document."""
+"""This module contains an object that represents a Telegram Document."""
 
 from telegram import PhotoSize, TelegramObject
 
@@ -33,29 +33,39 @@ class Document(TelegramObject):
 
     Args:
         file_id (str):
-        **kwargs: Arbitrary keyword arguments.
-
-    Keyword Args:
         thumb (Optional[:class:`telegram.PhotoSize`]):
         file_name (Optional[str]):
         mime_type (Optional[str]):
         file_size (Optional[int]):
+        **kwargs (dict): Arbitrary keyword arguments.
+
     """
 
-    def __init__(self, file_id, **kwargs):
+    _id_keys = ('file_id',)
+
+    def __init__(self,
+                 file_id,
+                 thumb=None,
+                 file_name=None,
+                 mime_type=None,
+                 file_size=None,
+                 **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))
+        self.thumb = thumb
+        self.file_name = file_name
+        self.mime_type = mime_type
+        self.file_size = file_size
+
+        self._id_attrs = (self.file_id,)
 
     @staticmethod
-    def de_json(data):
+    def de_json(data, bot):
         """
         Args:
-            data (str):
+            data (dict):
+            bot (telegram.Bot):
 
         Returns:
             telegram.Document:
@@ -63,6 +73,8 @@ class Document(TelegramObject):
         if not data:
             return None
 
-        data['thumb'] = PhotoSize.de_json(data.get('thumb'))
+        data = super(Document, Document).de_json(data, bot)
+
+        data['thumb'] = PhotoSize.de_json(data.get('thumb'), bot)
 
         return Document(**data)

telegram/emoji.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python
 # flake8: noqa
-# pylint: disable=C0103,R0903
+# pylint: disable=C0103,R0903,E0213
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,14 +18,27 @@
 #
 # 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 an Emoji."""
+"""This module contains an object that represents an Emoji.
 
-from future.utils import bytes_to_native_str as n
+This module will be removed in the future.
+"""
+
+import warnings
+
+from future.utils import bytes_to_native_str
 
 
-class Emoji(object):
+class Emoji2(object):
     """This object represents an Emoji."""
 
+    def n(b):
+
+        def e(cls):
+            warnings.warn("telegram.Emoji is being deprecated, please see https://git.io/v6DeB")
+            return bytes_to_native_str(b)
+
+        return property(e)
+
     GRINNING_FACE_WITH_SMILING_EYES = n(b'\xF0\x9F\x98\x81')
     FACE_WITH_TEARS_OF_JOY = n(b'\xF0\x9F\x98\x82')
     SMILING_FACE_WITH_OPEN_MOUTH = n(b'\xF0\x9F\x98\x83')
@@ -879,3 +892,6 @@ class Emoji(object):
     CLOCK_FACE_TEN_THIRTY = n(b'\xF0\x9F\x95\xA5')
     CLOCK_FACE_ELEVEN_THIRTY = n(b'\xF0\x9F\x95\xA6')
     CLOCK_FACE_TWELVE_THIRTY = n(b'\xF0\x9F\x95\xA7')
+
+
+Emoji = Emoji2()

telegram/error.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,7 +16,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 Error."""
+"""This module contains an object that represents a Telegram Error."""
 
 
 def _lstrip_str(in_s, lstr):
@@ -62,9 +62,7 @@ class TelegramError(Exception):
 
 
 class Unauthorized(TelegramError):
-
-    def __init__(self):
-        super(Unauthorized, self).__init__('Unauthorized')
+    pass
 
 
 class InvalidToken(TelegramError):
@@ -85,3 +83,29 @@ class TimedOut(NetworkError):
 
     def __init__(self):
         super(TimedOut, self).__init__('Timed out')
+
+
+class ChatMigrated(TelegramError):
+
+    def __init__(self, new_chat_id):
+        """
+        Args:
+            new_chat_id (int):
+
+        """
+        super(ChatMigrated,
+              self).__init__('Group migrated to supergroup. New chat id: {}'.format(new_chat_id))
+        self.new_chat_id = new_chat_id
+
+
+class RetryAfter(TelegramError):
+
+    def __init__(self, retry_after):
+        """
+        Args:
+            retry_after (int):
+
+        """
+        super(RetryAfter,
+              self).__init__('Flood control exceeded. Retry in {} seconds'.format(retry_after))
+        self.retry_after = float(retry_after)

telegram/ext/__init__.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -26,7 +26,8 @@ from .choseninlineresulthandler import ChosenInlineResultHandler
 from .commandhandler import CommandHandler
 from .handler import Handler
 from .inlinequeryhandler import InlineQueryHandler
-from .messagehandler import MessageHandler, Filters
+from .messagehandler import MessageHandler
+from .filters import BaseFilter, Filters
 from .regexhandler import RegexHandler
 from .stringcommandhandler import StringCommandHandler
 from .stringregexhandler import StringRegexHandler
@@ -35,5 +36,5 @@ from .conversationhandler import ConversationHandler
 
 __all__ = ('Dispatcher', 'JobQueue', 'Job', 'Updater', 'CallbackQueryHandler',
            'ChosenInlineResultHandler', 'CommandHandler', 'Handler', 'InlineQueryHandler',
-           'MessageHandler', 'Filters', 'RegexHandler', 'StringCommandHandler',
+           'MessageHandler', 'BaseFilter', 'Filters', 'RegexHandler', 'StringCommandHandler',
            'StringRegexHandler', 'TypeHandler', 'ConversationHandler')

telegram/ext/callbackqueryhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,14 +18,18 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """ This module contains the CallbackQueryHandler class """
 
-from .handler import Handler
+import re
+
+from future.utils import string_types
+
 from telegram import Update
-from telegram.utils.deprecate import deprecate
+from .handler import Handler
 
 
 class CallbackQueryHandler(Handler):
     """
-    Handler class to handle Telegram callback queries.
+    Handler class to handle Telegram callback queries. Optionally based on a regex.
+    Read the documentation of the ``re`` module for more information.
 
     Args:
         callback (function): A function that takes ``bot, update`` as
@@ -34,27 +38,69 @@ class CallbackQueryHandler(Handler):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.
             Default is ``False``.
+        pattern (optional[str or Pattern]): Optional regex pattern. If not ``None`` ``re.match``
+            is used to determine if an update should be handled by this handler.
+        pass_groups (optional[bool]): If the callback should be passed the
+            result of ``re.match(pattern, data).groups()`` as a keyword
+            argument called ``groups``. Default is ``False``
+        pass_groupdict (optional[bool]): If the callback should be passed the
+            result of ``re.match(pattern, data).groupdict()`` as a keyword
+            argument called ``groupdict``. Default is ``False``
+        pass_user_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``user_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the user that sent the update. For each update of
+            the same user, it will be the same ``dict``. Default is ``False``.
+        pass_chat_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``chat_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the chat that the update was sent in.
+            For each update in the same chat, it will be the same ``dict``. Default is ``False``.
     """
 
-    def __init__(self, callback, pass_update_queue=False, pass_job_queue=False):
-        super(CallbackQueryHandler, self).__init__(callback,
-                                                   pass_update_queue=pass_update_queue,
-                                                   pass_job_queue=pass_job_queue)
+    def __init__(self,
+                 callback,
+                 pass_update_queue=False,
+                 pass_job_queue=False,
+                 pattern=None,
+                 pass_groups=False,
+                 pass_groupdict=False,
+                 pass_user_data=False,
+                 pass_chat_data=False):
+        super(CallbackQueryHandler, self).__init__(
+            callback,
+            pass_update_queue=pass_update_queue,
+            pass_job_queue=pass_job_queue,
+            pass_user_data=pass_user_data,
+            pass_chat_data=pass_chat_data)
+
+        if isinstance(pattern, string_types):
+            pattern = re.compile(pattern)
+
+        self.pattern = pattern
+        self.pass_groups = pass_groups
+        self.pass_groupdict = pass_groupdict
 
     def check_update(self, update):
-        return isinstance(update, Update) and update.callback_query
+        if isinstance(update, Update) and update.callback_query:
+            if self.pattern:
+                if update.callback_query.data:
+                    match = re.match(self.pattern, update.callback_query.data)
+                    return bool(match)
+            else:
+                return True
 
     def handle_update(self, update, dispatcher):
-        optional_args = self.collect_optional_args(dispatcher)
+        optional_args = self.collect_optional_args(dispatcher, update)
+        if self.pattern:
+            match = re.match(self.pattern, update.callback_query.data)
+
+            if self.pass_groups:
+                optional_args['groups'] = match.groups()
+            if self.pass_groupdict:
+                optional_args['groupdict'] = match.groupdict()
 
         return self.callback(dispatcher.bot, update, **optional_args)
-
-    # old non-PEP8 Handler methods
-    m = "telegram.CallbackQueryHandler."
-    checkUpdate = deprecate(check_update, m + "checkUpdate", m + "check_update")
-    handleUpdate = deprecate(handle_update, m + "handleUpdate", m + "handle_update")

telegram/ext/choseninlineresulthandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -35,23 +35,39 @@ class ChosenInlineResultHandler(Handler):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.
             Default is ``False``.
+        pass_user_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``user_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the user that sent the update. For each update of
+            the same user, it will be the same ``dict``. Default is ``False``.
+        pass_chat_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``chat_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the chat that the update was sent in.
+            For each update in the same chat, it will be the same ``dict``. Default is ``False``.
     """
 
-    def __init__(self, callback, pass_update_queue=False, pass_job_queue=False):
-        super(ChosenInlineResultHandler, self).__init__(callback,
-                                                        pass_update_queue=pass_update_queue,
-                                                        pass_job_queue=pass_job_queue)
+    def __init__(self,
+                 callback,
+                 pass_update_queue=False,
+                 pass_job_queue=False,
+                 pass_user_data=False,
+                 pass_chat_data=False):
+        super(ChosenInlineResultHandler, self).__init__(
+            callback,
+            pass_update_queue=pass_update_queue,
+            pass_job_queue=pass_job_queue,
+            pass_user_data=pass_user_data,
+            pass_chat_data=pass_chat_data)
 
     def check_update(self, update):
         return isinstance(update, Update) and update.chosen_inline_result
 
     def handle_update(self, update, dispatcher):
-        optional_args = self.collect_optional_args(dispatcher)
+        optional_args = self.collect_optional_args(dispatcher, update)
 
         return self.callback(dispatcher.bot, update, **optional_args)
 

telegram/ext/commandhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,10 +17,10 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """ This module contains the CommandHandler class """
+import warnings
 
 from .handler import Handler
 from telegram import Update
-from telegram.utils.deprecate import deprecate
 
 
 class CommandHandler(Handler):
@@ -30,62 +30,107 @@ class CommandHandler(Handler):
     name and/or some additional text.
 
     Args:
-        command (str): The name of the command this handler should listen for.
+        command (str|list): The name of the command or list of command this handler should
+            listen for.
         callback (function): A function that takes ``bot, update`` as
             positional arguments. It will be called when the ``check_update``
             has determined that an update should be processed by this handler.
+        filters (telegram.ext.BaseFilter): A filter inheriting from
+            :class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
+            :class:`telegram.ext.filters.Filters`. Filters can be combined using bitwise
+            operators (& for and, | for or).
         allow_edited (Optional[bool]): If the handler should also accept edited messages.
             Default is ``False``
         pass_args (optional[bool]): If the handler should be passed the
             arguments passed to the command as a keyword argument called `
             ``args``. It will contain a list of strings, which is the text
-            following the command split on spaces. Default is ``False``
+            following the command split on single or consecutive whitespace characters.
+            Default is ``False``
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.
             Default is ``False``.
+        pass_user_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``user_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the user that sent the update. For each update of
+            the same user, it will be the same ``dict``. Default is ``False``.
+        pass_chat_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``chat_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the chat that the update was sent in.
+            For each update in the same chat, it will be the same ``dict``. Default is ``False``.
     """
 
     def __init__(self,
                  command,
                  callback,
+                 filters=None,
                  allow_edited=False,
                  pass_args=False,
                  pass_update_queue=False,
-                 pass_job_queue=False):
-        super(CommandHandler, self).__init__(callback,
-                                             pass_update_queue=pass_update_queue,
-                                             pass_job_queue=pass_job_queue)
-        self.command = command
+                 pass_job_queue=False,
+                 pass_user_data=False,
+                 pass_chat_data=False):
+        super(CommandHandler, self).__init__(
+            callback,
+            pass_update_queue=pass_update_queue,
+            pass_job_queue=pass_job_queue,
+            pass_user_data=pass_user_data,
+            pass_chat_data=pass_chat_data)
+        try:
+            _str = basestring  # Python 2
+        except NameError:
+            _str = str  # Python 3
+
+        if isinstance(command, _str):
+            self.command = [command]
+        else:
+            self.command = command
+        self.filters = filters
         self.allow_edited = allow_edited
         self.pass_args = pass_args
 
+        # We put this up here instead of with the rest of checking code
+        # in check_update since we don't wanna spam a ton
+        if isinstance(self.filters, list):
+            warnings.warn('Using a list of filters in MessageHandler is getting '
+                          'deprecated, please use bitwise operators (& and |) '
+                          'instead. More info: https://git.io/vPTbc.')
+
     def check_update(self, update):
         if (isinstance(update, Update)
                 and (update.message or update.edited_message and self.allow_edited)):
             message = update.message or update.edited_message
 
-            return (message.text and message.text.startswith('/')
-                    and message.text[1:].split(' ')[0].split('@')[0] == self.command)
+            if message.text:
+                command = message.text[1:].split(' ')[0].split('@')
+                command.append(
+                    message.bot.username)  # in case the command was send without a username
+
+                if self.filters is None:
+                    res = True
+                elif isinstance(self.filters, list):
+                    res = any(func(message) for func in self.filters)
+                else:
+                    res = self.filters(message)
+
+                return res and (message.text.startswith('/') and command[0] in self.command
+                                and command[1].lower() == message.bot.username.lower())
+            else:
+                return False
 
         else:
             return False
 
     def handle_update(self, update, dispatcher):
-        optional_args = self.collect_optional_args(dispatcher)
+        optional_args = self.collect_optional_args(dispatcher, update)
 
         message = update.message or update.edited_message
 
         if self.pass_args:
-            optional_args['args'] = message.text.split(' ')[1:]
+            optional_args['args'] = message.text.split()[1:]
 
         return self.callback(dispatcher.bot, update, **optional_args)
-
-    # old non-PEP8 Handler methods
-    m = "telegram.CommandHandler."
-    checkUpdate = deprecate(check_update, m + "checkUpdate", m + "check_update")
-    handleUpdate = deprecate(handle_update, m + "handleUpdate", m + "handle_update")

telegram/ext/conversationhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -21,13 +21,16 @@
 import logging
 
 from telegram import Update
-from telegram.ext import Handler
+from telegram.ext import (Handler, CallbackQueryHandler, InlineQueryHandler,
+                          ChosenInlineResultHandler)
 from telegram.utils.promise import Promise
 
 
 class ConversationHandler(Handler):
     """
-    A handler to hold a conversation with a user by managing four collections of other handlers.
+    A handler to hold a conversation with a single user by managing four collections of other
+    handlers. Note that neither posts in Telegram Channels, nor group interactions with multiple
+    users are managed by instances of this class.
 
     The first collection, a ``list`` named ``entry_points``, is used to initiate the conversation,
     for example with a ``CommandHandler`` or ``RegexHandler``.
@@ -85,7 +88,10 @@ class ConversationHandler(Handler):
                  fallbacks,
                  allow_reentry=False,
                  run_async_timeout=None,
-                 timed_out_behavior=None):
+                 timed_out_behavior=None,
+                 per_chat=True,
+                 per_user=True,
+                 per_message=False):
 
         self.entry_points = entry_points
         """:type: list[telegram.ext.Handler]"""
@@ -103,43 +109,76 @@ class ConversationHandler(Handler):
         """:type: list[telegram.ext.Handler]"""
 
         self.conversations = dict()
-        """:type: dict[(int, int): str]"""
+        self.per_user = per_user
+        self.per_chat = per_chat
+        self.per_message = per_message
+        """:type: dict[tuple: object]"""
 
         self.current_conversation = None
         self.current_handler = None
 
         self.logger = logging.getLogger(__name__)
 
+        if not any((self.per_user, self.per_chat, self.per_message)):
+            raise ValueError("'per_user', 'per_chat' and 'per_message' can't all be 'False'")
+
+        if self.per_message and not self.per_chat:
+            logging.warning("If 'per_message=True' is used, 'per_chat=True' should also be used, "
+                            "since message IDs are not globally unique.")
+
+        all_handlers = list()
+        all_handlers.extend(entry_points)
+        all_handlers.extend(fallbacks)
+
+        for state_handlers in states.values():
+            all_handlers.extend(state_handlers)
+
+        if self.per_message:
+            for handler in all_handlers:
+                if not isinstance(handler, CallbackQueryHandler):
+                    logging.warning("If 'per_message=True', all entry points and state handlers"
+                                    " must be 'CallbackQueryHandler', since no other handlers "
+                                    "have a message context.")
+        else:
+            for handler in all_handlers:
+                if isinstance(handler, CallbackQueryHandler):
+                    logging.warning("If 'per_message=False', 'CallbackQueryHandler' will not be "
+                                    "tracked for every message.")
+
+        if self.per_chat:
+            for handler in all_handlers:
+                if isinstance(handler, (InlineQueryHandler, ChosenInlineResultHandler)):
+                    logging.warning("If 'per_chat=True', 'InlineQueryHandler' can not be used, "
+                                    "since inline queries have no chat context.")
+
+    def _get_key(self, update):
+        chat = update.effective_chat
+        user = update.effective_user
+
+        key = list()
+
+        if self.per_chat:
+            key.append(chat.id)
+
+        if self.per_user:
+            key.append(user.id)
+
+        if self.per_message:
+            key.append(update.callback_query.inline_message_id
+                       or update.callback_query.message.message_id)
+
+        return tuple(key)
+
     def check_update(self, update):
 
-        if not isinstance(update, Update):
+        # Ignore messages in channels
+        if (not isinstance(update, Update) or update.channel_post or self.per_chat
+                and (update.inline_query or update.chosen_inline_result) or self.per_message
+                and not update.callback_query or update.callback_query and self.per_chat
+                and not update.callback_query.message):
             return False
 
-        user = None
-        chat = None
-
-        if update.message:
-            user = update.message.from_user
-            chat = update.message.chat
-
-        elif update.edited_message:
-            user = update.edited_message.from_user
-            chat = update.edited_message.chat
-
-        elif update.inline_query:
-            user = update.inline_query.from_user
-
-        elif update.chosen_inline_result:
-            user = update.chosen_inline_result.from_user
-
-        elif update.callback_query:
-            user = update.callback_query.from_user
-            chat = update.callback_query.message.chat if update.callback_query.message else None
-
-        else:
-            return False
-
-        key = (chat.id, user.id) if chat else (None, user.id)
+        key = self._get_key(update)
         state = self.conversations.get(key)
 
         # Resolve promises
@@ -147,10 +186,16 @@ class ConversationHandler(Handler):
             self.logger.debug('waiting for promise...')
 
             old_state, new_state = state
-            new_state.result(timeout=self.run_async_timeout)
+            error = False
+            try:
+                res = new_state.result(timeout=self.run_async_timeout)
+            except Exception as exc:
+                self.logger.exception("Promise function raised exception")
+                self.logger.exception("{}".format(exc))
+                error = True
 
-            if new_state.done.is_set():
-                self.update_state(new_state.result(), key)
+            if not error and new_state.done.is_set():
+                self.update_state(res, key)
                 state = self.conversations.get(key)
 
             else:
@@ -213,10 +258,13 @@ class ConversationHandler(Handler):
 
     def update_state(self, new_state, key):
         if new_state == self.END:
-            del self.conversations[key]
+            if key in self.conversations:
+                del self.conversations[key]
+            else:
+                pass
 
         elif isinstance(new_state, Promise):
-            self.conversations[key] = (self.conversations[key], new_state)
+            self.conversations[key] = (self.conversations.get(key), new_state)
 
         elif new_state is not None:
             self.conversations[key] = new_state

telegram/ext/dispatcher.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,70 +19,43 @@
 """This module contains the Dispatcher class."""
 
 import logging
+import weakref
 from functools import wraps
-from threading import Thread, Lock, Event, current_thread
+from threading import Thread, Lock, Event, current_thread, BoundedSemaphore
 from time import sleep
+from uuid import uuid4
+from collections import defaultdict
+
 from queue import Queue, Empty
 
 from future.builtins import range
 
-from telegram import (TelegramError, NullHandler)
-from telegram.utils import request
+from telegram import TelegramError
 from telegram.ext.handler import Handler
-from telegram.utils.deprecate import deprecate
 from telegram.utils.promise import Promise
 
-logging.getLogger(__name__).addHandler(NullHandler())
-
-ASYNC_QUEUE = Queue()
-ASYNC_THREADS = set()
+logging.getLogger(__name__).addHandler(logging.NullHandler())
 """:type: set[Thread]"""
-ASYNC_LOCK = Lock()  # guards ASYNC_THREADS
 DEFAULT_GROUP = 0
 
 
-def _pooled():
-    """
-    A wrapper to run a thread in a thread pool
-    """
-    while 1:
-        promise = ASYNC_QUEUE.get()
-
-        # If unpacking fails, the thread pool is being closed from Updater._join_async_threads
-        if not isinstance(promise, Promise):
-            logging.getLogger(__name__).debug("Closing run_async thread %s/%d" %
-                                              (current_thread().getName(), len(ASYNC_THREADS)))
-            break
-
-        try:
-            promise.run()
-
-        except:
-            logging.getLogger(__name__).exception("run_async function raised exception")
-
-
 def run_async(func):
-    """
-    Function decorator that will run the function in a new thread.
+    """Function decorator that will run the function in a new thread.
+
+    Using this decorator is only possible when only a single Dispatcher exist in the system.
 
     Args:
         func (function): The function to run in the thread.
+        async_queue (Queue): The queue of the functions to be executed asynchronously.
 
     Returns:
         function:
-    """
 
-    # TODO: handle exception in async threads
-    #       set a threading.Event to notify caller thread
+    """
 
     @wraps(func)
     def async_func(*args, **kwargs):
-        """
-        A wrapper to run a function in a thread
-        """
-        promise = Promise(func, args, kwargs)
-        ASYNC_QUEUE.put(promise)
-        return promise
+        return Dispatcher.get_instance().run_async(func, *args, **kwargs)
 
     return async_func
 
@@ -100,12 +73,23 @@ class Dispatcher(object):
             callbacks
         workers (Optional[int]): Number of maximum concurrent worker threads for the ``@run_async``
             decorator
+
     """
+    __singleton_lock = Lock()
+    __singleton_semaphore = BoundedSemaphore()
+    __singleton = None
+    logger = logging.getLogger(__name__)
 
     def __init__(self, bot, update_queue, workers=4, exception_event=None, job_queue=None):
         self.bot = bot
         self.update_queue = update_queue
         self.job_queue = job_queue
+        self.workers = workers
+
+        self.user_data = defaultdict(dict)
+        """:type: dict[int, dict]"""
+        self.chat_data = defaultdict(dict)
+        """:type: dict[int, dict]"""
 
         self.handlers = {}
         """:type: dict[int, list[Handler]"""
@@ -113,28 +97,86 @@ class Dispatcher(object):
         """:type: list[int]"""
         self.error_handlers = []
 
-        self.logger = logging.getLogger(__name__)
         self.running = False
         self.__stop_event = Event()
         self.__exception_event = exception_event or Event()
+        self.__async_queue = Queue()
+        self.__async_threads = set()
 
-        with ASYNC_LOCK:
-            if not ASYNC_THREADS:
-                if request.is_con_pool_initialized():
-                    raise RuntimeError('Connection Pool already initialized')
-
-                # we need a connection pool the size of:
-                # * for each of the workers
-                # * 1 for Dispatcher
-                # * 1 for polling Updater (even if updater is webhook, we can spare a connection)
-                # * 1 for JobQueue
-                request.CON_POOL_SIZE = workers + 3
-                for i in range(workers):
-                    thread = Thread(target=_pooled, name=str(i))
-                    ASYNC_THREADS.add(thread)
-                    thread.start()
+        # For backward compatibility, we allow a "singleton" mode for the dispatcher. When there's
+        # only one instance of Dispatcher, it will be possible to use the `run_async` decorator.
+        with self.__singleton_lock:
+            if self.__singleton_semaphore.acquire(blocking=0):
+                self._set_singleton(self)
             else:
-                self.logger.debug('Thread pool already initialized, skipping.')
+                self._set_singleton(None)
+
+    @classmethod
+    def _reset_singleton(cls):
+        # NOTE: This method was added mainly for test_updater benefit and specifically pypy. Never
+        #       call it in production code.
+        cls.__singleton_semaphore.release()
+
+    def _init_async_threads(self, base_name, workers):
+        base_name = '{}_'.format(base_name) if base_name else ''
+
+        for i in range(workers):
+            thread = Thread(target=self._pooled, name='{}{}'.format(base_name, i))
+            self.__async_threads.add(thread)
+            thread.start()
+
+    @classmethod
+    def _set_singleton(cls, val):
+        cls.logger.debug('Setting singleton dispatcher as %s', val)
+        cls.__singleton = weakref.ref(val) if val else None
+
+    @classmethod
+    def get_instance(cls):
+        """Get the singleton instance of this class.
+
+        Returns:
+            Dispatcher
+
+        """
+        if cls.__singleton is not None:
+            return cls.__singleton()
+        else:
+            raise RuntimeError('{} not initialized or multiple instances exist'.format(
+                cls.__name__))
+
+    def _pooled(self):
+        """
+        A wrapper to run a thread in a thread pool
+        """
+        thr_name = current_thread().getName()
+        while 1:
+            promise = self.__async_queue.get()
+
+            # If unpacking fails, the thread pool is being closed from Updater._join_async_threads
+            if not isinstance(promise, Promise):
+                self.logger.debug("Closing run_async thread %s/%d", thr_name,
+                                  len(self.__async_threads))
+                break
+
+            promise.run()
+
+    def run_async(self, func, *args, **kwargs):
+        """Queue a function (with given args/kwargs) to be run asynchronously.
+
+        Args:
+            func (function): The function to run in the thread.
+            args (Optional[tuple]): Arguments to `func`.
+            kwargs (Optional[dict]): Keyword arguments to `func`.
+
+        Returns:
+            Promise
+
+        """
+        # TODO: handle exception in async threads
+        #       set a threading.Event to notify caller thread
+        promise = Promise(func, args, kwargs)
+        self.__async_queue.put(promise)
+        return promise
 
     def start(self):
         """
@@ -151,6 +193,7 @@ class Dispatcher(object):
             self.logger.error(msg)
             raise TelegramError(msg)
 
+        self._init_async_threads(uuid4(), self.workers)
         self.running = True
         self.logger.debug('Dispatcher started')
 
@@ -183,6 +226,25 @@ class Dispatcher(object):
                 sleep(0.1)
             self.__stop_event.clear()
 
+        # async threads must be join()ed only after the dispatcher thread was joined,
+        # otherwise we can still have new async threads dispatched
+        threads = list(self.__async_threads)
+        total = len(threads)
+
+        # Stop all threads in the thread pool by put()ting one non-tuple per thread
+        for i in range(total):
+            self.__async_queue.put(None)
+
+        for i, thr in enumerate(threads):
+            self.logger.debug('Waiting for async thread {0}/{1} to end'.format(i + 1, total))
+            thr.join()
+            self.__async_threads.remove(thr)
+            self.logger.debug('async thread {0}/{1} has ended'.format(i + 1, total))
+
+    @property
+    def has_running_threads(self):
+        return self.running or bool(self.__async_threads)
+
     def process_update(self, update):
         """
         Processes a single update.
@@ -242,7 +304,7 @@ class Dispatcher(object):
             which handlers were added to the group defines the priority.
 
         Args:
-            handler (Handler): A Handler instance
+            handler (telegram.ext.Handler): A Handler instance
             group (Optional[int]): The group identifier. Default is 0
         """
 
@@ -263,7 +325,7 @@ class Dispatcher(object):
         Remove a handler from the specified group
 
         Args:
-            handler (Handler): A Handler instance
+            handler (telegram.ext.Handler): A Handler instance
             group (optional[object]): The group identifier. Default is 0
         """
         if handler in self.handlers[group]:
@@ -305,11 +367,3 @@ class Dispatcher(object):
 
         for callback in self.error_handlers:
             callback(self.bot, update, error)
-
-    # old non-PEP8 Dispatcher methods
-    m = "telegram.dispatcher."
-    addHandler = deprecate(add_handler, m + "AddHandler", m + "add_handler")
-    removeHandler = deprecate(remove_handler, m + "removeHandler", m + "remove_handler")
-    addErrorHandler = deprecate(add_error_handler, m + "addErrorHandler", m + "add_error_handler")
-    removeErrorHandler = deprecate(remove_error_handler, m + "removeErrorHandler",
-                                   m + "remove_error_handler")

telegram/ext/filters.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2017
+# 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 Filters for use with the MessageHandler class """
+from telegram import Chat
+
+try:
+    str_type = base_string
+except NameError:
+    str_type = str
+
+
+class BaseFilter(object):
+    """Base class for all Message Filters
+
+    Subclassing from this class filters to be combined using bitwise operators:
+
+    And:
+
+        >>> (Filters.text & Filters.entity(MENTION))
+
+    Or:
+
+        >>> (Filters.audio | Filters.video)
+
+    Not:
+
+        >>> ~ Filters.command
+
+    Also works with more than two filters:
+
+        >>> (Filters.text & (Filters.entity(URL) | Filters.entity(TEXT_LINK)))
+        >>> Filters.text & (~ Filters.forwarded)
+
+    If you want to create your own filters create a class inheriting from this class and implement
+    a `filter` method that returns a boolean: `True` if the message should be handled, `False`
+    otherwise. Note that the filters work only as class instances, not actual class objects
+    (so remember to initialize your filter classes).
+    """
+
+    def __call__(self, message):
+        return self.filter(message)
+
+    def __and__(self, other):
+        return MergedFilter(self, and_filter=other)
+
+    def __or__(self, other):
+        return MergedFilter(self, or_filter=other)
+
+    def __invert__(self):
+        return InvertedFilter(self)
+
+    def filter(self, message):
+        raise NotImplementedError
+
+
+class InvertedFilter(BaseFilter):
+    """Represents a filter that has been inverted.
+
+    Args:
+        f: The filter to invert
+    """
+
+    def __init__(self, f):
+        self.f = f
+
+    def filter(self, message):
+        return not self.f(message)
+
+    def __str__(self):
+        return "<telegram.ext.filters.InvertedFilter inverting {}>".format(self.f)
+
+    __repr__ = __str__
+
+
+class MergedFilter(BaseFilter):
+    """Represents a filter consisting of two other filters.
+
+    Args:
+        base_filter: Filter 1 of the merged filter
+        and_filter: Optional filter to "and" with base_filter. Mutually exclusive with or_filter.
+        or_filter: Optional filter to "or" with base_filter. Mutually exclusive with and_filter.
+    """
+
+    def __init__(self, base_filter, and_filter=None, or_filter=None):
+        self.base_filter = base_filter
+        self.and_filter = and_filter
+        self.or_filter = or_filter
+
+    def filter(self, message):
+        if self.and_filter:
+            return self.base_filter(message) and self.and_filter(message)
+        elif self.or_filter:
+            return self.base_filter(message) or self.or_filter(message)
+
+    def __str__(self):
+        return ("<telegram.ext.filters.MergedFilter consisting of"
+                " {} {} {}>").format(self.base_filter, "and" if self.and_filter else "or",
+                                     self.and_filter or self.or_filter)
+
+    __repr__ = __str__
+
+
+class Filters(object):
+    """
+    Predefined filters for use with the `filter` argument of :class:`telegram.ext.MessageHandler`.
+    """
+
+    class _All(BaseFilter):
+
+        def filter(self, message):
+            return True
+
+    all = _All()
+
+    class _Text(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.text and not message.text.startswith('/'))
+
+    text = _Text()
+
+    class _Command(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.text and message.text.startswith('/'))
+
+    class _Reply(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.reply_to_message)
+
+    reply = _Reply()
+
+    command = _Command()
+
+    class _Audio(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.audio)
+
+    audio = _Audio()
+
+    class _Document(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.document)
+
+    document = _Document()
+
+    class _Photo(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.photo)
+
+    photo = _Photo()
+
+    class _Sticker(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.sticker)
+
+    sticker = _Sticker()
+
+    class _Video(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.video)
+
+    video = _Video()
+
+    class _Voice(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.voice)
+
+    voice = _Voice()
+
+    class _Contact(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.contact)
+
+    contact = _Contact()
+
+    class _Location(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.location)
+
+    location = _Location()
+
+    class _Venue(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.venue)
+
+    venue = _Venue()
+
+    class _StatusUpdate(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.new_chat_member or message.left_chat_member
+                        or message.new_chat_title or message.new_chat_photo
+                        or message.delete_chat_photo or message.group_chat_created
+                        or message.supergroup_chat_created or message.channel_chat_created
+                        or message.migrate_to_chat_id or message.migrate_from_chat_id
+                        or message.pinned_message)
+
+    status_update = _StatusUpdate()
+
+    class _Forwarded(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.forward_date)
+
+    forwarded = _Forwarded()
+
+    class _Game(BaseFilter):
+
+        def filter(self, message):
+            return bool(message.game)
+
+    game = _Game()
+
+    class entity(BaseFilter):
+        """Filters messages to only allow those which have a :class:`telegram.MessageEntity`
+        where their `type` matches `entity_type`.
+
+        Args:
+            entity_type: Entity type to check for. All types can be found as constants
+                in :class:`telegram.MessageEntity`.
+
+        Returns: function to use as filter
+        """
+
+        def __init__(self, entity_type):
+            self.entity_type = entity_type
+
+        def filter(self, message):
+            return any([entity.type == self.entity_type for entity in message.entities])
+
+    class _Private(BaseFilter):
+
+        def filter(self, message):
+            return message.chat.type == Chat.PRIVATE
+
+    private = _Private()
+
+    class _Group(BaseFilter):
+
+        def filter(self, message):
+            return message.chat.type in [Chat.GROUP, Chat.SUPERGROUP]
+
+    group = _Group()
+
+    class language(BaseFilter):
+        """
+        Filters messages to only allow those which are from users with a certain language code.
+        Note that according to telegrams documentation, every single user does not have the
+        language_code attribute.
+
+        Args:
+            lang (str|list): Which language code(s) to allow through. This will be matched using
+                .startswith meaning that 'en' will match both 'en_US' and 'en_GB'
+        """
+
+        def __init__(self, lang):
+            if isinstance(lang, str_type):
+                self.lang = [lang]
+            else:
+                self.lang = lang
+
+        def filter(self, message):
+            return message.from_user.language_code and any(
+                [message.from_user.language_code.startswith(x) for x in self.lang])

telegram/ext/handler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2016
+# Copyright (C) 2015-2017
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,8 +19,6 @@
 """ This module contains the base class for handlers as used by the
 Dispatcher """
 
-from telegram.utils.deprecate import deprecate
-
 
 class Handler(object):
     """
@@ -34,17 +32,32 @@ class Handler(object):
         pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``update_queue`` will be passed to the callback function. It will be the ``Queue``
             instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
-             be used to insert updates. Default is ``False``.
+            be used to insert updates. Default is ``False``.
         pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
             ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
             instance created by the ``Updater`` which can be used to schedule new jobs.
             Default is ``False``.
+        pass_user_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``user_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the user that sent the update. For each update of
+            the same user, it will be the same ``dict``. Default is ``False``.
+        pass_chat_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``chat_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the chat that the update was sent in.
+            For each update in the same chat, it will be the same ``dict``. Default is ``False``.
     """
 
-    def __init__(self, callback, pass_update_queue=False, pass_job_queue=False):
+    def __init__(self,
+                 callback,
+                 pass_update_queue=False,
+                 pass_job_queue=False,
+                 pass_user_data=False,
+                 pass_chat_data=False):
         self.callback = callback
         self.pass_update_queue = pass_update_queue
         self.pass_job_queue = pass_job_queue
+        self.pass_user_data = pass_user_data
+        self.pass_chat_data = pass_chat_data
 
     def check_update(self, update):
         """
@@ -69,30 +82,33 @@ class Handler(object):
 
         Args:
             update (object): The update to be handled
-            dispatcher (Dispatcher): The dispatcher to collect optional args
+            dispatcher (telegram.ext.Dispatcher): The dispatcher to collect optional args
 
         """
         raise NotImplementedError
 
-    def collect_optional_args(self, dispatcher):
+    def collect_optional_args(self, dispatcher, update=None):
         """
         Prepares the optional arguments that are the same for all types of
         handlers
 
         Args:
-            dispatcher (Dispatcher):
+            dispatcher (telegram.ext.Dispatcher):
         """
         optional_args = dict()
+
         if self.pass_update_queue:
             optional_args['update_queue'] = dispatcher.update_queue
         if self.pass_job_queue:
             optional_args['job_queue'] = dispatcher.job_queue
+        if self.pass_user_data or self.pass_chat_data:
+            chat = update.effective_chat
+            user = update.effective_user
+
+            if self.pass_user_data:
+                optional_args['user_data'] = dispatcher.user_data[user.id if user else None]
+
+            if self.pass_chat_data:
+                optional_args['chat_data'] = dispatcher.chat_data[chat.id if chat else None]
 
         return optional_args
-
-    # old non-PEP8 Handler methods
-    m = "telegram.Handler."
-    checkUpdate = deprecate(check_update, m + "checkUpdate", m + "check_update")
-    handleUpdate = deprecate(handle_update, m + "handleUpdate", m + "handle_update")
-    collectOptionalArgs = deprecate(collect_optional_args, m + "collectOptionalArgs",
-                                    m + "collect_optional_args")