Bump to v10.0.2

Fixes #1073

.codeclimate.yml

@@ -1,20 +0,0 @@
-exclude_paths:
-- "tests/*"
-- "examples/*"
-engines:
-  duplication:
-    enabled: true
-    config:
-      languages:
-      - python:
-    checks:
-      Similar code:
-        enabled: false
-
-  radon:
-    enabled: true
-    config:
-      threshold: "C"
-ratings:
-  paths:
-    - "**.py"

.gitignore

@@ -40,6 +40,7 @@ htmlcov/
 .coverage
 .coverage.*
 .cache
+.pytest_cache
 nosetests.xml
 coverage.xml
 *,cover

.pre-commit-config.yaml

@@ -6,10 +6,10 @@
         args:
         - --diff
 -   repo: git://github.com/pre-commit/pre-commit-hooks
-    sha: 78818b90cd694c29333ba54d38f9e60b6359ccfc
+    sha: v1.2.0
     hooks:
     -   id: flake8
-        files: ^telegram/.*\.py$
+        exclude: ^(setup.py|docs/source/conf.py)$
 -   repo: git://github.com/pre-commit/mirrors-pylint
     sha: v1.7.1
     hooks:

.travis.yml

@@ -1,12 +1,10 @@
 language: python
 python:
   - "2.7"
-  - "3.3"
   - "3.4"
   - "3.5"
   - "3.6"
   - "pypy-5.7.1"
-  - "pypy3.5-5.8.0"
 
 dist: trusty
 sudo: false
@@ -36,4 +34,4 @@ script:
 
 after_success:
   - coverage combine
-  - codecov -F Travis
+  - codecov -F Travis

AUTHORS.rst

@@ -22,7 +22,9 @@ The following wonderful people contributed directly or indirectly to this projec
 - `bimmlerd <https://github.com/bimmlerd>`_
 - `d-qoi <https://github.com/d-qoi>`_
 - `daimajia <https://github.com/daimajia>`_
+- `Daniel Reed <https://github.com/nmlorg>`_
 - `Eli Gao <https://github.com/eligao>`_
+- `Emilio Molinari <https://github.com/xates>`_
 - `ErgoZ Riftbit Vaper <https://github.com/ergoz>`_
 - `Eugene Lisitsky <https://github.com/lisitsky>`_
 - `Eugenio Panadero <https://github.com/azogue>`_
@@ -44,21 +46,27 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Li-aung Yip <https://github.com/LiaungYip>`_
 - `macrojames <https://github.com/macrojames>`_
 - `Michael Elovskikh <https://github.com/wronglink>`_
+- `Mischa Krüger <https://github.com/Makman2>`_
 - `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>`_
+- `Oleg Sushchenko <https://github.com/feuillemorte>`_
+- `Or Bin <https://github.com/OrBin>`_
 - `overquota <https://github.com/overquota>`_
 - `Patrick Hofmann <https://github.com/PH89>`_
+- `Paul Larsen <https://github.com/PaulSonOfLars>`_
 - `Pieter Schutz <https://github.com/eldinnie>`_
 - `Rahiel Kasim <https://github.com/rahiel>`_
 - `Sascha <https://github.com/saschalalala>`_
 - `Shelomentsev D <https://github.com/shelomentsevd>`_
+- `Simon Schürrle <https://github.com/SitiSchu>`_
 - `sooyhwang <https://github.com/sooyhwang>`_
 - `thodnev <https://github.com/thodnev>`_
 - `Valentijn <https://github.com/Faalentijn>`_
 - `voider1 <https://github.com/voider1>`_
+- `Wagner Macedo <https://github.com/wagnerluis1982>`_
 - `wjt <https://github.com/wjt>`_
 
 Please add yourself here alphabetically when you submit your first pull request.

CHANGES.rst

@@ -1,6 +1,141 @@
 =======
 Changes
 =======
+**2018-04-17**
+*Released 10.0.2*
+
+Important fix:
+
+- Handle utf8 decoding errors (`#1076`_)
+
+New features:
+
+- Added Filter.regex (`#1028`_)
+- Filters for Category and file types (`#1046`_)
+- Added video note filter (`#1067`_)
+
+Fixes:
+
+- Fix in telegram.Message (`#1042`_)
+- Make chat_id a positional argument inside shortcut methods of Chat and User classes (`#1050`_)
+- Make Bot.full_name return a unicode object. (`#1063`_)
+- CommandHandler faster check (`#1074`_)
+- Correct documentation of Dispatcher.add_handler (`#1071`_)
+- Various small fixes to documentation.
+
+.. _`#1028`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1028
+.. _`#1042`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1042
+.. _`#1046`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1046
+.. _`#1050`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1050
+.. _`#1067`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1067
+.. _`#1063`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1063
+.. _`#1074`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1074
+.. _`#1076`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1076
+.. _`#1071`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1071
+
+**2018-03-05**
+*Released 10.0.1*
+
+Fixes:
+
+- Fix conversationhandler timeout (PR `#1032`_)
+- Add missing docs utils (PR `#912`_)
+
+.. _`#1032`: https://github.com/python-telegram-bot/python-telegram-bot/pull/826
+.. _`#912`: https://github.com/python-telegram-bot/python-telegram-bot/pull/826
+
+**2018-03-02**
+*Released 10.0.0*
+
+Non backward compatabile changes and changed defaults
+
+- JobQueue: Remove deprecated prevent_autostart & put() (PR `#1012`_)
+- Bot, Updater: Remove deprecated network_delay (PR `#1012`_)
+- Remove deprecated Message.new_chat_member (PR `#1012`_)
+- Retry bootstrap phase indefinitely (by default) on network errors (PR `#1018`_)
+
+New Features
+
+- Support v3.6 API (PR `#1006`_)
+- User.full_name convinience property (PR `#949`_)
+- Add `send_phone_number_to_provider` and `send_email_to_provider` arguments to send_invoice (PR `#986`_)
+- Bot: Add shortcut methods reply_{markdown,html} (PR `#827`_)
+- Bot: Add shortcut method reply_media_group (PR `#994`_)
+- Added utils.helpers.effective_message_type (PR `#826`_)
+- Bot.get_file now allows passing a file in addition to file_id (PR `#963`_)
+- Add .get_file() to Audio, Document, PhotoSize, Sticker, Video, VideoNote and Voice (PR `#963`_)
+- Add .send_*() methods to User and Chat (PR `#963`_)
+- Get jobs by name (PR `#1011`_)
+- Add Message caption html/markdown methods (PR `#1013`_)
+- File.download_as_bytearray - new method to get a d/led file as bytearray (PR `#1019`_)
+- File.download(): Now returns a meaningful return value (PR `#1019`_)
+- Added conversation timeout in ConversationHandler (PR `#895`_)
+
+Changes
+
+- Store bot in PreCheckoutQuery (PR `#953`_)
+- Updater: Issue INFO log upon received signal (PR `#951`_)
+- JobQueue: Thread safety fixes (PR `#977`_)
+- WebhookHandler: Fix exception thrown during error handling (PR `#985`_)
+- Explicitly check update.effective_chat in ConversationHandler.check_update (PR `#959`_)
+- Updater: Better handling of timeouts during get_updates (PR `#1007`_)
+- Remove unnecessary to_dict() (PR `#834`_)
+- CommandHandler - ignore strings in entities and "/" followed by whitespace (PR `#1020`_)
+- Documentation & style fixes (PR `#942`_, PR `#956`_, PR `#962`_, PR `#980`_, PR `#983`_)
+
+.. _`#826`: https://github.com/python-telegram-bot/python-telegram-bot/pull/826
+.. _`#827`: https://github.com/python-telegram-bot/python-telegram-bot/pull/827
+.. _`#834`: https://github.com/python-telegram-bot/python-telegram-bot/pull/834
+.. _`#895`: https://github.com/python-telegram-bot/python-telegram-bot/pull/895
+.. _`#942`: https://github.com/python-telegram-bot/python-telegram-bot/pull/942
+.. _`#949`: https://github.com/python-telegram-bot/python-telegram-bot/pull/949
+.. _`#951`: https://github.com/python-telegram-bot/python-telegram-bot/pull/951
+.. _`#956`: https://github.com/python-telegram-bot/python-telegram-bot/pull/956
+.. _`#953`: https://github.com/python-telegram-bot/python-telegram-bot/pull/953
+.. _`#962`: https://github.com/python-telegram-bot/python-telegram-bot/pull/962
+.. _`#959`: https://github.com/python-telegram-bot/python-telegram-bot/pull/959
+.. _`#963`: https://github.com/python-telegram-bot/python-telegram-bot/pull/963
+.. _`#977`: https://github.com/python-telegram-bot/python-telegram-bot/pull/977
+.. _`#980`: https://github.com/python-telegram-bot/python-telegram-bot/pull/980
+.. _`#983`: https://github.com/python-telegram-bot/python-telegram-bot/pull/983
+.. _`#985`: https://github.com/python-telegram-bot/python-telegram-bot/pull/985
+.. _`#986`: https://github.com/python-telegram-bot/python-telegram-bot/pull/986
+.. _`#994`: https://github.com/python-telegram-bot/python-telegram-bot/pull/994
+.. _`#1006`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1006
+.. _`#1007`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1007
+.. _`#1011`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1011
+.. _`#1012`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1012
+.. _`#1013`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1013
+.. _`#1018`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1018
+.. _`#1019`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1019
+.. _`#1020`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1020
+
+**2017-12-08**
+*Released 9.0.0*
+
+Breaking changes (possibly)
+
+- Drop support for python 3.3 (PR `#930`_)
+
+
+New Features
+
+- Support Bot API 3.5 (PR `#920`_)
+
+
+Changes
+
+- Fix race condition in dispatcher start/stop (`#887`_)
+- Log error trace if there is no error handler registered (`#694`_)
+- Update examples with consistent string formatting (`#870`_)
+- Various changes and improvements to the docs.
+
+.. _`#920`: https://github.com/python-telegram-bot/python-telegram-bot/pull/920
+.. _`#930`: https://github.com/python-telegram-bot/python-telegram-bot/pull/930
+.. _`#887`: https://github.com/python-telegram-bot/python-telegram-bot/pull/887
+.. _`#694`: https://github.com/python-telegram-bot/python-telegram-bot/pull/694
+.. _`#870`: https://github.com/python-telegram-bot/python-telegram-bot/pull/870
+
 **2017-10-15**
 *Released 8.1.1*
 

CODE_OF_CONDUCT.md

@@ -0,0 +1,47 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Publication of any content supporting, justifying or otherwise affiliating with terror and/or hate towards others
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at devs@python-telegram-bot.org. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

README.rst

@@ -8,12 +8,12 @@ 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>`_.
 
 .. image:: https://img.shields.io/pypi/v/python-telegram-bot.svg
-   :target: https://pypi.python.org/pypi/python-telegram-bot
+   :target: https://pypi.org/project/python-telegram-bot/
    :alt: PyPi Package Version
 
 .. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot.svg
-   :target: https://pypi.python.org/pypi/python-telegram-bot
-   :alt: Supported python versions
+   :target: https://pypi.org/project/python-telegram-bot/
+   :alt: Supported Python versions
 
 .. image:: https://www.cpu.re/static/python-telegram-bot/downloads.svg
    :target: https://www.cpu.re/static/python-telegram-bot/downloads-by-python-version.txt
@@ -35,9 +35,6 @@ We have made you a wrapper you can't refuse
    :target: https://ci.appveyor.com/project/Eldinnie/python-telegram-bot
    :alt: AppVeyor CI Status
 
-.. image:: https://codeclimate.com/github/python-telegram-bot/python-telegram-bot/badges/gpa.svg
-   :target: https://codeclimate.com/github/python-telegram-bot/python-telegram-bot
-   :alt: Code Climate
 
 .. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot
@@ -96,7 +93,7 @@ make the development of bots easy and straightforward. These classes are contain
 Telegram API support
 ====================
 
-All types and methods of the Telegram Bot API 3.4 are supported.
+All types and methods of the Telegram Bot API 3.6 are supported.
 
 ==========
 Installing

appveyor.yml

@@ -7,7 +7,6 @@ environment:
     # isn't covered by this document) at the time of writing.
 
     - PYTHON: "C:\\Python27"
-    - PYTHON: "C:\\Python33"
     - PYTHON: "C:\\Python34"
     - PYTHON: "C:\\Python35"
     - PYTHON: "C:\\Python36"

codecov.yml

@@ -0,0 +1 @@
+comment: false

docs/source/conf.py

@@ -50,7 +50,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Python Telegram Bot'
-copyright = u'2015-2017, Leandro Toledo'
+copyright = u'2015-2018, Leandro Toledo'
 author = u'Leandro Toledo'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -58,9 +58,9 @@ author = u'Leandro Toledo'
 # built documents.
 #
 # The short X.Y version.
-version = '8.1'  # telegram.__version__[:3]
+version = '10.0'  # telegram.__version__[:3]
 # The full version, including alpha/beta/rc tags.
-release = '8.1.1'  # telegram.__version__
+release = '10.0.2'  # telegram.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/index.rst

@@ -12,6 +12,10 @@ objects in the package reflect the types as defined by the `telegram bot api <ht
 .. toctree::
    telegram
 
+Changelog
+---------
+
+.. include:: ../../CHANGES.rst
 
 Indices and tables
 ==================

docs/source/telegram.inputmedia.rst

@@ -0,0 +1,6 @@
+telegram.InputMedia
+===================
+
+.. autoclass:: telegram.InputMedia
+    :members:
+    :show-inheritance:

docs/source/telegram.inputmediaphoto.rst

@@ -0,0 +1,6 @@
+telegram.InputMediaPhoto
+========================
+
+.. autoclass:: telegram.InputMediaPhoto
+    :members:
+    :show-inheritance:

docs/source/telegram.inputmediavideo.rst

@@ -0,0 +1,6 @@
+telegram.InputMediaVideo
+========================
+
+.. autoclass:: telegram.InputMediaVideo
+    :members:
+    :show-inheritance:

