Bump version to v6.0.0

* Allow edited as seperate input

In short made it possible to tune messagehandler more to your wishes. and choose exactly what updates to receive. messages, edited_message or channel_post or a combination.

- Added the edited_updates argument to MessageHandler
- Added DepricationWarning when using allow_edited
- replaced _is_allowed_message and _is_allowed_channel_post with _is_allowed_update
- Modified tests to reflect new way

* oops

Spelled deprecation wrong
made an error in the _is_allowed_update.

* Python 2 does not have assertWarns.

* remove unneeded statements

.codeclimate.yml

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

.coveragerc

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

.github/CONTRIBUTING.rst

@@ -0,0 +1,207 @@
+How To Contribute
+===================
+
+Every open source project lives from the generous help by contributors that sacrifice their time and ``python-telegram-bot`` is no different. To make participation as pleasant as possible, this project adheres to the `Code of Conduct`_ by the Python Software Foundation.
+
+Setting things up
+-------------------
+
+1. Fork the ``python-telegram-bot`` repository to your GitHub account.
+
+2. Clone your forked repository of ``python-telegram-bot`` to your computer:
+
+   .. code-block:: bash
+
+      $ git clone https://github.com/<your username>/python-telegram-bot
+      $ cd python-telegram-bot
+
+3. Add a track to the original repository:
+
+   .. code-block:: bash
+
+      $ git remote add upstream https://github.com/python-telegram-bot/python-telegram-bot
+
+4. Install dependencies:
+
+   .. code-block:: bash
+
+      $ sudo pip install -r requirements.txt -r requirements-dev.txt
+
+
+5. Install pre-commit hooks:
+
+   .. code-block:: bash
+
+      $ pre-commit install
+
+Finding something to do
+###################
+
+If you already know what you'd like to work on, you can skip this section.
+
+If you have an idea for something to do, first check if it's already been filed on the `issue tracker`_. If so, add a comment to the issue saying you'd like to work on it, and we'll help you get started! Otherwise, please file a new issue and assign yourself to it.
+
+Another great way to start contributing is by writing tests. Tests are really important because they help prevent developers from accidentally breaking existing code, allowing them to build cool things faster. If you're interested in helping out, let the development team know by posting to the `developers' mailing list`_, and we'll help you get started.
+
+Instructions for making a code change
+####################
+
+The central development branch is ``master``, which should be clean and ready for release at any time. In general, all changes should be done as feature branches based off of ``master``.
+
+Here's how to make a one-off code change.
+
+1. **Choose a descriptive branch name.** It should be lowercase, hyphen-separated, and a noun describing the change (so, ``fuzzy-rules``, but not ``implement-fuzzy-rules``). Also, it shouldn't start with ``hotfix`` or ``release``.
+
+2. **Create a new branch with this name, starting from** ``master``. In other words, run:
+
+   .. code-block:: bash
+
+      $ git fetch upstream
+      $ git checkout master
+      $ git merge upstream/master
+      $ git checkout -b your-branch-name
+
+3. **Make a commit to your feature branch**. Each commit should be self-contained and have a descriptive commit message that helps other developers understand why the changes were made.
+
+   - You can refer to relevant issues in the commit message by writing, e.g., "#105".
+
+   - Your code should adhere to the `PEP 8 Style Guide`_, with the exception that we have a maximum line length of 99.
+
+   - For consistency, please conform to `Google Python Style Guide`_ and `Google Python Style Docstrings`_. In addition, code should be formatted consistently with other code around it.
+
+   - The following exceptions to the above (Google's) style guides applies:
+
+        - Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
+
+   - Please ensure that the code you write is well-tested.
+
+   - Don’t break backward compatibility.
+
+   - Add yourself to the AUTHORS.rst_ file in an alphabetical fashion.
+
+   - Before making a commit ensure that all automated tests still pass:
+
+     .. code-block::
+
+        $ make test
+
+     If you don't have ``make``, do:
+
+     .. code-block::
+
+        $ nosetests -v
+
+   - To actually make the commit (this will trigger tests for yapf, lint and pep8 automatically):
+
+     .. code-block:: bash
+
+        $ git add your-file-changed.py
+
+   - yapf may change code formatting, make sure to re-add them to your commit.
+
+     .. code-block:: bash
+
+      $ git commit -a -m "your-commit-message-here"
+
+   - Finally, push it to your GitHub fork, run:
+
+     .. code-block:: bash
+
+      $ git push origin your-branch-name
+
+4. **When your feature is ready to merge, create a pull request.**
+
+   - Go to your fork on GitHub, select your branch from the dropdown menu, and click "New pull request".
+
+   - Add a descriptive comment explaining the purpose of the branch (e.g. "Add the new API feature to create inline bot queries."). This will tell the reviewer what the purpose of the branch is.
+
+   - Click "Create pull request". An admin will assign a reviewer to your commit.
+
+5. **Address review comments until all reviewers give LGTM ('looks good to me').**
+
+   - When your reviewer has reviewed the code, you'll get an email. You'll need to respond in two ways:
+
+       - Make a new commit addressing the comments you agree with, and push it to the same branch. Ideally, the commit message would explain what the commit does (e.g. "Fix lint error"), but if there are lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".
+
+       - In addition, please reply to each comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. All comments must be resolved before LGTM can be given.
+
+   - Resolve any merge conflicts that arise. To resolve conflicts between 'your-branch-name' (in your fork) and 'master' (in the ``python-telegram-bot`` repository), run:
+
+     .. code-block:: bash
+
+      	$ git checkout your-branch-name
+      	$ git fetch upstream
+	$ git merge upstream/master
+      	$ ...[fix the conflicts]...
+      	$ ...[make sure the tests pass before committing]...
+      	$ git commit -a
+      	$ git push origin your-branch-name
+
+   - At the end, the reviewer will merge the pull request.
+
+6. **Tidy up!** Delete the feature branch from both your local clone and the GitHub repository:
+
+   .. code-block:: bash
+
+      $ git branch -D your-branch-name
+      $ git push origin --delete your-branch-name
+
+7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``!
+
+Style commandments
+---------------------
+
+Specific commandments
+#####################
+
+- Avoid using "double quotes" where you can reasonably use 'single quotes'.
+
+AssertEqual argument order
+######################
+
+- assertEqual method's arguments should be in ('actual', 'expected') order.
+
+Properly calling callables
+#######################
+
+Methods, functions and classes can specify optional parameters (with default
+values) using Python's keyword arg syntax. When providing a value to such a
+callable we prefer that the call also uses keyword arg syntax. For example:
+
+.. code-block:: python
+
+   # GOOD
+   f(0, optional=True)
+
+   # BAD
+   f(0, True)
+
+This gives us the flexibility to re-order arguments and more importantly
+to add new required arguments. It's also more explicit and easier to read.
+
+Properly defining optional arguments
+########################
+
+It's always good to not initialize optional arguments at class creation,
+instead use ``**kwargs`` to get them. It's well known Telegram API can
+change without notice, in that case if a new argument is added it won't
+break the API classes. For example:
+
+.. code-block:: python
+
+    # GOOD
+    def __init__(self, id, name, last_name=None, **kwargs):
+       self.last_name = last_name
+
+    # BAD
+    def __init__(self, id, name, last_name=None):
+       self.last_name = last_name
+
+
+.. _`Code of Conduct`: https://www.python.org/psf/codeofconduct/
+.. _`issue tracker`: https://github.com/python-telegram-bot/python-telegram-bot/issues
+.. _`developers' mailing list`: mailto:devs@python-telegram-bot.org
+.. _`PEP 8 Style Guide`: https://www.python.org/dev/peps/pep-0008/
+.. _`Google Python Style Guide`: https://google-styleguide.googlecode.com/svn/trunk/pyguide.html
+.. _`Google Python Style Docstrings`: http://sphinx-doc.org/latest/ext/example_google.html
+.. _AUTHORS.rst: ../AUTHORS.rst

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,31 @@
+<!--
+Thanks for reporting issues of python-telegram-bot!
+To make it easier for us to help you please enter detailed information below.
+
+Please note, we only support the latest version of python-telegram-bot and
+master branch. Please make sure to upgrade & recreate the issue on the latest
+version prior to opening an issue.
+-->
+### Steps to reproduce
+1.
+
+2.
+
+3.
+
+### Expected behaviour
+Tell us what should happen
+
+### Actual behaviour
+Tell us what happens instead
+
+### Configuration
+**Operating System:**
+
+
+**Version of Python, python-telegram-bot & dependencies:**
+
+``$ python -m telegram``
+
+### Logs
+Insert logs here (if necessary)

