release v3.1.2

Fix file.download with custom_path

CHANGES.rst

@@ -1,3 +1,10 @@
+**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*

README.rst

@@ -155,9 +155,9 @@ _`Getting started`
 
 View the last release API documentation at: https://core.telegram.org/bots/api
 
-------
+--------------------
 _`The Updater class`
-------
+--------------------
 
 The ``Updater`` class is the new way to create bots with ``python-telegram-bot``. It provides an easy-to-use interface to the ``telegram.Bot`` by caring about getting new updates from telegram and forwarding them to the ``Dispatcher`` class. We can register handler functions in the ``Dispatcher`` to make our bot react to Telegram commands, messages and even arbitrary updates.
 
@@ -298,9 +298,9 @@ There are many more API methods, to read the full API documentation::
 
     $ pydoc telegram.Bot
 
------------
+----------
 _`Logging`
------------
+----------
 
 You can get logs in your main application by calling `logging` and setting the log level you want::
 
@@ -318,14 +318,24 @@ _`Examples`
 
 Here follows some examples to help you to get your own Bot up to speed:
 
-- `echobot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot.py>`_ replies back messages.
+- `echobot2 <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot2.py>`_ replies back messages.
 
-- `roboed <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/roboed.py>`_ talks to `Robô Ed <http://www.ed.conpet.gov.br/br/converse.php>`_.
+- `clibot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/clibot.py>`_ has a command line interface.
+
+- `Welcome Bot <https://github.com/jh0ker/welcomebot>`_ greets everyone who joins a group chat.
+
+Legacy examples (pre-3.0):
+
+- `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>`_.
 
 - `Simple-Echo-Telegram-Bot <https://github.com/sooyhwang/Simple-Echo-Telegram-Bot>`_ simple Python Telegram bot that echoes your input with Flask microframework, setWebhook method, and Google App Engine (optional) - by @sooyhwang.
 
 - `DevOps Reaction Bot <https://github.com/leandrotoledo/gae-devops-reaction-telegram-bot>`_ sends latest or random posts from `DevOps Reaction <http://devopsreactions.tumblr.com/>`_. Running on `Google App Engine <https://cloud.google.com/appengine>`_ (billing has to be enabled for fully Socket API support).
 
+Other notable examples:
+
 - `TwitterForwarderBot <https://github.com/franciscod/telegram-twitter-forwarder-bot>`_ forwards you tweets from people that you have subscribed to.
 
 ================

docs/source/conf.py

@@ -60,7 +60,7 @@ author = u'Leandro Toledo'
 # The short X.Y version.
 version = '3.1'
 # The full version, including alpha/beta/rc tags.
-release = '3.1.1'
+release = '3.1.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

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

@@ -1,22 +1,8 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-# Simple Bot to reply to Telegram messages
-# Copyright (C) 2015 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 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/].
-
+# 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.
@@ -27,8 +13,8 @@ Then, the bot is started and the CLI-Loop is entered, where all text inputs are
 inserted into the update queue for the bot to handle.
 
 Usage:
-Basic Echobot example, repeats messages. Reply to last chat from the command
-line by typing "/reply <text>"
+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.
 """
 
@@ -36,24 +22,20 @@ from telegram import Updater
 from telegram.dispatcher import run_async
 from time import sleep
 import logging
-import sys
 
-root = logging.getLogger()
-root.setLevel(logging.INFO)
-
-ch = logging.StreamHandler(sys.stdout)
-ch.setLevel(logging.INFO)
-formatter = \
-    logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-ch.setFormatter(formatter)
-root.addHandler(ch)
-
-last_chat_id = 0
+# 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
 
-# Command Handlers
+
+# 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):
     """ Answer in Telegram """
     bot.sendMessage(update.message.chat_id, text='Hi!')
@@ -87,25 +69,20 @@ def message(bot, update, **kwargs):
     """
     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.
+    your parameter list. The kwargs contain all optional parameters that are
     """
 
-    print(kwargs)
-
     sleep(2)  # IO-heavy operation here
     bot.sendMessage(update.message.chat_id, text='Echo: %s' %
                                                  update.message.text)
 
 
-def error(bot, update, error):
-    """ Print error to console """
-    logger.warn('Update %s caused error %s' % (update, error))
-
-
+# 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, you can get the argument
-    list by appending args to the function parameters.
+    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:
@@ -117,6 +94,9 @@ 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:
+    http://python-telegram-bot.readthedocs.org/en/latest/telegram.dispatcher.html
     """
     update_queue.put('/%s' % update)
 