docs/source/telegram.rst

@@ -3,8 +3,8 @@ telegram package
 
 .. toctree::
 
-   telegram.utils.helpers
    telegram.ext
+   telegram.utils
    telegram.audio
    telegram.bot
    telegram.callbackquery
@@ -21,6 +21,9 @@ telegram package
    telegram.inlinekeyboardbutton
    telegram.inlinekeyboardmarkup
    telegram.inputfile
+   telegram.inputmedia
+   telegram.inputmediaphoto
+   telegram.inputmediavideo
    telegram.keyboardbutton
    telegram.location
    telegram.message

docs/source/telegram.utils.promise.rst

@@ -0,0 +1,6 @@
+telegram.utils.promise.Promise
+==============================
+
+.. autoclass:: telegram.utils.promise.Promise
+    :members:
+    :show-inheritance:

docs/source/telegram.utils.request.rst

@@ -0,0 +1,6 @@
+telegram.utils.request.Request
+==============================
+
+.. autoclass:: telegram.utils.request.Request
+    :members:
+    :show-inheritance:

docs/source/telegram.utils.rst

@@ -0,0 +1,8 @@
+telegram.utils package
+======================
+
+.. toctree::
+
+    telegram.utils.helpers
+    telegram.utils.promise
+    telegram.utils.request

examples/README.md

@@ -1,6 +1,6 @@
 # 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.
+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`](#pure-api) example, they all use the high-level framework this library provides with the [`telegram.ext`](https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.html) 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.
 
@@ -22,5 +22,8 @@ This example sheds some light on inline keyboards, callback queries and message
 ### [`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).
 
+### [`paymentbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/paymentbot.py)
+A basic example of a bot that can accept payments. Don't forget to enable and configure payments 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

@@ -46,7 +46,7 @@ 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))
+    logger.info("Gender of %s: %s", user.first_name, update.message.text)
     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())
@@ -58,7 +58,7 @@ def photo(bot, update):
     user = update.message.from_user
     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'))
+    logger.info("Photo of %s: %s", user.first_name, 'user_photo.jpg')
     update.message.reply_text('Gorgeous! Now, send me your location please, '
                               'or send /skip if you don\'t want to.')
 
@@ -67,7 +67,7 @@ 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)
+    logger.info("User %s did not send a photo.", user.first_name)
     update.message.reply_text('I bet you look great! Now, send me your location please, '
                               'or send /skip.')
 
@@ -77,8 +77,8 @@ def skip_photo(bot, update):
 def location(bot, update):
     user = update.message.from_user
     user_location = update.message.location
-    logger.info("Location of %s: %f / %f"
-                % (user.first_name, user_location.latitude, user_location.longitude))
+    logger.info("Location of %s: %f / %f", user.first_name, user_location.latitude,
+                user_location.longitude)
     update.message.reply_text('Maybe I can visit you sometime! '
                               'At last, tell me something about yourself.')
 
@@ -87,7 +87,7 @@ 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)
+    logger.info("User %s did not send a location.", user.first_name)
     update.message.reply_text('You seem a bit paranoid! '
                               'At last, tell me something about yourself.')
 
@@ -96,7 +96,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))
+    logger.info("Bio of %s: %s", user.first_name, update.message.text)
     update.message.reply_text('Thank you! I hope we can talk again some day.')
 
     return ConversationHandler.END
@@ -104,7 +104,7 @@ def bio(bot, update):
 
 def cancel(bot, update):
     user = update.message.from_user
-    logger.info("User %s canceled the conversation." % user.first_name)
+    logger.info("User %s canceled the conversation.", user.first_name)
     update.message.reply_text('Bye! I hope we can talk again some day.',
                               reply_markup=ReplyKeyboardRemove())
 
@@ -112,7 +112,8 @@ def cancel(bot, update):
 
 
 def error(bot, update, error):
-    logger.warn('Update "%s" caused error "%s"' % (update, error))
+    """Log Errors caused by Updates."""
+    logger.warning('Update "%s" caused error "%s"', update, error)
 
 
 def main():

examples/conversationbot2.py

@@ -41,7 +41,7 @@ def facts_to_str(user_data):
     facts = list()
 
     for key, value in user_data.items():
-        facts.append('%s - %s' % (key, value))
+        facts.append('{} - {}'.format(key, value))
 
     return "\n".join(facts).join(['\n', '\n'])
 
@@ -58,7 +58,8 @@ def start(bot, update):
 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())
+    update.message.reply_text(
+        'Your {}? Yes, I would love to hear about that!'.format(text.lower()))
 
     return TYPING_REPLY
 
@@ -77,10 +78,9 @@ def received_information(bot, update, user_data):
     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)
+                              "{}"
+                              "You can tell me more, or change your opinion on something.".format(
+                                  facts_to_str(user_data)), reply_markup=markup)
 
     return CHOOSING
 
@@ -90,15 +90,16 @@ def done(bot, update, 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))
+                              "{}"
+                              "Until next time!".format(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))
+    """Log Errors caused by Updates."""
+    logger.warning('Update "%s" caused error "%s"', update, error)
 
 
 def main():

examples/echobot.py

@@ -1,9 +1,11 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-#
-# Simple Bot to reply to Telegram messages. This is built on the API wrapper, see
-# echobot2.py to see the same example built on the telegram.ext bot framework.
-# This program is dedicated to the public domain under the CC0 license.
+"""Simple Bot to reply to Telegram messages.
+
+This is built on the API wrapper, see echobot2.py to see the same example built
+on the telegram.ext bot framework.
+This program is dedicated to the public domain under the CC0 license.
+"""
 import logging
 import telegram
 from telegram.error import NetworkError, Unauthorized
@@ -12,7 +14,9 @@ from time import sleep
 
 update_id = None
 
+
 def main():
+    """Run the bot."""
     global update_id
     # Telegram Bot Authorization Token
     bot = telegram.Bot('TOKEN')
@@ -37,6 +41,7 @@ def main():
 
 
 def echo(bot):
+    """Echo the message the user sent."""
     global update_id
     # Request updates after the last update_id
     for update in bot.get_updates(offset=update_id, timeout=10):

examples/echobot2.py

@@ -1,9 +1,10 @@
 #!/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.
-"""
+
+"""Simple Bot to reply to Telegram messages.
+
+This program is dedicated to the public domain under the CC0 license.
+
 This Bot uses the Updater class to handle the bot.
 
 First, a few handler functions are defined. Then, those functions are passed to
@@ -29,22 +30,27 @@ 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):
+    """Send a message when the command /start is issued."""
     update.message.reply_text('Hi!')
 
 
 def help(bot, update):
+    """Send a message when the command /help is issued."""
     update.message.reply_text('Help!')
 
 
 def echo(bot, update):
+    """Echo the user message."""
     update.message.reply_text(update.message.text)
 
 
 def error(bot, update, error):
-    logger.warn('Update "%s" caused error "%s"' % (update, error))
+    """Log Errors caused by Updates."""
+    logger.warning('Update "%s" caused error "%s"', update, error)
 
 
 def main():
+    """Start the bot."""
     # Create the EventHandler and pass it your bot's token.
     updater = Updater("TOKEN")
 

examples/inlinebot.py

@@ -1,9 +1,10 @@
 #!/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.
-"""
+
+"""Simple Bot to reply to Telegram messages.
+
+This program is dedicated to the public domain under the CC0 license.
+
 This Bot uses the Updater class to handle the bot.
 
 First, a few handler functions are defined. Then, those functions are passed to
@@ -17,7 +18,7 @@ bot.
 """
 from uuid import uuid4
 
-import re
+from telegram.utils.helpers import escape_markdown
 
 from telegram import InlineQueryResultArticle, ParseMode, \
     InputTextMessageContent
@@ -34,45 +35,43 @@ 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):
+    """Send a message when the command /start is issued."""
     update.message.reply_text('Hi!')
 
 
 def help(bot, update):
+    """Send a message when the command /help is issued."""
     update.message.reply_text('Help!')
 
 
-def escape_markdown(text):
-    """Helper function to escape telegram markup symbols"""
-    escape_chars = '\*_`\['
-    return re.sub(r'([%s])' % escape_chars, r'\\\1', text)
-
-
 def inlinequery(bot, update):
+    """Handle the inline query."""
     query = update.inline_query.query
-    results = list()
-
-    results.append(InlineQueryResultArticle(id=uuid4(),
-                                            title="Caps",
-                                            input_message_content=InputTextMessageContent(
-                                                query.upper())))
-
-    results.append(InlineQueryResultArticle(id=uuid4(),
-                                            title="Bold",
-                                            input_message_content=InputTextMessageContent(
-                                                "*%s*" % escape_markdown(query),
-                                                parse_mode=ParseMode.MARKDOWN)))
-
-    results.append(InlineQueryResultArticle(id=uuid4(),
-                                            title="Italic",
-                                            input_message_content=InputTextMessageContent(
-                                                "_%s_" % escape_markdown(query),
-                                                parse_mode=ParseMode.MARKDOWN)))
+    results = [
+        InlineQueryResultArticle(
+            id=uuid4(),
+            title="Caps",
+            input_message_content=InputTextMessageContent(
+                query.upper())),
+        InlineQueryResultArticle(
+            id=uuid4(),
+            title="Bold",
+            input_message_content=InputTextMessageContent(
+                "*{}*".format(escape_markdown(query)),
+                parse_mode=ParseMode.MARKDOWN)),
+        InlineQueryResultArticle(
+            id=uuid4(),
+            title="Italic",
+            input_message_content=InputTextMessageContent(
+                "_{}_".format(escape_markdown(query)),
+                parse_mode=ParseMode.MARKDOWN))]
 
     update.inline_query.answer(results)
 
 
 def error(bot, update, error):
-    logger.warning('Update "%s" caused error "%s"' % (update, error))
+    """Log Errors caused by Updates."""
+    logger.warning('Update "%s" caused error "%s"', update, error)
 
 
 def main():

examples/inlinekeyboard.py

@@ -1,15 +1,16 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-#
-# Basic example for a bot that uses inline keyboards.
-# This program is dedicated to the public domain under the CC0 license.
+"""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 InlineKeyboardButton, InlineKeyboardMarkup
 from telegram.ext import Updater, CommandHandler, CallbackQueryHandler
 
 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
                     level=logging.INFO)
+logger = logging.getLogger(__name__)
 
 
 def start(bot, update):
@@ -26,7 +27,7 @@ def start(bot, update):
 def button(bot, update):
     query = update.callback_query
 
-    bot.edit_message_text(text="Selected option: %s" % query.data,
+    bot.edit_message_text(text="Selected option: {}".format(query.data),
                           chat_id=query.message.chat_id,
                           message_id=query.message.message_id)
 
@@ -36,20 +37,26 @@ def help(bot, update):
 
 
 def error(bot, update, error):
-    logging.warning('Update "%s" caused error "%s"' % (update, error))
+    """Log Errors caused by Updates."""
+    logger.warning('Update "%s" caused error "%s"', update, error)
 
 
-# Create the Updater and pass it your bot's token.
-updater = Updater("TOKEN")
+def main():
+    # Create the Updater and pass it your bot's token.
+    updater = Updater("TOKEN")
 
-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)
+    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)
 
-# Start the Bot
-updater.start_polling()
+    # Start the Bot
+    updater.start_polling()
 
-# Run the bot until the user presses Ctrl-C or the process receives SIGINT,
-# SIGTERM or SIGABRT
-updater.idle()
+    # Run the bot until the user presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()

examples/paymentbot.py

@@ -1,8 +1,10 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-# Basic example for a bot that can receive payment from user.
-# This program is dedicated to the public domain under the CC0 license.
+"""Basic example for a bot that can receive payment from user.
+
+This program is dedicated to the public domain under the CC0 license.
+"""
 
 from telegram import (LabeledPrice, ShippingOption)
 from telegram.ext import (Updater, CommandHandler, MessageHandler,
@@ -10,13 +12,15 @@ from telegram.ext import (Updater, CommandHandler, MessageHandler,
 import logging
 
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO)
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.INFO)
 
 logger = logging.getLogger(__name__)
 
 
 def error(bot, update, error):
-    logger.warn('Update "%s" caused error "%s"' % (update, error))
+    """Log Errors caused by Updates."""
+    logger.warning('Update "%s" caused error "%s"', update, error)
 
 
 def start_callback(bot, update):
@@ -31,7 +35,7 @@ def start_with_shipping_callback(bot, update):
     description = "Payment Example using python-telegram-bot"
     # select a payload just for you to recognize its the donation from your bot
     payload = "Custom-Payload"
-    # get your provider_token at @botfather, see https://core.telegram.org/bots/payments#getting-a-token
+    # In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
     provider_token = "PROVIDER_TOKEN"
     start_parameter = "test-payment"
     currency = "USD"
@@ -55,7 +59,7 @@ def start_without_shipping_callback(bot, update):
     description = "Payment Example using python-telegram-bot"
     # select a payload just for you to recognize its the donation from your bot
     payload = "Custom-Payload"
-    # get your provider_token at @botfather, see https://core.telegram.org/bots/payments#getting-a-token
+    # In order to get a provider_token see https://core.telegram.org/bots/payments#getting-a-token
     provider_token = "PROVIDER_TOKEN"
     start_parameter = "test-payment"
     currency = "USD"

examples/timerbot.py

@@ -1,9 +1,11 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-#
-# Simple Bot to send timed Telegram messages
+
+
+"""Simple Bot to send timed Telegram messages.
+
 # This program is dedicated to the public domain under the CC0 license.
-"""
+
 This Bot uses the Updater class to handle the bot and the JobQueue to send
 timed messages.
 
