Added various deep linking tools

JosXa · JosXa · commit 9afe6802686b · 2018-02-01T23:06:14.000+01:00
diff --git a/examples/README.md b/examples/README.md
@@ -1,5 +1,7 @@
 # Examples
 
+**BEFORE YOU START:** In order to run all of the examples, you must insert the token you received from @BotFather in the file `settings.py`!
+
 The examples in this folder are small bots meant to show you how a bot that is written with `python-telegram-bot` looks like. Some bots focus on one specific aspect of the Telegram Bot API while others focus on one of the mechanics of this library. Except for the [`echobot.py`](#pure-api) example, they all use the high-level framework this library provides with the [`telegram.ext`](https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.html) submodule.
 
 All examples are licensed under the [CC0 License](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt) and are therefore fully dedicated to the public domain. You can use them as the base for your own bots without worrying about copyrights.
diff --git a/examples/__init__.py b/examples/__init__.py
diff --git a/examples/conversationbot.py b/examples/conversationbot.py
@@ -16,7 +16,7 @@
 Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """
-
+from examples.settings import TOKEN
 from telegram import (ReplyKeyboardMarkup, ReplyKeyboardRemove)
 from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters, RegexHandler,
                           ConversationHandler)
@@ -117,8 +117,8 @@ def error(bot, update, error):
 
 
 def main():
-    # Create the EventHandler and pass it your bot's token.
-    updater = Updater("TOKEN")
+    # Create the Updater and pass it your bot's token as a string.
+    updater = Updater(TOKEN)
 
     # Get the dispatcher to register handlers
     dp = updater.dispatcher
diff --git a/examples/conversationbot2.py b/examples/conversationbot2.py
@@ -16,7 +16,7 @@
 Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """
-
+from examples.settings import TOKEN
 from telegram import ReplyKeyboardMarkup
 from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters, RegexHandler,
                           ConversationHandler)
@@ -103,8 +103,8 @@ def error(bot, update, error):
 
 
 def main():
-    # Create the Updater and pass it your bot's token.
-    updater = Updater("TOKEN")
+    # Create the Updater and pass it your bot's token as a string.
+    updater = Updater(TOKEN)
 
     # Get the dispatcher to register handlers
     dp = updater.dispatcher
diff --git a/examples/deeplinking.py b/examples/deeplinking.py
@@ -0,0 +1,109 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""Bot that explains Telegram's "Deep Linking Parameters" functionality.
+
+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:
+Deep Linking example. Send /start to get the link.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+import logging
+
+from examples.settings import TOKEN
+from telegram import ParseMode
+from telegram.ext import Updater, CommandHandler, Filters
+# Enable logging
+from telegram.utils import helpers
+
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+# Define constants the will allow us to reuse the deep-linking parameters.
+CHECK_THIS_OUT = 'check-this-out'
+USING_ENTITIES = 'using-entities-here'
+SO_COOL = 'so-cool'
+
+
+def start(bot, update):
+    """Send a deep-linked URL when the command /start is issued."""
+    url = helpers.create_deep_linked_url(bot.get_me().username, CHECK_THIS_OUT)
+    text = "Feel free to tell your friends about it:\n\n" + url
+    update.message.reply_text(text)
+
+
+def deep_linked_level_1(bot, update):
+    """Reached through the CHECK_THIS_OUT payload"""
+    url = helpers.create_deep_linked_url(bot.get_me().username, SO_COOL)
+    text = "Awesome, you just accessed hidden functionality!\n\nContinue here: " + url
+    update.message.reply_text(text)
+
+
+def deep_linked_level_2(bot, update):
+    """Reached through the SO_COOL payload"""
+    url = helpers.create_deep_linked_url(bot.get_me().username, USING_ENTITIES)
+    text = "You can also mask the deep-linked URLs as links: " \
+           "[▶️ CLICK HERE]({0}).".format(url)
+    update.message.reply_text(text, parse_mode=ParseMode.MARKDOWN, disable_web_page_preview=True)
+
+
+def deep_linked_level_3(bot, update, args):
+    """Reached through the USING_ENTITIES payload"""
+    payload = args
+    update.message.reply_text("Congratulations! This is as deep as it gets 👏🏻\n\n"
+                              "The payload was: {0}".format(payload))
+
+
+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 bot's token as a string.
+    updater = Updater(TOKEN)
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # Register a deep-linking handler
+    dp.add_handler(CommandHandler("start", deep_linked_level_1, Filters.regex(CHECK_THIS_OUT)))
+
+    # This one works with a textual link instead of an URL
+    dp.add_handler(CommandHandler("start", deep_linked_level_2, Filters.regex(SO_COOL)))
+
+    # We can also pass on the deep-linking payload
+    dp.add_handler(CommandHandler("start",
+                                  deep_linked_level_3,
+                                  Filters.regex(USING_ENTITIES),
+                                  pass_args=True))
+
+    # Make sure the deep-linking handlers occur *before* the normal /start handler.
+    dp.add_handler(CommandHandler("start", start))
+
+    # 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/examples/echobot.py b/examples/echobot.py
@@ -7,19 +7,20 @@
 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
 