.gitignore

@@ -43,6 +43,7 @@ htmlcov/
 nosetests.xml
 coverage.xml
 *,cover
+.coveralls.yml
 
 # Translations
 *.mo
@@ -57,3 +58,19 @@ docs/_build/
 # PyBuilder
 target/
 .idea/
+
+# Sublime Text 2
+*.sublime*
+
+# unitests files
+telegram.mp3
+telegram.mp4
+telegram.ogg
+telegram.png
+telegram.webp
+
+# original files from merges
+*.orig
+
+# Exclude .exrc file for Vim
+.exrc

.gitmodules

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

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+-   repo: git://github.com/python-telegram-bot/mirrors-yapf
+    sha: v0.12.2
+    hooks:
+    -   id: yapf
+        files: ^(telegram|tests)/.*\.py$
+-   repo: git://github.com/pre-commit/pre-commit-hooks
+    sha: 18d7035de5388cc7775be57f529c154bf541aab9
+    hooks:
+    -   id: flake8
+        files: ^telegram/.*\.py$
+-   repo: git://github.com/pre-commit/mirrors-pylint
+    sha: v1.5.5
+    hooks:
+    -   id: pylint
+        files: ^telegram/.*\.py$
+        args:
+        - --errors-only
+        - --disable=no-name-in-module,import-error

.travis.yml

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

AUTHORS.rst

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

CHANGES.rst