@@ -17,7 +19,7 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """
 
-from telegram.ext import Updater, CommandHandler, Job
+from telegram.ext import Updater, CommandHandler
 import logging
 
 # Enable logging
@@ -34,12 +36,12 @@ def start(bot, update):
 
 
 def alarm(bot, job):
-    """Function to send the alarm message"""
+    """Send the alarm message."""
     bot.send_message(job.context, text='Beep!')
 
 
-def set(bot, update, args, job_queue, chat_data):
-    """Adds a job to the queue"""
+def set_timer(bot, update, args, job_queue, chat_data):
+    """Add a job to the queue."""
     chat_id = update.message.chat_id
     try:
         # args[0] should contain the time for the timer in seconds
@@ -59,8 +61,7 @@ def set(bot, update, args, job_queue, chat_data):
 
 
 def unset(bot, update, chat_data):
-    """Removes the job if the user changed their mind"""
-
+    """Remove the job if the user changed their mind."""
     if 'job' not in chat_data:
         update.message.reply_text('You have no active timer')
         return
@@ -73,10 +74,12 @@ def unset(bot, update, chat_data):
 
 
 def error(bot, update, error):
-    logger.warning('Update "%s" caused error "%s"' % (update, error))
+    """Log Errors caused by Updates."""
+    logger.warning('Update "%s" caused error "%s"', update, error)
 
 
 def main():
+    """Run bot."""
     updater = Updater("TOKEN")
 
     # Get the dispatcher to register handlers
@@ -85,7 +88,7 @@ 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,
+    dp.add_handler(CommandHandler("set", set_timer,
                                   pass_args=True,
                                   pass_job_queue=True,
                                   pass_chat_data=True))

requirements-dev.txt

@@ -6,4 +6,5 @@ yapf
 pre-commit
 beautifulsoup4
 pytest
+pytest-catchlog
 pytest-timeout

setup.py

@@ -53,7 +53,6 @@ with codecs.open('README.rst', 'r', 'utf-8') as fd:
               'Programming Language :: Python :: 2',
               '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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -96,6 +96,9 @@ from .constants import (MAX_MESSAGE_LENGTH, MAX_CAPTION_LENGTH, SUPPORTED_WEBHOO
                         MAX_FILESIZE_DOWNLOAD, MAX_FILESIZE_UPLOAD,
                         MAX_MESSAGES_PER_SECOND_PER_CHAT, MAX_MESSAGES_PER_SECOND,
                         MAX_MESSAGES_PER_MINUTE_PER_GROUP)
+from .files.inputmedia import InputMedia
+from .files.inputmediavideo import InputMediaVideo
+from .files.inputmediaphoto import InputMediaPhoto
 from .version import __version__  # flake8: noqa
 
 __author__ = 'devs@python-telegram-bot.org'
@@ -121,5 +124,6 @@ __all__ = [
     'MAX_MESSAGES_PER_SECOND', 'MAX_MESSAGES_PER_MINUTE_PER_GROUP', 'WebhookInfo', 'Animation',
     'Game', 'GameHighScore', 'VideoNote', 'LabeledPrice', 'SuccessfulPayment', 'ShippingOption',
     'ShippingAddress', 'PreCheckoutQuery', 'OrderInfo', 'Invoice', 'ShippingQuery', 'ChatPhoto',
-    'StickerSet', 'MaskPosition', 'CallbackGame'
+    'StickerSet', 'MaskPosition', 'CallbackGame', 'InputMedia', 'InputMediaPhoto',
+    'InputMediaVideo'
 ]

telegram/__main__.py

@@ -1,3 +1,21 @@
+# !/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2018
+# 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/].
 import sys
 
 import certifi

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -70,6 +70,8 @@ class TelegramObject(object):
                 else:
                     data[key] = value
 
+        if data.get('from_user'):
+            data['from'] = data.pop('from_user', None)
         return data
 
     def __eq__(self, other):

telegram/bot.py

@@ -3,7 +3,7 @@
 # pylint: disable=E0611,E0213,E1102,C0103,E1101,W0613,R0913,R0904
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -21,10 +21,13 @@
 """This module contains an object that represents a Telegram Bot."""
 
 import functools
+import json
 import logging
 import warnings
 from datetime import datetime
 
+from future.utils import string_types
+
 from telegram import (User, Message, Update, Chat, ChatMember, UserProfilePhotos, File,
                       ReplyMarkup, TelegramObject, WebhookInfo, GameHighScore, StickerSet,
                       PhotoSize, Audio, Document, Sticker, Video, Voice, VideoNote, Location,
@@ -335,12 +338,13 @@ class Bot(TelegramObject):
                    disable_notification=False,
                    reply_to_message_id=None,
                    reply_markup=None,
-                   timeout=20.,
+                   timeout=20,
+                   parse_mode=None,
                    **kwargs):
         """Use this method to send photos.
 
         Note:
-            The video argument can be either a file_id, an URL or a file from disk
+            The photo argument can be either a file_id, an URL or a file from disk
             ``open(filename, 'rb')``
 
         Args:
@@ -353,6 +357,9 @@ class Bot(TelegramObject):
                 an existing :class:`telegram.PhotoSize` object to send.
             caption (:obj:`str`, optional): Photo caption (may also be used when resending photos
                 by file_id), 0-200 characters.
+            parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
+                show bold, italic, fixed-width text or inline URLs in the media caption. See the
+                constants in :class:`telegram.ParseMode` for the available modes.
             disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
                 receive a notification with no sound.
             reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
@@ -379,6 +386,8 @@ class Bot(TelegramObject):
 
         if caption:
             data['caption'] = caption
+        if parse_mode:
+            data['parse_mode'] = parse_mode
 
         return url, data
 
@@ -394,7 +403,8 @@ class Bot(TelegramObject):
                    disable_notification=False,
                    reply_to_message_id=None,
                    reply_markup=None,
-                   timeout=20.,
+                   timeout=20,
+                   parse_mode=None,
                    **kwargs):
         """
         Use this method to send audio files, if you want Telegram clients to display them in the
@@ -417,6 +427,9 @@ class Bot(TelegramObject):
                 the Internet, or upload a new one using multipart/form-data. Lastly you can pass
                 an existing :class:`telegram.Audio` object to send.
             caption (:obj:`str`, optional): Audio caption, 0-200 characters.
+            parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
+                show bold, italic, fixed-width text or inline URLs in the media caption. See the
+                constants in :class:`telegram.ParseMode` for the available modes.
             duration (:obj:`int`, optional): Duration of sent audio in seconds.
             performer (:obj:`str`, optional): Performer.
             title (:obj:`str`, optional): Track name.
@@ -452,6 +465,8 @@ class Bot(TelegramObject):
             data['title'] = title
         if caption:
             data['caption'] = caption
+        if parse_mode:
+            data['parse_mode'] = parse_mode
 
         return url, data
 
@@ -465,7 +480,8 @@ class Bot(TelegramObject):
                       disable_notification=False,
                       reply_to_message_id=None,
                       reply_markup=None,
-                      timeout=20.,
+                      timeout=20,
+                      parse_mode=None,
                       **kwargs):
         """Use this method to send general files.
 
@@ -485,6 +501,9 @@ class Bot(TelegramObject):
                 when you send file generated by temp module, for example). Undocumented.
             caption (:obj:`str`, optional): Document caption (may also be used when resending
                 documents by file_id), 0-200 characters.
+            parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
+                show bold, italic, fixed-width text or inline URLs in the media caption. See the
+                constants in :class:`telegram.ParseMode` for the available modes.
             disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
                 receive a notification with no sound.
             reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
@@ -513,6 +532,8 @@ class Bot(TelegramObject):
             data['filename'] = filename
         if caption:
             data['caption'] = caption
+        if parse_mode:
+            data['parse_mode'] = parse_mode
 
         return url, data
 
@@ -576,9 +597,11 @@ class Bot(TelegramObject):
                    disable_notification=False,
                    reply_to_message_id=None,
                    reply_markup=None,
-                   timeout=20.,
+                   timeout=20,
                    width=None,
                    height=None,
+                   parse_mode=None,
+                   supports_streaming=None,
                    **kwargs):
         """
         Use this method to send video files, Telegram clients support mp4 videos
@@ -601,6 +624,11 @@ class Bot(TelegramObject):
             height (:obj:`int`, optional): Video height.
             caption (:obj:`str`, optional): Video caption (may also be used when resending videos
                 by file_id), 0-200 characters.
+            parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
+                show bold, italic, fixed-width text or inline URLs in the media caption. See the
+                constants in :class:`telegram.ParseMode` for the available modes.
+            supports_streaming (:obj:`bool`, optional): Pass True, if the uploaded video is
+                suitable for streaming.
             disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
                 receive a notification with no sound.
             reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
@@ -629,6 +657,10 @@ class Bot(TelegramObject):
             data['duration'] = duration
         if caption:
             data['caption'] = caption
+        if parse_mode:
+            data['parse_mode'] = parse_mode
+        if supports_streaming:
+            data['supports_streaming'] = supports_streaming
         if width:
             data['width'] = width
         if height:
@@ -646,7 +678,8 @@ class Bot(TelegramObject):
                    disable_notification=False,
                    reply_to_message_id=None,
                    reply_markup=None,
-                   timeout=20.,
+                   timeout=20,
+                   parse_mode=None,
                    **kwargs):
         """
         Use this method to send audio files, if you want Telegram clients to display the file
@@ -666,6 +699,9 @@ class Bot(TelegramObject):
                 the Internet, or upload a new one using multipart/form-data. Lastly you can pass
                 an existing :class:`telegram.Voice` object to send.
             caption (:obj:`str`, optional): Voice message caption, 0-200 characters.
+            parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
+                show bold, italic, fixed-width text or inline URLs in the media caption. See the
+                constants in :class:`telegram.ParseMode` for the available modes.
             duration (:obj:`int`, optional): Duration of the voice message in seconds.
             disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
                 receive a notification with no sound.
@@ -695,6 +731,8 @@ class Bot(TelegramObject):
             data['duration'] = duration
         if caption:
             data['caption'] = caption
+        if parse_mode:
+            data['parse_mode'] = parse_mode
 
         return url, data
 
@@ -708,7 +746,7 @@ class Bot(TelegramObject):
                         disable_notification=False,
                         reply_to_message_id=None,
                         reply_markup=None,
-                        timeout=20.,
+                        timeout=20,
                         **kwargs):
         """Use this method to send video messages.
 
@@ -757,6 +795,51 @@ class Bot(TelegramObject):
 
         return url, data
 
+    @log
+    def send_media_group(self,
+                         chat_id,
+                         media,
+                         disable_notification=None,
+                         reply_to_message_id=None,
+                         timeout=20,
+                         **kwargs):
+        """Use this method to send a group of photos or videos as an album.
+
+        Args:
+            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
+                of the target channel (in the format @channelusername).
+            media (List[:class:`telegram.InputMedia`]): An array describing photos and videos to be
+                sent, must include 2–10 items.
+            disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
+                receive a notification with no sound.
+            reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
+                original message.
+            timeout (:obj:`int` | :obj:`float`, optional): Send file timeout (default: 20 seconds).
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        Returns:
+            List[:class:`telegram.Message`]: An array of the sent Messages.
+
+        Raises:
+            :class:`telegram.TelegramError`
+        """
+        # TODO: Make InputMediaPhoto, InputMediaVideo and send_media_group work with new files
+
+        url = '{0}/sendMediaGroup'.format(self.base_url)
+
+        media = [med.to_dict() for med in media]
+
+        data = {'chat_id': chat_id, 'media': media}
+
+        if reply_to_message_id:
+            data['reply_to_message_id'] = reply_to_message_id
+        if disable_notification:
+            data['disable_notification'] = disable_notification
+
+        result = self._request.post(url, data, timeout=timeout)
+
+        return [Message.de_json(res, self) for res in result]
+
     @log
     @message
     def send_location(self,
@@ -1263,10 +1346,15 @@ class Bot(TelegramObject):
         moment, bots can download files of up to 20MB in size. The file can then be downloaded
         with :attr:`telegram.File.download`. It is guaranteed that the link will be
         valid for at least 1 hour. When the link expires, a new one can be requested by
-        calling getFile again.
+        calling get_file again.
 
         Args:
-            file_id (:obj:`str`): File identifier to get info about.
+            file_id (:obj:`str` | :class:`telegram.Audio` | :class:`telegram.Document` |          \
+                     :class:`telegram.PhotoSize` | :class:`telegram.Sticker` |                    \
+                     :class:`telegram.Video` | :class:`telegram.VideoNote` |                      \
+                     :class:`telegram.Voice`):
+                Either the file identifier or an object that has a file_id attribute
+                to get file information about.
             timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                 the read timeout from the server (instead of the one specified during creation of
                 the connection pool).
@@ -1281,6 +1369,11 @@ class Bot(TelegramObject):
         """
         url = '{0}/getFile'.format(self.base_url)
 
+        try:
+            file_id = file_id.file_id
+        except AttributeError:
+            pass
+
         data = {'file_id': file_id}
         data.update(kwargs)
 
@@ -1456,6 +1549,8 @@ class Bot(TelegramObject):
             parse_mode (:obj:`str`): Send Markdown or HTML, if you want Telegram apps to show bold,
                 italic, fixed-width text or inline URLs in your bot's message. See the constants in
                 :class:`telegram.ParseMode` for the available modes.
+            disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in
+                this message.
             reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A
                 JSON-serialized object for an inline keyboard, custom reply keyboard, instructions
                 to remove reply keyboard or to force a reply from the user.
@@ -1498,6 +1593,7 @@ class Bot(TelegramObject):
                              caption=None,
                              reply_markup=None,
                              timeout=None,
+                             parse_mode=None,
                              **kwargs):
         """
         Use this method to edit captions of messages sent by the bot or via the bot
@@ -1511,6 +1607,9 @@ class Bot(TelegramObject):
             inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
                 specified. Identifier of the inline message.
             caption (:obj:`str`, optional): New caption of the message.
+            parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to
+                show bold, italic, fixed-width text or inline URLs in the media caption. See the
+                constants in :class:`telegram.ParseMode` for the available modes.
             reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A
                 JSON-serialized object for an inline keyboard, custom reply keyboard, instructions
                 to remove reply keyboard or to force a reply from the user.
@@ -1538,6 +1637,8 @@ class Bot(TelegramObject):
 
         if caption:
             data['caption'] = caption
+        if parse_mode:
+            data['parse_mode'] = parse_mode
         if chat_id:
             data['chat_id'] = chat_id
         if message_id:
@@ -1606,7 +1707,6 @@ class Bot(TelegramObject):
                     offset=None,
                     limit=100,
                     timeout=0,
-                    network_delay=None,
                     read_latency=2.,
                     allowed_updates=None,
                     **kwargs):
@@ -1650,10 +1750,6 @@ class Bot(TelegramObject):
         """
         url = '{0}/getUpdates'.format(self.base_url)
 
