Bump version to v5.3.0

* Add "reply" filter

This filter will filter messages that reply to other's message.

* Add test for "reply" filter

* Add "Kjwon15" to AUTHORS.rst

.github/CONTRIBUTING.rst

@@ -0,0 +1,201 @@
+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
+
+   - 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='', **kwargs):
+       self.last_name = last_name
+
+    # BAD
+    def __init__(self, id, name, last_name=''):
+       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

@@ -61,3 +61,16 @@ target/
 
 # 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

.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,17 +1,21 @@
 language: python
 python:
-  - "2.6"
   - "2.7"
   - "3.3"
   - "3.4"
+  - "3.5"
   - "pypy"
   - "pypy3"
+branches:
+  only:
+    - master
 install:
-  - pip install pylint flake8 coveralls
+  - pip install coveralls
   - pip install -r requirements.txt
+  - pip install -r requirements-dev.txt
+  - if [[ $TRAVIS_PYTHON_VERSION != 'pypy'* ]]; then pip install ujson; fi
 script:
-  - nosetests --with-coverage --cover-package telegram/
-  - flake8 telegram
-  - 'if [[ $TRAVIS_PYTHON_VERSION != 2.6 ]]; then pylint -E telegram --disable=no-name-in-module,import-error; fi'
+  - nosetests -v --with-flaky --no-flaky-report --with-coverage --cover-package=telegram/
+  - if [[ $TRAVIS_PYTHON_VERSION == 3.5 ]]; then pre-commit run --all-files; fi
 after_success:
   coveralls

AUTHORS.rst

@@ -11,16 +11,30 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Avanatiker <https://github.com/Avanatiker>`_
 - `Balduro <https://github.com/Balduro>`_
 - `bimmlerd <https://github.com/bimmlerd>`_
+- `Eli Gao <https://github.com/eligao>`_
 - `ErgoZ Riftbit Vaper <https://github.com/ergoz>`_
+- `Eugene Lisitsky <https://github.com/lisitsky>`_
 - `franciscod <https://github.com/franciscod>`_
+- `Jacob Bom <https://github.com/bomjacob>`_
 - `JASON0916 <https://github.com/JASON0916>`_
 - `jh0ker <https://github.com/jh0ker>`_
 - `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>`_
 - `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>`_
 - `Rahiel Kasim <https://github.com/rahiel>`_
+- `Shelomentsev D <https://github.com/shelomentsevd>`_
 - `sooyhwang <https://github.com/sooyhwang>`_
+- `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,3 +1,204 @@
+=======
+Changes
+=======
+
+**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*

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/python-telegram-bot/python-telegram-bot/blob/master/CHANGES
-.. _AUTHORS.rst: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/AUTHORS.rst

Makefile

@@ -1,4 +1,12 @@
-.PHONY: clean pep8 lint test install
+.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,22 +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:
-	nosetests
+	$(NOSETESTS) -v
 
 install:
-	pip install -r requirements.txt
+	$(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,26 +1,26 @@
 .. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-logo-text_768.png?raw=true
    :align: center
-   :target: https://github.com/python-telegram-bot/logos
+   :target: https://python-telegram-bot.org
    :alt: python-telegram-bot Logo
 
-A Python wrapper around the Telegram Bot API.
+We have made you a wrapper you can't refuse
 
-*Stay tuned for library updates and new releases on our* `Telegram Channel <http://telegram.me/pythontelegrambotchannel>`_.
+*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
+   :alt: Supported python versions
 
-.. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=latest
-   :target: https://readthedocs.org/projects/python-telegram-bot/?badge=latest
+.. 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/pypi/l/python-telegram-bot.svg
-   :target: http://www.gnu.org/licenses/lgpl-3.0.html
+   :target: https://www.gnu.org/licenses/lgpl-3.0.html
    :alt: LGPLv3 License
 
 .. image:: https://travis-ci.org/python-telegram-bot/python-telegram-bot.svg?branch=master
@@ -34,6 +34,14 @@ A Python wrapper around the Telegram Bot API.
 .. 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
@@ -41,313 +49,144 @@ Table of contents
 
 - `Introduction`_
 
-- `Status`_
-
-  1. `Telegram API support`_
-
-  2. `Python Version support`_
+- `Telegram API support`_
 
 - `Installing`_
 
-- `Getting the code`_
-
 - `Getting started`_
 
-  1. `The Updater class`_
-  
-  2. `API`_
-  
-  3. `Logging`_
+  #. `Learning by example`_
 
-  4. `Examples`_
+  #. `Logging`_
 
-  5. `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 **3. Oct 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
-getFile                   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
-PyPy           Yes
-PyPy3          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/python-telegram-bot/python-telegram-bot
-
-Check out the latest development version anonymously with::
+.. code:: shell
 
     $ git clone https://github.com/python-telegram-bot/python-telegram-bot
     $ cd python-telegram-bot
+    $ python setup.py install
 
-Run tests:
+===============
+Getting started
+===============
 
-    $ make test
+Our Wiki contains a lot of resources to get you started with ``python-telegram-bot``:
 
-To see other options available, run:
+- `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>`_
 
-    $ make help
+Other references:
 
-==================
-_`Getting started`
-==================
+- `Telegram API documentation <https://core.telegram.org/bots/api>`_
+- `python-telegram-bot documentation <https://python-telegram-bot.readthedocs.io/>`_
 
-View the last release API documentation at: https://core.telegram.org/bots/api
+-------------------
+Learning by example
+-------------------
 
-------
-_`The Updater class`
-------
+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.
 
-The ``Updater`` class is the new way to create bots with ``python-telegram-bot``. It provides an easy-to-use interface to the ``telegram.Bot`` by caring about getting new updates from telegram and forwarding them to the ``Dispatcher`` class. We can register handler functions in the ``Dispatcher`` to make our bot react to Telegram commands, messages and even arbitrary updates.
+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.
 
-As with the old method, we'll need an Access Token. To generate an Access Token, we have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#botfather>`_).
+-------
+Logging
+-------
 
-First, we create an ``Updater`` object::
+This library uses the ``logging`` module. To set up logging to standard output, put:
 
-   >>> from telegram import Updater
-   >>> updater = Updater(token='token')
+.. code:: python
 
-For quicker access to the ``Dispatcher`` used by our ``Updater``, we can introduce it locally::
+    import logging
+    logging.basicConfig(level=logging.DEBUG,
+                        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
 
-   >>> dispatcher = updater.dispatcher
+at the beginning of your script.
 
-Now, we need to define a function that should process a specific type of update::
+You can also use logs in your application by calling ``logging.getLogger()`` and setting the log level you want:
 
-   >>> def start(bot, update):
-   ...   bot.sendMessage(chat_id=update.message.chat_id, text="I'm a bot, please talk to me!")
+.. code:: python
 
-We want this function to be called on a Telegram message that contains the ``/start`` command, so we need to register it in the dispatcher::
+    logger = logging.getLogger()
+    logger.setLevel(logging.INFO)
 
-   >>> dispatcher.addTelegramCommandHandler('start', start)
-   
-The last step is to tell the ``Updater`` to start working::
+If you want DEBUG logs instead:
 
-   >>> updater.start_polling()
+.. code:: python
 
-Our bot is now up and running (go ahead and try it)! It's not doing anything yet, besides answering to the ``/start`` command. Let's add another handler function and register it::
+    logger.setLevel(logging.DEBUG)
 
-   >>> def echo(bot, update):
-   ...   bot.sendMessage(chat_id=update.message.chat_id, text=update.message.text)
-   ...
-   >>> dispatcher.addTelegramMessageHandler(echo)
 
-Our bot should now reply to all messages that are not a command with a message that has the same content.
+=============
+Documentation
+=============
 
-People might try to send commands to the bot that it doesn't understand, so we should get that covered as well::
+``python-telegram-bot``'s documentation lives at `readthedocs.io <https://python-telegram-bot.readthedocs.io/>`_.
 
-   >>> def unknown(bot, update):
-   ...   bot.sendMessage(chat_id=update.message.chat_id, text="Sorry, I didn't understand that command.")
-   ...
-   >>> dispatcher.addUnknownTelegramCommandHandler(unknown)
+============
+Getting help
+============
 
-Let's add some functionality to our bot. We want to add the ``/caps`` command, that will take some text as parameter and return it in all caps. We can get the arguments that were passed to the command in the handler function simply by adding it to the parameter list::
+You can get help in several ways:
 
-   >>> def caps(bot, update, args):
-   ...   text_caps = ' '.join(args).upper()
-   ...   bot.sendMessage(chat_id=update.message.chat_id, text=text_caps)
-   ... 
-   >>> dispatcher.addTelegramCommandHandler('caps', caps)
+1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
 
-Now it's time to stop the bot::
+2. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources.
 
-   >>> updater.stop()
+3. You can ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
 
-Check out more examples in the `examples folder <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples>`_!
+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>`_.
 
-------
-_`API`
-------
 
-Note: Using the ``Bot`` class directly is the 'old' method, but some of this is still important information, even if you're using the ``Updater`` class!
+============
+Contributing
+============
 
-The API is exposed via the ``telegram.Bot`` class.
-
-To generate an Access Token you have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#botfather>`_).
-
-For full details see the `Bots: An introduction for developers <https://core.telegram.org/bots>`_.
-
-To create an instance of the ``telegram.Bot``::
-
-    >>> import telegram
-    >>> bot = telegram.Bot(token='token')
-
-To see if your credentials are successful::
-
-    >>> print bot.getMe()
-    {"first_name": "Toledo's Palace Bot", "username": "ToledosPalaceBot"}
-
-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.
-
-To fetch text messages sent to your Bot::
-
-    >>> updates = bot.getUpdates()
-    >>> print [u.message.text for u in updates]
-
-To fetch images sent to your Bot::
-
-    >>> updates = bot.getUpdates()
-    >>> print [u.message.photo for u in updates if u.message.photo]
-
-To reply messages you'll always need the chat_id::
-
-    >>> chat_id = bot.getUpdates()[-1].message.chat_id
-
-To post a text message::
-
-    >>> bot.sendMessage(chat_id=chat_id, text="I'm sorry Dave I'm afraid I can't do that.")
-
-To post a text message with markdown::
-
-    >>> bot.sendMessage(chat_id=chat_id, text="*bold* _italic_ [link](http://google.com).", parse_mode=telegram.ParseMode.MARKDOWN)
-
-To post an Emoji (special thanks to `Tim Whitlock <http://apps.timwhitlock.info/emoji/tables/unicode>`_)::
-
-    >>> bot.sendMessage(chat_id=chat_id, text=telegram.Emoji.PILE_OF_POO)
-
-To post an image file via URL (right now only sendPhoto supports this)::
-
-    >>> bot.sendPhoto(chat_id=chat_id, photo='https://telegram.org/img/t_logo.png')
-
-To post a voice file::
-
-    >>> bot.sendVoice(chat_id=chat_id, voice=open('tests/telegram.ogg', 'rb'))
-
-To tell the user that something is happening on bot's side::
-
-    >>> bot.sendChatAction(chat_id=chat_id, action=telegram.ChatAction.TYPING)
-
-To create `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_::
-
-    >>> 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)
-
-To download a file (you will need its file_id)::
-
-    >>> file_id = message.voice.file_id
-    >>> newFile = bot.getFile(file_id)
-    >>> newFile.download('voice.ogg')
-
-There are many more API methods, to read the full API documentation::
-
-    $ pydoc telegram.Bot
-
------------
-_`Logging`
------------
-
-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/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot.py>`_ replies back messages.
-
-- `roboed <https://github.com/python-telegram-bot/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).
-
-- `TwitterForwarderBot <https://github.com/franciscod/telegram-twitter-forwarder-bot>`_ forwards you tweets from people that you have subscribed to.
-
-================
-_`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/ALnA-AJQm5R7Km9hdCgyng>`_.
+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/python-telegram-bot/python-telegram-bot/issues/new>`_, just please keep the style consistent with the original source.
+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-2016, 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 = '3.1'
+version = '5.3'  # telegram.__version__[:3]
 # The full version, including alpha/beta/rc tags.
-release = '3.1.0'
+release = '5.3.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.updater module
+telegram.animation module
 =========================
 
-.. automodule:: telegram.updater
+.. 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.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

@@ -1,7 +1,7 @@
-telegram.dispatcher module
+telegram.constants module
 =========================
 
-.. automodule:: telegram.dispatcher
+.. 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.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,31 @@
+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.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,32 +6,73 @@ Submodules
 
 .. toctree::
 
+   telegram.contrib
+   telegram.ext
+   telegram.animation
    telegram.audio
    telegram.base
    telegram.bot
-   telegram.updater
-   telegram.dispatcher
+   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.chat
+   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.getFile(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 the you presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()

examples/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 the you presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()

examples/echobot.py

@@ -1,34 +1,19 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-# Simple Bot to reply to 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
 
-try:
-    from urllib.error import URLError
-except ImportError:
-    from urllib2 import URLError  # python 2
 
+update_id = None
 
 def main():
+    global update_id
     # Telegram Bot Authorization Token
     bot = telegram.Bot('TOKEN')
 
@@ -39,41 +24,29 @@ def main():
     except IndexError:
         update_id = None
 
-    logging.basicConfig(
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
 
     while True:
         try:
-            update_id = echo(bot, update_id)
-        except telegram.TelegramError as e:
-            # These are network problems with Telegram.
-            if e.message in ("Bad Gateway", "Timed out"):
-                sleep(1)
-            elif e.message == "Unauthorized":
-                # The user has removed or blocked the bot.
-                update_id += 1
-            else:
-                raise e
-        except URLError as e:
-            # These are network problems on our end.
+            echo(bot)
+        except NetworkError:
             sleep(1)
+        except Unauthorized:
+            # The user has removed or blocked the bot.
+            update_id += 1
 
 
-def echo(bot, update_id):
-
+def echo(bot):
+    global update_id
     # Request updates after the last update_id
     for update in bot.getUpdates(offset=update_id, timeout=10):
         # chat_id is required to reply to any message
         chat_id = update.message.chat_id
         update_id = update.update_id + 1
-        message = update.message.text
 
-        if message:
+        if update.message:  # your bot can receive updates without messages
             # Reply to the message
-            bot.sendMessage(chat_id=chat_id,
-                            text=message)
-
-    return update_id
+            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 the you presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()

examples/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.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
+
+    # 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.editMessageText(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.DEBUG)
+
+logger = logging.getLogger(__name__)
+timers = dict()
+
+
+# Define a few command handlers. These usually take the two arguments bot and
+# update. Error handlers also receive the raised TelegramError object in error.
+def start(bot, update):
+    update.message.reply_text('Hi! Use /set <seconds> to set a timer')
+
+
+def alarm(bot, job):
+    """Function to send the alarm message"""
+    bot.sendMessage(job.context, text='Beep!')
+
+
+def set(bot, update, args, job_queue):
+    """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(alarm, due, repeat=False, context=chat_id)
+        timers[chat_id] = job
+        job_queue.put(job)
+
+        update.message.reply_text('Timer successfully set!')
+
+    except (IndexError, ValueError):
+        update.message.reply_text('Usage: /set <seconds>')
+
+
+def unset(bot, update):
+    """Removes the job if the user changed their mind"""
+    chat_id = update.message.chat_id
+
+    if chat_id not in timers:
+        update.message.reply_text('You have no active timer')
+        return
+
+    job = timers[chat_id]
+    job.schedule_removal()
+    del timers[chat_id]
+
+    update.message.reply_text('Timer successfully unset!')
+
+
+def error(bot, update, error):
+    logger.warn('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))
+    dp.add_handler(CommandHandler("unset", unset))
+
+    # log all errors
+    dp.add_error_handler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Block until the you presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()

examples/updater_bot.py

@@ -1,165 +0,0 @@
-#!/usr/bin/env python
-
-"""
-This Bot uses the Updater class to handle the bot.
-
-First, a few handler functions are defined. Then, those functions are passed to
-the Dispatcher and registered at their respective places.
-Then, the bot is started and the CLI-Loop is entered, where all text inputs are
-inserted into the update queue for the bot to handle.
-
-Usage:
-Basic Echobot example, repeats messages. Reply to last chat from the command
-line by typing "/reply <text>"
-Type 'stop' on the command line to stop the bot.
-"""
-
-from telegram import Updater
-from telegram.dispatcher import run_async
-from time import sleep
-import logging
-import sys
-
-root = logging.getLogger()
-root.setLevel(logging.INFO)
-
-ch = logging.StreamHandler(sys.stdout)
-ch.setLevel(logging.INFO)
-formatter = \
-    logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-ch.setFormatter(formatter)
-root.addHandler(ch)
-
-last_chat_id = 0
-
-logger = logging.getLogger(__name__)
-
-
-# Command Handlers
-def start(bot, update):
-    """ Answer in Telegram """
-    bot.sendMessage(update.message.chat_id, text='Hi!')
-
-
-def help(bot, update):
-    """ Answer in Telegram """
-    bot.sendMessage(update.message.chat_id, text='Help!')
-
-
-def any_message(bot, update):
-    """ Print to console """
-
-    # Save last chat_id to use in reply handler
-    global last_chat_id
-    last_chat_id = update.message.chat_id
-
-    logger.info("New message\nFrom: %s\nchat_id: %d\nText: %s" %
-                (update.message.from_user,
-                 update.message.chat_id,
-                 update.message.text))
-
-
-def unknown_command(bot, update):
-    """ Answer in Telegram """
-    bot.sendMessage(update.message.chat_id, text='Command not recognized!')
-
-
-@run_async
-def message(bot, update):
-    """
-    Example for an asynchronous handler. It's not guaranteed that replies will
-    be in order when using @run_async.
-    """
-
-    sleep(2)  # IO-heavy operation here
-    bot.sendMessage(update.message.chat_id, text='Echo: %s' %
-                                                 update.message.text)
-
-
-def error(bot, update, error):
-    """ Print error to console """
-    logger.warn('Update %s caused error %s' % (update, error))
-
-
-def cli_reply(bot, update, args):
-    """
-    For any update of type telegram.Update or str, you can get the argument
-    list by appending args to the function parameters.
-    Here, we reply to the last active chat with the text after the command.
-    """
-    if last_chat_id is not 0:
-        bot.sendMessage(chat_id=last_chat_id, text=' '.join(args))
-
-
-def cli_noncommand(bot, update, update_queue):
-    """
-    You can also get the update queue as an argument in any handler by
-    appending it to the argument list. Be careful with this though.
-    Here, we put the input string back into the queue, but as a command.
-    """
-    update_queue.put('/%s' % update)
-
-
-def unknown_cli_command(bot, update):
-    logger.warn("Command not found: %s" % update)
-
-
-def main():
-    # Create the EventHandler and pass it your bot's token.
-    token = 'token'
-    updater = Updater(token, workers=2)
-
-    # Get the dispatcher to register handlers
-    dp = updater.dispatcher
-
-    dp.addTelegramCommandHandler("start", start)
-    dp.addTelegramCommandHandler("help", help)
-    dp.addUnknownTelegramCommandHandler(unknown_command)
-    dp.addTelegramMessageHandler(message)
-    dp.addTelegramRegexHandler('.*', any_message)
-
-    dp.addStringCommandHandler('reply', cli_reply)
-    dp.addUnknownStringCommandHandler(unknown_cli_command)
-    dp.addStringRegexHandler('[^/].*', cli_noncommand)
-
-    dp.addErrorHandler(error)
-
-    # Start the Bot and store the update Queue, so we can insert updates
-    update_queue = updater.start_polling(poll_interval=0.1, timeout=20)
-
-    '''
-    # Alternatively, run with webhook:
-    updater.bot.setWebhook(webhook_url='https://example.com/%s' % token,
-                           certificate=open('cert.pem', 'rb'))
-
-    update_queue = updater.start_webhook('0.0.0.0',
-                                         443,
-                                         url_path=token,
-                                         cert='cert.pem',
-                                         key='key.key')
-
-    # Or, if SSL is handled by a reverse proxy, the webhook URL is already set
-    # and the reverse proxy is configured to deliver directly to port 6000:
-
-    update_queue = updater.start_webhook('0.0.0.0',
-                                         6000)
-    '''
-
-    # Start CLI-Loop
-    while True:
-        try:
-            text = raw_input()
-        except NameError:
-            text = input()
-
-        # Gracefully stop the event handler
-        if text == 'stop':
-            updater.stop()
-            break
-
-        # else, put the text into the update queue
-        elif len(text) > 0:
-            update_queue.put(text)  # Put command into queue
-
-if __name__ == '__main__':
-    main()

examples/updater_simplebot.py

@@ -1,75 +0,0 @@
-#!/usr/bin/env python
-
-"""
-This Bot uses the Updater class to handle the bot.
-
-First, a few handler functions are defined. Then, those functions are passed to
-the Dispatcher and registered at their respective places.
-Then, the bot is started and the CLI-Loop is entered.
-
-Usage:
-Basic Echobot example, repeats messages.
-Type 'stop' on the command line to stop the bot.
-"""
-
-from telegram import Updater
-import logging
-import sys
-
-# Enable logging
-root = logging.getLogger()
-root.setLevel(logging.INFO)
-
-ch = logging.StreamHandler(sys.stdout)
-ch.setLevel(logging.DEBUG)
-formatter = \
-    logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-ch.setFormatter(formatter)
-root.addHandler(ch)
-
-logger = logging.getLogger(__name__)
-
-
-# Command Handlers
-def start(bot, update):
-    bot.sendMessage(update.message.chat_id, text='Hi!')
-
-
-def help(bot, update):
-    bot.sendMessage(update.message.chat_id, text='Help!')
-
-
-def echo(bot, update):
-    bot.sendMessage(update.message.chat_id, text=update.message.text)
-
-
-def error(bot, update, error):
-    logger.warn('Update "%s" caused error "%s"' % (update, error))
-
-
-def main():
-    # Create the EventHandler and pass it your bot's token.
-    updater = Updater("TOKEN")
-
-    # Get the dispatcher to register handlers
-    dp = updater.dispatcher
-
-    # on different commands - answer in Telegram
-    dp.addTelegramCommandHandler("start", start)
-    dp.addTelegramCommandHandler("help", help)
-
-    # on noncommand i.e message - echo the message on Telegram
-    dp.addTelegramMessageHandler(echo)
-
-    # on error - print error to stdout
-    dp.addErrorHandler(error)
-
-    # Start the Bot
-    updater.start_polling(timeout=5)
-
-    # Run the bot until the user presses Ctrl-C or the process receives SIGINT,
-    # SIGTERM or SIGABRT
-    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

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

setup.cfg

@@ -8,3 +8,12 @@ all_files  = 1
 
 [upload_sphinx]
 upload-dir = docs/build/html
+
+[flake8]
+max-line-length = 99
+ignore = W503
+
+[yapf]
+based_on_style = google
+split_before_logical_operator = True
+column_limit = 99

setup.py

@@ -1,18 +1,11 @@
 #!/usr/bin/env python
+"""The setup and build script for the python-telegram-bot library."""
 
-'''The setup and build script for the python-telegram-bot library.'''
-
+import codecs
 import os
-
 from setuptools import setup, find_packages
 
 
-def read(*paths):
-    """Build a file path from *paths* and return the contents."""
-    with open(os.path.join(*paths), 'r') as f:
-        return f.read()
-
-
 def requirements():
     """Build the requirements list for this project"""
     requirements_list = []
@@ -24,34 +17,40 @@ def requirements():
     return requirements_list
 
 
-setup(
-    name='python-telegram-bot',
-    version='3.1.0',
-    author='Leandro Toledo',
-    author_email='leandrotoledodesouza@gmail.com',
-    license='LGPLv3',
-    url='https://github.com/python-telegram-bot/python-telegram-bot',
-    keywords='python telegram bot api wrapper',
-    description='A Python wrapper around the Telegram Bot API',
-    long_description=(read('README.rst')),
-    packages=find_packages(exclude=['tests*']),
-    install_requires=requirements(),
-    include_package_data=True,
-    classifiers=[
-        'Development Status :: 5 - Production/Stable',
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)',
-        'Operating System :: OS Independent',
-        'Topic :: Software Development :: Libraries :: Python Modules',
-        'Topic :: Communications :: Chat',
-        'Topic :: Internet',
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 2',
-        'Programming Language :: Python :: 2.6',
-        'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.2',
-        'Programming Language :: Python :: 3.3',
-        'Programming Language :: Python :: 3.4',
-    ],
-)
+with codecs.open('README.rst', 'r', 'utf-8') as fd:
+    fn = os.path.join('telegram', 'version.py')
+    with open(fn) as fh:
+        code = compile(fh.read(), fn, 'exec')
+        exec(code)
+
+    setup(name='python-telegram-bot',
+          version=__version__,
+          author='Leandro Toledo',
+          author_email='devs@python-telegram-bot.org',
+          license='LGPLv3',
+          url='https://python-telegram-bot.org/',
+          keywords='python telegram bot api wrapper',
+          description="We have made you a wrapper you can't refuse",
+          long_description=fd.read(),
+          packages=find_packages(exclude=['tests*']),
+          install_requires=requirements(),
+          extras_require={
+              'json': 'ujson',
+          },
+          include_package_data=True,
+          classifiers=[
+              'Development Status :: 5 - Production/Stable',
+              'Intended Audience :: Developers',
+              'License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)',
+              'Operating System :: OS Independent',
+              'Topic :: Software Development :: Libraries :: Python Modules',
+              'Topic :: Communications :: Chat',
+              'Topic :: Internet',
+              'Programming Language :: Python',
+              'Programming Language :: Python :: 2',
+              'Programming Language :: Python :: 2.7',
+              'Programming Language :: Python :: 3',
+              'Programming Language :: Python :: 3.3',
+              'Programming Language :: Python :: 3.4',
+              'Programming Language :: Python :: 3.5',
+          ],)

telegram/__init__.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser Public License as published by
@@ -15,15 +16,14 @@
 #
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
-
 """A library that provides a Python interface to the Telegram Bot API"""
 
-__author__ = 'leandrotoledodesouza@gmail.com'
-__version__ = '3.1.0'
+from sys import version_info
 
 from .base import TelegramObject
 from .user import User
 from .chat import Chat
+from .chatmember import ChatMember
 from .photosize import PhotoSize
 from .audio import Audio
 from .voice import Voice
@@ -32,27 +32,84 @@ from .sticker import Sticker
 from .video import Video
 from .contact import Contact
 from .location import Location
+from .venue import Venue
 from .chataction import ChatAction
 from .userprofilephotos import UserProfilePhotos
+from .keyboardbutton import KeyboardButton
 from .replymarkup import ReplyMarkup
 from .replykeyboardmarkup import ReplyKeyboardMarkup
-from .replykeyboardhide import ReplyKeyboardHide
+from .replykeyboardremove import ReplyKeyboardRemove, ReplyKeyboardHide
 from .forcereply import ForceReply
 from .error import TelegramError
 from .inputfile import InputFile
 from .file import File
-from .nullhandler import NullHandler
 from .emoji import Emoji
 from .parsemode import ParseMode
+from .messageentity import MessageEntity
+from .animation import Animation
+from .game import Game
 from .message import Message
+from .inputmessagecontent import InputMessageContent
+from .callbackquery import CallbackQuery
+from .choseninlineresult import ChosenInlineResult
+from .inlinekeyboardbutton import InlineKeyboardButton
+from .inlinekeyboardmarkup import InlineKeyboardMarkup
+from .inlinequery import InlineQuery
+from .inlinequeryresult import InlineQueryResult
+from .inlinequeryresultarticle import InlineQueryResultArticle
+from .inlinequeryresultaudio import InlineQueryResultAudio
+from .inlinequeryresultcachedaudio import InlineQueryResultCachedAudio
+from .inlinequeryresultcacheddocument import InlineQueryResultCachedDocument
+from .inlinequeryresultcachedgif import InlineQueryResultCachedGif
+from .inlinequeryresultcachedmpeg4gif import InlineQueryResultCachedMpeg4Gif
+from .inlinequeryresultcachedphoto import InlineQueryResultCachedPhoto
+from .inlinequeryresultcachedsticker import InlineQueryResultCachedSticker
+from .inlinequeryresultcachedvideo import InlineQueryResultCachedVideo
+from .inlinequeryresultcachedvoice import InlineQueryResultCachedVoice
+from .inlinequeryresultcontact import InlineQueryResultContact
+from .inlinequeryresultdocument import InlineQueryResultDocument
+from .inlinequeryresultgif import InlineQueryResultGif
+from .inlinequeryresultlocation import InlineQueryResultLocation
+from .inlinequeryresultmpeg4gif import InlineQueryResultMpeg4Gif
+from .inlinequeryresultphoto import InlineQueryResultPhoto
+from .inlinequeryresultvenue import InlineQueryResultVenue
+from .inlinequeryresultvideo import InlineQueryResultVideo
+from .inlinequeryresultvoice import InlineQueryResultVoice
+from .inlinequeryresultgame import InlineQueryResultGame
+from .inputtextmessagecontent import InputTextMessageContent
+from .inputlocationmessagecontent import InputLocationMessageContent
+from .inputvenuemessagecontent import InputVenueMessageContent
+from .inputcontactmessagecontent import InputContactMessageContent
+from .webhookinfo import WebhookInfo
+from .gamehighscore import GameHighScore
 from .update import Update
 from .bot import Bot
-from .dispatcher import Dispatcher
-from .updater import Updater
+from .constants import (MAX_MESSAGE_LENGTH, MAX_CAPTION_LENGTH, SUPPORTED_WEBHOOK_PORTS,
+                        MAX_FILESIZE_DOWNLOAD, MAX_FILESIZE_UPLOAD,
+                        MAX_MESSAGES_PER_SECOND_PER_CHAT, MAX_MESSAGES_PER_SECOND,
+                        MAX_MESSAGES_PER_MINUTE_PER_GROUP)
+from .version import __version__  # flake8: noqa
 
-__all__ = ['Bot', 'Updater', 'Dispatcher', 'Emoji', 'TelegramError',
-           'InputFile', 'ReplyMarkup', 'ForceReply', 'ReplyKeyboardHide',
-           'ReplyKeyboardMarkup', 'UserProfilePhotos', 'ChatAction',
-           'Location', 'Contact', 'Video', 'Sticker', 'Document', 'File',
-           'Audio', 'PhotoSize', 'Chat', 'Update', 'ParseMode', 'Message',
-           'User', 'TelegramObject', 'NullHandler', 'Voice']
+__author__ = 'devs@python-telegram-bot.org'
+
+__all__ = [
+    'Audio', 'Bot', 'Chat', 'ChatMember', 'ChatAction', 'ChosenInlineResult', 'CallbackQuery',
+    'Contact', 'Document', 'Emoji', 'File', 'ForceReply', 'InlineKeyboardButton',
+    'InlineKeyboardMarkup', 'InlineQuery', 'InlineQueryResult', 'InlineQueryResult',
+    'InlineQueryResultArticle', 'InlineQueryResultAudio', 'InlineQueryResultCachedAudio',
+    'InlineQueryResultCachedDocument', 'InlineQueryResultCachedGif',
+    'InlineQueryResultCachedMpeg4Gif', 'InlineQueryResultCachedPhoto',
+    'InlineQueryResultCachedSticker', 'InlineQueryResultCachedVideo',
+    'InlineQueryResultCachedVoice', 'InlineQueryResultContact', 'InlineQueryResultDocument',
+    'InlineQueryResultGif', 'InlineQueryResultLocation', 'InlineQueryResultMpeg4Gif',
+    'InlineQueryResultPhoto', 'InlineQueryResultVenue', 'InlineQueryResultVideo',
+    'InlineQueryResultVoice', 'InlineQueryResultGame', 'InputContactMessageContent', 'InputFile',
+    'InputLocationMessageContent', 'InputMessageContent', 'InputTextMessageContent',
+    'InputVenueMessageContent', 'KeyboardButton', 'Location', 'Message', 'MessageEntity',
+    'ParseMode', 'PhotoSize', 'ReplyKeyboardRemove', 'ReplyKeyboardMarkup', 'ReplyMarkup',
+    'Sticker', 'TelegramError', 'TelegramObject', 'Update', 'User', 'UserProfilePhotos', 'Venue',
+    'Video', 'Voice', 'MAX_MESSAGE_LENGTH', 'MAX_CAPTION_LENGTH', 'SUPPORTED_WEBHOOK_PORTS',
+    'MAX_FILESIZE_DOWNLOAD', 'MAX_FILESIZE_UPLOAD', 'MAX_MESSAGES_PER_SECOND_PER_CHAT',
+    'MAX_MESSAGES_PER_SECOND', 'MAX_MESSAGES_PER_MINUTE_PER_GROUP', 'WebhookInfo', 'Animation',
+    'Game', 'GameHighScore'
+]

telegram/__main__.py

@@ -0,0 +1,23 @@
+import sys
+
+import urllib3
+import certifi
+import future
+
+from . import __version__ as telegram_ver
+
+
+def print_ver_info():
+    print('python-telegram-bot {0}'.format(telegram_ver))
+    print('urllib3 {0}'.format(urllib3.__version__))
+    print('certifi {0}'.format(certifi.__version__))
+    print('future {0}'.format(future.__version__))
+    print('Python {0}'.format(sys.version.replace('\n', ' ')))
+
+
+def main():
+    print_ver_info()
+
+
+if __name__ == '__main__':
+    main()