Bumping version to v4.1 [ci skip]

yapf formatter, pre-commit hooks and new travis tests

.codeclimate.yml

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

.coveragerc

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

.gitignore

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

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+-   repo: git://github.com/pre-commit/mirrors-yapf
+    sha: 'v0.7.1'
+    hooks:
+    -   id: yapf
+        args: ['-i']
+
+-   repo: git://github.com/pre-commit/pre-commit-hooks
+    sha: 'v0.5.0'
+    hooks:
+    -   id: flake8
+        args: ['telegram']
+
+-   repo: git://github.com/pre-commit/mirrors-pylint
+    sha: 'v1.5.5'
+    hooks:
+    -   id: pylint
+        args: ['--errors-only', '--disable=no-name-in-module,import-error', 'telegram']

.travis.yml

@@ -4,5 +4,17 @@ python:
   - "2.7"
   - "3.3"
   - "3.4"
-  - "nightly"
-script: make test
+  - "3.5"
+  - "pypy"
+  - "pypy3"
+install:
+  - pip install coveralls
+  - pip install -r requirements.txt
+  - pip install -r requirements-dev.txt
+script:
+  - nosetests -v --with-flaky --no-flaky-report --with-coverage --cover-package=telegram/
+  - 'if [ $TRAVIS_PYTHON_VERSION != 2.6 ] && [ $TRAVIS_PYTHON_VERSION != 3.3 ] && [ $TRAVIS_PYTHON_VERSION != pypy3 ]; then yapf -r telegram; fi'
+  - flake8 telegram
+  - 'if [ $TRAVIS_PYTHON_VERSION != 2.6 ]; then pylint -E telegram --disable=no-name-in-module,import-error; fi'
+after_success:
+  coveralls

AUTHORS.rst

@@ -1 +1,30 @@
-* Leandro Toledo
+Credits
+=======
+
+``python-telegram-bot`` is written and maintained by `Leandro Toledo <https://github.com/leandrotoledo>`_.
+
+Contributors
+------------
+
+The following wonderful people contributed directly or indirectly to this project:
+
+- `Avanatiker <https://github.com/Avanatiker>`_
+- `Balduro <https://github.com/Balduro>`_
+- `bimmlerd <https://github.com/bimmlerd>`_
+- `ErgoZ Riftbit Vaper <https://github.com/ergoz>`_
+- `franciscod <https://github.com/franciscod>`_
+- `JASON0916 <https://github.com/JASON0916>`_
+- `jh0ker <https://github.com/jh0ker>`_
+- `JRoot3D <https://github.com/JRoot3D>`_
+- `jlmadurga <https://github.com/jlmadurga>`_
+- `macrojames <https://github.com/macrojames>`_
+- `naveenvhegde <https://github.com/naveenvhegde>`_
+- `njittam <https://github.com/njittam>`_
+- `Noam Meltzer <https://github.com/tsnoam>`_
+- `Oleg Shlyazhko <https://github.com/ollmer>`_
+- `Rahiel Kasim <https://github.com/rahiel>`_
+- `Shelomentsev D <https://github.com/shelomentsevd>`_
+- `sooyhwang <https://github.com/sooyhwang>`_
+- `wjt <https://github.com/wjt>`_
+
+Please add yourself here alphabetically when you submit your first pull request.

CHANGES

@@ -1,102 +0,0 @@
-2015-08-10
-  Released 2.5.1
-  Moved from GPLv2 to LGPLv3
-
-
-2015-08-09
-  Released 2.5
-  Fixes logging calls in API
-
-
-2015-08-08
-  Released 2.4
-  Fixes Emoji class for Python 3
-  PEP8 improvements
-
-
-2015-08-08
-  Released 2.3
-  Fixes ForceReply class
-  Remove logging.basicConfig from library
-
-
-2015-07-25
-  Released 2.2
-  Allows debug=True when initializing telegram.Bot
-
-
-2015-07-20
-  Released 2.1
-  Fix to_dict for Document and Video
-
-
-2015-07-19
-
-  Released 2.0
-  Fixes bugs
-  Improves __str__ over to_json()
-  Creates abstractclass TelegramObject
-
-
-2015-07-15
-
-  Released 1.9
-  Python 3 officially supported
-  PEP8 improvements
-
-
-2015-07-12
-
-  Released 1.8
-  Fixes crash when replying an unicode text message (special thanks to JRoot3D)
-
-
-2015-07-11
-
-  Released 1.7
-  Fixes crash when username is not defined on chat (special thanks to JRoot3D)
-
-
-2015-07-10
-
-  Released 1.6
-  Improvements for GAE support
-
-
-2015-07-10
-
-  Released 1.5
-  Fixes randomly unicode issues when using InputFile
-
-
-2015-07-10
-
-  Released 1.4
-  requests lib is no longer required
-  Google App Engine (GAE) is supported
-
-
-2015-07-10
-
-  Released 1.3
-  Added support to setWebhook (special thanks to macrojames)
-
-
-2015-07-09
-
-  Released 1.2
-  CustomKeyboard classes now available
-  Emojis available
-  PEP8 improvements
-
-
-2015-07-08
-
-  Released 1.1
-  PyPi package now available
-
-
-2015-07-08
-
-  Released 1.0
-  Initial checkin of python-telegram-bot

CHANGES.rst

@@ -0,0 +1,364 @@
+**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 `Transistion Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transistion-guide-to-Version-4.0>`_
+- **Changes from 4.0rc1**
+    - The syntax of filters for ``MessageHandler`` (upper/lower cases)
+    - Handler groups are now identified by ``int`` only, and ordered
+- **Note:** v4.0 has been skipped due to a PyPI accident
+
+**2016-04-22**
+
+*Released 4.0rc1*
+
+- Implement Bot API 2.0
+- Almost complete recode of ``Dispatcher``
+- Please read the `Transistion Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transistion-guide-to-Version-4.0>`_
+
+**2016-03-22**
+
+*Released 3.4*
+
+- Move ``Updater``, ``Dispatcher`` and ``JobQueue`` to new ``telegram.ext`` submodule (thanks to @rahiel)
+- Add ``disable_notification`` parameter (thanks to @aidarbiktimirov)
+- Fix bug where commands sent by Telegram Web would not be recognized (thanks to @shelomentsevd)
+- Add option to skip old updates on bot startup
+- Send files from ``BufferedReader``
+
+**2016-02-28**
+
+*Released 3.3*
+
+- Inline bots
+- Send any file by URL
+- Specialized exceptions: ``Unauthorized``, ``InvalidToken``, ``NetworkError`` and ``TimedOut``
+- Integration for botan.io (thanks to @ollmer)
+- HTML Parsemode (thanks to @jlmadurga)
+- Bugfixes and under-the-hood improvements
+
+**Very special thanks to Noam Meltzer (@tsnoam) for all of his work!**
+
+**2016-01-09**
+
+*Released 3.3b1*
+
+- Implement inline bots (beta)
+
+**2016-01-05**
+
+*Released 3.2.0*
+
+- Introducing ``JobQueue`` (original author: @franciscod)
+- Streamlining all exceptions to ``TelegramError`` (Special thanks to @tsnoam)
+- Proper locking of ``Updater`` and ``Dispatcher`` ``start`` and ``stop`` methods
+- Small bugfixes
+
+**2015-12-29**
+
+*Released 3.1.2*
+
+- Fix custom path for file downloads
+- Don't stop the dispatcher thread on uncaught errors in handlers
+
+**2015-12-21**
+
+*Released 3.1.1*
+
+- Fix a bug where asynchronous handlers could not have additional arguments
+- Add ``groups`` and ``groupdict`` as additional arguments for regex-based handlers
+
+**2015-12-16**
+
+*Released 3.1.0*
+
+- The ``chat``-field in ``Message`` is now of type ``Chat``. (API update Oct 8 2015)
+- ``Message`` now contains the optional fields ``supergroup_chat_created``, ``migrate_to_chat_id``, ``migrate_from_chat_id`` and ``channel_chat_created``. (API update Nov 2015)
+
+**2015-12-08**
+
+*Released 3.0.0*
+
+- Introducing the ``Updater`` and ``Dispatcher`` classes
+
+**2015-11-11**
+
+*Released 2.9.2*
+
+- Error handling on request timeouts has been improved
+
+**2015-11-10**
+
+*Released 2.9.1*
+
+- Add parameter ``network_delay`` to Bot.getUpdates for slow connections
+
+**2015-11-10**
+
+*Released 2.9*
+
+- Emoji class now uses ``bytes_to_native_str`` from ``future`` 3rd party lib
+- Make ``user_from`` optional to work with channels
+- Raise exception if Telegram times out on long-polling
+
+*Special thanks to @jh0ker for all hard work*
+
+
+**2015-10-08**
+
+*Released 2.8.7*
+
+- Type as optional for ``GroupChat`` class
+
+
+**2015-10-08**
+
+*Released 2.8.6*
+
+- Adds type to ``User`` and ``GroupChat`` classes (pre-release Telegram feature)
+
+
+**2015-09-24**
+
+*Released 2.8.5*
+
+- Handles HTTP Bad Gateway (503) errors on request
+- Fixes regression on ``Audio`` and ``Document`` for unicode fields
+
+
+**2015-09-20**
+
+*Released 2.8.4*
+
+- ``getFile`` and ``File.download`` is now fully supported
+
+
+**2015-09-10**
+
+*Released 2.8.3*
+
+- Moved ``Bot._requestURL`` to its own class (``telegram.utils.request``)
+- Much better, such wow, Telegram Objects tests
+- Add consistency for ``str`` properties on Telegram Objects
+- Better design to test if ``chat_id`` is invalid
+- Add ability to set custom filename on ``Bot.sendDocument(..,filename='')``
+- Fix Sticker as ``InputFile``
+- Send JSON requests over urlencoded post data
+- Markdown support for ``Bot.sendMessage(..., parse_mode=ParseMode.MARKDOWN)``
+- Refactor of ``TelegramError`` class (no more handling ``IOError`` or ``URLError``)
+
+
+**2015-09-05**
+
+*Released 2.8.2*
+
+- Fix regression on Telegram ReplyMarkup
+- Add certificate to ``is_inputfile`` method
+
+
+**2015-09-05**
+
+*Released 2.8.1*
+
+- Fix regression on Telegram objects with thumb properties
+
+
+**2015-09-04**
+
+*Released 2.8*
+
+- TelegramError when ``chat_id`` is empty for send* methods
+- ``setWebhook`` now supports sending self-signed certificate
+- Huge redesign of existing Telegram classes
+- Added support for PyPy
+- Added docstring for existing classes
+
+
+**2015-08-19**
+
+*Released 2.7.1*
+
+- Fixed JSON serialization for ``message``
+
+
+**2015-08-17**
+
+*Released 2.7*
+
+- Added support for ``Voice`` object and ``sendVoice`` method
+- Due backward compatibility performer or/and title will be required for ``sendAudio``
+- Fixed JSON serialization when forwarded message
+
+
+**2015-08-15**
+
+*Released 2.6.1*
+
+- Fixed parsing image header issue on < Python 2.7.3
+
+
+**2015-08-14**
+
+*Released 2.6.0*
+
+- Depreciation of ``require_authentication`` and ``clearCredentials`` methods
+- Giving ``AUTHORS`` the proper credits for their contribution for this project
+- ``Message.date`` and ``Message.forward_date`` are now ``datetime`` objects
+
+
+**2015-08-12**
+
+*Released 2.5.3*
+
+- ``telegram.Bot`` now supports to be unpickled
+
+
+**2015-08-11**
+
+*Released 2.5.2*
+
+- New changes from Telegram Bot API have been applied
+- ``telegram.Bot`` now supports to be pickled
+- Return empty ``str`` instead ``None`` when ``message.text`` is empty
+
+
+**2015-08-10**
+
+*Released 2.5.1*
+
+- Moved from GPLv2 to LGPLv3
+
+
+**2015-08-09**
+
+*Released 2.5*
+
+- Fixes logging calls in API
+
+
+**2015-08-08**
+
+*Released 2.4*
+
+- Fixes ``Emoji`` class for Python 3
+- ``PEP8`` improvements
+
+
+**2015-08-08**
+
+*Released 2.3*
+
+- Fixes ``ForceReply`` class
+- Remove ``logging.basicConfig`` from library
+
+
+**2015-07-25**
+
+*Released 2.2*
+
+- Allows ``debug=True`` when initializing ``telegram.Bot``
+
+
+**2015-07-20**
+
+*Released 2.1*
+
+- Fix ``to_dict`` for ``Document`` and ``Video``
+
+
+**2015-07-19**
+
+*Released 2.0*
+
+- Fixes bugs
+- Improves ``__str__`` over ``to_json()``
+- Creates abstract class ``TelegramObject``
+
+
+**2015-07-15**
+
+*Released 1.9*
+
+- Python 3 officially supported
+- ``PEP8`` improvements
+
+
+**2015-07-12**
+
+*Released 1.8*
+
+- Fixes crash when replying an unicode text message (special thanks to JRoot3D)
+
+
+**2015-07-11**
+
+*Released 1.7*
+
+- Fixes crash when ``username`` is not defined on ``chat`` (special thanks to JRoot3D)
+
+
+**2015-07-10**
+
+*Released 1.6*
+
+- Improvements for GAE support
+
+
+**2015-07-10**
+
+*Released 1.5*
+
+- Fixes randomly unicode issues when using ``InputFile``
+
+
+**2015-07-10**
+
+*Released 1.4*
+
+- ``requests`` lib is no longer required
+- Google App Engine (GAE) is supported
+
+
+**2015-07-10**
+
+*Released 1.3*
+
+- Added support to ``setWebhook`` (special thanks to macrojames)
+
+
+**2015-07-09**
+
+*Released 1.2*
+
+- ``CustomKeyboard`` classes now available
+- Emojis available
+- ``PEP8`` improvements
+
+
+**2015-07-08**
+
+*Released 1.1*
+
+- PyPi package now available
+
+
+**2015-07-08**
+
+*Released 1.0*
+
+- Initial checkin of python-telegram-bot

CONTRIBUTING.rst