-        if network_delay is not None:
-            warnings.warn('network_delay is deprecated, use read_latency instead')
-            read_latency = network_delay
-
         data = {'timeout': timeout}
 
         if offset:
@@ -2153,6 +2249,9 @@ class Bot(TelegramObject):
                      disable_notification=False,
                      reply_to_message_id=None,
                      reply_markup=None,
+                     provider_data=None,
+                     send_phone_number_to_provider=None,
+                     send_email_to_provider=None,
                      timeout=None,
                      **kwargs):
         """Use this method to send invoices.
@@ -2169,6 +2268,10 @@ class Bot(TelegramObject):
             currency (:obj:`str`): Three-letter ISO 4217 currency code.
             prices (List[:class:`telegram.LabeledPrice`)]: Price breakdown, a list of components
                 (e.g. product price, tax, discount, delivery cost, delivery tax, bonus, etc.).
+            provider_data (:obj:`str` | :obj:`object`, optional): JSON-encoded data about the
+                invoice, which will be shared with the payment provider. A detailed description of
+                required fields should be provided by the payment provider. When an object is
+                passed, it will be encoded as JSON.
             photo_url (:obj:`str`, optional): URL of the product photo for the invoice. Can be a
                 photo of the goods or a marketing image for a service. People like it better when
                 they see what they are paying for.
@@ -2183,6 +2286,10 @@ class Bot(TelegramObject):
                 complete the order.
             need_shipping_address (:obj:`bool`, optional): Pass True, if you require the user's
                 shipping address to complete the order.
+            send_phone_number_to_provider (:obj:`bool`, optional): Pass True, if user's phone
+                number should be sent to provider.
+            send_email_to_provider (:obj:`bool`, optional): Pass True, if user's email address
+                should be sent to provider.
             is_flexible (:obj:`bool`, optional): Pass True, if the final price depends on the
                 shipping method.
             disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
@@ -2216,7 +2323,11 @@ class Bot(TelegramObject):
             'currency': currency,
             'prices': [p.to_dict() for p in prices]
         }
-
+        if provider_data is not None:
+            if isinstance(provider_data, string_types):
+                data['provider_data'] = provider_data
+            else:
+                data['provider_data'] = json.dumps(provider_data)
         if photo_url is not None:
             data['photo_url'] = photo_url
         if photo_size is not None:
@@ -2235,6 +2346,10 @@ class Bot(TelegramObject):
             data['need_shipping_address'] = need_shipping_address
         if is_flexible is not None:
             data['is_flexible'] = is_flexible
+        if send_phone_number_to_provider is not None:
+            data['send_phone_number_to_provider'] = send_email_to_provider
+        if send_email_to_provider is not None:
+            data['send_email_to_provider'] = send_email_to_provider
 
         return url, data
 
@@ -2524,7 +2639,7 @@ class Bot(TelegramObject):
         Args:
             chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
                 of the target`channel (in the format @channelusername).
-            photo (`telegram.InputFile`): New chat photo.
+            photo (`filelike object`): New chat photo.
             timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                 the read timeout from the server (instead of the one specified during creation of
                 the connection pool).
@@ -2965,6 +3080,7 @@ class Bot(TelegramObject):
     sendVideo = send_video
     sendVoice = send_voice
     sendVideoNote = send_video_note
+    sendMediaGroup = send_media_group
     sendLocation = send_location
     editMessageLiveLocation = edit_message_live_location
     stopMessageLiveLocation = stop_message_live_location

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -105,13 +105,6 @@ class CallbackQuery(TelegramObject):
 
         return cls(bot=bot, **data)
 
-    def to_dict(self):
-        data = super(CallbackQuery, self).to_dict()
-
-        # Required
-        data['from'] = data.pop('from_user', None)
-        return data
-
     def answer(self, *args, **kwargs):
         """Shortcut for::
 

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -212,3 +212,107 @@ class Chat(TelegramObject):
 
         """
         return self.bot.unban_chat_member(self.id, *args, **kwargs)
+
+    def send_message(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_message(Chat.chat_id, *args, **kwargs)
+
+        Where Chat is the current instance.
+
+        Returns:
+            :class:`telegram.Message`: On success, instance representing the message posted.
+
+        """
+        return self.bot.send_message(self.id, *args, **kwargs)
+
+    def send_photo(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_photo(Chat.chat_id, *args, **kwargs)
+
+        Where Chat is the current instance.
+
+        Returns:
+            :class:`telegram.Message`: On success, instance representing the message posted.
+
+        """
+        return self.bot.send_photo(self.id, *args, **kwargs)
+
+    def send_audio(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_audio(Chat.chat_id, *args, **kwargs)
+
+        Where Chat is the current instance.
+
+        Returns:
+            :class:`telegram.Message`: On success, instance representing the message posted.
+
+        """
+        return self.bot.send_audio(self.id, *args, **kwargs)
+
+    def send_document(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_document(Chat.chat_id, *args, **kwargs)
+
+        Where Chat is the current instance.
+
+        Returns:
+            :class:`telegram.Message`: On success, instance representing the message posted.
+
+        """
+        return self.bot.send_document(self.id, *args, **kwargs)
+
+    def send_sticker(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_sticker(Chat.chat_id, *args, **kwargs)
+
+        Where Chat is the current instance.
+
+        Returns:
+            :class:`telegram.Message`: On success, instance representing the message posted.
+
+        """
+        return self.bot.send_sticker(self.id, *args, **kwargs)
+
+    def send_video(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_video(Chat.chat_id, *args, **kwargs)
+
+        Where Chat is the current instance.
+
+        Returns:
+            :class:`telegram.Message`: On success, instance representing the message posted.
+
+        """
+        return self.bot.send_video(self.id, *args, **kwargs)
+
+    def send_video_note(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_video_note(Chat.chat_id, *args, **kwargs)
+
+        Where Chat is the current instance.
+
+        Returns:
+            :class:`telegram.Message`: On success, instance representing the message posted.
+
+        """
+        return self.bot.send_video_note(self.id, *args, **kwargs)
+
+    def send_voice(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_voice(Chat.chat_id, *args, **kwargs)
+
+        Where Chat is the current instance.
+
+        Returns:
+            :class:`telegram.Message`: On success, instance representing the message posted.
+
+        """
+        return self.bot.send_voice(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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/choseninlineresult.py

@@ -2,7 +2,7 @@
 # pylint: disable=R0902,R0912,R0913
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -79,11 +79,3 @@ class ChosenInlineResult(TelegramObject):
         data['location'] = Location.de_json(data.get('location'), bot)
 
         return cls(**data)
-
-    def to_dict(self):
-        data = super(ChosenInlineResult, self).to_dict()
-
-        # Required
-        data['from'] = data.pop('from_user', None)
-
-        return data

telegram/constants.py

@@ -1,5 +1,5 @@
 # python-telegram-bot - a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # by the python-telegram-bot contributors <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -134,24 +134,26 @@ class CommandHandler(Handler):
             message = update.message or update.edited_message
 
             if message.text and message.text.startswith('/') and len(message.text) > 1:
-                command = message.text[1:].split(None, 1)[0].split('@')
-                command.append(
-                    message.bot.username)  # in case the command was send without a username
+                first_word = message.text_html.split(None, 1)[0]
+                if len(first_word) > 1 and first_word.startswith('/'):
+                    command = first_word[1:].split('@')
+                    command.append(
+                        message.bot.username)  # in case the command was sent 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)
+                    if not (command[0].lower() in self.command
+                            and command[1].lower() == message.bot.username.lower()):
+                        return False
 
-                return res and (command[0].lower() in self.command
-                                and command[1].lower() == message.bot.username.lower())
-            else:
-                return False
+                    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)
 
-        else:
-            return False
+                    return res
+
+        return False
 
     def handle_update(self, update, dispatcher):
         """Send the update to the :attr:`callback`.

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -55,7 +55,7 @@ class ConversationHandler(Handler):
     To change the state of conversation, the callback function of a handler must return the new
     state after responding to the user. If it does not return anything (returning ``None`` by
     default), the state will not change. To end the conversation, the callback function must
-    return :attr`END` or ``-1``.
+    return :attr:`END` or ``-1``.
 
     Attributes:
         entry_points (List[:class:`telegram.ext.Handler`]): A list of ``Handler`` objects that can
@@ -76,6 +76,9 @@ class ConversationHandler(Handler):
         per_user (:obj:`bool`): Optional. If the conversationkey should contain the User's ID.
         per_message (:obj:`bool`): Optional. If the conversationkey should contain the Message's
             ID.
+        conversation_timeout (:obj:`float`|:obj:`datetime.timedelta`): Optional. When this handler
+            is inactive more than this timeout (in seconds), it will be automatically ended. If
+            this value is 0 (default), there will be no timeout.
 
     Args:
         entry_points (List[:class:`telegram.ext.Handler`]): A list of ``Handler`` objects that can
@@ -107,6 +110,9 @@ class ConversationHandler(Handler):
             Default is ``True``.
         per_message (:obj:`bool`, optional): If the conversationkey should contain the Message's
             ID. Default is ``False``.
+        conversation_timeout (:obj:`float`|:obj:`datetime.timedelta`, optional): When this handler
+            is inactive more than this timeout (in seconds), it will be automatically ended. If
+            this value is 0 or None (default), there will be no timeout.
 
     Raises:
         ValueError
@@ -124,7 +130,8 @@ class ConversationHandler(Handler):
                  timed_out_behavior=None,
                  per_chat=True,
                  per_user=True,
-                 per_message=False):
+                 per_message=False,
+                 conversation_timeout=None):
 
         self.entry_points = entry_points
         self.states = states
@@ -136,7 +143,9 @@ class ConversationHandler(Handler):
         self.per_user = per_user
         self.per_chat = per_chat
         self.per_message = per_message
+        self.conversation_timeout = conversation_timeout
 
+        self.timeout_jobs = dict()
         self.conversations = dict()
         self.current_conversation = None
         self.current_handler = None
@@ -206,10 +215,11 @@ class ConversationHandler(Handler):
 
         """
         # 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):
+        if (not isinstance(update, Update) or
+                update.channel_post or
+                self.per_chat and not update.effective_chat 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
 
         key = self._get_key(update)
@@ -293,6 +303,15 @@ class ConversationHandler(Handler):
 
         """
         new_state = self.current_handler.handle_update(update, dispatcher)
+        timeout_job = self.timeout_jobs.pop(self.current_conversation, None)
+
+        if timeout_job is not None:
+            timeout_job.schedule_removal()
+        if self.conversation_timeout and new_state != self.END:
+            self.timeout_jobs[self.current_conversation] = dispatcher.job_queue.run_once(
+                self._trigger_timeout, self.conversation_timeout,
+                context=self.current_conversation
+            )
 
         self.update_state(new_state, self.current_conversation)
 
@@ -308,3 +327,7 @@ class ConversationHandler(Handler):
 
         elif new_state is not None:
             self.conversations[key] = new_state
+
+    def _trigger_timeout(self, bot, job):
+        del self.timeout_jobs[job.context]
+        self.update_state(self.END, job.context)

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -183,14 +183,20 @@ class Dispatcher(object):
         self.__async_queue.put(promise)
         return promise
 
-    def start(self):
+    def start(self, ready=None):
         """Thread target of thread 'dispatcher'.
 
         Runs in background and processes the update queue.
 
+        Args:
+            ready (:obj:`threading.Event`, optional): If specified, the event will be set once the
+                dispatcher is ready.
+
         """
         if self.running:
             self.logger.warning('already running')
+            if ready is not None:
+                ready.set()
             return
 
         if self.__exception_event.is_set():
@@ -202,6 +208,9 @@ class Dispatcher(object):
         self.running = True
         self.logger.debug('Dispatcher started')
 
+        if ready is not None:
+            ready.set()
+
         while 1:
             try:
                 # Pop update from update queue.
@@ -299,7 +308,7 @@ class Dispatcher(object):
         A handler must be an instance of a subclass of :class:`telegram.ext.Handler`. All handlers
         are organized in groups with a numeric value. The default group is 0. All groups will be
         evaluated for handling an update, but only 0 or 1 handler per group will be used. If
-        :class:`telegram.DispatcherHandlerStop` is raised from one of the handlers, no further
+        :class:`telegram.ext.DispatcherHandlerStop` is raised from one of the handlers, no further
         handlers (regardless of the group) will be called.
 
         The priority/order of handlers is determined as follows:
@@ -370,5 +379,10 @@ class Dispatcher(object):
             error (:class:`telegram.TelegramError`): The Telegram error that was raised.
 
         """
-        for callback in self.error_handlers:
-            callback(self.bot, update, error)
+        if self.error_handlers:
+            for callback in self.error_handlers:
+                callback(self.bot, update, error)
+
+        else:
+            self.logger.exception(
+                'No error handlers are registered, logging exception...', exc_info=error)

telegram/ext/filters.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,6 +17,8 @@
 # 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."""
+
+import re
 from telegram import Chat
 from future.utils import string_types
 
@@ -171,6 +173,33 @@ class Filters(object):
     command = _Command()
     """:obj:`Filter`: Messages starting with ``/``."""
 
+    class regex(BaseFilter):
+        """
+        Filters updates by searching for an occurence of ``pattern`` in the message text.
+        The ``re.search`` function is used to determine whether an update should be filtered.
+        Refer to the documentation of the ``re`` module for more information.
+
+        Note: Does not allow passing groups or a groupdict like the ``RegexHandler`` yet,
+        but this will probably be implemented in a future update, gradually phasing out the
+        RegexHandler (see https://github.com/python-telegram-bot/python-telegram-bot/issues/835).
+
+        Examples:
+            Example ``CommandHandler("start", deep_linked_callback, Filters.regex('parameter'))``
+
+        Args:
+            pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
+        """
+
+        def __init__(self, pattern):
+            self.pattern = re.compile(pattern)
+            self.name = 'Filters.regex({})'.format(self.pattern)
+
+        # TODO: Once the callback revamp (#1026) is done, the regex filter should be able to pass
+        # the matched groups and groupdict to the context object.
+
+        def filter(self, message):
+            return bool(self.pattern.search(message.text))
+
     class _Reply(BaseFilter):
         name = 'Filters.reply'
 
@@ -192,6 +221,79 @@ class Filters(object):
     class _Document(BaseFilter):
         name = 'Filters.document'
 
+        class category(BaseFilter):
+            """This Filter filters documents by their category in the mime-type attribute
+
+            Note:
+                This Filter only filters by the mime_type of the document,
+                    it doesn't check the validity of the document.
+                The user can manipulate the mime-type of a message and
+                    send media with wrong types that don't fit to this handler.
+
+            Examples:
+                Filters.documents.category('audio/') returnes `True` for all types
+                of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'
+            """
+
+            def __init__(self, category):
+                """Initialize the category you want to filter
+
+                Args:
+                    category (str, optional): category of the media you want to filter"""
+                self.category = category
+                self.name = "Filters.document.category('{}')".format(self.category)
+
+            def filter(self, message):
+                if message.document:
+                    return message.document.mime_type.startswith(self.category)
+
+        application = category('application/')
+        audio = category('audio/')
+        image = category('image/')
+        video = category('video/')
+        text = category('text/')
+
+        class mime_type(BaseFilter):
+            """This Filter filters documents by their mime-type attribute
+
+            Note:
+                This Filter only filters by the mime_type of the document,
+                    it doesn't check the validity of document.
+                The user can manipulate the mime-type of a message and
+                    send media with wrong types that don't fit to this handler.
+
+            Examples:
+                Filters.documents.mime_type('audio/mpeg') filters all audio in mp3 format.
+            """
+
+            def __init__(self, mimetype):
+                """Initialize the category you want to filter
+
+                Args:
+                    filetype (str, optional): mime_type of the media you want to filter"""
+                self.mimetype = mimetype
+                self.name = "Filters.document.mime_type('{}')".format(self.mimetype)
+
+            def filter(self, message):
+                if message.document:
+                    return message.document.mime_type == self.mimetype
+
+        apk = mime_type('application/vnd.android.package-archive')
+        doc = mime_type('application/msword')
+        docx = mime_type('application/vnd.openxmlformats-officedocument.wordprocessingml.document')
+        exe = mime_type('application/x-ms-dos-executable')
+        gif = mime_type('video/mp4')
+        jpg = mime_type('image/jpeg')
+        mp3 = mime_type('audio/mpeg')
+        pdf = mime_type('application/pdf')
+        py = mime_type('text/x-python')
+        svg = mime_type('image/svg+xml')
+        txt = mime_type('text/plain')
+        targz = mime_type('application/x-compressed-tar')
+        wav = mime_type('audio/x-wav')
+        xml = mime_type('application/xml')
+        zip = mime_type('application/zip')
+
         def filter(self, message):
             return bool(message.document)
 
@@ -234,6 +336,15 @@ class Filters(object):
     voice = _Voice()
     """:obj:`Filter`: Messages that contain :class:`telegram.Voice`."""
 
+    class _VideoNote(BaseFilter):
+        name = 'Filters.video_note'
+
+        def filter(self, message):
+            return bool(message.video_note)
+
+    video_note = _VideoNote()
+    """:obj:`Filter`: Messages that contain :class:`telegram.VideoNote`."""
+
     class _Contact(BaseFilter):
         name = 'Filters.contact'
 
@@ -265,7 +376,7 @@ class Filters(object):
         """Subset for messages containing a status update.
 
         Examples:
-            Use these filters like: ``Filters.status_update.new_chat_member`` etc. Or use just
+            Use these filters like: ``Filters.status_update.new_chat_members`` etc. Or use just
             ``Filters.status_update`` for all status update messages.
 
         """
@@ -277,7 +388,7 @@ class Filters(object):
                 return bool(message.new_chat_members)
 
         new_chat_members = _NewChatMembers()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.new_chat_member`."""
+        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.new_chat_members`."""
 
         class _LeftChatMember(BaseFilter):
             name = 'Filters.status_update.left_chat_member'
@@ -346,19 +457,29 @@ class Filters(object):
         pinned_message = _PinnedMessage()
         """:obj:`Filter`: Messages that contain :attr:`telegram.Message.pinned_message`."""
 
+        class _ConnectedWebsite(BaseFilter):
+            name = 'Filters.status_update.connected_website'
+
+            def filter(self, message):
+                return bool(message.connected_website)
+
+        connected_website = _ConnectedWebsite()
+        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.connected_website`."""
+
         name = 'Filters.status_update'
 
         def filter(self, message):
             return bool(self.new_chat_members(message) or self.left_chat_member(message) or
                         self.new_chat_title(message) or self.new_chat_photo(message) or
                         self.delete_chat_photo(message) or self.chat_created(message) or
-                        self.migrate(message) or self.pinned_message(message))
+                        self.migrate(message) or self.pinned_message(message) or
+                        self.connected_website(message))
 
     status_update = _StatusUpdate()
     """Subset for messages containing a status update.
 
     Examples:
-        Use these filters like: ``Filters.status_update.new_chat_member`` etc. Or use just
+        Use these filters like: ``Filters.status_update.new_chat_members`` etc. Or use just
         ``Filters.status_update`` for all status update messages.
 
     Attributes:
@@ -374,7 +495,7 @@ class Filters(object):
             :attr:`telegram.Message.migrate_from_chat_id` or
             :attr: `telegram.Message.migrate_from_chat_id`.
         new_chat_members (:obj:`Filter`): Messages that contain
-            :attr:`telegram.Message.new_chat_member`.
+            :attr:`telegram.Message.new_chat_members`.
         new_chat_photo (:obj:`Filter`): Messages that contain
             :attr:`telegram.Message.new_chat_photo`.
         new_chat_title (:obj:`Filter`): Messages that contain

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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/ext/inlinequeryhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/ext/jobqueue.py

@@ -1,8 +1,7 @@
 #!/usr/bin/env python
-# flake8: noqa E501
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -21,7 +20,6 @@
 
 import logging
 import time
-import warnings
 import datetime
 import weakref
 from numbers import Number
@@ -38,23 +36,16 @@ class JobQueue(object):
     """This class allows you to periodically perform tasks with the bot.
 
     Attributes:
-        queue (:obj:`PriorityQueue`): The queue that holds the Jobs.
+        _queue (:obj:`PriorityQueue`): The queue that holds the Jobs.
         bot (:class:`telegram.Bot`): Bot that's send to the handlers.
 
     Args:
         bot (:class:`telegram.Bot`): The bot instance that should be passed to the jobs.
 
-    Deprecated:
-        prevent_autostart (:obj:`bool`, optional): Thread does not start during initialisation.
-        Use `start` method instead.
-
     """
 
-    def __init__(self, bot, prevent_autostart=None):
-        if prevent_autostart is not None:
-            warnings.warn("prevent_autostart is being deprecated, use `start` method instead.")
-
-        self.queue = PriorityQueue()
+    def __init__(self, bot):
+        self._queue = PriorityQueue()
         self.bot = bot
         self.logger = logging.getLogger(self.__class__.__name__)
         self.__start_lock = Lock()
@@ -64,37 +55,6 @@ class JobQueue(object):
         self._next_peek = None
         self._running = False
 
-    def put(self, job, next_t=None):
-        """Queue a new job.
-
-        Note:
-            This method is deprecated. Please use: :attr:`run_once`, :attr:`run_daily`
-            or :attr:`run_repeating` instead.
-
-        Args:
-            job (:class:`telegram.ext.Job`): The ``Job`` instance representing the new job.
-            next_t (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` | :obj:`datetime.datetime` | :obj:`datetime.time`, optional):
-                Time in or at which the job should run for the first time. This parameter will
-                be interpreted depending on its type.
-
-                * :obj:`int` or :obj:`float` will be interpreted as "seconds from now" in which the
-                  job should run.
-                * :obj:`datetime.timedelta` will be interpreted as "time from now" in which the
-                  job should run.
-                * :obj:`datetime.datetime` will be interpreted as a specific date and time at
-                  which the job should run.
-                * :obj:`datetime.time` will be interpreted as a specific time at which the job
-                  should run. This could be either today or, if the time has already passed,
-                  tomorrow.
-
-        """
-
-        warnings.warn("'JobQueue.put' is being deprecated, use 'JobQueue.run_once', "
-                      "'JobQueue.run_daily' or 'JobQueue.run_repeating' instead")
-        if job.job_queue is None:
-            job.job_queue = self
-        self._put(job, next_t=next_t)
-
     def _put(self, job, next_t=None, last_t=None):
         if next_t is None:
             next_t = job.interval
@@ -119,7 +79,7 @@ class JobQueue(object):
 
         self.logger.debug('Putting job %s with t=%f', job.name, next_t)
 
-        self.queue.put((next_t, job))
+        self._queue.put((next_t, job))
 
         # Wake up the loop if this job should be executed next
         self._set_next_peek(next_t)
@@ -132,7 +92,8 @@ class JobQueue(object):
                 job. It should take ``bot, job`` as parameters, where ``job`` is the
                 :class:`telegram.ext.Job` instance. It can be used to access it's
                 ``job.context`` or change it to a repeating job.
-            when (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` | :obj:`datetime.datetime` | :obj:`datetime.time`):
+            when (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` |                         \
+                  :obj:`datetime.datetime` | :obj:`datetime.time`):
                 Time in or at which the job should run. This parameter will be interpreted
                 depending on its type.
 
@@ -171,7 +132,8 @@ class JobQueue(object):
             interval (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta`): The interval in which
                 the job will run. If it is an :obj:`int` or a :obj:`float`, it will be interpreted
                 as seconds.
-            first (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` | :obj:`datetime.datetime` | :obj:`datetime.time`, optional):
+            first (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` |                        \
+                   :obj:`datetime.datetime` | :obj:`datetime.time`, optional):
                 Time in or at which the job should run. This parameter will be interpreted
                 depending on its type.
 
@@ -196,7 +158,6 @@ class JobQueue(object):
             queue.
 
         """
-
         job = Job(callback,
                   interval=interval,
                   repeat=True,
@@ -227,7 +188,6 @@ class JobQueue(object):
             queue.
 
         """
-
         job = Job(callback,
                   interval=datetime.timedelta(days=1),
                   repeat=True,
@@ -250,14 +210,13 @@ class JobQueue(object):
 
     def tick(self):
         """Run all jobs that are due and re-enqueue them with their interval."""
-
         now = time.time()
 
         self.logger.debug('Ticking jobs with t=%f', now)
 
         while True:
             try:
-                t, job = self.queue.get(False)
+                t, job = self._queue.get(False)
             except Empty:
                 break
 
@@ -270,7 +229,7 @@ class JobQueue(object):
                 # 2. At the first iteration of the loop only if `self.put()` had triggered
                 #    `self.__tick` because `self._next_peek` wasn't set
                 self.logger.debug("Next task isn't due yet. Finished!")
-                self.queue.put((t, job))
+                self._queue.put((t, job))
                 self._set_next_peek(t)
                 break
 
@@ -285,7 +244,7 @@ class JobQueue(object):
                         self.logger.debug('Running job %s', job.name)
                         job.run(self.bot)
 
-                except:
+                except Exception:
                     self.logger.exception('An uncaught error was raised while executing job %s',
                                           job.name)
             else:
@@ -298,7 +257,6 @@ class JobQueue(object):
 
     def start(self):
         """Starts the job_queue thread."""
-
         self.__start_lock.acquire()
 
         if not self._running:
@@ -335,7 +293,6 @@ class JobQueue(object):
 
     def stop(self):
         """Stops the thread."""
-
         with self.__start_lock:
             self._running = False
 
@@ -345,8 +302,13 @@ class JobQueue(object):
 
     def jobs(self):
         """Returns a tuple of all jobs that are currently in the ``JobQueue``."""
+        with self._queue.mutex:
+            return tuple(job[1] for job in self._queue.queue if job)
 
-        return tuple(job[1] for job in self.queue.queue if job)
+    def get_jobs_by_name(self, name):
+        """Returns a tuple of jobs with the given name that are currently in the ``JobQueue``"""
+        with self._queue.mutex:
+            return tuple(job[1] for job in self._queue.queue if job and job[1].name == name)
 
 
 class Job(object):
@@ -407,7 +369,6 @@ class Job(object):
 
     def run(self, bot):
         """Executes the callback function."""
-
         self.callback(bot, self)
 
     def schedule_removal(self):
@@ -416,7 +377,6 @@ class Job(object):
         its callback function again.
 
         """
-
         self._remove.set()
 
     @property
@@ -459,10 +419,11 @@ class Job(object):
     @property
     def interval_seconds(self):
         """:obj:`int`: The interval for this job in seconds."""
-        if isinstance(self.interval, datetime.timedelta):
-            return self.interval.total_seconds()
+        interval = self.interval
+        if isinstance(interval, datetime.timedelta):
+            return interval.total_seconds()
         else:
-            return self.interval
+            return interval
 
     @property
     def repeat(self):
@@ -478,7 +439,6 @@ class Job(object):
     @property
     def days(self):
         """Tuple[:obj:`int`]: Optional. Defines on which days of the week the job should run."""
-
         return self._days
 
     @days.setter
@@ -498,7 +458,6 @@ class Job(object):
     @property
     def job_queue(self):
         """:class:`telegram.ext.JobQueue`: Optional. The ``JobQueue`` this job belongs to."""
-
         return self._job_queue
 
     @job_queue.setter

telegram/ext/messagehandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/ext/messagequeue.py

@@ -4,7 +4,7 @@
 # Tymofii A. Khodniev (thodnev) <thodnev@mail.ru>
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/ext/precheckoutqueryhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/ext/regexhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/ext/shippingqueryhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/ext/stringcommandhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/ext/stringregexhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/ext/typehandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/ext/updater.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -21,7 +21,6 @@
 import logging
 import os
 import ssl
-import warnings
 from threading import Thread, Lock, current_thread, Event
 from time import sleep
 import subprocess
@@ -30,7 +29,8 @@ from queue import Queue
 
 from telegram import Bot, TelegramError
 from telegram.ext import Dispatcher, JobQueue
-from telegram.error import Unauthorized, InvalidToken, RetryAfter
+from telegram.error import Unauthorized, InvalidToken, RetryAfter, TimedOut
+from telegram.utils.helpers import get_signal_name
 from telegram.utils.request import Request
 from telegram.utils.webhookhandler import (WebhookServer, WebhookHandler)
 
@@ -149,16 +149,15 @@ class Updater(object):
             target(*args, **kwargs)
         except Exception:
             self.__exception_event.set()
-            self.logger.exception('unhandled exception')
+            self.logger.exception('unhandled exception in %s', thr_name)
             raise
         self.logger.debug('{0} - ended'.format(thr_name))
 
     def start_polling(self,
                       poll_interval=0.0,
                       timeout=10,
-                      network_delay=None,
                       clean=False,
-                      bootstrap_retries=0,
+                      bootstrap_retries=-1,
                       read_latency=2.,
                       allowed_updates=None):
         """Starts polling updates from Telegram.
@@ -172,8 +171,8 @@ class Updater(object):
             bootstrap_retries (:obj:`int`, optional): Whether the bootstrapping phase of the
                 `Updater` will retry on failures on the Telegram server.
 
-                * < 0 - retry indefinitely
-                *   0 - no retries (default)
+                * < 0 - retry indefinitely (default)
+                *   0 - no retries
                 * > 0 - retry up to X times
 
             allowed_updates (List[:obj:`str`], optional): Passed to
@@ -181,28 +180,24 @@ class Updater(object):
             read_latency (:obj:`float` | :obj:`int`, optional): Grace time in seconds for receiving
                 the reply from server. Will be added to the `timeout` value and used as the read
                 timeout from server (Default: 2).
-            network_delay: Deprecated. Will be honoured as :attr:`read_latency` for a while but
-                will be removed in the future.
 
         Returns:
             :obj:`Queue`: The update queue that can be filled from the main thread.
 
         """
-
-        if network_delay is not None:
-            warnings.warn('network_delay is deprecated, use read_latency instead')
-            read_latency = network_delay
-
         with self.__lock:
             if not self.running:
                 self.running = True
 
                 # Create & start threads
                 self.job_queue.start()
-                self._init_thread(self.dispatcher.start, "dispatcher")
+                dispatcher_ready = Event()
+                self._init_thread(self.dispatcher.start, "dispatcher", ready=dispatcher_ready)
                 self._init_thread(self._start_polling, "updater", poll_interval, timeout,
                                   read_latency, bootstrap_retries, clean, allowed_updates)
 
+                dispatcher_ready.wait()
+
                 # Return the update queue so the main thread can insert updates
                 return self.update_queue
 
@@ -234,8 +229,8 @@ class Updater(object):
             bootstrap_retries (:obj:`int`, optional): Whether the bootstrapping phase of the
                 `Updater` will retry on failures on the Telegram server.
 
-                * < 0 - retry indefinitely
-                *   0 - no retries (default)
+                * < 0 - retry indefinitely (default)
+                *   0 - no retries
                 * > 0 - retry up to X times
 
             webhook_url (:obj:`str`, optional): Explicitly specify the webhook url. Useful behind
@@ -247,7 +242,6 @@ class Updater(object):
             :obj:`Queue`: The update queue that can be filled from the main thread.
 
         """
-
         with self.__lock:
             if not self.running:
                 self.running = True
@@ -263,50 +257,79 @@ class Updater(object):
 
     def _start_polling(self, poll_interval, timeout, read_latency, bootstrap_retries, clean,
                        allowed_updates):  # pragma: no cover
-        # """
         # Thread target of thread 'updater'. Runs in background, pulls
         # updates from Telegram and inserts them in the update queue of the
         # Dispatcher.
-        # """
 
-        cur_interval = poll_interval
-        self.logger.debug('Updater thread started')
+        self.logger.debug('Updater thread started (polling)')
 
         self._bootstrap(bootstrap_retries, clean=clean, webhook_url='', allowed_updates=None)
 
-        while self.running:
-            try:
-                updates = self.bot.get_updates(
-                    self.last_update_id,
-                    timeout=timeout,
-                    read_latency=read_latency,
-                    allowed_updates=allowed_updates)
-            except RetryAfter as e:
-                self.logger.info(str(e))
-                cur_interval = 0.5 + e.retry_after
-            except TelegramError as te:
-                self.logger.error("Error while getting Updates: {0}".format(te))
+        self.logger.debug('Bootstrap done')
 
-                # Put the error into the update queue and let the Dispatcher
-                # broadcast it
-                self.update_queue.put(te)
+        def polling_action_cb():
+            updates = self.bot.get_updates(
+                self.last_update_id, timeout=timeout, read_latency=read_latency,
+                allowed_updates=allowed_updates)
 
-                cur_interval = self._increase_poll_interval(cur_interval)
-            else:
+            if updates:
                 if not self.running:
-                    if len(updates) > 0:
-                        self.logger.debug('Updates ignored and will be pulled '
-                                          'again on restart.')
-                    break
-
-                if updates:
+                    self.logger.debug('Updates ignored and will be pulled again on restart')
+                else:
                     for update in updates:
                         self.update_queue.put(update)
                     self.last_update_id = updates[-1].update_id + 1
 
-                cur_interval = poll_interval
+            return True
 
-            sleep(cur_interval)
+        def polling_onerr_cb(exc):
+            # Put the error into the update queue and let the Dispatcher
+            # broadcast it
+            self.update_queue.put(exc)
+
+        self._network_loop_retry(polling_action_cb, polling_onerr_cb, 'getting Updates',
+                                 poll_interval)
+
+    def _network_loop_retry(self, action_cb, onerr_cb, description, interval):
+        """Perform a loop calling `action_cb`, retrying after network errors.
+
+        Stop condition for loop: `self.running` evaluates False or return value of `action_cb`
+        evaluates False.
+
+        Args:
+            action_cb (:obj:`callable`): Network oriented callback function to call.
+            onerr_cb (:obj:`callable`): Callback to call when TelegramError is caught. Receives the
+                exception object as a parameter.
+            description (:obj:`str`): Description text to use for logs and exception raised.
+            interval (:obj:`float` | :obj:`int`): Interval to sleep between each call to
+                `action_cb`.
+
+        """
+        self.logger.debug('Start network loop retry %s', description)
+        cur_interval = interval
+        while self.running:
+            try:
+                if not action_cb():
+                    break
+            except RetryAfter as e:
+                self.logger.info('%s', e)
+                cur_interval = 0.5 + e.retry_after
+            except TimedOut as toe:
+                self.logger.debug('Timed out %s: %s', description, toe)
+                # If failure is due to timeout, we should retry asap.
+                cur_interval = 0
+            except InvalidToken as pex:
+                self.logger.error('Invalid token; aborting')
+                raise pex
+            except TelegramError as te:
+                self.logger.error('Error while %s: %s', description, te)
+                onerr_cb(te)
+                cur_interval = self._increase_poll_interval(cur_interval)
+            else:
+                cur_interval = interval
+
+            if cur_interval:
+                sleep(cur_interval)
 
     @staticmethod
     def _increase_poll_interval(current_interval):
@@ -321,7 +344,7 @@ class Updater(object):
 
     def _start_webhook(self, listen, port, url_path, cert, key, bootstrap_retries, clean,
                        webhook_url, allowed_updates):
-        self.logger.debug('Updater thread started')
+        self.logger.debug('Updater thread started (webhook)')
         use_ssl = cert is not None and key is not None
         if not url_path.startswith('/'):
             url_path = '/{0}'.format(url_path)
@@ -372,39 +395,56 @@ class Updater(object):
     def _gen_webhook_url(listen, port, url_path):
         return 'https://{listen}:{port}{path}'.format(listen=listen, port=port, path=url_path)
 
-    def _bootstrap(self, max_retries, clean, webhook_url, allowed_updates, cert=None):
-        retries = 0
-        while 1:
+    def _bootstrap(self, max_retries, clean, webhook_url, allowed_updates, cert=None,
+                   bootstrap_interval=5):
+        retries = [0]
 
-            try:
-                if clean:
-                    # Disable webhook for cleaning
-                    self.bot.delete_webhook()
-                    self._clean_updates()
-                    sleep(1)
+        def bootstrap_del_webhook():
+            self.bot.delete_webhook()
+            return False
 
-                self.bot.set_webhook(
-                    url=webhook_url, certificate=cert, allowed_updates=allowed_updates)
-            except (Unauthorized, InvalidToken):
-                raise
-            except TelegramError:
-                msg = 'error in bootstrap phase; try={0} max_retries={1}'.format(retries,
-                                                                                 max_retries)
-                if max_retries < 0 or retries < max_retries:
-                    self.logger.warning(msg)
-                    retries += 1
-                else:
-                    self.logger.exception(msg)
-                    raise
+        def bootstrap_clean_updates():
+            self.logger.debug('Cleaning updates from Telegram server')
+            updates = self.bot.get_updates()
+            while updates:
+                updates = self.bot.get_updates(updates[-1].update_id + 1)
+            return False
+
+        def bootstrap_set_webhook():
+            self.bot.set_webhook(
+                url=webhook_url, certificate=cert, allowed_updates=allowed_updates)
+            return False
+
+        def bootstrap_onerr_cb(exc):
+            if not isinstance(exc, Unauthorized) and (max_retries < 0 or retries[0] < max_retries):
+                retries[0] += 1
+                self.logger.warning('Failed bootstrap phase; try=%s max_retries=%s',
+                                    retries[0], max_retries)
             else:
-                break
+                self.logger.error('Failed bootstrap phase after %s retries (%s)', retries[0], exc)
+                raise exc
+
+        # Cleaning pending messages is done by polling for them - so we need to delete webhook if
+        # one is configured.
+        # We also take this chance to delete pre-configured webhook if this is a polling Updater.
+        # NOTE: We don't know ahead if a webhook is configured, so we just delete.
+        if clean or not webhook_url:
+            self._network_loop_retry(bootstrap_del_webhook, bootstrap_onerr_cb,
+                                     'bootstrap del webhook', bootstrap_interval)
+            retries[0] = 0
+
+        # Clean pending messages, if requested.
+        if clean:
+            self._network_loop_retry(bootstrap_clean_updates, bootstrap_onerr_cb,
+                                     'bootstrap clean updates', bootstrap_interval)
+            retries[0] = 0
             sleep(1)
 
-    def _clean_updates(self):
-        self.logger.debug('Cleaning updates from Telegram server')
-        updates = self.bot.get_updates()
-        while updates:
-            updates = self.bot.get_updates(updates[-1].update_id + 1)
+        # Restore/set webhook settings, if needed. Again, we don't know ahead if a webhook is set,
+        # so we set it anyhow.
+        if webhook_url:
+            self._network_loop_retry(bootstrap_set_webhook, bootstrap_onerr_cb,
+                                     'bootstrap set webhook', bootstrap_interval)
 
     def stop(self):
         """Stops the polling/webhook thread, the dispatcher and the job queue."""
@@ -446,6 +486,8 @@ class Updater(object):
     def signal_handler(self, signum, frame):
         self.is_idle = False
         if self.running:
+            self.logger.info('Received signal {} ({}), stopping...'.format(
+                signum, get_signal_name(signum)))
             self.stop()
             if self.user_sig_handler:
                 self.user_sig_handler(signum, frame)

telegram/files/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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -32,6 +32,7 @@ class Audio(TelegramObject):
         title (:obj:`str`): Optional. Title of the audio as defined by sender or by audio tags.
         mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender.
         file_size (:obj:`int`): Optional. File size.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     Args:
         file_id (:obj:`str`): Unique identifier for this file.
@@ -41,6 +42,7 @@ class Audio(TelegramObject):
         title (:obj:`str`, optional): Title of the audio as defined by sender or by audio tags.
         mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
         file_size (:obj:`int`, optional): File size.
+        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     """
@@ -52,6 +54,7 @@ class Audio(TelegramObject):
                  title=None,
                  mime_type=None,
                  file_size=None,
+                 bot=None,
                  **kwargs):
         # Required
         self.file_id = str(file_id)
@@ -61,6 +64,7 @@ class Audio(TelegramObject):
         self.title = title
         self.mime_type = mime_type
         self.file_size = file_size
+        self.bot = bot
 
         self._id_attrs = (self.file_id,)
 
@@ -69,4 +73,22 @@ class Audio(TelegramObject):
         if not data:
             return None
 
-        return cls(**data)
+        return cls(bot=bot, **data)
+
+    def get_file(self, timeout=None, **kwargs):
+        """Convenience wrapper over :attr:`telegram.Bot.get_file`
+
+        Args:
+            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
+                the read timeout from the server (instead of the one specified during creation of
+                the connection pool).
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        Returns:
+            :class:`telegram.File`
+
+        Raises:
+            :class:`telegram.TelegramError`
+
+        """
+        return self.bot.get_file(self.file_id, timeout=timeout, **kwargs)

telegram/files/chatphoto.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/files/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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/files/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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -30,6 +30,7 @@ class Document(TelegramObject):
         file_name (:obj:`str`): Original filename.
         mime_type (:obj:`str`): Optional. MIME type of the file.
         file_size (:obj:`int`): Optional. File size.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     Args:
         file_id (:obj:`str`): Unique file identifier
@@ -37,6 +38,7 @@ class Document(TelegramObject):
         file_name (:obj:`str`, optional): Original filename as defined by sender.
         mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
         file_size (:obj:`int`, optional): File size.
+        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     """
@@ -48,6 +50,7 @@ class Document(TelegramObject):
                  file_name=None,
                  mime_type=None,
                  file_size=None,
+                 bot=None,
                  **kwargs):
         # Required
         self.file_id = str(file_id)
@@ -56,6 +59,7 @@ class Document(TelegramObject):
         self.file_name = file_name
         self.mime_type = mime_type
         self.file_size = file_size
+        self.bot = bot
 
         self._id_attrs = (self.file_id,)
 
@@ -68,4 +72,22 @@ class Document(TelegramObject):
 
         data['thumb'] = PhotoSize.de_json(data.get('thumb'), bot)
 
-        return cls(**data)
+        return cls(bot=bot, **data)
+
+    def get_file(self, timeout=None, **kwargs):
+        """Convenience wrapper over :attr:`telegram.Bot.get_file`
+
+        Args:
+            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
+                the read timeout from the server (instead of the one specified during creation of
+                the connection pool).
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        Returns:
+            :class:`telegram.File`
+
+        Raises:
+            :class:`telegram.TelegramError`
+
+        """
+        return self.bot.get_file(self.file_id, timeout=timeout, **kwargs)

telegram/files/file.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -74,32 +74,34 @@ class File(TelegramObject):
         that object using the ``out.write`` method.
 
         Note:
-            `custom_path` and `out` are mutually exclusive.
+            :attr:`custom_path` and :attr:`out` are mutually exclusive.
 
         Args:
             custom_path (:obj:`str`, optional): Custom path.
-            out (:obj:`object`, optional): A file-like object. Must be opened in binary mode, if
-                applicable.
+            out (:obj:`io.BufferedWriter`, optional): A file-like object. Must be opened for
+                writing in binary mode, if applicable.
             timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                 the read timeout from the server (instead of the one specified during creation of
                 the connection pool).
 
+        Returns:
+            :obj:`str` | :obj:`io.BufferedWriter`: The same object as :attr:`out` if specified.
+            Otherwise, returns the filename downloaded to.
+
         Raises:
-            ValueError: If both ``custom_path`` and ``out`` are passed.
+            ValueError: If both :attr:`custom_path` and :attr:`out` are passed.
 
         """
         if custom_path is not None and out is not None:
             raise ValueError('custom_path and out are mutually exclusive')
 
         # Convert any UTF-8 char into a url encoded ASCII string.
-        sres = urllib_parse.urlsplit(self.file_path)
-        url = urllib_parse.urlunsplit(urllib_parse.SplitResult(
-            sres.scheme, sres.netloc, urllib_parse.quote(sres.path), sres.query, sres.fragment))
+        url = self._get_encoded_url()
 
         if out:
             buf = self.bot.request.retrieve(url)
             out.write(buf)
-
+            return out
         else:
             if custom_path:
                 filename = custom_path
@@ -107,3 +109,27 @@ class File(TelegramObject):
                 filename = basename(self.file_path)
 
             self.bot.request.download(url, filename, timeout=timeout)
+            return filename
+
+    def _get_encoded_url(self):
+        """Convert any UTF-8 char in :obj:`File.file_path` into a url encoded ASCII string."""
+        sres = urllib_parse.urlsplit(self.file_path)
+        return urllib_parse.urlunsplit(urllib_parse.SplitResult(
+            sres.scheme, sres.netloc, urllib_parse.quote(sres.path), sres.query, sres.fragment))
+
+    def download_as_bytearray(self, buf=None):
+        """Download this file and return it as a bytearray.
+
+        Args:
+            buf (:obj:`bytearray`, optional): Extend the given bytearray with the downloaded data.
+
+        Returns:
+            :obj:`bytearray`: The same object as :attr:`buf` if it was specified. Otherwise a newly
+            allocated :obj:`bytearray`.
+
+        """
+        if buf is None:
+            buf = bytearray()
+
+        buf.extend(self.bot.request.retrieve(self._get_encoded_url()))
+        return buf

telegram/files/inputfile.py

@@ -2,7 +2,7 @@
 # pylint: disable=W0622,E0611
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/files/inputmedia.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2018
+# 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/].
+"""Base class for Telegram InputMedia Objects."""
+
+from telegram import TelegramObject
+
+
+class InputMedia(TelegramObject):
+    """Base class for Telegram InputMedia Objects.
+
+    See :class:`telegram.InputMediaPhoto` and :class:`telegram.InputMediaVideo` for
+    detailed use.
+
+    """
+    pass

telegram/files/inputmediaphoto.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2018
+# 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 InputMediaPhoto."""
+from telegram import InputMedia, PhotoSize
+
+
+class InputMediaPhoto(InputMedia):
+    """Represents a photo to be sent.
+
+    Attributes:
+        type (:obj:`str`): ``photo``.
+        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the
+            Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the
+            Internet. Lastly you can pass an existing :class:`telegram.PhotoSize` object to send.
+        caption (:obj:`str`): Optional. Caption of the photo to be sent, 0-200 characters.
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
+
+    Args:
+        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the
+            Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the
+            Internet. Lastly you can pass an existing :class:`telegram.PhotoSize` object to send.
+        caption (:obj:`str`, optional ): Caption of the photo to be sent, 0-200 characters.
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
+
+    Note:
+        At the moment using a new file is not yet supported.
+    """
+
+    # TODO: Make InputMediaPhoto, InputMediaVideo and send_media_group work with new files
+
+    def __init__(self, media, caption=None, parse_mode=None):
+        self.type = 'photo'
+
+        if isinstance(media, PhotoSize):
+            self.media = media.file_id
+        elif hasattr(media, 'read'):
+            raise ValueError(
+                'Sending files is not supported (yet).  Use file_id, url or PhotoSize')
+        else:
+            self.media = media
+
+        if caption:
+            self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode

telegram/files/inputmediavideo.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2018
+# 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 InputMediaPhoto."""
+from telegram import InputMedia, Video
+
+
+class InputMediaVideo(InputMedia):
+    """Represents a video to be sent.
+
+    Attributes:
+        type (:obj:`str`): ``video``.
+        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
+            servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
+            Lastly you can pass an existing :class:`telegram.Video` object to send.
+        caption (:obj:`str`): Optional. Caption of the video to be sent, 0-200 characters.
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
+        width (:obj:`int`): Optional. Video width.
+        height (:obj:`int`): Optional. Video height.
+        duration (:obj:`int`): Optional. Video duration.
+        supports_streaming (:obj:`bool`): Optional. Pass True, if the uploaded video is suitable
+            for streaming.
+
+    Args:
+        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
+            servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
+            Lastly you can pass an existing :class:`telegram.Video` object to send.
+        caption (:obj:`str`, optional): Caption of the video to be sent, 0-200 characters.
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
+        width (:obj:`int`, optional): Video width.
+        height (:obj:`int`, optional): Video height.
+        duration (:obj:`int`, optional): Video duration.
+        supports_streaming (:obj:`bool`, optional): Pass True, if the uploaded video is suitable
+            for streaming.
+
+    Note:
+        When using a :class:`telegram.Video` for the :attr:`media` attribute. It will take the
+        width, height and duration from that video, unless otherwise specified with the optional
+        arguments.
+        At the moment using a new file is not yet supported.
+    """
+
+    # TODO: Make InputMediaPhoto, InputMediaVideo and send_media_group work with new files
+
+    def __init__(self, media, caption=None, width=None, height=None, duration=None,
+                 supports_streaming=None, parse_mode=None):
+        self.type = 'video'
+
+        if isinstance(media, Video):
+            self.media = media.file_id
+            self.width = media.width
+            self.height = media.height
+            self.duration = media.duration
+        elif hasattr(media, 'read'):
+            raise ValueError('Sending files is not supported (yet).  Use file_id, url or Video')
+        else:
+            self.media = media
+
+        if caption:
+            self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
+        if width:
+            self.width = width
+        if height:
+            self.height = height
+        if duration:
+            self.duration = duration
+        if supports_streaming:
+            self.supports_streaming = supports_streaming

telegram/files/location.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/files/photosize.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -29,23 +29,26 @@ class PhotoSize(TelegramObject):
         width (:obj:`int`): Photo width.
         height (:obj:`int`): Photo height.
         file_size (:obj:`int`): Optional. File size.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     Args:
         file_id (:obj:`str`): Unique identifier for this file.
         width (:obj:`int`): Photo width.
         height (:obj:`int`): Photo height.
         file_size (:obj:`int`, optional): File size.
+        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     """
 
-    def __init__(self, file_id, width, height, file_size=None, **kwargs):
+    def __init__(self, file_id, width, height, file_size=None, bot=None, **kwargs):
         # Required
         self.file_id = str(file_id)
         self.width = int(width)
         self.height = int(height)
         # Optionals
         self.file_size = file_size
+        self.bot = bot
 
         self._id_attrs = (self.file_id,)
 
@@ -54,7 +57,7 @@ class PhotoSize(TelegramObject):
         if not data:
             return None
 
-        return cls(**data)
+        return cls(bot=bot, **data)
 
     @classmethod
     def de_list(cls, data, bot):
@@ -66,3 +69,21 @@ class PhotoSize(TelegramObject):
             photos.append(cls.de_json(photo, bot))
 
         return photos
+
+    def get_file(self, timeout=None, **kwargs):
+        """Convenience wrapper over :attr:`telegram.Bot.get_file`
+
+        Args:
+            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
+                the read timeout from the server (instead of the one specified during creation of
+                the connection pool).
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        Returns:
+            :class:`telegram.File`
+
+        Raises:
+            :class:`telegram.TelegramError`
+
+        """
+        return self.bot.get_file(self.file_id, timeout=timeout, **kwargs)

telegram/files/sticker.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -35,6 +35,7 @@ class Sticker(TelegramObject):
         mask_position (:class:`telegram.MaskPosition`): Optional. For mask stickers, the position
             where the mask should be placed.
         file_size (:obj:`int`): Optional. File size.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     Args:
         file_id (:obj:`str`): Unique identifier for this file.
@@ -48,7 +49,8 @@ class Sticker(TelegramObject):
         mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the
             position where the mask should be placed.
         file_size (:obj:`int`, optional): File size.
-        **kwargs (obj:`dict`): Arbitrary keyword arguments.
+        **kwargs (obj:`dict`): Arbitrary keyword arguments.7
+        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
 
     """
 
@@ -61,6 +63,7 @@ class Sticker(TelegramObject):
                  file_size=None,
                  set_name=None,
                  mask_position=None,
+                 bot=None,
                  **kwargs):
         # Required
         self.file_id = str(file_id)