@@ -125,28 +105,39 @@ def unknown_cli_command(bot, update):
     logger.warn("Command not found: %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=2)
+    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.addTelegramCommandHandler("start", start)
     dp.addTelegramCommandHandler("help", help)
     dp.addUnknownTelegramCommandHandler(unknown_command)
+    # Message handlers only receive updates that don't contain commands
     dp.addTelegramMessageHandler(message)
+    # Regex handlers will receive all updates on which their regex matches
     dp.addTelegramRegexHandler('.*', any_message)
 
+    # String handlers work pretty much the same
     dp.addStringCommandHandler('reply', cli_reply)
     dp.addUnknownStringCommandHandler(unknown_cli_command)
     dp.addStringRegexHandler('[^/].*', cli_noncommand)
 
+    # All TelegramErrors are caught for you and delivered to the error
+    # handler(s). Other types of Errors are not caught.
     dp.addErrorHandler(error)
 
     # Start the Bot and store the update Queue, so we can insert updates
-    update_queue = updater.start_polling(poll_interval=0.1, timeout=20)
+    update_queue = updater.start_polling(poll_interval=0.1, timeout=10)
 
     '''
     # Alternatively, run with webhook:
@@ -178,9 +169,9 @@ def main():
             updater.stop()
             break
 
-        # else, put the text into the update queue
+        # else, put the text into the update queue to be handled by our handlers
         elif len(text) > 0:
-            update_queue.put(text)  # Put command into queue
+            update_queue.put(text)
 
 if __name__ == '__main__':
     main()

examples/echobot2.py

@@ -2,53 +2,34 @@
 # -*- coding: utf-8 -*-
 #
 # Simple Bot to reply to Telegram messages
-# Copyright (C) 2015 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 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/].
-
+# 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.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
 
 Usage:
 Basic Echobot example, repeats messages.
-Type 'stop' on the command line to stop the bot.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
 """
 
 from telegram import Updater
 import logging
-import sys
 
 # Enable logging
-root = logging.getLogger()
-root.setLevel(logging.INFO)
-
-ch = logging.StreamHandler(sys.stdout)
-ch.setLevel(logging.DEBUG)
-formatter = \
-    logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-ch.setFormatter(formatter)
-root.addHandler(ch)
+logging.basicConfig(
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        level=logging.INFO)
 
 logger = logging.getLogger(__name__)
 
 
-# Command Handlers
+# 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!')
 
@@ -79,14 +60,15 @@ def main():
     # on noncommand i.e message - echo the message on Telegram
     dp.addTelegramMessageHandler(echo)
 
-    # on error - print error to stdout
+    # log all errors
     dp.addErrorHandler(error)
 
     # Start the Bot
-    updater.start_polling(timeout=5)
+    updater.start_polling()
 
-    # Run the bot until the user presses Ctrl-C or the process receives SIGINT,
-    # SIGTERM or SIGABRT
+    # 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__':

examples/legacy/echobot.py

@@ -2,21 +2,7 @@
 # -*- coding: utf-8 -*-
 #
 # Simple Bot to reply to Telegram messages
-# Copyright (C) 2015 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 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/].
-
+# This program is dedicated to the public domain under the CC0 license.
 
 import logging
 import telegram

examples/legacy/roboed.py

@@ -2,23 +2,7 @@
 # encoding: utf-8
 #
 # Robô Ed Telegram Bot
-# Copyright (C) 2015 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 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'
+# This program is dedicated to the public domain under the CC0 license.
 
 import logging
 import telegram

setup.py

@@ -26,7 +26,7 @@ def requirements():
 
 setup(
     name='python-telegram-bot',
-    version='3.1.1',
+    version='3.1.2',
     author='Leandro Toledo',
     author_email='devs@python-telegram-bot.org',
     license='LGPLv3',

telegram/__init__.py

@@ -19,7 +19,7 @@
 """A library that provides a Python interface to the Telegram Bot API"""
 
 __author__ = 'devs@python-telegram-bot.org'
-__version__ = '3.1.1'
+__version__ = '3.1.2'
 
 from .base import TelegramObject
 from .user import User

telegram/dispatcher.py

@@ -25,6 +25,7 @@ from functools import wraps
 from inspect import getargspec
 from threading import Thread, BoundedSemaphore, Lock
 from re import match
+from traceback import print_exc
 
 from telegram import (TelegramError, Update, NullHandler)
 
@@ -118,12 +119,11 @@ class Dispatcher:
             A dictionary that contains the result of
             re.match(matcher, ...).groupdict()
 
-    Attributes:
-
     Args:
         bot (telegram.Bot): The bot object that should be passed to the
-        handlers update_queue (queue.Queue): The synchronized queue that will
-        contain the updates.
+            handlers
+        update_queue (queue.Queue): The synchronized queue that will
+            contain the updates.
     """
     def __init__(self, bot, update_queue, workers=4):
         self.bot = bot
@@ -181,6 +181,10 @@ class Dispatcher:
                 self.logger.warn("Error was raised while processing Update.")
                 self.dispatchError(update, te)
 
+            # All other errors should not stop the thread, so just print them
+            except:
+                print_exc()
+
         self.logger.info('Dispatcher thread stopped')
 
     def stop(self):

telegram/file.py

@@ -74,7 +74,7 @@ class File(TelegramObject):
         url = self.file_path
 
         if custom_path:
-            filename = basename(custom_path)
+            filename = custom_path
         else:
             filename = basename(url)
 

telegram/updater.py

@@ -82,13 +82,13 @@ class Updater:
         self.is_idle = False
         self.httpd = None
 
-    def start_polling(self, poll_interval=1.0, timeout=10, network_delay=2):
+    def start_polling(self, poll_interval=0.0, timeout=10, network_delay=2):
         """
         Starts polling updates from Telegram.
 
         Args:
             poll_interval (Optional[float]): Time to wait between polling
-                updates from Telegram in seconds. Default is 1.0
+                updates from Telegram in seconds. Default is 0.0
             timeout (Optional[float]): Passed to Bot.getUpdates
             network_delay (Optional[float]): Passed to Bot.getUpdates
 
@@ -192,9 +192,11 @@ class Updater:
             except URLError as e:
                 self.logger.error("Error while getting Updates: %s" % e)
                 # increase waiting times on subsequent errors up to 30secs
-                if current_interval < 30:
+                if current_interval == 0:
+                    current_interval = 1
+                elif current_interval < 30:
                     current_interval += current_interval / 2
-                if current_interval > 30:
+                elif current_interval > 30:
                     current_interval = 30
 
         self.logger.info('Updater thread stopped')