@@ -1,138 +1,507 @@
-2015-08-19
-  Released 2.7.1
-  Fixed JSON serialization for message
+=======
+Changes
+=======
+
+**2017-05-19**
+
+*Released 6.0.0*
+
+- Add support for Bot API 2.3.1
+- Add support for ``deleteMessage`` API method
+- New, simpler API for ``JobQueue`` - https://github.com/python-telegram-bot/python-telegram-bot/pull/484
+- Download files into file-like objects - https://github.com/python-telegram-bot/python-telegram-bot/pull/459
+- Use vendor ``urllib3`` to address issues with timeouts
+  - The default timeout for messages is now 5 seconds. For sending media, the default timeout is now 20 seconds.
+- String attributes that are not set are now ``None`` by default, instead of empty strings
+- Add ``text_markdown`` and ``text_html`` properties to ``Message`` - https://github.com/python-telegram-bot/python-telegram-bot/pull/507
+- Add support for Socks5 proxy - https://github.com/python-telegram-bot/python-telegram-bot/pull/518
+- Add support for filters in ``CommandHandler`` - https://github.com/python-telegram-bot/python-telegram-bot/pull/536
+- Add the ability to invert (not) filters - https://github.com/python-telegram-bot/python-telegram-bot/pull/552
+- Add ``Filters.group`` and ``Filters.private``
+- Compatibility with GAE via ``urllib3.contrib`` package - https://github.com/python-telegram-bot/python-telegram-bot/pull/583
+- Add equality rich comparision operators to telegram objects - https://github.com/python-telegram-bot/python-telegram-bot/pull/604
+- Several bugfixes and other improvements
+- Remove some deprecated code
+
+**2017-04-17**
+
+*Released 5.3.1*
+
+- Hotfix release due to bug introduced by urllib3 version 1.21
+
+**2016-12-11**
+
+*Released 5.3*
+
+- Implement API changes of November 21st (Bot API 2.3)
+- ``JobQueue`` now supports ``datetime.timedelta`` in addition to seconds
+- ``JobQueue`` now supports running jobs only on certain days
+- New ``Filters.reply`` filter
+- Bugfix for ``Message.edit_reply_markup``
+- Other bugfixes
+
+**2016-10-25**
+
+*Released 5.2*
+
+- Implement API changes of October 3rd (games update)
+- Add ``Message.edit_*`` methods
+- Filters for the ``MessageHandler`` can now be combined using bitwise operators (``& and |``)
+- Add a way to save user- and chat-related data temporarily
+- Other bugfixes and improvements
+
+**2016-09-24**
+
+*Released 5.1*
+
+- Drop Python 2.6 support
+- Deprecate ``telegram.Emoji``
+
+- Use ``ujson`` if available
+- Add instance methods to ``Message``, ``Chat``, ``User``, ``InlineQuery`` and ``CallbackQuery``
+- RegEx filtering for ``CallbackQueryHandler`` and ``InlineQueryHandler``
+- New ``MessageHandler`` filters: ``forwarded`` and ``entity``
+- Add ``Message.get_entity`` to correctly handle UTF-16 codepoints and ``MessageEntity`` offsets
+- Fix bug in ``ConversationHandler`` when first handler ends the conversation
+- Allow multiple ``Dispatcher`` instances
+- Add ``ChatMigrated`` Exception
+- Properly split and handle arguments in ``CommandHandler``
+
+**2016-07-15**
+
+*Released 5.0*
+
+- Rework ``JobQueue``
+- Introduce ``ConversationHandler``
+
+**2016-07-12**
+
+*Released 4.3.4*
+
+- Fix proxy support with ``urllib3`` when proxy requires auth
+
+**2016-07-08**
+
+*Released 4.3.3*
+
+- Fix proxy support with ``urllib3``
+
+**2016-07-04**
+
+*Released 4.3.2*
+
+- Fix: Use ``timeout`` parameter in all API methods
+
+**2016-06-29**
+
+*Released 4.3.1*
+
+- Update wrong requirement: ``urllib3>=1.10``
+
+**2016-06-28**
+
+*Released 4.3*
+
+- Use ``urllib3.PoolManager`` for connection re-use
+- Rewrite ``run_async`` decorator to re-use threads
+- New requirements: ``urllib3`` and ``certifi``
+
+**2016-06-10**
+
+*Released 4.2.1*
+
+- Fix ``CallbackQuery.to_dict()`` bug (thanks to @jlmadurga)
+- Fix ``editMessageText`` exception when receiving a ``CallbackQuery``
+
+**2016-05-28**
+
+*Released 4.2*
+
+- Implement Bot API 2.1
+- Move ``botan`` module to ``telegram.contrib``
+- New exception type: ``BadRequest``
+
+**2016-05-22**
+
+*Released 4.1.2*
+
+- Fix ``MessageEntity`` decoding with Bot API 2.1 changes
+
+**2016-05-16**
+
+*Released 4.1.1*
+
+- Fix deprecation warning in ``Dispatcher``
+
+**2016-05-15**
+
+*Released 4.1*
+
+- Implement API changes from May 6, 2016
+- Fix bug when ``start_polling`` with ``clean=True``
+- Methods now have snake_case equivalent, for example ``telegram.Bot.send_message`` is the same as ``telegram.Bot.sendMessage``
+
+**2016-05-01**
+
+*Released 4.0.3*
+
+- Add missing attribute ``location`` to ``InlineQuery``
+
+**2016-04-29**
+
+*Released 4.0.2*
+
+- Bugfixes
+- ``KeyboardReplyMarkup`` now accepts ``str`` again
+
+**2016-04-27**
+
+*Released 4.0.1*
+
+- Implement Bot API 2.0
+- Almost complete recode of ``Dispatcher``
+- Please read the `Transition Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transition-guide-to-Version-4.0>`_
+- **Changes from 4.0rc1**
+    - The syntax of filters for ``MessageHandler`` (upper/lower cases)
+    - Handler groups are now identified by ``int`` only, and ordered
+- **Note:** v4.0 has been skipped due to a PyPI accident
+
+**2016-04-22**
+
+*Released 4.0rc1*
+
+- Implement Bot API 2.0
+- Almost complete recode of ``Dispatcher``
+- Please read the `Transistion Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transistion-guide-to-Version-4.0>`_
+
+**2016-03-22**
+
+*Released 3.4*
+
+- Move ``Updater``, ``Dispatcher`` and ``JobQueue`` to new ``telegram.ext`` submodule (thanks to @rahiel)
+- Add ``disable_notification`` parameter (thanks to @aidarbiktimirov)
+- Fix bug where commands sent by Telegram Web would not be recognized (thanks to @shelomentsevd)
+- Add option to skip old updates on bot startup
+- Send files from ``BufferedReader``
+
+**2016-02-28**
+
+*Released 3.3*
+
+- Inline bots
+- Send any file by URL
+- Specialized exceptions: ``Unauthorized``, ``InvalidToken``, ``NetworkError`` and ``TimedOut``
+- Integration for botan.io (thanks to @ollmer)
+- HTML Parsemode (thanks to @jlmadurga)
+- Bugfixes and under-the-hood improvements
+
+**Very special thanks to Noam Meltzer (@tsnoam) for all of his work!**
+
+**2016-01-09**
+
+*Released 3.3b1*
+
+- Implement inline bots (beta)
+
+**2016-01-05**
+
+*Released 3.2.0*
+
+- Introducing ``JobQueue`` (original author: @franciscod)
+- Streamlining all exceptions to ``TelegramError`` (Special thanks to @tsnoam)
+- Proper locking of ``Updater`` and ``Dispatcher`` ``start`` and ``stop`` methods
+- Small bugfixes
+
+**2015-12-29**
+
+*Released 3.1.2*
+
+- Fix custom path for file downloads
+- Don't stop the dispatcher thread on uncaught errors in handlers
+
+**2015-12-21**
+
+*Released 3.1.1*
+
+- Fix a bug where asynchronous handlers could not have additional arguments
+- Add ``groups`` and ``groupdict`` as additional arguments for regex-based handlers
+
+**2015-12-16**
+
+*Released 3.1.0*
+
+- The ``chat``-field in ``Message`` is now of type ``Chat``. (API update Oct 8 2015)
+- ``Message`` now contains the optional fields ``supergroup_chat_created``, ``migrate_to_chat_id``, ``migrate_from_chat_id`` and ``channel_chat_created``. (API update Nov 2015)
+
+**2015-12-08**
+
+*Released 3.0.0*
+
+- Introducing the ``Updater`` and ``Dispatcher`` classes
+
+**2015-11-11**
+
+*Released 2.9.2*
+
+- Error handling on request timeouts has been improved
+
+**2015-11-10**
+
+*Released 2.9.1*
+
+- Add parameter ``network_delay`` to Bot.getUpdates for slow connections
+
+**2015-11-10**
+
+*Released 2.9*
+
+- Emoji class now uses ``bytes_to_native_str`` from ``future`` 3rd party lib
+- Make ``user_from`` optional to work with channels
+- Raise exception if Telegram times out on long-polling
+
+*Special thanks to @jh0ker for all hard work*
 
 
-2015-08-17
-  Released 2.7
-  Added support for Voice object and sendVoice method
-  Due backward compatibility performer or/and title will be required for sendAudio
-  Fixed JSON serialization when forwarded message
+**2015-10-08**
+
+*Released 2.8.7*
+
+- Type as optional for ``GroupChat`` class
 
 
-2015-08-15
-  Released 2.6.1
-  Fixed parsing image header issue on < Python 2.7.3
+**2015-10-08**
+
+*Released 2.8.6*
+
+- Adds type to ``User`` and ``GroupChat`` classes (pre-release Telegram feature)
 
 
-2015-08-14
-  Released 2.6.0
-  Depreciation of require_authentication and clearCredentials methods
-  Giving AUTHORS the proper credits for their contribution for this project
-  Message.date and Message.forward_date are now datetime objects
+**2015-09-24**
+
+*Released 2.8.5*
+
+- Handles HTTP Bad Gateway (503) errors on request
+- Fixes regression on ``Audio`` and ``Document`` for unicode fields
 
 
-2015-08-12
-  Released 2.5.3
-  telegram.Bot now supports to be unpickled
+**2015-09-20**
+
+*Released 2.8.4*
+
+- ``getFile`` and ``File.download`` is now fully supported
 
 
-2015-08-11
-  Released 2.5.2
-  New changes from Telegram Bot API have been applied
-  telegram.Bot now supports to be pickled
-  Return empty str instead None when message.text is empty
+**2015-09-10**
+
+*Released 2.8.3*
+
+- Moved ``Bot._requestURL`` to its own class (``telegram.utils.request``)
+- Much better, such wow, Telegram Objects tests
+- Add consistency for ``str`` properties on Telegram Objects
+- Better design to test if ``chat_id`` is invalid
+- Add ability to set custom filename on ``Bot.sendDocument(..,filename='')``
+- Fix Sticker as ``InputFile``
+- Send JSON requests over urlencoded post data
+- Markdown support for ``Bot.sendMessage(..., parse_mode=ParseMode.MARKDOWN)``
+- Refactor of ``TelegramError`` class (no more handling ``IOError`` or ``URLError``)
 
 
-2015-08-10
-  Released 2.5.1
-  Moved from GPLv2 to LGPLv3
+**2015-09-05**
+
+*Released 2.8.2*
+
+- Fix regression on Telegram ReplyMarkup
+- Add certificate to ``is_inputfile`` method
 
 
-2015-08-09
-  Released 2.5
-  Fixes logging calls in API
+**2015-09-05**
+
+*Released 2.8.1*
+
+- Fix regression on Telegram objects with thumb properties
 
 
-2015-08-08
-  Released 2.4
-  Fixes Emoji class for Python 3
-  PEP8 improvements
+**2015-09-04**
+
+*Released 2.8*
+
+- TelegramError when ``chat_id`` is empty for send* methods
+- ``setWebhook`` now supports sending self-signed certificate
+- Huge redesign of existing Telegram classes
+- Added support for PyPy
+- Added docstring for existing classes
 
 
-2015-08-08
-  Released 2.3
-  Fixes ForceReply class
-  Remove logging.basicConfig from library
+**2015-08-19**
+
+*Released 2.7.1*
+
+- Fixed JSON serialization for ``message``
 
 
-2015-07-25
-  Released 2.2
-  Allows debug=True when initializing telegram.Bot
+**2015-08-17**
+
+*Released 2.7*
+
+- Added support for ``Voice`` object and ``sendVoice`` method
+- Due backward compatibility performer or/and title will be required for ``sendAudio``
+- Fixed JSON serialization when forwarded message
 
 
-2015-07-20
-  Released 2.1
-  Fix to_dict for Document and Video
+**2015-08-15**
+
+*Released 2.6.1*
+
+- Fixed parsing image header issue on < Python 2.7.3
 
 
-2015-07-19
+**2015-08-14**
 
-  Released 2.0
-  Fixes bugs
-  Improves __str__ over to_json()
-  Creates abstractclass TelegramObject
+*Released 2.6.0*
+
+- Depreciation of ``require_authentication`` and ``clearCredentials`` methods
+- Giving ``AUTHORS`` the proper credits for their contribution for this project
+- ``Message.date`` and ``Message.forward_date`` are now ``datetime`` objects
 
 
-2015-07-15
+**2015-08-12**
 
-  Released 1.9
-  Python 3 officially supported
-  PEP8 improvements
+*Released 2.5.3*
+
+- ``telegram.Bot`` now supports to be unpickled
 
 
-2015-07-12
+**2015-08-11**
 
-  Released 1.8
-  Fixes crash when replying an unicode text message (special thanks to JRoot3D)
+*Released 2.5.2*
+
+- New changes from Telegram Bot API have been applied
+- ``telegram.Bot`` now supports to be pickled
+- Return empty ``str`` instead ``None`` when ``message.text`` is empty
 
 
-2015-07-11
+**2015-08-10**
 
-  Released 1.7
-  Fixes crash when username is not defined on chat (special thanks to JRoot3D)
+*Released 2.5.1*
+
+- Moved from GPLv2 to LGPLv3
 
 
-2015-07-10
+**2015-08-09**
 