@@ -72,6 +75,7 @@ class Sticker(TelegramObject):
         self.file_size = file_size
         self.set_name = set_name
         self.mask_position = mask_position
+        self.bot = bot
 
         self._id_attrs = (self.file_id,)
 
@@ -85,7 +89,7 @@ class Sticker(TelegramObject):
         data['thumb'] = PhotoSize.de_json(data.get('thumb'), bot)
         data['mask_position'] = MaskPosition.de_json(data.get('mask_position'), bot)
 
-        return cls(**data)
+        return cls(bot=bot, **data)
 
     @classmethod
     def de_list(cls, data, bot):
@@ -94,6 +98,24 @@ class Sticker(TelegramObject):
 
         return [cls.de_json(d, bot) for d in data]
 
+    def get_file(self, timeout=None, **kwargs):
+        """Convenience wrapper over :attr:`telegram.Bot.get_file`
+
+        Args:
+            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
+                the read timeout from the server (instead of the one specified during creation of
+                the connection pool).
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        Returns:
+            :class:`telegram.File`
+
+        Raises:
+            :class:`telegram.TelegramError`
+
+        """
+        return self.bot.get_file(self.file_id, timeout=timeout, **kwargs)
+
 
 class StickerSet(TelegramObject):
     """This object represents a sticker set.

telegram/files/venue.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/files/video.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -32,6 +32,7 @@ class Video(TelegramObject):
         thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail.
         mime_type (:obj:`str`): Optional. Mime type of a file as defined by sender.
         file_size (:obj:`int`): Optional. File size.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     Args:
         file_id (:obj:`str`): Unique identifier for this file.
@@ -41,6 +42,7 @@ class Video(TelegramObject):
         thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail.
         mime_type (:obj:`str`, optional): Mime type of a file as defined by sender.
         file_size (:obj:`int`, optional): File size.
+        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     """
@@ -53,6 +55,7 @@ class Video(TelegramObject):
                  thumb=None,
                  mime_type=None,
                  file_size=None,
