python-telegram-bot · tsnoam · Jun 9, 2017 · May 21, 2017 · May 21, 2017 · May 21, 2017
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -29,6 +29,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Hugo Damer <https://github.com/HakimusGIT>`_
 - `Jacob Bom <https://github.com/bomjacob>`_
 - `JASON0916 <https://github.com/JASON0916>`_
+- `jeffffc <https://github.com/jeffffc>`_
 - `jh0ker <https://github.com/jh0ker>`_
 - `John Yong <https://github.com/whipermr5>`_
 - `jossalgon <https://github.com/jossalgon>`_

diff --git a/telegram/bot.py b/telegram/bot.py
@@ -1835,6 +1835,7 @@ def send_invoice(self,
                      photo_height=None,
                      need_name=None,
                      need_phone_number=None,
+                     need_email=None,
                      need_shipping_address=None,
                      is_flexible=None,
                      disable_notification=False,
@@ -1867,6 +1868,8 @@ def send_invoice(self,
                 the order
             need_phone_number (Optional[bool]): Pass True, if you require the user's phone number
                 to complete the order
+            need_email (Optional[bool]): Pass True, if you require the user's email to
+                complete the order
             need_shipping_address (Optional[bool]): Pass True, if you require the user's shipping
                 address to complete the order
             is_flexible (Optional[bool]): Pass True, if the final price depends on the shipping
@@ -1915,6 +1918,8 @@ def send_invoice(self,
             data['need_name'] = need_name
         if need_phone_number is not None:
             data['need_phone_number'] = need_phone_number
+        if need_email is not None:
+            data['need_email'] = need_email
         if need_shipping_address is not None:
             data['need_shipping_address'] = need_shipping_address
         if is_flexible is not None:
@@ -1926,7 +1931,9 @@ def answer_shipping_query(self,
                               shipping_query_id,
                               ok,
                               shipping_options=None,
-                              error_message=None):
+                              error_message=None,
+                              timeout=None,
+                              **kwargs):
         """
         If you sent an invoice requesting a shipping address and the parameter is_flexible was
         specified, the Bot API will send an Update with a shipping_query field to the bot. Use
@@ -1943,6 +1950,7 @@ def answer_shipping_query(self,
                 form that explains why it is impossible to complete the order (e.g. "Sorry,
                 delivery to your desired address is unavailable'). Telegram will display this
                 message to the user.
+            **kwargs (dict): Arbitrary keyword arguments.
 
         Returns:
             bool: On success, `True` is returned.
@@ -1951,18 +1959,32 @@ def answer_shipping_query(self,
             :class:`telegram.TelegramError`
 
         """
-        url = '{0]/answerShippingQuery'.format(self.base_url)
+
+        if ok is True and (shipping_options is None or error_message is not None):
+            raise TelegramError(
+                'answerShippingQuery: If ok is True, shipping_options '
+                'should not be empty and there should not be error_message')
+
+        if ok is False and (shipping_options is not None or error_message is None):
+            raise TelegramError(
+                'answerShippingQuery: If ok is False, error_message '
+                'should not be empty and there should not be shipping_options')
+
+        url_ = '{0}/answerShippingQuery'.format(self.base_url)
 
         data = {'shipping_query_id': shipping_query_id, 'ok': ok}
 
-        if shipping_options is not None:
+        if ok is True:
             data['shipping_options'] = shipping_options
         if error_message is not None:
             data['error_message'] = error_message
 
-        return url, data
+        result = self._request.post(url_, data, timeout=timeout)
 
-    def answer_pre_checkout_query(self, pre_checkout_query_id, ok, error_message=None):
+        return result
+
+    def answer_pre_checkout_query(self, pre_checkout_query_id, ok,
+                                  error_message=None, timeout=None, **kwargs):
         """
         If you sent an invoice requesting a shipping address and the parameter is_flexible was
         specified, the Bot API will send an Update with a shipping_query field to the bot.
@@ -1977,6 +1999,7 @@ def answer_pre_checkout_query(self, pre_checkout_query_id, ok, error_message=Non
                 "Sorry, somebody just bought the last of our amazing black T-shirts while you were
                 busy filling out your payment details. Please choose a different color or
                 garment!"). Telegram will display this message to the user.
+            **kwargs (dict): Arbitrary keyword arguments.
 
         Returns:
             bool: On success, `True` is returned.
@@ -1985,14 +2008,23 @@ def answer_pre_checkout_query(self, pre_checkout_query_id, ok, error_message=Non
             :class:`telegram.TelegramError`
 
         """
-        url = '{0]/answerPreCheckoutQuery'.format(self.base_url)
+
+        if not (ok ^ (error_message is None)):
+            raise TelegramError(
+                'answerPreCheckoutQuery: If ok is True, there should '
+                'not be error_message; if ok is False, error_message '
+                'should not be empty')
+
+        url_ = '{0}/answerPreCheckoutQuery'.format(self.base_url)
 
         data = {'pre_checkout_query_id': pre_checkout_query_id, 'ok': ok}
 
         if error_message is not None:
             data['error_message'] = error_message
 
-        return url, data
+        result = self._request.post(url_, data, timeout=timeout)
+
+        return result
 
     @staticmethod
     def de_json(data, bot):

diff --git a/telegram/ext/__init__.py b/telegram/ext/__init__.py
@@ -33,8 +33,11 @@
 from .stringregexhandler import StringRegexHandler
 from .typehandler import TypeHandler
 from .conversationhandler import ConversationHandler
+from .precheckoutqueryhandler import PreCheckoutQueryHandler
+from .shippingqueryhandler import ShippingQueryHandler
 
 __all__ = ('Dispatcher', 'JobQueue', 'Job', 'Updater', 'CallbackQueryHandler',
            'ChosenInlineResultHandler', 'CommandHandler', 'Handler', 'InlineQueryHandler',
            'MessageHandler', 'BaseFilter', 'Filters', 'RegexHandler', 'StringCommandHandler',
-           'StringRegexHandler', 'TypeHandler', 'ConversationHandler')
+           'StringRegexHandler', 'TypeHandler', 'ConversationHandler',
+           'PreCheckoutQueryHandler', 'ShippingQueryHandler')
diff --git a/telegram/ext/precheckoutqueryhandler.py b/telegram/ext/precheckoutqueryhandler.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2017
+# 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 the PreCheckoutQueryHandler class """
+
+from telegram import Update
+from .handler import Handler
+
+
+class PreCheckoutQueryHandler(Handler):
+    """
+    Handler class to handle Telegram PreCheckout callback queries.
+
+    Args:
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``check_update``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+            be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
+        pass_user_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``user_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the user that sent the update. For each update of
+            the same user, it will be the same ``dict``. Default is ``False``.
+        pass_chat_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``chat_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the chat that the update was sent in.
+            For each update in the same chat, it will be the same ``dict``. Default is ``False``.
+    """
+
+    def __init__(self,
+                 callback,
+                 pass_update_queue=False,
+                 pass_job_queue=False,
+                 pass_user_data=False,
+                 pass_chat_data=False):
+        super(PreCheckoutQueryHandler, self).__init__(
+            callback,
+            pass_update_queue=pass_update_queue,
+            pass_job_queue=pass_job_queue,
+            pass_user_data=pass_user_data,
+            pass_chat_data=pass_chat_data)
+
+    def check_update(self, update):
+        return isinstance(update, Update) and update.pre_checkout_query
+
+    def handle_update(self, update, dispatcher):
+        optional_args = self.collect_optional_args(dispatcher, update)
+        return self.callback(dispatcher.bot, update, **optional_args)
diff --git a/telegram/ext/shippingqueryhandler.py b/telegram/ext/shippingqueryhandler.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2017
+# 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 the ShippingQueryHandler class """
+
+from telegram import Update
+from .handler import Handler
+
+
+class ShippingQueryHandler(Handler):
+    """
+    Handler class to handle Telegram shipping callback queries.
+
+    Args:
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``check_update``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+            be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
+        pass_user_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``user_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the user that sent the update. For each update of
+            the same user, it will be the same ``dict``. Default is ``False``.
+        pass_chat_data (optional[bool]): If set to ``True``, a keyword argument called
+            ``chat_data`` will be passed to the callback function. It will be a ``dict`` you
+            can use to keep any data related to the chat that the update was sent in.
+            For each update in the same chat, it will be the same ``dict``. Default is ``False``.
+    """
+
+    def __init__(self,
+                 callback,
+                 pass_update_queue=False,
+                 pass_job_queue=False,
+                 pass_user_data=False,
+                 pass_chat_data=False):
+        super(ShippingQueryHandler, self).__init__(
+            callback,
+            pass_update_queue=pass_update_queue,
+            pass_job_queue=pass_job_queue,
+            pass_user_data=pass_user_data,
+            pass_chat_data=pass_chat_data)
+
+    def check_update(self, update):
+        return isinstance(update, Update) and update.shipping_query
+
+    def handle_update(self, update, dispatcher):
+        optional_args = self.collect_optional_args(dispatcher, update)
+        return self.callback(dispatcher.bot, update, **optional_args)
diff --git a/telegram/precheckoutquery.py b/telegram/precheckoutquery.py
@@ -35,6 +35,7 @@ class PreCheckoutQuery(TelegramObject):
         invoice_payload (str): Bot specified invoice payload
         shipping_option_id (Optional[str]): Identifier of the shipping option chosen by the user
         order_info (Optional[:class:`telegram.OrderInfo`]): Order info provided by the user
+        bot (Optional[Bot]): The Bot to use for instance methods
         **kwargs (dict): Arbitrary keyword arguments.
 
     """
@@ -47,6 +48,7 @@ def __init__(self,
                  invoice_payload,
                  shipping_option_id=None,
                  order_info=None,
+                 bot=None,
                  **kwargs):
         self.id = id
         self.from_user = from_user
@@ -56,6 +58,8 @@ def __init__(self,
         self.shipping_option_id = shipping_option_id
         self.order_info = order_info
 
+        self.bot = bot
+
         self._id_attrs = (self.id,)
 
     @staticmethod
@@ -88,3 +92,9 @@ def to_dict(self):
         data['from'] = data.pop('from_user', None)
 
         return data
+
+    def answer(self, *args, **kwargs):
+        """
+        Shortcut for ``bot.answerPreCheckoutQuery(update.pre_checkout_query.id, *args, **kwargs)``
+        """
+        return self.bot.answerPreCheckoutQuery(self.id, *args, **kwargs)
diff --git a/telegram/shippingquery.py b/telegram/shippingquery.py
@@ -32,16 +32,19 @@ class ShippingQuery(TelegramObject):
         from_user (:class:`telegram.User`): User who sent the query
         invoice_payload (str): Bot specified invoice payload
         shipping_address (:class:`telegram.ShippingQuery`): User specified shipping address
+        bot (Optional[Bot]): The Bot to use for instance methods
         **kwargs (dict): Arbitrary keyword arguments.
 
     """
 
-    def __init__(self, id, from_user, invoice_payload, shipping_address, **kwargs):
+    def __init__(self, id, from_user, invoice_payload, shipping_address, bot=None, **kwargs):
         self.id = id
         self.from_user = from_user
         self.invoice_payload = invoice_payload
         self.shipping_address = shipping_address
 
+        self.bot = bot
+
         self._id_attrs = (self.id,)
 
     @staticmethod
@@ -74,3 +77,7 @@ def to_dict(self):
         data['from'] = data.pop('from_user', None)
 
         return data
+
+    def answer(self, *args, **kwargs):
+        """Shortcut for ``bot.answerShippingQuery(update.shipping_query.id, *args, **kwargs)``"""
+        return self.bot.answerShippingQuery(self.id, *args, **kwargs)