-  Released 1.6
-  Improvements for GAE support
+*Released 2.5*
+
+- Fixes logging calls in API
 
 
-2015-07-10
+**2015-08-08**
 
-  Released 1.5
-  Fixes randomly unicode issues when using InputFile
+*Released 2.4*
+
+- Fixes ``Emoji`` class for Python 3
+- ``PEP8`` improvements
 
 
-2015-07-10
+**2015-08-08**
 
-  Released 1.4
-  requests lib is no longer required
-  Google App Engine (GAE) is supported
+*Released 2.3*
+
+- Fixes ``ForceReply`` class
+- Remove ``logging.basicConfig`` from library
 
 
-2015-07-10
+**2015-07-25**
 
-  Released 1.3
-  Added support to setWebhook (special thanks to macrojames)
+*Released 2.2*
+
+- Allows ``debug=True`` when initializing ``telegram.Bot``
 
 
-2015-07-09
+**2015-07-20**
 
-  Released 1.2
-  CustomKeyboard classes now available
-  Emojis available
-  PEP8 improvements
+*Released 2.1*
+
+- Fix ``to_dict`` for ``Document`` and ``Video``
 
 
-2015-07-08
+**2015-07-19**
 
-  Released 1.1
-  PyPi package now available
+*Released 2.0*
+
+- Fixes bugs
+- Improves ``__str__`` over ``to_json()``
+- Creates abstract class ``TelegramObject``
 
 
-2015-07-08
+**2015-07-15**
 
-  Released 1.0
-  Initial checkin of python-telegram-bot
+*Released 1.9*
+
+- Python 3 officially supported
+- ``PEP8`` improvements
+
+
+**2015-07-12**
+
+*Released 1.8*
+
+- Fixes crash when replying an unicode text message (special thanks to JRoot3D)
+
+
+**2015-07-11**
+
+*Released 1.7*
+
+- Fixes crash when ``username`` is not defined on ``chat`` (special thanks to JRoot3D)
+
+
+**2015-07-10**
+
+*Released 1.6*
+
+- Improvements for GAE support
+
+
+**2015-07-10**
+
+*Released 1.5*
+
+- Fixes randomly unicode issues when using ``InputFile``
+
+
+**2015-07-10**
+
+*Released 1.4*
+
+- ``requests`` lib is no longer required
+- Google App Engine (GAE) is supported
+
+
+**2015-07-10**
+
+*Released 1.3*
+
+- Added support to ``setWebhook`` (special thanks to macrojames)
+
+
+**2015-07-09**
+
+*Released 1.2*
+
+- ``CustomKeyboard`` classes now available
+- Emojis available
+- ``PEP8`` improvements
+
+
+**2015-07-08**
+
+*Released 1.1*
+
+- PyPi package now available
+
+
+**2015-07-08**
+
+*Released 1.0*
+
+- Initial checkin of python-telegram-bot

CONTRIBUTING.rst

@@ -1,39 +0,0 @@
-How To Contribute
-=================
-
-Every open source project lives from the generous help by contributors that sacrifice their time and ``python-telegram-bot`` is no different.
-
-To make participation as pleasant as possible, this project adheres to the `Code of Conduct`_ by the Python Software Foundation.
-
-Here are a few guidelines to get you started:
-
-- Add yourself to the AUTHORS.rst_ file in an alphabetical fashion.
-  Every contribution is valuable and shall be credited.
-- If your change is noteworthy, add an entry to the CHANGES_.
-- No contribution is too small; please submit as many fixes for typos and grammar bloopers as you can!
-- Don’t break backward compatibility.
-- *Always* add tests and docs for your code.
-  This is a hard rule; patches with missing tests or documentation won’t be merged.
-  If a feature is not tested or documented, it doesn’t exist.
-- Obey `PEP 8`_ and `PEP 257`_.
-- Follow `Google Python Style Guide`_ and `Google Python Style Docstrings`_.
-- Write `good commit messages`_.
-
-.. note::
-   If you have something great but aren’t sure whether it adheres -- or even can adhere -- to the rules above: **please submit a pull request anyway**!
-
-   In the best case, we can mold it into something, in the worst case the pull request gets politely closed.
-   There’s absolutely nothing to fear.
-
-Thank you for considering to contribute to ``python-telegram-bot``!
-If you have any question or concerns, feel free to reach out to me.
-
-
-.. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/
-.. _`PEP 257`: https://www.python.org/dev/peps/pep-0257/
-.. _`good commit messages`: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
-.. _`Code of Conduct`: https://www.python.org/psf/codeofconduct/
-.. _`Google Python Style Guide`: https://google-styleguide.googlecode.com/svn/trunk/pyguide.html
-.. _`Google Python Style Docstrings`: http://sphinx-doc.org/latest/ext/example_google.html
-.. _CHANGES: https://github.com/leandrotoledo/python-telegram-bot/blob/master/CHANGES
-.. _AUTHORS.rst: https://github.com/leandrotoledo/python-telegram-bot/blob/master/AUTHORS.rst

MANIFEST.in

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

Makefile

@@ -1,4 +1,12 @@
-.PHONY: clean pep8 lint test
+.DEFAULT_GOAL := help
+.PHONY: clean pep257 pep8 yapf lint test install
+
+PYLINT          := pylint
+NOSETESTS       := nosetests
+PEP257          := pep257
+PEP8            := flake8
+YAPF            := yapf
+PIP             := pip
 
 clean:
 	rm -fr build
@@ -6,19 +14,39 @@ clean:
 	find . -name '*.pyc' -exec rm -f {} \;
 	find . -name '*.pyo' -exec rm -f {} \;
 	find . -name '*~' -exec rm -f {} \;
+	find . -regex "./telegram.\(mp3\|mp4\|ogg\|png\|webp\)" -exec rm {} \;
+
+pep257:
+	$(PEP257) telegram
 
 pep8:
-	flake8 telegram
+	$(PEP8) telegram
+
+yapf:
+	$(YAPF) -r telegram
 
 lint:
-	pylint -E telegram
+	$(PYLINT) -E telegram --disable=no-name-in-module,import-error
 
 test:
-	@- $(foreach TEST, $(wildcard tests/test_*.py), python $(TEST))
+	$(NOSETESTS) -v
+
+install:
+	$(PIP)  install -r requirements.txt -r requirements-dev.txt
 
 help:
 	@echo "Available targets:"
 	@echo "- clean       Clean up the source directory"
+	@echo "- pep257      Check docstring style with pep257"
 	@echo "- pep8        Check style with flake8"
 	@echo "- lint        Check style with pylint"
+	@echo "- yapf        Check style with yapf"
 	@echo "- test        Run tests"
+	@echo
+	@echo "Available variables:"
+	@echo "- PYLINT      default: $(PYLINT)"
+	@echo "- NOSETESTS   default: $(NOSETESTS)"
+	@echo "- PEP257      default: $(PEP257)"
+	@echo "- PEP8        default: $(PEP8)"
+	@echo "- YAPF        default: $(YAPF)"
+	@echo "- PIP         default: $(PIP)"

README.rst

@@ -1,36 +1,47 @@
-Python Telegram Bot
+.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-logo-text_768.png?raw=true
+   :align: center
+   :target: https://python-telegram-bot.org
+   :alt: python-telegram-bot Logo
 
-A Python wrapper around the Telegram Bot API.
+We have made you a wrapper you can't refuse
 
-By `Leandro Toledo <leandrotoledodesouza@gmail.com>`_
+*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
    :alt: PyPi Package Version
-    
-.. image:: https://img.shields.io/pypi/dm/python-telegram-bot.svg
+
+.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot.svg
    :target: https://pypi.python.org/pypi/python-telegram-bot
-   :alt: PyPi Package Monthly Download
-   
-.. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=latest
-   :target: https://readthedocs.org/projects/python-telegram-bot/?badge=latest
+   :alt: Supported python versions
+
+.. image:: https://img.shields.io/badge/docs-latest-af1a97.svg
+   :target: https://python-telegram-bot.readthedocs.io/
    :alt: Documentation Status