+                 bot=None,
                  **kwargs):
         # Required
         self.file_id = str(file_id)
@@ -63,6 +66,7 @@ class Video(TelegramObject):
         self.thumb = thumb
         self.mime_type = mime_type
         self.file_size = file_size
+        self.bot = bot
 
         self._id_attrs = (self.file_id,)
 
@@ -75,4 +79,22 @@ class Video(TelegramObject):
 
         data['thumb'] = PhotoSize.de_json(data.get('thumb'), bot)
 
-        return cls(**data)
+        return cls(bot=bot, **data)
+
+    def get_file(self, timeout=None, **kwargs):
+        """Convenience wrapper over :attr:`telegram.Bot.get_file`
+
+        Args:
+            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
+                the read timeout from the server (instead of the one specified during creation of
+                the connection pool).
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        Returns:
+            :class:`telegram.File`
+
+        Raises:
+            :class:`telegram.TelegramError`
+
+        """
+        return self.bot.get_file(self.file_id, timeout=timeout, **kwargs)

telegram/files/videonote.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -30,6 +30,7 @@ class VideoNote(TelegramObject):
         duration (:obj:`int`): Duration of the video in seconds as defined by sender.
         thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail.
         file_size (:obj:`int`): Optional. File size.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     Args:
         file_id (:obj:`str`): Unique identifier for this file.