@@ -0,0 +1,140 @@
+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:
+
+   ``$ git clone https://github.com/<your username>/python-telegram-bot``
+
+   ``$ cd python-telegram-bot``
+
+3. Add a track to the original repository:
+
+   ``$ git remote add upstream https://github.com/python-telegram-bot/python-telegram-bot``
+
+4. Install dependencies:
+
+   ``$ pip install -r requirements.txt -r requirements-dev.txt``
+
+
+5. Install pre-commit hooks:
+
+   ``$ 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:
+
+   ``$ 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:
+
+      ``$ make test``
+
+   - To actually make the commit (this will trigger tests for yapf, lint and pep8 automatically):
+
+      ``$ git add your-file-changed.py``
+
+        - yapf may change code formatting, make sure to re-add them to your commit.
+
+      ``$ git commit -a -m "your-commit-message-here"``
+
+   - Finally, push it to your GitHub fork, run:
+
+      ``$ 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:
+
+      ``$ 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:
+
+   ``$ git branch -D your-branch-name``
+
+   ``$ git push origin --delete your-branch-name``
+
+7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``!
+
+.. _`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: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/AUTHORS.rst

MANIFEST.in

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

Makefile

@@ -1,7 +1,12 @@
-help:
-	@echo "  clean		remove unwanted stuff"
-	@echo "  lint		check style with flake8"
-	@echo "  test		run tests"
+.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
@@ -9,9 +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:
+	$(PEP8) telegram
+
+yapf:
+	$(YAPF) -r telegram
 
 lint:
-	flake8 --doctests --max-complexity 10 telegram
+	$(PYLINT) -E telegram --disable=no-name-in-module,import-error
 
 test:
-	python telegram_test.py
+	$(NOSETESTS) -v
+
+install:
+	$(PIP)  install -r requirements.txt -r requirements-dev.txt
+
+help:
+	@echo "Available targets:"
+	@echo "- clean       Clean up the source directory"
+	@echo "- pep257      Check docstring style with pep257"
+	@echo "- pep8        Check style with flake8"
+	@echo "- lint        Check style with pylint"
+	@echo "- yapf        Check style with yapf"
+	@echo "- test        Run tests"
+	@echo
+	@echo "Available variables:"
+	@echo "- PYLINT      default: $(PYLINT)"
+	@echo "- NOSETESTS   default: $(NOSETESTS)"
+	@echo "- PEP257      default: $(PEP257)"
+	@echo "- PEP8        default: $(PEP8)"
+	@echo "- YAPF        default: $(YAPF)"
+	@echo "- PIP         default: $(PIP)"

README.rst

@@ -1,60 +1,85 @@
-Python Telegram Bot
+.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-logo-text_768.png?raw=true
+   :align: center
+   :target: https://github.com/python-telegram-bot/logos
+   :alt: python-telegram-bot Logo
 
-A Python wrapper around the Telegram Bot API.
+Not **just** a Python wrapper around the Telegram Bot API
 
-By `Leandro Toledo <leandrotoledodesouza@gmail.com>`_
+*Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_.
 
-.. image:: https://travis-ci.org/leandrotoledo/python-telegram-bot.svg?branch=master
-    :target: https://travis-ci.org/leandrotoledo/python-telegram-bot
-    :alt: Travis CI Status
+.. 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://codeclimate.com/github/leandrotoledo/python-telegram-bot/badges/gpa.svg
-   :target: https://codeclimate.com/github/leandrotoledo/python-telegram-bot
+.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot.svg
+   :target: https://pypi.python.org/pypi/python-telegram-bot
+   :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
+   :alt: Documentation Status
+
+.. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg
+   :target: https://www.gnu.org/licenses/lgpl-3.0.html
+   :alt: LGPLv3 License
+
+.. image:: https://travis-ci.org/python-telegram-bot/python-telegram-bot.svg?branch=master
+   :target: https://travis-ci.org/python-telegram-bot/python-telegram-bot
+   :alt: Travis CI Status
+
+.. image:: https://codeclimate.com/github/python-telegram-bot/python-telegram-bot/badges/gpa.svg
+   :target: https://codeclimate.com/github/python-telegram-bot/python-telegram-bot
    :alt: Code Climate
 
+.. image:: https://coveralls.io/repos/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:: https://img.shields.io/badge/Telegram-Group-blue.svg
+   :target: https://telegram.me/pythontelegrambotgroup
+   :alt: Telegram Group
+
 =================
 Table of contents
 =================
 
 - `Introduction`_
 
-- `Status`_
-
-  1. `Telegram API support`_
-
-  2. `Python Version support`_
+- `Telegram API support`_
 
 - `Installing`_
 
 - `Getting the code`_
 
-- `Documentation`_
+- `Getting started`_
 
-  1. `API`_
+  #. `Learning by example`_
 
-  2. `Logging`_
+  #. `API`_
 
-  3. `Examples`_
+  #. `Extensions`_
+
+  #. `JobQueue`_
+
+  #. `Logging`_
+
+  #. `Documentation`_
+
+- `Getting help`_
+
+- `Contributing`_
 
 - `License`_
 
-- `Contact`_
-
-- `TODO`_
-
 ===============
 _`Introduction`
 ===============
 
 This library provides a pure Python interface for the `Telegram Bot API <https://core.telegram.org/bots/api>`_. It works with Python versions from 2.6+. It also works with `Google App Engine <https://cloud.google.com/appengine>`_.
 
-=========
-_`Status`
-=========
-
------------------------
+=======================
 _`Telegram API support`
------------------------
+=======================
 
 ========================= ============
 Telegram Bot API Method   *Supported?*
@@ -67,35 +92,29 @@ sendAudio                 Yes
 sendDocument              Yes
 sendSticker               Yes
 sendVideo                 Yes
+sendVoice                 Yes
 sendLocation              Yes
 sendChatAction            Yes
 getUpdates                Yes
 getUserProfilePhotos      Yes
+getFile                   Yes
 setWebhook                Yes
+answerInlineQuery         Yes
+kickChatMember            Yes
+unbanChatMember           Yes
+answerCallbackQuery       Yes
+editMessageText           Yes
+editMessageCaption        Yes
+editMessageReplyMarkup    Yes
 ========================= ============
 
--------------------------
-_`Python Version support`
--------------------------
-
-============== ============
-Python Version *Supported?*
-============== ============
-2.6            Yes
-2.7            Yes
-3.3            Yes
-3.4            Yes
-============== ============
-
 =============
 _`Installing`
 =============
 
-You can install python-telegram-bot using::
+You can install or upgrade python-telegram-bot with:
 
-    $ pip install python-telegram-bot
-
-Or upgrade to the latest version::
+.. code:: shell
 
     $ pip install python-telegram-bot --upgrade
 
@@ -103,142 +122,387 @@ Or upgrade to the latest version::
 _`Getting the code`
 ===================
 
-The code is hosted at https://github.com/leandrotoledo/python-telegram-bot
+The code is hosted at https://github.com/python-telegram-bot/python-telegram-bot
 
-Check out the latest development version anonymously with::
+Check out the latest development version anonymously with:
 
-    $ git clone https://github.com/leandrotoledo/python-telegram-bot
+.. code:: shell
+
+    $ git clone https://github.com/python-telegram-bot/python-telegram-bot
     $ cd python-telegram-bot
 
+Install dependencies:
+
+.. code:: shell
+
+    $ pip install -r requirements.txt -r requirements-dev.txt
+
 Run tests:
 
+.. code:: shell
+
     $ make test
 
-To see other options available, run:
+To see other available options, run:
+
+.. code:: shell
 
     $ make help
 
-================
-_`Documentation`
-================
+==================
+_`Getting started`
+==================
 
 View the last release API documentation at: https://core.telegram.org/bots/api
 