-   
-.. image:: https://img.shields.io/github/license/leandrotoledo/python-telegram-bot.svg
-   :target: http://www.gnu.org/licenses/lgpl-3.0.html
+
+.. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg
+   :target: https://www.gnu.org/licenses/lgpl-3.0.html
    :alt: LGPLv3 License
 
-.. image:: https://travis-ci.org/leandrotoledo/python-telegram-bot.svg?branch=master
-   :target: https://travis-ci.org/leandrotoledo/python-telegram-bot
+.. image:: https://travis-ci.org/python-telegram-bot/python-telegram-bot.svg?branch=master
+   :target: https://travis-ci.org/python-telegram-bot/python-telegram-bot
    :alt: Travis CI Status
 
-.. image:: https://codeclimate.com/github/leandrotoledo/python-telegram-bot/badges/gpa.svg
-   :target: https://codeclimate.com/github/leandrotoledo/python-telegram-bot
+.. image:: https://codeclimate.com/github/python-telegram-bot/python-telegram-bot/badges/gpa.svg
+   :target: https://codeclimate.com/github/python-telegram-bot/python-telegram-bot
    :alt: Code Climate
-   
-.. image:: https://coveralls.io/repos/leandrotoledo/python-telegram-bot/badge.svg?branch=master&service=github
-   :target: https://coveralls.io/github/leandrotoledo/python-telegram-bot?branch=master
+
+.. image:: https://coveralls.io/repos/python-telegram-bot/python-telegram-bot/badge.svg?branch=master&service=github
+   :target: https://coveralls.io/github/python-telegram-bot/python-telegram-bot?branch=master
    :alt: Coveralls
+   
+.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
+   :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
+   :alt: Median time to resolve an issue
+
+.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg
+   :target: https://telegram.me/pythontelegrambotgroup
+   :alt: Telegram Group
 
 =================
 Table of contents
@@ -38,238 +49,150 @@ Table of contents
 
 - `Introduction`_
 
-- `Status`_
-
-  1. `Telegram API support`_
-
-  2. `Python Version support`_
+- `Telegram API support`_
 
 - `Installing`_
 
-- `Getting the code`_
-
 - `Getting started`_
 
-  1. `API`_
+  #. `Learning by example`_
 
-  2. `Logging`_
+  #. `Logging`_
 
-  3. `Examples`_
-  
-  4. `Documentation`_
+  #. `Documentation`_
+
+- `Getting help`_
+
+- `Contributing`_
 
 - `License`_
 
-- `Contact`_
+============
+Introduction
+============
 
-- `TODO`_
+This library provides a pure Python interface for the
+`Telegram Bot API <https://core.telegram.org/bots/api>`_.
+It's compatible with Python versions 2.7, 3.3+ and `PyPy <http://pypy.org/>`_.
+It also works with `Google App Engine <https://cloud.google.com/appengine>`_.
 
-===============
-_`Introduction`
-===============
+In addition to the pure API implementation, this library features a number of high-level classes to
+make the development of bots easy and straightforward. These classes are contained in the
+``telegram.ext`` submodule.
 
-This library provides a pure Python interface for the `Telegram Bot API <https://core.telegram.org/bots/api>`_. It works with Python versions from 2.6+. It also works with `Google App Engine <https://cloud.google.com/appengine>`_.
+====================
+Telegram API support
+====================
 
-=========
-_`Status`
-=========
+As of **4. Dec 2016**, all types and methods of the Telegram Bot API are supported.
 
------------------------
-_`Telegram API support`
------------------------
+==========
+Installing
+==========
 
-========================= ============
-Telegram Bot API Method   *Supported?*
-========================= ============
-getMe                     Yes
-sendMessage               Yes
-forwardMessage            Yes
-sendPhoto                 Yes
-sendAudio                 Yes
-sendDocument              Yes
-sendSticker               Yes
-sendVideo                 Yes
-sendVoice                 Yes
-sendLocation              Yes
-sendChatAction            Yes
-getUpdates                Yes
-getUserProfilePhotos      Yes
-setWebhook                Yes
-========================= ============
+You can install or upgrade python-telegram-bot with:
 
--------------------------
-_`Python Version support`
--------------------------
-
-============== ============
-Python Version *Supported?*
-============== ============
-2.6            Yes
-2.7            Yes
-3.3            Yes
-3.4            Yes
-============== ============
-
-=============
-_`Installing`
-=============
-
-You can install python-telegram-bot using::
-
-    $ pip install python-telegram-bot
-
-Or upgrade to the latest version::
+.. code:: shell
 
     $ pip install python-telegram-bot --upgrade
 
-===================
-_`Getting the code`
-===================
+Or you can install from source with:
 
-The code is hosted at https://github.com/leandrotoledo/python-telegram-bot
+.. code:: shell
 
-Check out the latest development version anonymously with::
-
-    $ git clone https://github.com/leandrotoledo/python-telegram-bot
+    $ git clone https://github.com/python-telegram-bot/python-telegram-bot --recursive
     $ cd python-telegram-bot
+    $ python setup.py install
+    
+In case you have a previously cloned local repository already, you should initialize the added urllib3 submodule before installing with:
 
-Run tests:
+.. code:: shell
 
-    $ make test
+    $ git submodule update --init --recursive
 
-To see other options available, run:
+===============
+Getting started
+===============
 
-    $ make help
+Our Wiki contains a lot of resources to get you started with ``python-telegram-bot``:
 
-==================
-_`Getting started`
-==================
+- `Introduction to the API <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_
+- Tutorial: `Your first Bot <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-Your-first-Bot>`_
 
-View the last release API documentation at: https://core.telegram.org/bots/api
+Other references:
 
-------
-_`API`
-------
+- `Telegram API documentation <https://core.telegram.org/bots/api>`_
+- `python-telegram-bot documentation <https://python-telegram-bot.readthedocs.io/>`_
 
-The API is exposed via the ``telegram.Bot`` class.
+-------------------
+Learning by example
+-------------------
 
-To generate an Access Token you have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#botfather>`_).
+We believe that the best way to learn and understand this simple package is by example. So here
+are some examples for you to review. Even if it's not your approach for learning, please take a
+look at ``echobot2``, it is de facto the base for most of the bots out there. Best of all,
+the code for these examples are released to the public domain, so you can start by grabbing the
+code and building on top of it.
 
-For full details see the `Bots: An introduction for developers <https://core.telegram.org/bots>`_.
+Visit `this page <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ to discover the official examples or look at the examples on the `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Examples>`_ to see other bots the community has built.
 
-To create an instance of the ``telegram.Bot``::
+-------
+Logging
+-------
 
-    >>> import telegram
-    >>> bot = telegram.Bot(token='token')
+This library uses the ``logging`` module. To set up logging to standard output, put:
 
-To see if your credentials are successful::
+.. code:: python
 
-    >>> print bot.getMe()
-    {"first_name": "Toledo's Palace Bot", "username": "ToledosPalaceBot"}
+    import logging
+    logging.basicConfig(level=logging.DEBUG,
+                        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
 
-Bots can't initiate conversations with users. A user must either add them to a group or send them a message first. People can use ``telegram.me/<bot_username>`` links or username search to find your bot.
+at the beginning of your script.
 
-To fetch text messages sent to your Bot::
+You can also use logs in your application by calling ``logging.getLogger()`` and setting the log level you want:
 
-    >>> updates = bot.getUpdates()
-    >>> print [u.message.text for u in updates]
+.. code:: python
 
-To fetch images sent to your Bot::
+    logger = logging.getLogger()
+    logger.setLevel(logging.INFO)
 
-    >>> updates = bot.getUpdates()
-    >>> print [u.message.photo for u in updates if u.message.photo]
+If you want DEBUG logs instead:
 
-To reply messages you'll always need the chat_id::
+.. code:: python
 
-    >>> chat_id = bot.getUpdates()[-1].message.chat_id
+    logger.setLevel(logging.DEBUG)
 
-To post a text message::
 
-    >>> bot.sendMessage(chat_id=chat_id, text="I'm sorry Dave I'm afraid I can't do that.")
+=============
+Documentation
+=============
 
-To post an Emoji (special thanks to `Tim Whitlock <http://apps.timwhitlock.info/emoji/tables/unicode>`_)::
+``python-telegram-bot``'s documentation lives at `readthedocs.io <https://python-telegram-bot.readthedocs.io/>`_.
 