@@ -37,11 +38,12 @@ class VideoNote(TelegramObject):
         duration (:obj:`int`): Duration of the video in seconds as defined by sender.
         thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail.
         file_size (:obj:`int`, optional): File size.
+        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     """
 
-    def __init__(self, file_id, length, duration, thumb=None, file_size=None, **kwargs):
+    def __init__(self, file_id, length, duration, thumb=None, file_size=None, bot=None, **kwargs):
         # Required
         self.file_id = str(file_id)
         self.length = int(length)
@@ -49,6 +51,7 @@ class VideoNote(TelegramObject):
         # Optionals
         self.thumb = thumb
         self.file_size = file_size
+        self.bot = bot
 
         self._id_attrs = (self.file_id,)
 
@@ -61,4 +64,22 @@ class VideoNote(TelegramObject):
 
         data['thumb'] = PhotoSize.de_json(data.get('thumb'), bot)
 
-        return cls(**data)
+        return cls(bot=bot, **data)
+
+    def get_file(self, timeout=None, **kwargs):
+        """Convenience wrapper over :attr:`telegram.Bot.get_file`
+
+        Args:
+            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
+                the read timeout from the server (instead of the one specified during creation of
+                the connection pool).
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        Returns:
+            :class:`telegram.File`
+
+        Raises:
+            :class:`telegram.TelegramError`
+
+        """
+        return self.bot.get_file(self.file_id, timeout=timeout, **kwargs)

telegram/files/voice.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -29,23 +29,26 @@ class Voice(TelegramObject):
         duration (:obj:`int`): Duration of the audio in seconds as defined by sender.
         mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender.
         file_size (:obj:`int`): Optional. File size.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     Args:
         file_id (:obj:`str`): Unique identifier for this file.
         duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender.
         mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
         file_size (:obj:`int`, optional): File size.
+        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     """
 