+This library uses the `logging` module. To set up logging to standard output, put:
+
+.. code:: python
+
+    import logging
+    logging.basicConfig(level=logging.DEBUG,
+                        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+
+at the beginning of your script.
+
+**Note:** The ``telegram.ext`` module will catch errors that would cause the bot to crash. All these are logged to the ``logging`` module, so it's recommended to use this if you are looking for error causes.
+
+----------------------
+_`Learning by example`
+----------------------
+
+We believe that the best way to learn and understand this simple package is by example. So here are some examples for you to review. Even if it's not your approach for learning, please take a look at ``echobot2`` (below), it is de facto the base for most of the bots out there. Best of all, 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.
+
+- `clibot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/clibot.py>`_ has a command line interface.
+
+- `echobot2 <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot2.py>`_ replies back messages.
+
+- `inlinebot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinebot.py>`_ basic example of an `inline bot <https://core.telegram.org/bots/inline>`_
+
+- `state machine bot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/state_machine_bot.py>`_ keeps the state for individual users, useful for multipart conversations
+
+- `timerbot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/timerbot.py>`_ uses the ``JobQueue`` to send timed messages.
+
+Examples using only the API:
+
+- `echobot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/legacy/echobot.py>`_ replies back messages.
+
+- `roboed <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/legacy/roboed.py>`_ talks to `Robô Ed <http://www.ed.conpet.gov.br/br/converse.php>`_.
+
+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.
+
 ------
 _`API`
 ------
 
-The API is exposed via the ``telegram.Bot`` class.
+Note: Using the ``Bot`` class directly is the 'old' method, we have an easier way to make bots described in the next section.  All of this is however still important information, even if you're using the ``telegram.ext`` submodule!
 
-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>`_).
+The API is exposed via the ``telegram.Bot`` class. The methods have names as described in the official `Telegram Bot API <https://core.telegram.org/bots/api>`_, but equivalent snake_case methods are available for `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_ enthusiasts. So for example `telegram.Bot.send_message` is the same as `telegram.Bot.sendMessage`.
+
+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#6-botfather>`_).
 
 For full details see the `Bots: An introduction for developers <https://core.telegram.org/bots>`_.
 
-To create an instance of the ``telegram.Bot``::
+To create an instance of the ``telegram.Bot``:
+
+.. code:: python
 
     >>> import telegram
     >>> bot = telegram.Bot(token='token')
 
-To see if your credentials are successful::
+To see if your credentials are successful:
 
-    >>> print bot.getMe()
+.. code:: python
+
+    >>> 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::
+To fetch text messages sent to your Bot:
+
+.. code:: python
 
     >>> updates = bot.getUpdates()
-    >>> print [u.message.text for u in updates]
+    >>> print([u.message.text for u in updates])
 
-To fetch images sent to your Bot::
+To fetch images sent to your Bot:
+
+.. code:: python
 
     >>> updates = bot.getUpdates()
-    >>> print [u.message.photo for u in updates if u.message.photo]
+    >>> print([u.message.photo for u in updates if u.message.photo])
 
-To reply messages you'll always need the chat_id::
+To reply messages you'll always need the ``chat_id``:
+
+.. code:: python
 
     >>> chat_id = bot.getUpdates()[-1].message.chat_id
 
-To post a text message::
+To post a text message:
+
+.. code:: python
 
     >>> bot.sendMessage(chat_id=chat_id, text="I'm sorry Dave I'm afraid I can't do that.")
 
-To post an Emoji (special thanks to `Tim Whitlock <http://apps.timwhitlock.info/emoji/tables/unicode>`_)::
+To post a text message with markdown:
+
+.. code:: python
+
+    >>> bot.sendMessage(chat_id=chat_id, text="*bold* _italic_ [link](http://google.com).", parse_mode=telegram.ParseMode.MARKDOWN)
+
+To post a text message with Html style:
+
+.. code:: python
+
+	>>> bot.sendMessage(chat_id=chat_id, text='<b>bold</b> <i>italic</i> <a href="http://google.com">link</a>.', parse_mode=telegram.ParseMode.HTML)
+
+To post an Emoji (special thanks to `Tim Whitlock <http://apps.timwhitlock.info/emoji/tables/unicode>`_):
+
+.. code:: python
 
     >>> 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)::
+To post an image file via URL:
+
+.. code:: python
 
     >>> bot.sendPhoto(chat_id=chat_id, photo='https://telegram.org/img/t_logo.png')
 
-To post an audio file::
+To post an image file from disk:
 
-    >>> bot.sendAudio(chat_id=chat_id, audio=open('tests/telegram.ogg', 'rb'))
+.. code:: python
 
-To tell the user that something is happening on bot's side::
+    >>> bot.sendPhoto(chat_id=chat_id, photo=open('tests/test.png', 'rb'))
+
+To post a voice file from disk:
+
+.. code:: python
+
+    >>> bot.sendVoice(chat_id=chat_id, voice=open('tests/telegram.ogg', 'rb'))
+
+To tell the user that something is happening on bot's side:
+
+.. code:: python
 
     >>> bot.sendChatAction(chat_id=chat_id, action=telegram.ChatAction.TYPING)
 
-To create `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_::
+To create `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_:
 