+import telegram
+from examples.settings import TOKEN
+from telegram.error import NetworkError, Unauthorized
 
 update_id = None
 
 
 def main():
     """Run the bot."""
     global update_id
-    # Telegram Bot Authorization Token
-    bot = telegram.Bot('TOKEN')
+    # Telegram Bot Authorization Token as string
+    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.
diff --git a/examples/echobot2.py b/examples/echobot2.py
@@ -16,7 +16,7 @@
 Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """
-
+from examples.settings import TOKEN
 from telegram.ext import Updater, CommandHandler, MessageHandler, Filters
 import logging
 
@@ -51,8 +51,8 @@ def error(bot, update, error):
 
 def main():
     """Start the bot."""
-    # Create the EventHandler and pass it your bot's token.
-    updater = Updater("TOKEN")
+    # Create the Updater and pass it your bot's token as a string.
+    updater = Updater(TOKEN)
 
     # Get the dispatcher to register handlers
     dp = updater.dispatcher
diff --git a/examples/inlinebot.py b/examples/inlinebot.py
@@ -20,6 +20,7 @@
 
 import re
 
+from examples.settings import TOKEN
 from telegram.utils.helpers import escape_markdown
 
 from telegram import InlineQueryResultArticle, ParseMode, \
@@ -77,8 +78,8 @@ def error(bot, update, error):
 
 
 def main():
-    # Create the Updater and pass it your bot's token.
-    updater = Updater("TOKEN")
+    # Create the Updater and pass it your bot's token as a string.
+    updater = Updater(TOKEN)
 
     # Get the dispatcher to register handlers
     dp = updater.dispatcher
diff --git a/examples/inlinekeyboard.py b/examples/inlinekeyboard.py
@@ -5,6 +5,8 @@
 # This program is dedicated to the public domain under the CC0 license.
 """
 import logging
+
+from examples.settings import TOKEN
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup
 from telegram.ext import Updater, CommandHandler, CallbackQueryHandler
 
@@ -42,8 +44,8 @@ def error(bot, update, error):
 
 
 def main():
-    # Create the Updater and pass it your bot's token.
-    updater = Updater("TOKEN")
+    # Create the Updater and pass it your bot's token as a string.
+    updater = Updater(TOKEN)
 
     updater.dispatcher.add_handler(CommandHandler('start', start))
     updater.dispatcher.add_handler(CallbackQueryHandler(button))
diff --git a/examples/paymentbot.py b/examples/paymentbot.py
@@ -5,7 +5,7 @@
 
 This program is dedicated to the public domain under the CC0 license.
 """
-
+from examples.settings import TOKEN
 from telegram import (LabeledPrice, ShippingOption)
 from telegram.ext import (Updater, CommandHandler, MessageHandler,
                           Filters, PreCheckoutQueryHandler, ShippingQueryHandler)
@@ -112,8 +112,8 @@ def successful_payment_callback(bot, update):
 
 
 def main():
-    # Create the EventHandler and pass it your bot's token.
-    updater = Updater(token="BOT_TOKEN")
+    # Create the Updater and pass it your bot's token as a string.
+    updater = Updater(TOKEN)
 
     # Get the dispatcher to register handlers
     dp = updater.dispatcher
diff --git a/examples/settings.py b/examples/settings.py
@@ -0,0 +1,2 @@
+# Insert your token to be able to run all of the examples
+TOKEN = "YOUR_TOKEN_HERE"
diff --git a/examples/timerbot.py b/examples/timerbot.py
@@ -18,7 +18,7 @@
 Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """
-
+from examples.settings import TOKEN
 from telegram.ext import Updater, CommandHandler
 import logging
 
@@ -79,8 +79,8 @@ def error(bot, update, error):
 
 
 def main():
-    """Run bot."""
-    updater = Updater("TOKEN")
+    # Create the Updater and pass it your bot's token as a string.
+    updater = Updater(TOKEN)
 
     # Get the dispatcher to register handlers
     dp = updater.dispatcher
diff --git a/telegram/ext/filters.py b/telegram/ext/filters.py
@@ -17,6 +17,8 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the Filters for use with the MessageHandler class."""
+
+import re
 from telegram import Chat
 from future.utils import string_types
 
@@ -171,32 +173,31 @@ def filter(self, message):
     command = _Command()
     """:obj:`Filter`: Messages starting with ``/``."""
 
-
-    class argument_equals(BaseFilter):
+    class regex(BaseFilter):
         """
-        Filters /commands with a specific argument value. Useful for deep-linking.
+        Filters updates by searching for an occurence of ``pattern`` in the message text.
+        The ``re.search`` function is used to determine whether an update should be filtered.
+        Refer to the documentation of the ``re`` module for more information.
+
+        Note: Does not allow passing groups or a groupdict like the ``RegexHandler`` yet,
+        but this will probably be implemented in a future update, gradually phasing out the
+        RegexHandler (see https://github.com/python-telegram-bot/python-telegram-bot/issues/835).
 
         Examples:
-            Example ``CommandHandler("start", deep_linked_callback,
-            Filters.argument_equals('parameter'))``
+            Example ``CommandHandler("start", deep_linked_callback, Filters.regex('parameter'))``
 
         Args:
-            argument(:obj:`str`): String to compare with command arguments
-
-        """
-        """:obj:`Filter`: 
+            pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
         """
 
-        def __init__(self, argument):
-            self.argument = argument
-            self.name = 'Filters.argument_equals({})'.format(self.argument)
+        def __init__(self, pattern):
+            if isinstance(pattern, string_types):
+                pattern = re.compile(pattern)
+            self.pattern = pattern
+            self.name = 'Filters.regex({})'.format(self.pattern)
 
         def filter(self, message):
-            if ' ' in message.text:
-                return bool(message.text and message.text.startswith('/') and
-                            message.text.split(' ', 1)[1] == self.argument)
-            else:
-                return False
+            return bool(re.search(self.pattern, message.text))
 
 
     class _Reply(BaseFilter):
diff --git a/telegram/utils/helpers.py b/telegram/utils/helpers.py
@@ -113,3 +113,40 @@ def mention_markdown(user_id, name):
     """
     if isinstance(user_id, int):
         return '[{}](tg://user?id={})'.format(escape_markdown(name), user_id)
+
+
+def create_deep_linked_url(bot_username, payload=None):
+    """
+    Creates a deep-linked URL for this ``bot_username`` with the specified ``payload``.
+    See  https://core.telegram.org/bots#deep-linking  to learn more.
+
+    The ``payload`` may consist of the following characters: ``A-Z, a-z, 0-9, _, -``
+
+    Note: Works well in conjunction with
+    ``CommandHandler("start", callback, Filters.regex('payload')``.
+
+    Examples:
+        Example ``create_deep_linked_url(bot.get_me().username, "some-params")``
+
+    Args:
+        bot_username (:obj:`str`) The username to link to
+        payload (:obj:`str`) Parameters to encode in the created URL
+
+    Returns:
+        :obj:`str`: An URL to start the bot with specific parameters
+    """
+    base_url = 'https://t.me/{}'.format(bot_username)
+    if not payload:
+        return base_url
+
+    if len(payload) > 64:
+        raise ValueError("The deep-linking payload must not exceed 64 characters.")
+
+    if not re.match(r'^[A-Za-z0-9_-]+$', payload):
+        raise ValueError("Only the following characters are allowed for deep-linked "
+                         "URLs: A-Z, a-z, 0-9, _ and -")
+
+    return '{0}?start={1}'.format(
+        base_url,
+        payload
+    )
diff --git a/tests/test_filters.py b/tests/test_filters.py
diff --git a/tests/test_helpers.py b/tests/test_helpers.py