-    def __init__(self, file_id, duration, mime_type=None, file_size=None, **kwargs):
+    def __init__(self, file_id, duration, mime_type=None, file_size=None, bot=None, **kwargs):
         # Required
         self.file_id = str(file_id)
         self.duration = int(duration)
         # Optionals
         self.mime_type = mime_type
         self.file_size = file_size
+        self.bot = bot
 
         self._id_attrs = (self.file_id,)
 
@@ -56,4 +59,22 @@ class Voice(TelegramObject):
 
         data = super(Voice, cls).de_json(data, bot)
 
-        return cls(**data)
+        return cls(bot=bot, **data)
+
+    def get_file(self, timeout=None, **kwargs):
+        """Convenience wrapper over :attr:`telegram.Bot.get_file`
+
+        Args:
+            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
+                the read timeout from the server (instead of the one specified during creation of
+                the connection pool).
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        Returns:
+            :class:`telegram.File`
+
+        Raises:
+            :class:`telegram.TelegramError`
+
+        """
+        return self.bot.get_file(self.file_id, timeout=timeout, **kwargs)

telegram/forcereply.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/games/animation.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/games/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-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/games/game.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/games/gamehighscore.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/inline/inlinekeyboardbutton.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/inline/inlinekeyboardmarkup.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/inline/inlinequery.py

@@ -2,7 +2,7 @@
 # pylint: disable=R0902,R0912,R0913
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -75,14 +75,6 @@ class InlineQuery(TelegramObject):
 
         return cls(bot=bot, **data)
 
-    def to_dict(self):
-        data = super(InlineQuery, self).to_dict()
-
-        # Required
-        data['from'] = data.pop('from_user', None)
-
-        return data
-
     def answer(self, *args, **kwargs):
         """Shortcut for::
 

telegram/inline/inlinequeryresult.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/inline/inlinequeryresultarticle.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/inline/inlinequeryresultaudio.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -35,6 +35,9 @@ class InlineQueryResultAudio(InlineQueryResult):
         performer (:obj:`str`): Optional. Caption, 0-200 characters.
         audio_duration (:obj:`str`): Optional. Performer.
         caption (:obj:`str`): Optional. Audio duration in seconds.
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -47,6 +50,9 @@ class InlineQueryResultAudio(InlineQueryResult):
         performer (:obj:`str`, optional): Caption, 0-200 characters.
         audio_duration (:obj:`str`, optional): Performer.
         caption (:obj:`str`, optional): Audio duration in seconds.
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -64,6 +70,7 @@ class InlineQueryResultAudio(InlineQueryResult):
                  caption=None,
                  reply_markup=None,
                  input_message_content=None,
+                 parse_mode=None,
                  **kwargs):
 
         # Required
@@ -78,6 +85,8 @@ class InlineQueryResultAudio(InlineQueryResult):
             self.audio_duration = audio_duration
         if caption:
             self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
         if reply_markup:
             self.reply_markup = reply_markup
         if input_message_content:

telegram/inline/inlinequeryresultcachedaudio.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -32,6 +32,9 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         audio_file_id (:obj:`str`): A valid file identifier for the audio file.
         caption (:obj:`str`): Optional. Caption, 0-200 characters
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -41,6 +44,9 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         audio_file_id (:obj:`str`): A valid file identifier for the audio file.
         caption (:obj:`str`, optional): Caption, 0-200 characters
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -55,6 +61,7 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
                  caption=None,
                  reply_markup=None,
                  input_message_content=None,
+                 parse_mode=None,
                  **kwargs):
         # Required
         super(InlineQueryResultCachedAudio, self).__init__('audio', id)
@@ -63,6 +70,8 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
         # Optionals
         if caption:
             self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
         if reply_markup:
             self.reply_markup = reply_markup
         if input_message_content:

telegram/inline/inlinequeryresultcacheddocument.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -34,6 +34,9 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
         document_file_id (:obj:`str`): A valid file identifier for the file.
         description (:obj:`str`): Optional. Short description of the result.
         caption (:obj:`str`): Optional. Caption, 0-200 characters
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -45,6 +48,9 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
         document_file_id (:obj:`str`): A valid file identifier for the file.
         description (:obj:`str`, optional): Short description of the result.
         caption (:obj:`str`, optional): Caption, 0-200 characters
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -61,6 +67,7 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
                  caption=None,
                  reply_markup=None,
                  input_message_content=None,
+                 parse_mode=None,
                  **kwargs):
         # Required
         super(InlineQueryResultCachedDocument, self).__init__('document', id)
@@ -72,6 +79,8 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
             self.description = description
         if caption:
             self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
         if reply_markup:
             self.reply_markup = reply_markup
         if input_message_content:

telegram/inline/inlinequeryresultcachedgif.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -34,6 +34,9 @@ class InlineQueryResultCachedGif(InlineQueryResult):
         gif_file_id (:obj:`str`): A valid file identifier for the GIF file.
         title (:obj:`str`): Optional. Title for the result.
         caption (:obj:`str`): Optional. Caption, 0-200 characters
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -44,6 +47,9 @@ class InlineQueryResultCachedGif(InlineQueryResult):
         gif_file_id (:obj:`str`): A valid file identifier for the GIF file.
         title (:obj:`str`, optional): Title for the result.caption (:obj:`str`, optional):
         caption (:obj:`str`, optional): Caption, 0-200 characters
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -59,6 +65,7 @@ class InlineQueryResultCachedGif(InlineQueryResult):
                  caption=None,
                  reply_markup=None,
                  input_message_content=None,
+                 parse_mode=None,
                  **kwargs):
         # Required
         super(InlineQueryResultCachedGif, self).__init__('gif', id)
@@ -69,6 +76,8 @@ class InlineQueryResultCachedGif(InlineQueryResult):
             self.title = title
         if caption:
             self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
         if reply_markup:
             self.reply_markup = reply_markup
         if input_message_content:

telegram/inline/inlinequeryresultcachedmpeg4gif.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -34,6 +34,9 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
         mpeg4_file_id (:obj:`str`): A valid file identifier for the MP4 file.
         title (:obj:`str`): Optional. Title for the result.
         caption (:obj:`str`): Optional. Caption, 0-200 characters
+        parse_mode (:obj:`str`): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -44,6 +47,9 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
         mpeg4_file_id (:obj:`str`): A valid file identifier for the MP4 file.
         title (:obj:`str`, optional): Title for the result.
         caption (:obj:`str`, optional): Caption, 0-200 characters
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -59,6 +65,7 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
                  caption=None,
                  reply_markup=None,
                  input_message_content=None,
+                 parse_mode=None,
                  **kwargs):
         # Required
         super(InlineQueryResultCachedMpeg4Gif, self).__init__('mpeg4_gif', id)
@@ -69,6 +76,8 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
             self.title = title
         if caption:
             self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
         if reply_markup:
             self.reply_markup = reply_markup
         if input_message_content:

telegram/inline/inlinequeryresultcachedphoto.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -35,6 +35,9 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
         title (:obj:`str`): Optional. Title for the result.
         description (:obj:`str`): Optional. Short description of the result.
         caption (:obj:`str`): Optional. Caption, 0-200 characters
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -46,6 +49,9 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
         title (:obj:`str`, optional): Title for the result.
         description (:obj:`str`, optional): Short description of the result.
         caption (:obj:`str`, optional): Caption, 0-200 characters
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -62,6 +68,7 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
                  caption=None,
                  reply_markup=None,
                  input_message_content=None,
+                 parse_mode=None,
                  **kwargs):
         # Required
         super(InlineQueryResultCachedPhoto, self).__init__('photo', id)
@@ -74,6 +81,8 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
             self.description = description
         if caption:
             self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
         if reply_markup:
             self.reply_markup = reply_markup
         if input_message_content:

telegram/inline/inlinequeryresultcachedsticker.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/inline/inlinequeryresultcachedvideo.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -35,6 +35,9 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
         title (:obj:`str`): Title for the result.
         description (:obj:`str`): Optional. Short description of the result.
         caption (:obj:`str`): Optional. Caption, 0-200 characters.
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -46,6 +49,9 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
         title (:obj:`str`): Title for the result.
         description (:obj:`str`, optional): Short description of the result.
         caption (:obj:`str`, optional): Caption, 0-200 characters.
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -62,6 +68,7 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
                  caption=None,
                  reply_markup=None,
                  input_message_content=None,
+                 parse_mode=None,
                  **kwargs):
         # Required
         super(InlineQueryResultCachedVideo, self).__init__('video', id)
@@ -73,6 +80,8 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
             self.description = description
         if caption:
             self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
         if reply_markup:
             self.reply_markup = reply_markup
         if input_message_content:

telegram/inline/inlinequeryresultcachedvoice.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -33,6 +33,9 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
         voice_file_id (:obj:`str`): A valid file identifier for the voice message.
         title (:obj:`str`): Voice message title.
         caption (:obj:`str`): Optional. Caption, 0-200 characters.
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -43,6 +46,9 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
         voice_file_id (:obj:`str`): A valid file identifier for the voice message.
         title (:obj:`str`): Voice message title.
         caption (:obj:`str`, optional): Caption, 0-200 characters.
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -58,6 +64,7 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
                  caption=None,
                  reply_markup=None,
                  input_message_content=None,
+                 parse_mode=None,
                  **kwargs):
         # Required
         super(InlineQueryResultCachedVoice, self).__init__('voice', id)
@@ -67,6 +74,8 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
         # Optionals
         if caption:
             self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
         if reply_markup:
             self.reply_markup = reply_markup
         if input_message_content:

telegram/inline/inlinequeryresultcontact.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/inline/inlinequeryresultdocument.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -33,6 +33,9 @@ class InlineQueryResultDocument(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         title (:obj:`str`): Title for the result.
         caption (:obj:`str`): Optional. Caption, 0-200 characters
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         document_url (:obj:`str`): A valid URL for the file.
         mime_type (:obj:`str`): Mime type of the content of the file, either "application/pdf"
             or "application/zip".
@@ -49,6 +52,9 @@ class InlineQueryResultDocument(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         title (:obj:`str`): Title for the result.
         caption (:obj:`str`, optional): Caption, 0-200 characters
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         document_url (:obj:`str`): A valid URL for the file.
         mime_type (:obj:`str`): Mime type of the content of the file, either "application/pdf"
             or "application/zip".
@@ -76,6 +82,7 @@ class InlineQueryResultDocument(InlineQueryResult):
                  thumb_url=None,
                  thumb_width=None,
                  thumb_height=None,
+                 parse_mode=None,
                  **kwargs):
         # Required
         super(InlineQueryResultDocument, self).__init__('document', id)
@@ -86,6 +93,8 @@ class InlineQueryResultDocument(InlineQueryResult):
         # Optionals
         if caption:
             self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
         if description:
             self.description = description
         if reply_markup:

telegram/inline/inlinequeryresultgame.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify

telegram/inline/inlinequeryresultgif.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -37,6 +37,9 @@ class InlineQueryResultGif(InlineQueryResult):
         thumb_url (:obj:`str`): URL of the static thumbnail for the result (jpeg or gif).
         title (:obj:`str`): Optional. Title for the result.
         caption (:obj:`str`): Optional. Caption, 0-200 characters
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -51,6 +54,9 @@ class InlineQueryResultGif(InlineQueryResult):
         thumb_url (:obj:`str`): URL of the static thumbnail for the result (jpeg or gif).
         title (:obj:`str`, optional): Title for the result.caption (:obj:`str`, optional):
         caption (:obj:`str`, optional): Caption, 0-200 characters
+        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
+            in :class:`telegram.ParseMode` for the available modes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -70,6 +76,7 @@ class InlineQueryResultGif(InlineQueryResult):
                  reply_markup=None,
                  input_message_content=None,
                  gif_duration=None,
+                 parse_mode=None,
                  **kwargs):
 
         # Required
@@ -88,6 +95,8 @@ class InlineQueryResultGif(InlineQueryResult):
             self.title = title
         if caption:
             self.caption = caption
+        if parse_mode:
+            self.parse_mode = parse_mode
         if reply_markup:
             self.reply_markup = reply_markup
         if input_message_content:

telegram/inline/inlinequeryresultlocation.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2017
+# Copyright (C) 2015-2018
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify