python-telegram-bot · jsmnbom · Aug 29, 2018 · Jul 26, 2018 · Jul 26, 2018 · Jul 26, 2018
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,6 +1,49 @@
 =======
 Changes
 =======
+
+*Released 11.0.0*
+
+Fully support Bot API version 4.0!
+
+Telegram Passport (`#1174`_):
+
+- Add full support for telegram passport.
+    - New types: PassportData, PassportFile, EncryptedPassportElement, EncryptedCredentials, PassportElementError, PassportElementErrorDataField, PassportElementErrorFrontSide, PassportElementErrorReverseSide, PassportElementErrorSelfie, PassportElementErrorFile and PassportElementErrorFiles.
+    - New bot method: set_passport_data_errors
+    - New filter: Filters.passport_data
+    - Field passport_data field on Message
+    - PassportData is automagically decrypted when you specify your private key when creating Updater or Bot.
+    - PassportFiles is also automagically decrypted as you download/retrieve them.
+- See new passportbot.py example for details on how to use, or go to `our telegram passport wiki page`_ for more info
+- NOTE: Passport decryption requires new dependency `cryptography`.
+
+Inputfile rework (`#1184`_):
+
+- Change how Inputfile is handled internally
+- This allows support for specifying the thumbnails of photos and videos using the thumb= argument in the different send\_ methods.
+- Also allows Bot.send_media_group to actually finally send more than one media.
+- Add thumb to Audio, Video and Videonote
+- Add Bot.edit_message_media together with InputMediaAnimation, InputMediaAudio, and inputMediaDocument.
+
+Other Bot API 4.0 changes:
+
+- Add forusquare_type to Venue, InlineQueryResultVenue, InputVenueMessageContent, and Bot.send_venue. (`#1170`_)
+- Add vCard support by adding vcard field to Contact, InlineQueryResultContact, InputContactMessageContent, and Bot.send_contact. (`#1166`_)
+- Support new message entities: CASHTAG and PHONE_NUMBER. (`#1179`_)
+    - Cashtag seems to be things like `$USD` and `$GBP`, but it seems telegram doesn't currently send them to bots.
+    - Phone number also seems to have limited support for now
+- Add Bot.send_animation, add width, height, and duration to Animation, and add Filters.animation. (`#1172`_)
+
+
+.. _`#1174`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1174
+.. _`#1184`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1184
+.. _`#1170`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1170
+.. _`#1166`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1166
+.. _`#1179`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1179
+.. _`#1172`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1172
+.. _`our telegram passport wiki page`: https://git.io/fAvYd
+
 **2018-05-02**
 *Released 10.1.0*
 

diff --git a/README.rst b/README.rst
@@ -95,7 +95,7 @@ make the development of bots easy and straightforward. These classes are contain
 Telegram API support
 ====================
 
-All types and methods of the Telegram Bot API 3.6 are supported.
+All types and methods of the Telegram Bot API **4.0** are supported.
 
 ==========
 Installing