-    >>> custom_keyboard = [[ telegram.Emoji.THUMBS_UP_SIGN, telegram.Emoji.THUMBS_DOWN_SIGN ]]
+.. code:: python
+
+    >>> custom_keyboard = [[ telegram.KeyboardButton(telegram.Emoji.THUMBS_UP_SIGN),
+    ...     telegram.KeyboardButton(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>`_::
+To hide `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_:
+
+.. code:: python
 
     >>> reply_markup = telegram.ReplyKeyboardHide()
     >>> bot.sendMessage(chat_id=chat_id, text="I'm back.", reply_markup=reply_markup)
 
-There are many more API methods, to read the full API documentation::
+To download a file (you will need its ``file_id``):
+
+.. code:: python
+
+    >>> 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:
+
+.. code:: shell
 
     $ pydoc telegram.Bot
 
+-------------
+_`Extensions`
+-------------
+
+The ``telegram.ext`` submodule is built on top of the bare-metal API. It provides an easy-to-use interface to the ``telegram.Bot`` by caring about getting new updates with the ``Updater`` class 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.
+
+We'll need an Access Token. **Note:** If you have done this in the previous step, you can use that one. To generate an Access Token, we have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#botfather>`_).
+
+First, we create an ``Updater`` object:
+
+.. code:: python
+
+   >>> from telegram.ext import Updater
+   >>> updater = Updater(token='token')
+
+For quicker access to the ``Dispatcher`` used by our ``Updater``, we can introduce it locally:
+
+.. code:: python
+
+   >>> dispatcher = updater.dispatcher
+
+Now, we need to define a function that should process a specific type of update:
+
+.. code:: python
+
+   >>> def start(bot, update):
+   ...   bot.sendMessage(chat_id=update.message.chat_id, text="I'm a bot, please talk to me!")
+
+We want this function to be called on a Telegram message that contains the ``/start`` command. To do that, we have to use a ``CommandHandler`` object and register it in the dispatcher:
+
+.. code:: python
+
+   >>> from telegram.ext import CommandHandler
+   >>> start_handler = CommandHandler('start', start)
+   >>> dispatcher.add_handler(start_handler)
+
+The last step is to tell the ``Updater`` to start working:
+
+.. code:: python
+
+   >>> updater.start_polling()
+
+Our bot is now up and running (go ahead and try it)! It's not doing anything yet, besides answering to the ``/start`` command. Let's add another handler that listens for regular messages. We're using the `MessageHandler` here to echo to all text messages:
+
+.. code:: python
+
+   >>> def echo(bot, update):
+   ...   bot.sendMessage(chat_id=update.message.chat_id, text=update.message.text)
+   ...
+   >>> from telegram.ext import MessageHandler, Filters
+   >>> echo_handler = MessageHandler([Filters.text], echo)
+   >>> dispatcher.add_handler(echo_handler)
+
+Our bot should now reply to all text messages that are not a command with a message that has the same content.
+
+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 a command in the handler function:
+
+.. code:: python
+
+   >>> def caps(bot, update, args):
+   ...   text_caps = ' '.join(args).upper()
+   ...   bot.sendMessage(chat_id=update.message.chat_id, text=text_caps)
+   ...
+   >>> caps_handler = CommandHandler('caps', caps, pass_args=True)
+   >>> dispatcher.add_handler(caps_handler)
+
+To enable our bot to respond to inline queries, we can add the following (you will also have to talk to BotFather):
+
+.. code:: python
+
+   >>> from telegram import InlineQueryResultArticle
+   >>> def inline_caps(bot, update):
+   ...   query = bot.update.inline_query.query
+   ...   results = list()
+   ...   results.append(InlineQueryResultArticle(query.upper(), 'Caps', query.upper()))
+   ...   bot.answerInlineQuery(update.inline_query.id, results)
+   ...
+   >>> from telegram.ext import InlineQueryHandler
+   >>> inline_caps_handler = InlineQueryHandler(inline_caps)
+   >>> dispatcher.add_handler(inline_caps_handler)
+
+People might try to send commands to the bot that it doesn't understand, so we can use a ``RegexHandler`` to recognize all commands that were not recognized by the previous handlers. **Note:** This handler has to be added last, else it will be triggered before the ``CommandHandlers`` had a chance to look at the update:
+
+.. code:: python
+
+   >>> def unknown(bot, update):
+   ...   bot.sendMessage(chat_id=update.message.chat_id, text="Sorry, I didn't understand that command.")
+   ...
+   >>> from telegram.ext import RegexHandler
+   >>> unknown_handler = RegexHandler(r'/.*', unknown)
+   >>> dispatcher.add_handler(unknown_handler)
+
+If you're done playing around, stop the bot with this:
+
+.. code:: python
+
+   >>> updater.stop()
+
+Check out more examples in the `examples folder <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples>`_!
+
 -----------
-_`Logging`
+_`JobQueue`
 -----------
 
-You can get logs in your main application by calling `logging` and setting the log level you want::
+The ``JobQueue`` allows you to perform tasks with a delay or even periodically. The ``Updater`` will create one for you:
+
+.. code:: python
+
+    >>> from telegram.ext import Updater
+    >>> u = Updater('TOKEN')
+    >>> j = u.job_queue
+
+The job queue uses functions for tasks, so we define one and add it to the queue. Usually, when the first job is added to the queue, it wil start automatically. We can prevent this by setting ``prevent_autostart=True``:
+
+.. code:: python
+
+    >>> def job1(bot):
+    ...     bot.sendMessage(chat_id='@examplechannel', text='One message every minute')
+    >>> j.put(job1, 60, next_t=0, prevent_autostart=True)
+
+You can also have a job that will not be executed repeatedly:
+
+.. code:: python
+
+    >>> def job2(bot):
+    ...     bot.sendMessage(chat_id='@examplechannel', text='A single message with 30s delay')
+    >>> j.put(job2, 30, repeat=False)
+
+Now, because we didn't prevent the auto start this time, the queue will start ticking. It runs in a seperate thread, so it is non-blocking. When we stop the Updater, the related queue will be stopped as well:
+
+.. code:: python
+
+    >>> u.stop()
+
+We can also stop the job queue by itself:
+
+.. code:: python
+
+    >>> j.stop()
+
+----------
+_`Logging`
+----------
+
+You can get logs in your main application by calling `logging` and setting the log level you want:
+
+.. code:: python
 
     >>> import logging
     >>> logger = logging.getLogger()
     >>> logger.setLevel(logging.INFO)
 
-If you want DEBUG logs instead::
+If you want DEBUG logs instead:
+
+.. code:: python
 
     >>> logger.setLevel(logging.DEBUG)
 
------------
-_`Examples`
------------
 
-Here follows some examples to help you to get your own Bot up to speed:
+================
+_`Documentation`
+================
 
-- `echobot <https://github.com/leandrotoledo/python-telegram-bot/blob/master/examples/echobot.py>`_ replies back messages.
+``python-telegram-bot``'s documentation lives at `Read the Docs <https://python-telegram-bot.readthedocs.org/en/latest/>`_.
 
-- `roboed <https://github.com/leandrotoledo/python-telegram-bot/blob/master/examples/roboed.py>`_ talks to `Robô Ed <http://www.ed.conpet.gov.br/br/converse.php>`_.
+===============
+_`Getting help`
+===============
 
-- `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.
+You can get help in several ways:
 
-- `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).
+1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
+   
+2. You can ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
+   
+3. As last resort, the developers are ready to help you with `serious issues <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
+
+
+===============
+_`Contributing`
+===============
+
+Contributions of all sizes are welcome. Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/CONTRIBUTING.rst>`_ to get started. You can also help by `reporting bugs <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
 
 ==========
 _`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/00b9c0f802509b949c1563d56eb053b0>`_.
-
-=======
-_`TODO`
-=======
-
-Patches and bug reports are `welcome <https://github.com/leandrotoledo/python-telegram-bot/issues/new>`_, just please keep the style consistent with the original source.
-
-- Add commands handler.
+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 <https://www.gnu.org/licenses/lgpl-3.0.html>`_, but applications that use the library don't have to be.

docs/Makefile

@@ -0,0 +1,192 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PythonTelegramBot.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PythonTelegramBot.qhc"
+
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/PythonTelegramBot"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PythonTelegramBot"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/requirements-docs.txt

@@ -0,0 +1,3 @@
+sphinx
+sphinx_rtd_theme
+sphinx-pypi-upload

docs/source/conf.py

@@ -0,0 +1,287 @@
+# -*- coding: utf-8 -*-
+#
+# Python Telegram Bot documentation build configuration file, created by
+# sphinx-quickstart on Mon Aug 10 22:25:07 2015.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+import shlex
+
+# 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
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../..'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Python Telegram Bot'
+copyright = u'2015-2016, Leandro Toledo'
+author = u'Leandro Toledo'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '4.1'
+# The full version, including alpha/beta/rc tags.
+release = '4.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# 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
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PythonTelegramBotdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  (master_doc, 'PythonTelegramBot.tex', u'Python Telegram Bot Documentation',
+   u'Leandro Toledo', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'pythontelegrambot', u'Python Telegram Bot Documentation',
+     [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  (master_doc, 'PythonTelegramBot', u'Python Telegram Bot Documentation',
+   author, 'PythonTelegramBot', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False

docs/source/index.rst

@@ -0,0 +1,23 @@
+.. Python Telegram Bot documentation master file, created by
+   sphinx-quickstart on Mon Aug 10 22:25:07 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Python Telegram Bot's documentation!
+===============================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+

docs/source/modules.rst

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

docs/source/telegram.audio.rst

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

docs/source/telegram.base.rst

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

docs/source/telegram.bot.rst

@@ -0,0 +1,6 @@
+telegram.bot module
+===================
+
+.. automodule:: telegram.bot
+    :members:
+    :show-inheritance:

docs/source/telegram.chat.rst

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

docs/source/telegram.chataction.rst

@@ -0,0 +1,7 @@
+telegram.chataction module
+==========================
+
+.. automodule:: telegram.chataction
+    :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.contact.rst

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

docs/source/telegram.document.rst

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

docs/source/telegram.emoji.rst

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

docs/source/telegram.error.rst

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

docs/source/telegram.ext.callbackqueryhandler.rst

@@ -0,0 +1,7 @@
+telegram.ext.handler module
+===========================
+
+.. automodule:: telegram.ext.handler
+    :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.dispatcher.rst

@@ -0,0 +1,7 @@
+telegram.ext.dispatcher module
+==============================
+
+.. automodule:: telegram.ext.dispatcher
+    :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,28 @@
+telegram.ext package
+====================
+
+Submodules
+----------
+
+.. toctree::
+
+    telegram.ext.updater
+    telegram.ext.dispatcher
+    telegram.ext.jobqueue
+    telegram.ext.handler
+    telegram.ext.choseninlineresulthandler
+    telegram.ext.commandhandler
+    telegram.ext.inlinequeryhandler
+    telegram.ext.messagehandler
+    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.forcereply.rst

@@ -0,0 +1,7 @@
+telegram.forcereply module
+==========================
+
+.. automodule:: telegram.forcereply
+    :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

@@ -0,0 +1,7 @@
+telegram.inlinequeryresult module
+=================================
+
+.. 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.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.inputfile.rst

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

docs/source/telegram.location.rst

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

docs/source/telegram.message.rst

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

docs/source/telegram.nullhandler.rst

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

docs/source/telegram.photosize.rst

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

docs/source/telegram.replykeyboardhide.rst

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

docs/source/telegram.replykeyboardmarkup.rst

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

docs/source/telegram.replymarkup.rst

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

docs/source/telegram.rst

@@ -0,0 +1,65 @@
+telegram package
+================
+
+Submodules
+----------
+
+.. toctree::
+
+   telegram.audio
+   telegram.base
+   telegram.bot
+   telegram.ext
+   telegram.inlinequery
+   telegram.inlinequeryresult
+   telegram.inlinekeyboardbutton
+   telegram.inlinekeyboardmarkup
+   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.inlinequeryresultgif
+   telegram.inlinequeryresultlocation
+   telegram.inlinequeryresultmpeg4gif
+   telegram.inlinequeryresultphoto
+   telegram.inlinequeryresultvenue
+   telegram.inlinequeryresultvideo
+   telegram.inlinequeryresultvoice
+   telegram.choseninlineresult
+   telegram.chataction
+   telegram.contact
+   telegram.document
+   telegram.emoji
+   telegram.error
+   telegram.forcereply
+   telegram.chat
+   telegram.inputfile
+   telegram.location
+   telegram.message
+   telegram.nullhandler
+   telegram.photosize
+   telegram.replykeyboardhide
+   telegram.replykeyboardmarkup
+   telegram.replymarkup
+   telegram.sticker
+   telegram.update
+   telegram.user
+   telegram.userprofilephotos
+   telegram.video
+   telegram.voice
+
+Module contents
+---------------
+
+.. automodule:: telegram
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/telegram.sticker.rst

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

docs/source/telegram.update.rst

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

docs/source/telegram.user.rst

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

docs/source/telegram.userprofilephotos.rst

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

docs/source/telegram.video.rst

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

docs/source/telegram.voice.rst

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

examples/LICENSE.txt

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

examples/clibot.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Example Bot to show some of the functionality of the library
+# This program is dedicated to the public domain under the CC0 license.
+
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few handler functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and the CLI-Loop is entered, where all text inputs are
+inserted into the update queue for the bot to handle.
+
+Usage:
+Repeats messages with a delay.
+Reply to last chat from the command line by typing "/reply <text>"
+Type 'stop' on the command line to stop the bot.
+"""
+
+from telegram.ext import Updater, StringCommandHandler, StringRegexHandler, \
+    MessageHandler, CommandHandler, RegexHandler, Filters
+from telegram.ext.dispatcher import run_async
+from time import sleep
+import logging
+
+from future.builtins import input
+
+# Enable Logging
+logging.basicConfig(
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+# We use this var to save the last chat id, so we can reply to it
+last_chat_id = 0
+
+
+# Define a few (command) handler callback functions. These usually take the
+# two arguments bot and update. Error handlers also receive the raised
+# TelegramError object in error.
+def start(bot, update):
+    """ Answer in Telegram """
+    bot.sendMessage(update.message.chat_id, text='Hi!')
+
+
+def help(bot, update):
+    """ Answer in Telegram """
+    bot.sendMessage(update.message.chat_id, text='Help!')
+
+
+def any_message(bot, update):
+    """ Print to console """
+
+    # Save last chat_id to use in reply handler
+    global last_chat_id
+    last_chat_id = update.message.chat_id
+
+    logger.info("New message\nFrom: %s\nchat_id: %d\nText: %s" %
+                (update.message.from_user,
+                 update.message.chat_id,
+                 update.message.text))
+
+
+@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. Also, you have to include **kwargs in
+    your parameter list. The kwargs contain all optional parameters that are
+    """
+
+    sleep(2)  # IO-heavy operation here
+    bot.sendMessage(update.message.chat_id, text='Echo: %s' %
+                                                 update.message.text)
+
+
+# These handlers are for updates of type str. We use them to react to inputs
+# on the command line interface
+def cli_reply(bot, update, args):
+    """
+    For any update of type telegram.Update or str that contains a command, you
+    can get the argument list by appending args to the function parameters.
+    Here, we reply to the last active chat with the text after the command.
+    """
+    if last_chat_id is not 0:
+        bot.sendMessage(chat_id=last_chat_id, text=' '.join(args))
+
+
+def cli_noncommand(bot, update, update_queue):
+    """
+    You can also get the update queue as an argument in any handler by
+    appending it to the argument list. Be careful with this though.
+    Here, we put the input string back into the queue, but as a command.
+
+    To learn more about those optional handler parameters, read the
+    documentation of the Handler classes.
+    """
+    update_queue.put('/%s' % update)
+
+
+def error(bot, update, error):
+    """ Print error to console """
+    logger.warn('Update %s caused error %s' % (update, error))
+
+
+def main():
+    # Create the EventHandler and pass it your bot's token.
+    token = 'TOKEN'
+    updater = Updater(token, workers=10)
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # This is how we add handlers for Telegram messages
+    dp.add_handler(CommandHandler("start", start))
+    dp.add_handler(CommandHandler("help", help))
+    # Message handlers only receive updates that don't contain commands
+    dp.add_handler(MessageHandler([Filters.text], message))
+    # Regex handlers will receive all updates on which their regex matches,
+    # but we have to add it in a separate group, since in one group,
+    # only one handler will be executed
+    dp.add_handler(RegexHandler('.*', any_message), group=1)
+
+    # String handlers work pretty much the same. Note that we have to tell
+    # the handler to pass the args or update_queue parameter
+    dp.add_handler(StringCommandHandler('reply', cli_reply, pass_args=True))
+    dp.add_handler(StringRegexHandler('[^/].*', cli_noncommand,
+                                      pass_update_queue=True))
+
+    # All TelegramErrors are caught for you and delivered to the error
+    # handler(s). Other types of Errors are not caught.
+    dp.add_error_handler(error)
+
+    # Start the Bot and store the update Queue, so we can insert updates
+    update_queue = updater.start_polling(timeout=10)
+
+    '''
+    # Alternatively, run with webhook:
+
+    update_queue = updater.start_webhook('0.0.0.0',
+                                         443,
+                                         url_path=token,
+                                         cert='cert.pem',
+                                         key='key.key',
+                                         webhook_url='https://example.com/%s'
+                                             % token)
+
+    # 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:
+        text = input()
+
+        # Gracefully stop the event handler
+        if text == 'stop':
+            updater.stop()
+            break
+
+        # else, put the text into the update queue to be handled by our handlers
+        elif len(text) > 0:
+            update_queue.put(text)
+
+if __name__ == '__main__':
+    main()

examples/echobot.py

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

examples/echobot2.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to reply to Telegram messages
+# This program is dedicated to the public domain under the CC0 license.
+
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few handler functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
+
+Usage:
+Basic Echobot example, repeats messages.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+from telegram.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):
+    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.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,108 @@
+#!/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):
+    bot.sendMessage(update.message.chat_id, text='Hi!')
+
+
+def help(bot, update):
+    bot.sendMessage(update.message.chat_id, 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)))
+
+    bot.answerInlineQuery(update.inline_query.id, results=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_example.py

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

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

examples/legacy/roboed.py

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

examples/roboed.py

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

examples/state_machine_bot.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Basic example for a bot that awaits an answer from the user
+# This program is dedicated to the public domain under the CC0 license.
+
+import logging
+from telegram import Emoji, ForceReply, ReplyKeyboardMarkup, KeyboardButton
+from telegram.ext import Updater, CommandHandler, MessageHandler, Filters
+
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - '
+                           '%(message)s',
+                    level=logging.INFO)
+
+# Define the different states a chat can be in
+MENU, AWAIT_CONFIRMATION, AWAIT_INPUT = range(3)
+
+# Python 2 and 3 unicode differences
+try:
+    YES, NO = (Emoji.THUMBS_UP_SIGN.decode('utf-8'),
+               Emoji.THUMBS_DOWN_SIGN.decode('utf-8'))
+except AttributeError:
+    YES, NO = (Emoji.THUMBS_UP_SIGN, Emoji.THUMBS_DOWN_SIGN)
+
+# States are saved in a dict that maps chat_id -> state
+state = dict()
+# Sometimes you need to save data temporarily
+context = dict()
+# This dict is used to store the settings value for the chat.
+# Usually, you'd use persistence for this (e.g. sqlite).
+values = dict()
+
+
+# Example handler. Will be called on the /set command and on regular messages
+def set_value(bot, update):
+    chat_id = update.message.chat_id
+    user_id = update.message.from_user.id
+    text = update.message.text
+    chat_state = state.get(chat_id, MENU)
+    chat_context = context.get(chat_id, None)
+
+    # Since the handler will also be called on messages, we need to check if
+    # the message is actually a command
+    if chat_state == MENU and text[0] == '/':
+        state[chat_id] = AWAIT_INPUT  # set the state
+        context[chat_id] = user_id  # save the user id to context
+        bot.sendMessage(chat_id,
+                        text="Please enter your settings value or send "
+                             "/cancel to abort",
+                        reply_markup=ForceReply())
+
+    # If we are waiting for input and the right user answered
+    elif chat_state == AWAIT_INPUT and chat_context == user_id:
+        state[chat_id] = AWAIT_CONFIRMATION
+
+        # Save the user id and the answer to context
+        context[chat_id] = (user_id, update.message.text)
+        reply_markup = ReplyKeyboardMarkup(
+            [[KeyboardButton(YES), KeyboardButton(NO)]],
+            one_time_keyboard=True)
+        bot.sendMessage(chat_id, text="Are you sure?",
+                        reply_markup=reply_markup)
+
+    # If we are waiting for confirmation and the right user answered
+    elif chat_state == AWAIT_CONFIRMATION and chat_context[0] == user_id:
+        del state[chat_id]
+        del context[chat_id]
+        if text == YES:
+            values[chat_id] = chat_context[1]
+            bot.sendMessage(chat_id,
+                            text="Changed value to %s." % values[chat_id])
+        else:
+            bot.sendMessage(chat_id,
+                            text="Value not changed: %s."
+                                 % values.get(chat_id, '<not set>'))
+
+
+# Handler for the /cancel command.
+# Sets the state back to MENU and clears the context
+def cancel(bot, update):
+    chat_id = update.message.chat_id
+    del state[chat_id]
+    del context[chat_id]
+
+
+def help(bot, update):
+    bot.sendMessage(update.message.chat_id, text="Use /set to test this bot.")
+
+
+# Create the Updater and pass it your bot's token.
+updater = Updater("TOKEN")
+
+# The command
+updater.dispatcher.add_handler(CommandHandler('set', set_value))
+# The answer and confirmation
+updater.dispatcher.add_handler(MessageHandler([Filters.text], set_value))
+updater.dispatcher.add_handler(CommandHandler('cancel', cancel))
+updater.dispatcher.add_handler(CommandHandler('start', help))
+updater.dispatcher.add_handler(CommandHandler('help', help))
+
+# 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/timerbot.py

@@ -0,0 +1,92 @@
+#!/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
+import logging
+
+# Enable logging
+logging.basicConfig(
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+job_queue = None
+
+
+# Define a few command handlers. These usually take the two arguments bot and
+# update. Error handlers also receive the raised TelegramError object in error.
+def start(bot, update):
+    bot.sendMessage(update.message.chat_id, text='Hi! Use /set <seconds> to '
+                                                 'set a timer')
+
+
+def set(bot, update, args):
+    """ Adds a job to the queue """
+    chat_id = update.message.chat_id
+    try:
+        # args[0] should contain the time for the timer in seconds
+        due = int(args[0])
+        if due < 0:
+                bot.sendMessage(chat_id, text='Sorry we can not go back to future!')
+        def alarm(bot):
+            """ Inner function to send the alarm message """
+            bot.sendMessage(chat_id, text='Beep!')
+
+        # Add job to queue
+        job_queue.put(alarm, due, repeat=False)
+        bot.sendMessage(chat_id, text='Timer successfully set!')
+
+    except IndexError:
+        bot.sendMessage(chat_id, text='Usage: /set <seconds>')
+    except ValueError:
+        bot.sendMessage(chat_id, text='Usage: /set <seconds>')
+
+
+def error(bot, update, error):
+    logger.warn('Update "%s" caused error "%s"' % (update, error))
+
+
+def main():
+    global job_queue
+
+    updater = Updater("TOKEN")
+    job_queue = updater.job_queue
+
+    # 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))
+
+    # 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()

requirements-dev.txt

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

requirements.txt

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

setup.cfg

@@ -0,0 +1,17 @@
+[wheel]
+universal = 1
+
+[build_sphinx]
+source-dir = docs/source
+build-dir  = docs/build
+all_files  = 1
+
+[upload_sphinx]
+upload-dir = docs/build/html
+
+[flake8]
+max-line-length = 99
+
+[yapf]
+based_on_style = google
+column_limit = 99

setup.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-
 '''The setup and build script for the python-telegram-bot library.'''
 
 import os
@@ -13,33 +12,43 @@ def read(*paths):
         return f.read()
 
 
-setup(
-    name='python-telegram-bot',
-    version='2.5.1',
-    author='Leandro Toledo',
-    author_email='leandrotoledodesouza@gmail.com',
-    license='LGPLv3',
-    url='https://github.com/leandrotoledo/python-telegram-bot',
-    keywords='telegram bot api',
-    description='A Python wrapper around the Telegram Bot API',
-    long_description=(read('README.rst')),
-    packages=find_packages(exclude=['tests*']),
-    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',
-    ],
-)
+def requirements():
+    """Build the requirements list for this project"""
+    requirements_list = []
+
+    with open('requirements.txt') as requirements:
+        for install in requirements:
+            requirements_list.append(install.strip())
+
+    return requirements_list
+
+
+setup(name='python-telegram-bot',
+      version='4.1',
+      author='Leandro Toledo',
+      author_email='devs@python-telegram-bot.org',
+      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.3',
+          'Programming Language :: Python :: 3.4',
+          'Programming Language :: Python :: 3.5',
+      ],)

telegram/__init__.py

@@ -1,52 +1,105 @@
 #!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""A library that provides a Python interface to the Telegram Bot API"""
 
-"""
-    A library that provides a Python interface to the Telegram Bot API
-    Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Lesser Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU Lesser Public License for more details.
-
-    You should have received a copy of the GNU Lesser Public License
-    along with this program.  If not, see [http://www.gnu.org/licenses/].
-"""
-
-__author__ = 'leandrotoledodesouza@gmail.com'
-__version__ = '2.5.1'
+from sys import version_info
 
 from .base import TelegramObject
 from .user import User
-from .message import Message
-from .update import Update
-from .groupchat import GroupChat
+from .chat import Chat
 from .photosize import PhotoSize
 from .audio import Audio
+from .voice import Voice
 from .document import Document
 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 .forcereply import ForceReply
-from .inputfile import InputFile
 from .error import TelegramError
+from .inputfile import InputFile
+from .file import File
 from .nullhandler import NullHandler
 from .emoji import Emoji
+from .parsemode import ParseMode
+from .messageentity import MessageEntity
+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 .inputtextmessagecontent import InputTextMessageContent
+from .inputlocationmessagecontent import InputLocationMessageContent
+from .inputvenuemessagecontent import InputVenueMessageContent
+from .inputcontactmessagecontent import InputContactMessageContent
+from .update import Update
 from .bot import Bot
 
-__all__ = ['Bot', 'Emoji', 'TelegramError', 'InputFile', 'ReplyMarkup',
-           'ForceReply', 'ReplyKeyboardHide', 'ReplyKeyboardMarkup',
-           'UserProfilePhotos', 'ChatAction', 'Location', 'Contact',
-           'Video', 'Sticker', 'Document', 'Audio', 'PhotoSize', 'GroupChat',
-           'Update', 'Message', 'User', 'TelegramObject', 'NullHandler']
+__author__ = 'devs@python-telegram-bot.org'
+__version__ = '4.1'
+__all__ = ['Audio', 'Bot', 'Chat', 'ChatAction', 'ChosenInlineResult', 'CallbackQuery', 'Contact',
+           'Document', 'Emoji', 'File', 'ForceReply', 'InlineKeyboardButton',
+           'InlineKeyboardMarkup', 'InlineQuery', 'InlineQueryResult', 'InlineQueryResult',
+           'InlineQueryResultArticle', 'InlineQueryResultAudio', 'InlineQueryResultCachedAudio',
+           'InlineQueryResultCachedDocument', 'InlineQueryResultCachedGif',
+           'InlineQueryResultCachedMpeg4Gif', 'InlineQueryResultCachedPhoto',
+           'InlineQueryResultCachedSticker', 'InlineQueryResultCachedVideo',
+           'InlineQueryResultCachedVoice', 'InlineQueryResultContact', 'InlineQueryResultDocument',
+           'InlineQueryResultGif', 'InlineQueryResultLocation', 'InlineQueryResultMpeg4Gif',
+           'InlineQueryResultPhoto', 'InlineQueryResultVenue', 'InlineQueryResultVideo',
+           'InlineQueryResultVoice', 'InputContactMessageContent', 'InputFile',
+           'InputLocationMessageContent', 'InputMessageContent', 'InputTextMessageContent',
+           'InputVenueMessageContent', 'KeyboardButton', 'Location', 'Message', 'MessageEntity',
+           'NullHandler', 'ParseMode', 'PhotoSize', 'ReplyKeyboardHide', 'ReplyKeyboardMarkup',
+           'ReplyMarkup', 'Sticker', 'TelegramError', 'TelegramObject', 'Update', 'User',
+           'UserProfilePhotos', 'Venue', 'Video', 'Voice']
+
+if version_info < (2, 7):
+    from warnings import warn
+    warn("python-telegram-bot will stop supporting Python 2.6 in a future release. "
+         "Please upgrade your Python!")

telegram/audio.py

@@ -1,50 +1,69 @@
 #!/usr/bin/env python
-
-"""
-    A library that provides a Python interface to the Telegram Bot API
-    Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Lesser Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU Lesser Public License for more details.
-
-    You should have received a copy of the GNU Lesser Public License
-    along with this program.  If not, see [http://www.gnu.org/licenses/].
-"""
-
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains a object that represents a Telegram Audio."""
 
 from telegram import TelegramObject
 
 
 class Audio(TelegramObject):
-    def __init__(self,
-                 file_id,
-                 duration,
-                 mime_type=None,
-                 file_size=None):
-        self.file_id = file_id
-        self.duration = duration
-        self.mime_type = mime_type
-        self.file_size = file_size
+    """This object represents a Telegram Audio.
+
+    Attributes:
+        file_id (str):
+        duration (int):
+        performer (str):
+        title (str):
+        mime_type (str):
+        file_size (int):
+
+    Args:
+        file_id (str):
+        duration (int):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        performer (Optional[str]):
+        title (Optional[str]):
+        mime_type (Optional[str]):
+        file_size (Optional[int]):
+    """
+
+    def __init__(self, file_id, duration, **kwargs):
+        # Required
+        self.file_id = str(file_id)
+        self.duration = int(duration)
+        # Optionals
+        self.performer = kwargs.get('performer', '')
+        self.title = kwargs.get('title', '')
+        self.mime_type = str(kwargs.get('mime_type', ''))
+        self.file_size = int(kwargs.get('file_size', 0))
 
     @staticmethod
     def de_json(data):
-        return Audio(file_id=data.get('file_id', None),
-                     duration=data.get('duration', None),
-                     mime_type=data.get('mime_type', None),
-                     file_size=data.get('file_size', None))
+        """
+        Args:
+            data (str):
 
-    def to_dict(self):
-        data = {'file_id': self.file_id,
-                'duration': self.duration}
-        if self.mime_type:
-            data['mime_type'] = self.mime_type
-        if self.file_size:
-            data['file_size'] = self.file_size
-        return data
+        Returns:
+            telegram.Audio:
+        """
+        if not data:
+            return None
+
+        return Audio(**data)

telegram/base.py

@@ -1,30 +1,29 @@
 #!/usr/bin/env python
-
-"""
-    A library that provides a Python interface to the Telegram Bot API
-    Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Lesser Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU Lesser Public License for more details.
-
-    You should have received a copy of the GNU Lesser Public License
-    along with this program.  If not, see [http://www.gnu.org/licenses/].
-"""
-
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""Base class for Telegram Objects."""
 
 import json
-from abc import ABCMeta, abstractmethod
+from abc import ABCMeta
 
 
 class TelegramObject(object):
-    """Base class for most telegram object"""
+    """Base class for most telegram objects."""
 
     __metaclass__ = ABCMeta
 
@@ -36,11 +35,40 @@ class TelegramObject(object):
 
     @staticmethod
     def de_json(data):
-        raise NotImplementedError
+        """
+        Args:
+            data (str):
+
+        Returns:
+            telegram.TelegramObject:
+        """
+        if not data:
+            return None
+
+        data = data.copy()
+
+        return data
 
     def to_json(self):
+        """
+        Returns:
+            str:
+        """
         return json.dumps(self.to_dict())
 
-    @abstractmethod
     def to_dict(self):
-        return
+        """
+        Returns:
+            dict:
+        """
+        data = dict()
+
+        for key in iter(self.__dict__):
+            value = self.__dict__[key]
+            if value is not None:
+                if hasattr(value, 'to_dict'):
+                    data[key] = value.to_dict()
+                else:
+                    data[key] = value
+
+        return data

telegram/callbackquery.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains a object that represents a Telegram
+CallbackQuery"""
+
+from telegram import TelegramObject, Message, User
+
+
+class CallbackQuery(TelegramObject):
+    """This object represents a Telegram CallbackQuery."""
+
+    def __init__(self, id, from_user, data, **kwargs):
+        # Required
+        self.id = id
+        self.from_user = from_user
+        self.data = data
+        # Optionals
+        self.message = kwargs.get('message')
+        self.inline_message_id = kwargs.get('inline_message_id', '')
+
+    @staticmethod
+    def de_json(data):
+        if not data:
+            return None
+
+        data['from_user'] = User.de_json(data.get('from'))
+        data['message'] = Message.de_json(data.get('message'))
+
+        return CallbackQuery(**data)