-    >>> bot.sendMessage(chat_id=chat_id, text=telegram.Emoji.PILE_OF_POO)
+============
+Getting help
+============
 
-To post an image file via URL (right now only sendPhoto supports this)::
+You can get help in several ways:
 
-    >>> bot.sendPhoto(chat_id=chat_id, photo='https://telegram.org/img/t_logo.png')
+1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
 
-To post a voice file::
+2. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources.
 
-    >>> bot.sendVoice(chat_id=chat_id, voice=open('tests/telegram.ogg', 'rb'))
+3. You can ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
 
-To tell the user that something is happening on bot's side::
+4. As last resort, the developers are ready to help you with `serious issues <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
 
-    >>> bot.sendChatAction(chat_id=chat_id, action=telegram.ChatAction.TYPING)
 
-To create `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_::
+============
+Contributing
+============
 
-    >>> custom_keyboard = [[ telegram.Emoji.THUMBS_UP_SIGN, telegram.Emoji.THUMBS_DOWN_SIGN ]]
-    >>> reply_markup = telegram.ReplyKeyboardMarkup(custom_keyboard)
-    >>> bot.sendMessage(chat_id=chat_id, text="Stay here, I'll be back.", reply_markup=reply_markup)
-
-To hide `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_::
-
-    >>> reply_markup = telegram.ReplyKeyboardHide()
-    >>> bot.sendMessage(chat_id=chat_id, text="I'm back.", reply_markup=reply_markup)
-
-There are many more API methods, to read the full API documentation::
-
-    $ pydoc telegram.Bot
-
------------
-_`Logging`
------------
-
-You can get logs in your main application by calling `logging` and setting the log level you want::
-
-    >>> import logging
-    >>> logger = logging.getLogger()
-    >>> logger.setLevel(logging.INFO)
-
-If you want DEBUG logs instead::
-
-    >>> logger.setLevel(logging.DEBUG)
-
------------
-_`Examples`
------------
-
-Here follows some examples to help you to get your own Bot up to speed:
-
-- `echobot <https://github.com/leandrotoledo/python-telegram-bot/blob/master/examples/echobot.py>`_ replies back messages.
-
-- `roboed <https://github.com/leandrotoledo/python-telegram-bot/blob/master/examples/roboed.py>`_ talks to `Robô Ed <http://www.ed.conpet.gov.br/br/converse.php>`_.
-
-- `Simple-Echo-Telegram-Bot <https://github.com/sooyhwang/Simple-Echo-Telegram-Bot>`_ simple Python Telegram bot that echoes your input with Flask microframework, setWebhook method, and Google App Engine (optional) - by @sooyhwang.
-
-- `DevOps Reaction Bot <https://github.com/leandrotoledo/gae-devops-reaction-telegram-bot>`_ sends latest or random posts from `DevOps Reaction <http://devopsreactions.tumblr.com/>`_. Running on `Google App Engine <https://cloud.google.com/appengine>`_ (billing has to be enabled for fully Socket API support).
-
-================
-_`Documentation`
-================
-
-``python-telegram-bot``'s documentation lives at `Read the Docs <http://python-telegram-bot.readthedocs.org/en/latest/>`_.
-
-==========
-_`License`
-==========
-
-You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <http://www.gnu.org/licenses/lgpl-3.0.html>`_. Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under `LGPL-3 <http://www.gnu.org/licenses/lgpl-3.0.html>`_, but applications that use the library don't have to be.
-
-==========
-_`Contact`
-==========
-
-Feel free to join to our `Telegram group <https://telegram.me/joinchat/00b9c0f802509b94d52953d3fa1ec504>`_.
-
-*If you face trouble joining in the group please ping me on Telegram (@leandrotoledo), I'll be glad to add you.*
+Contributions of all sizes are welcome. Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst>`_ to get started. You can also help by `reporting bugs <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
 
 =======
-_`TODO`
+License
 =======
 
-Patches and bug reports are `welcome <https://github.com/leandrotoledo/python-telegram-bot/issues/new>`_, just please keep the style consistent with the original source.
-
-- Add commands handler.
+You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_. Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under LGPL-3, but applications that use the library don't have to be.

docs/Makefile

@@ -189,4 +189,4 @@ xml:
 pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/source/conf.py

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

docs/source/index.rst

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

docs/source/modules.rst

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

docs/source/telegram.animation.rst

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

docs/source/telegram.bot.rst

@@ -3,5 +3,4 @@ telegram.bot module
 
 .. automodule:: telegram.bot
     :members:
-    :undoc-members:
     :show-inheritance:

docs/source/telegram.callbackgame.rst

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

docs/source/telegram.callbackquery.rst

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

docs/source/telegram.chat.rst

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

docs/source/telegram.chatmember.rst

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

docs/source/telegram.choseninlineresult.rst

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

docs/source/telegram.constants.rst

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

docs/source/telegram.contrib.botan.rst

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

docs/source/telegram.contrib.rst

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

docs/source/telegram.ext.callbackqueryhandler.rst

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

docs/source/telegram.ext.choseninlineresulthandler.rst

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

docs/source/telegram.ext.commandhandler.rst

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

docs/source/telegram.ext.conversationhandler.rst

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

docs/source/telegram.ext.dispatcher.rst

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

docs/source/telegram.ext.filters.rst

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

docs/source/telegram.ext.handler.rst

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

docs/source/telegram.ext.inlinequeryhandler.rst

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

docs/source/telegram.ext.jobqueue.rst

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

docs/source/telegram.ext.messagehandler.rst

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

docs/source/telegram.ext.messagequeue.rst

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

docs/source/telegram.ext.regexhandler.rst

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

docs/source/telegram.ext.rst

@@ -0,0 +1,32 @@
+telegram.ext package
+====================
+
+Submodules
+----------
+
+.. toctree::
+
+    telegram.ext.updater
+    telegram.ext.dispatcher
+    telegram.ext.jobqueue
+    telegram.ext.handler
+    telegram.ext.callbackqueryhandler
+    telegram.ext.choseninlineresulthandler
+    telegram.ext.conversationhandler
+    telegram.ext.commandhandler
+    telegram.ext.inlinequeryhandler
+    telegram.ext.messagehandler
+    telegram.ext.messagequeue
+    telegram.ext.filters
+    telegram.ext.regexhandler
+    telegram.ext.stringcommandhandler
+    telegram.ext.stringregexhandler
+    telegram.ext.typehandler
+
+Module contents
+---------------
+
+.. automodule:: telegram.ext
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/telegram.ext.stringcommandhandler.rst

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

docs/source/telegram.ext.stringregexhandler.rst

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

docs/source/telegram.ext.typehandler.rst

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

docs/source/telegram.ext.updater.rst

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

docs/source/telegram.file.rst

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

docs/source/telegram.game.rst

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

docs/source/telegram.gamehighscore.rst

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

docs/source/telegram.inlinekeyboardbutton.rst

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

docs/source/telegram.inlinekeyboardmarkup.rst

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

docs/source/telegram.inlinequery.rst

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

docs/source/telegram.inlinequeryresult.rst

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

docs/source/telegram.inlinequeryresultarticle.rst

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

docs/source/telegram.inlinequeryresultaudio.rst

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

docs/source/telegram.inlinequeryresultcachedaudio.rst

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

docs/source/telegram.inlinequeryresultcacheddocument.rst

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

docs/source/telegram.inlinequeryresultcachedgif.rst

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

docs/source/telegram.inlinequeryresultcachedmpeg4gif.rst

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

docs/source/telegram.inlinequeryresultcachedphoto.rst

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

docs/source/telegram.inlinequeryresultcachedsticker.rst

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

docs/source/telegram.inlinequeryresultcachedvideo.rst

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

docs/source/telegram.inlinequeryresultcachedvoice.rst

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

docs/source/telegram.inlinequeryresultcontact.rst

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

docs/source/telegram.inlinequeryresultdocument.rst

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

docs/source/telegram.inlinequeryresultgame.rst

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

docs/source/telegram.inlinequeryresultgif.rst

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

docs/source/telegram.inlinequeryresultlocation.rst

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

docs/source/telegram.inlinequeryresultmpeg4gif.rst

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

docs/source/telegram.inlinequeryresultphoto.rst

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

docs/source/telegram.inlinequeryresultvenue.rst

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

docs/source/telegram.inlinequeryresultvideo.rst

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

docs/source/telegram.inlinequeryresultvoice.rst

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

docs/source/telegram.inputcontactmessagecontent.rst

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

docs/source/telegram.inputlocationmessagecontent.rst

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

docs/source/telegram.inputmessagecontent.rst

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

docs/source/telegram.inputtextmessagecontent.rst

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

docs/source/telegram.inputvenuemessagecontent.rst

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

docs/source/telegram.keyboardbutton.rst

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

docs/source/telegram.messageentity.rst

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

docs/source/telegram.parsemode.rst

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

docs/source/telegram.replykeyboardremove.rst

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

docs/source/telegram.rst

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

docs/source/telegram.venue.rst

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

docs/source/telegram.webhookinfo.rst

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

examples/LICENSE.txt

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

examples/README.md

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

examples/conversationbot.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to reply to Telegram messages
+# This program is dedicated to the public domain under the CC0 license.
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few callback functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
+
+Usage:
+Example of a bot-user conversation using ConversationHandler.
+Send /start to initiate the conversation.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+from telegram import (ReplyKeyboardMarkup, ReplyKeyboardRemove)
+from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters, RegexHandler,
+                          ConversationHandler)
+
+import logging
+
+# Enable logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+GENDER, PHOTO, LOCATION, BIO = range(4)
+
+
+def start(bot, update):
+    reply_keyboard = [['Boy', 'Girl', 'Other']]
+
+    update.message.reply_text(
+        'Hi! My name is Professor Bot. I will hold a conversation with you. '
+        'Send /cancel to stop talking to me.\n\n'
+        'Are you a boy or a girl?',
+        reply_markup=ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True))
+
+    return GENDER
+
+
+def gender(bot, update):
+    user = update.message.from_user
+    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())
+
+    return PHOTO
+
+
+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'))
+    update.message.reply_text('Gorgeous! Now, send me your location please, '
+                              'or send /skip if you don\'t want to.')
+
+    return LOCATION
+
+
+def skip_photo(bot, update):
+    user = update.message.from_user
+    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.')
+
+    return LOCATION
+
+
+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))
+    update.message.reply_text('Maybe I can visit you sometime! '
+                              'At last, tell me something about yourself.')
+
+    return BIO
+
+
+def skip_location(bot, update):
+    user = update.message.from_user
+    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.')
+
+    return BIO
+
+
+def bio(bot, update):
+    user = update.message.from_user
+    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
+
+
+def cancel(bot, update):
+    user = update.message.from_user
+    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())
+
+    return ConversationHandler.END
+
+
+def error(bot, update, error):
+    logger.warn('Update "%s" caused error "%s"' % (update, error))
+
+
+def main():
+    # Create the EventHandler and pass it your bot's token.
+    updater = Updater("TOKEN")
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # Add conversation handler with the states GENDER, PHOTO, LOCATION and BIO
+    conv_handler = ConversationHandler(
+        entry_points=[CommandHandler('start', start)],
+
+        states={
+            GENDER: [RegexHandler('^(Boy|Girl|Other)$', gender)],
+
+            PHOTO: [MessageHandler(Filters.photo, photo),
+                    CommandHandler('skip', skip_photo)],
+
+            LOCATION: [MessageHandler(Filters.location, location),
+                       CommandHandler('skip', skip_location)],
+
+            BIO: [MessageHandler(Filters.text, bio)]
+        },
+
+        fallbacks=[CommandHandler('cancel', cancel)]
+    )
+
+    dp.add_handler(conv_handler)
+
+    # log all errors
+    dp.add_error_handler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Run the bot until you press Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()

examples/conversationbot2.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to reply to Telegram messages
+# This program is dedicated to the public domain under the CC0 license.
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few callback functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
+
+Usage:
+Example of a bot-user conversation using ConversationHandler.
+Send /start to initiate the conversation.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+from telegram import ReplyKeyboardMarkup
+from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters, RegexHandler,
+                          ConversationHandler)
+
+import logging
+
+# Enable logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+CHOOSING, TYPING_REPLY, TYPING_CHOICE = range(3)
+
+reply_keyboard = [['Age', 'Favourite colour'],
+                  ['Number of siblings', 'Something else...'],
+                  ['Done']]
+markup = ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True)
+
+
+def facts_to_str(user_data):
+    facts = list()
+
+    for key, value in user_data.items():
+        facts.append('%s - %s' % (key, value))
+
+    return "\n".join(facts).join(['\n', '\n'])
+
+
+def start(bot, update):
+    update.message.reply_text(
+        "Hi! My name is Doctor Botter. I will hold a more complex conversation with you. "
+        "Why don't you tell me something about yourself?",
+        reply_markup=markup)
+
+    return CHOOSING
+
+
+def regular_choice(bot, update, user_data):
+    text = update.message.text
+    user_data['choice'] = text
+    update.message.reply_text('Your %s? Yes, I would love to hear about that!' % text.lower())
+
+    return TYPING_REPLY
+
+
+def custom_choice(bot, update):
+    update.message.reply_text('Alright, please send me the category first, '
+                              'for example "Most impressive skill"')
+
+    return TYPING_CHOICE
+
+
+def received_information(bot, update, user_data):
+    text = update.message.text
+    category = user_data['choice']
+    user_data[category] = text
+    del user_data['choice']
+
+    update.message.reply_text("Neat! Just so you know, this is what you already told me:"
+                              "%s"
+                              "You can tell me more, or change your opinion on something."
+                              % facts_to_str(user_data),
+                              reply_markup=markup)
+
+    return CHOOSING
+
+
+def done(bot, update, user_data):
+    if 'choice' in user_data:
+        del user_data['choice']
+
+    update.message.reply_text("I learned these facts about you:"
+                              "%s"
+                              "Until next time!" % facts_to_str(user_data))
+
+    user_data.clear()
+    return ConversationHandler.END
+
+
+def error(bot, update, error):
+    logger.warn('Update "%s" caused error "%s"' % (update, error))
+
+
+def main():
+    # Create the Updater and pass it your bot's token.
+    updater = Updater("TOKEN")
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # Add conversation handler with the states GENDER, PHOTO, LOCATION and BIO
+    conv_handler = ConversationHandler(
+        entry_points=[CommandHandler('start', start)],
+
+        states={
+            CHOOSING: [RegexHandler('^(Age|Favourite colour|Number of siblings)$',
+                                    regular_choice,
+                                    pass_user_data=True),
+                       RegexHandler('^Something else...$',
+                                    custom_choice),
+                       ],
+
+            TYPING_CHOICE: [MessageHandler(Filters.text,
+                                           regular_choice,
+                                           pass_user_data=True),
+                            ],
+
+            TYPING_REPLY: [MessageHandler(Filters.text,
+                                          received_information,
+                                          pass_user_data=True),
+                           ],
+        },
+
+        fallbacks=[RegexHandler('^Done$', done, pass_user_data=True)]
+    )
+
+    dp.add_handler(conv_handler)
+
+    # log all errors
+    dp.add_error_handler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Run the bot until you press Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()

examples/echobot.py

@@ -1,65 +1,50 @@
 #!/usr/bin/env python
+# -*- coding: utf-8 -*-
 #
-# Simple Bot to reply Telegram messages
-# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see [http://www.gnu.org/licenses/].
-
-
+# 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
+from time import sleep
 
 
-LAST_UPDATE_ID = None
-
+update_id = None
 
 def main():
-    global LAST_UPDATE_ID
-
-    logging.basicConfig(
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-
+    global update_id
     # Telegram Bot Authorization Token
     bot = telegram.Bot('TOKEN')
 
-    # This will be our global variable to keep the latest update_id when requesting
-    # for updates. It starts with the latest update_id if available.
+    # get the first pending update_id, this is so we can skip over it in case
+    # we get an "Unauthorized" exception.
     try:
-        LAST_UPDATE_ID = bot.getUpdates()[-1].update_id
+        update_id = bot.get_updates()[0].update_id
     except IndexError:
-        LAST_UPDATE_ID = None
+        update_id = None
+
+    logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
 
     while True:
-        echo(bot)
+        try:
+            echo(bot)
+        except NetworkError:
+            sleep(1)
+        except Unauthorized:
+            # The user has removed or blocked the bot.
+            update_id += 1
 
 
 def echo(bot):
-    global LAST_UPDATE_ID
+    global update_id
+    # Request updates after the last update_id
+    for update in bot.get_updates(offset=update_id, timeout=10):
+        update_id = update.update_id + 1
 
-    # Request updates after the last updated_id
-    for update in bot.getUpdates(offset=LAST_UPDATE_ID, timeout=10):
-        # chat_id is required to reply any message
-        chat_id = update.message.chat_id
-        message = update.message.text.encode('utf-8')
-
-        if (message):
-            # Reply the message
-            bot.sendMessage(chat_id=chat_id,
-                            text=message)
-
-            # Updates global offset to get the new updates
-            LAST_UPDATE_ID = update.update_id + 1
+        if update.message:  # your bot can receive updates without messages
+            # Reply to the message
+            update.message.reply_text(update.message.text)
 
 
 if __name__ == '__main__':

examples/echobot2.py

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

examples/inlinebot.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to reply to Telegram messages
+# This program is dedicated to the public domain under the CC0 license.
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few handler functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
+
+Usage:
+Basic inline bot example. Applies different text transformations.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+from uuid import uuid4
+
+import re
+
+from telegram import InlineQueryResultArticle, ParseMode, \
+    InputTextMessageContent
+from telegram.ext import Updater, InlineQueryHandler, CommandHandler
+import logging
+
+# Enable logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+
+# Define a few command handlers. These usually take the two arguments bot and
+# update. Error handlers also receive the raised TelegramError object in error.
+def start(bot, update):
+    update.message.reply_text('Hi!')
+
+
+def help(bot, update):
+    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):
+    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)))
+
+    update.inline_query.answer(results)
+
+
+def error(bot, update, error):
+    logger.warning('Update "%s" caused error "%s"' % (update, error))
+
+
+def main():
+    # Create the Updater and pass it your bot's token.
+    updater = Updater("TOKEN")
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # on different commands - answer in Telegram
+    dp.add_handler(CommandHandler("start", start))
+    dp.add_handler(CommandHandler("help", help))
+
+    # on noncommand i.e message - echo the message on Telegram
+    dp.add_handler(InlineQueryHandler(inlinequery))
+
+    # log all errors
+    dp.add_error_handler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Block until the user presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()

examples/inlinekeyboard.py

@@ -0,0 +1,55 @@
+#!/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.
+
+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)
+
+
+def start(bot, update):
+    keyboard = [[InlineKeyboardButton("Option 1", callback_data='1'),
+                 InlineKeyboardButton("Option 2", callback_data='2')],
+
+                [InlineKeyboardButton("Option 3", callback_data='3')]]
+
+    reply_markup = InlineKeyboardMarkup(keyboard)
+
+    update.message.reply_text('Please choose:', reply_markup=reply_markup)
+
+
+def button(bot, update):
+    query = update.callback_query
+
+    bot.edit_message_text(text="Selected option: %s" % query.data,
+                          chat_id=query.message.chat_id,
+                          message_id=query.message.message_id)
+
+
+def help(bot, update):
+    update.message.reply_text("Use /start to test this bot.")
+
+
+def error(bot, update, error):
+    logging.warning('Update "%s" caused error "%s"' % (update, error))
+
+
+# Create the Updater and pass it your bot's token.
+updater = Updater("TOKEN")
+
+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()
+
+# Run the bot until the user presses Ctrl-C or the process receives SIGINT,
+# SIGTERM or SIGABRT
+updater.idle()

examples/roboed.py

@@ -1,54 +0,0 @@
-#!/usr/bin/env python
-# encoding: utf-8
-#
-# Robô Ed Telegram Bot
-# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see [http://www.gnu.org/licenses/].
-
-
-__author__ = 'leandrotoledodesouza@gmail.com'
-
-import logging
-import telegram
-import urllib
-
-
-def main():
-    logging.basicConfig(
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-    bot = telegram.Bot('TOKEN')  # Telegram Bot Authorization Token
-
-    LAST_UPDATE_ID = bot.getUpdates()[-1].update_id  # Get lastest update
-
-    while True:
-        for update in bot.getUpdates(offset=LAST_UPDATE_ID, timeout=10):
-            text = update.message.text
-            chat_id = update.message.chat.id
-            update_id = update.update_id
-
-            if text:
-                roboed = ed(text)  # Ask something to Robô Ed
-                bot.sendMessage(chat_id=chat_id, text=roboed)
-                LAST_UPDATE_ID = update_id + 1
-
-
-def ed(text):
-    url = 'http://www.ed.conpet.gov.br/mod_perl/bot_gateway.cgi?server=0.0.0.0%3A8085&charset_post=utf-8&charset=utf-8&pure=1&js=0&tst=1&msg=' + text
-    data = urllib.urlopen(url).read()
-
-    return data.strip()
-
-if __name__ == '__main__':
-    main()

examples/timerbot.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to send timed Telegram messages
+# This program is dedicated to the public domain under the CC0 license.
+"""
+This Bot uses the Updater class to handle the bot and the JobQueue to send
+timed messages.
+
+First, a few handler functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
+
+Usage:
+Basic Alarm Bot example, sends a message after a set time.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+from telegram.ext import Updater, CommandHandler, Job
+import logging
+
+# Enable logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+
+# Define a few command handlers. These usually take the two arguments bot and
+# update. Error handlers also receive the raised TelegramError object in error.
+def start(bot, update):
+    update.message.reply_text('Hi! Use /set <seconds> to set a timer')
+
+
+def alarm(bot, job):
+    """Function to 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"""
+    chat_id = update.message.chat_id
+    try:
+        # args[0] should contain the time for the timer in seconds
+        due = int(args[0])
+        if due < 0:
+            update.message.reply_text('Sorry we can not go back to future!')
+            return
+
+        # Add job to queue
+        job = job_queue.run_once(alarm, due, context=chat_id)
+        chat_data['job'] = job
+
+        update.message.reply_text('Timer successfully set!')
+
+    except (IndexError, ValueError):
+        update.message.reply_text('Usage: /set <seconds>')
+
+
+def unset(bot, update, chat_data):
+    """Removes the job if the user changed their mind"""
+
+    if 'job' not in chat_data:
+        update.message.reply_text('You have no active timer')
+        return
+
+    job = chat_data['job']
+    job.schedule_removal()
+    del chat_data['job']
+
+    update.message.reply_text('Timer successfully unset!')
+
+
+def error(bot, update, error):
+    logger.warning('Update "%s" caused error "%s"' % (update, error))
+
+
+def main():
+    updater = Updater("TOKEN")
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # on different commands - answer in Telegram
+    dp.add_handler(CommandHandler("start", start))
+    dp.add_handler(CommandHandler("help", start))
+    dp.add_handler(CommandHandler("set", set,
+                                  pass_args=True,
+                                  pass_job_queue=True,
+                                  pass_chat_data=True))
+    dp.add_handler(CommandHandler("unset", unset, pass_chat_data=True))
+
+    # log all errors
+    dp.add_error_handler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Block until you press Ctrl-C or the process receives SIGINT, SIGTERM or
+    # SIGABRT. This should be used most of the time, since start_polling() is
+    # non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()

requirements-dev.txt

@@ -0,0 +1,8 @@
+flake8
+nose
+pep257
+pylint
+flaky
+yapf
+pre-commit
+pre-commit-hooks

requirements.txt

@@ -0,0 +1,2 @@
+future>=0.15.2
+certifi