diff --git a/docs/source/telegram.credentials.rst b/docs/source/telegram.credentials.rst
@@ -0,0 +1,6 @@
+telegram.Credentials
+====================
+
+.. autoclass:: telegram.Credentials
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.datacredentials.rst b/docs/source/telegram.datacredentials.rst
@@ -0,0 +1,6 @@
+telegram.DataCredentials
+========================
+
+.. autoclass:: telegram.DataCredentials
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.encryptedcredentials.rst b/docs/source/telegram.encryptedcredentials.rst
@@ -0,0 +1,6 @@
+telegram.EncryptedCredentials
+=============================
+
+.. autoclass:: telegram.EncryptedCredentials
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.encryptedpassportelement.rst b/docs/source/telegram.encryptedpassportelement.rst
@@ -0,0 +1,6 @@
+telegram.EncryptedPassportElement
+=================================
+
+.. autoclass:: telegram.EncryptedPassportElement
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.filecredentials.rst b/docs/source/telegram.filecredentials.rst
@@ -0,0 +1,6 @@
+telegram.FileCredentials
+========================
+
+.. autoclass:: telegram.FileCredentials
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.iddocumentdata.rst b/docs/source/telegram.iddocumentdata.rst
@@ -0,0 +1,6 @@
+telegram.IdDocumentData
+=======================
+
+.. autoclass:: telegram.IdDocumentData
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.inputmediaanimation.rst b/docs/source/telegram.inputmediaanimation.rst
@@ -0,0 +1,6 @@
+telegram.InputMediaAnimation
+============================
+
+.. autoclass:: telegram.InputMediaAnimation
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.inputmediaaudio.rst b/docs/source/telegram.inputmediaaudio.rst
@@ -0,0 +1,6 @@
+telegram.InputMediaAudio
+========================
+
+.. autoclass:: telegram.InputMediaAudio
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.inputmediadocument.rst b/docs/source/telegram.inputmediadocument.rst
@@ -0,0 +1,6 @@
+telegram.InputMediaDocument
+===========================
+
+.. autoclass:: telegram.InputMediaDocument
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.passportdata.rst b/docs/source/telegram.passportdata.rst
@@ -0,0 +1,6 @@
+telegram.PassportData
+=====================
+
+.. autoclass:: telegram.PassportData
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.passportelementerror.rst b/docs/source/telegram.passportelementerror.rst
@@ -0,0 +1,6 @@
+telegram.PassportElementError
+=============================
+
+.. autoclass:: telegram.PassportElementError
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.passportelementerrordatafield.rst b/docs/source/telegram.passportelementerrordatafield.rst
@@ -0,0 +1,6 @@
+telegram.PassportElementErrorDataField
+======================================
+
+.. autoclass:: telegram.PassportElementErrorDataField
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.passportelementerrorfile.rst b/docs/source/telegram.passportelementerrorfile.rst
@@ -0,0 +1,6 @@
+telegram.PassportElementErrorFile
+=================================
+
+.. autoclass:: telegram.PassportElementErrorFile
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.passportelementerrorfiles.rst b/docs/source/telegram.passportelementerrorfiles.rst
@@ -0,0 +1,6 @@
+telegram.PassportElementErrorFiles
+==================================
+
+.. autoclass:: telegram.PassportElementErrorFiles
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.passportelementerrorfrontside.rst b/docs/source/telegram.passportelementerrorfrontside.rst
@@ -0,0 +1,6 @@
+telegram.PassportElementErrorFrontSide
+======================================
+
+.. autoclass:: telegram.PassportElementErrorFrontSide
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.passportelementerrorreverseside.rst b/docs/source/telegram.passportelementerrorreverseside.rst
@@ -0,0 +1,6 @@
+telegram.PassportElementErrorReverseSide
+========================================
+
+.. autoclass:: telegram.PassportElementErrorReverseSide
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.passportfile.rst b/docs/source/telegram.passportfile.rst
@@ -0,0 +1,6 @@
+telegram.PassportFile
+=====================
+
+.. autoclass:: telegram.PassportFile
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.personaldetails.rst b/docs/source/telegram.personaldetails.rst
@@ -0,0 +1,6 @@
+telegram.PersonalDetails
+========================
+
+.. autoclass:: telegram.PersonalDetails
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.residentialaddress.rst b/docs/source/telegram.residentialaddress.rst
@@ -0,0 +1,6 @@
+telegram.ResidentialAddress
+===========================
+
+.. autoclass:: telegram.ResidentialAddress
+    :members:
+    :show-inheritance:
diff --git a/docs/source/telegram.rst b/docs/source/telegram.rst
@@ -5,6 +5,7 @@ telegram package
 
    telegram.ext
    telegram.utils
+   telegram.animation
    telegram.audio
    telegram.bot
    telegram.callbackquery
@@ -22,6 +23,9 @@ telegram package
    telegram.inlinekeyboardmarkup
    telegram.inputfile
    telegram.inputmedia
+   telegram.inputmediaanimation
+   telegram.inputmediaaudio
+   telegram.inputmediadocument
    telegram.inputmediaphoto
    telegram.inputmediavideo
    telegram.keyboardbutton
@@ -106,10 +110,33 @@ Games
 .. toctree::
 
    telegram.game
-   telegram.animation
    telegram.callbackgame
    telegram.gamehighscore
 
+Passport
+--------
+
+.. toctree::
+
+    telegram.passportelementerror
+    telegram.passportelementerrorfile
+    telegram.passportelementerrorreverseside
+    telegram.passportelementerrorfrontside
+    telegram.passportelementerrorfiles
+    telegram.passportelementerrordatafield
+    telegram.passportelementerrorfile
+    telegram.credentials
+    telegram.datacredentials
+    telegram.securedata
+    telegram.filecredentials
+    telegram.iddocumentdata
+    telegram.personaldetails
+    telegram.residentialaddress
+    telegram.passportdata
+    telegram.passportfile
+    telegram.encryptedpassportelement
+    telegram.encryptedcredentials
+
 
 Module contents
 ---------------

diff --git a/docs/source/telegram.securedata.rst b/docs/source/telegram.securedata.rst
@@ -0,0 +1,6 @@
+telegram.SecureData
+===================
+
+.. autoclass:: telegram.SecureData
+    :members:
+    :show-inheritance:
diff --git a/examples/passportbot.html b/examples/passportbot.html
@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>Telegram passport test!</title>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <!--- Needs file from https://github.com/TelegramMessenger/TGPassportJsSDK downloaded --->
+    <script src="telegram-passport.js"></script>
+    <script>
+        "use strict";
+
+        Telegram.Passport.createAuthButton('telegram_passport_auth', {
+            bot_id:       BOT_ID, // YOUR BOT ID
+            scope:        ['id_document', 'phone_number', 'email'], // WHAT DATA YOU WANT TO RECEIVE
+            public_key:   '-----BEGIN PUBLIC KEY----- ...', // YOUR PUBLIC KEY
+            payload:      'thisisatest', // YOUR BOT WILL RECEIVE THIS DATA WITH THE REQUEST
+            callback_url: 'https://example.org' // TELEGRAM WILL SEND YOUR USER BACK TO THIS URL
+        });
+
+    </script>
+</head>
+<body>
+<h1>Telegram passport test</h1>
+
+<div id="telegram_passport_auth"></div>
+</body>
+</html>
diff --git a/examples/passportbot.py b/examples/passportbot.py
@@ -0,0 +1,99 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to print/download all incoming passport data
+# This program is dedicated to the public domain under the CC0 license.
+"""
+See https://telegram.org/blog/passport for info about what telegram passport is.
+
+See https://git.io/fAvYd for how to use Telegram Passport properly with python-telegram-bot.
+
+"""
+import logging
+
+from telegram.ext import Updater, MessageHandler, Filters
+
+# Enable logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.DEBUG)
+
+logger = logging.getLogger(__name__)
+
+
+def msg(bot, update):
+    # If we received any passport data
+    passport_data = update.message.passport_data
+    if passport_data:
+        # If our payload doesn't match what we think, this Update did not originate from us
+        # Ideally you would randomize the payload on the server
+        if passport_data.decrypted_credentials.payload != 'thisisatest':
+            return
+
+        # Print the decrypted credential data
+        # For all elements
+        # Print their decrypted data
+        # Files will be downloaded to current directory
+        for data in passport_data.decrypted_data:  # This is where the data gets decrypted
+            if data.type == 'phone_number':
+                print('Phone: ', data.phone_number)
+            elif data.type == 'email':
+                print('Email: ', data.email)
+            if data.type in ('personal_details', 'passport', 'driver_license', 'identity_card',
+                             'identity_passport', 'address'):
+                print(data.type, data.data)
+            if data.type in ('utility_bill', 'bank_statement', 'rental_agreement',
+                             'passport_registration', 'temporary_registration'):
+                print(data.type, len(data.files), 'files')
+                for file in data.files:
+                    actual_file = file.get_file()
+                    print(actual_file)
+                    actual_file.download()
+            if data.type in ('passport', 'driver_license', 'identity_card',
+                             'internal_passport'):
+                if data.front_side:
+                    file = data.front_side.get_file()
+                    print(data.type, file)
+                    file.download()
+            if data.type in ('driver_license' and 'identity_card'):
+                if data.reverse_side:
+                    file = data.reverse_side.get_file()
+                    print(data.type, file)
+                    file.download()
+            if data.type in ('passport', 'driver_license', 'identity_card',
+                             'internal_passport'):
+                if data.selfie:
+                    file = data.selfie.get_file()
+                    print(data.type, file)
+                    file.download()
+
+
+def error(bot, update, error):
+    """Log Errors caused by Updates."""
+    logger.warning('Update "%s" caused error "%s"', update, error)
+
+
+def main():
+    """Start the bot."""
+    # Create the Updater and pass it your token and private key
+    updater = Updater("TOKEN", private_key=open('private.key', 'rb').read())
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # On messages that include passport data call msg
+    dp.add_handler(MessageHandler(Filters.passport_data, msg))
+
+    # log all errors
+    dp.add_error_handler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Run the bot until you press Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/requirements.txt b/requirements.txt
@@ -1,2 +1,3 @@
 future>=0.16.0
 certifi
+cryptography