add documentation and minor stuff

jh0ker · jh0ker · commit 0d0ad1334cb5 · 2016-04-16T16:36:12.000+02:00
diff --git a/telegram/ext/callbackqueryhandler.py b/telegram/ext/callbackqueryhandler.py
@@ -25,6 +25,17 @@
 
 
 class CallbackQueryHandler(Handler):
+    """
+    Handler class to handle Telegram callback queries.
+
+    Args:
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
 
     def __init__(self, callback, pass_update_queue=False):
         super(Handler).__init__(callback, pass_update_queue)
diff --git a/telegram/ext/choseninlineresulthandler.py b/telegram/ext/choseninlineresulthandler.py
@@ -25,6 +25,18 @@
 
 
 class ChosenInlineResultHandler(Handler):
+    """
+    Handler class to handle Telegram updates that contain a chosen inline
+    result.
+
+    Args:
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
 
     def __init__(self, callback, pass_update_queue=False):
         super(Handler).__init__(callback, pass_update_queue)
diff --git a/telegram/ext/commandhandler.py b/telegram/ext/commandhandler.py
@@ -17,14 +17,31 @@
 # 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 base class for handlers as used by the
-Dispatcher """
+""" This module contains the CommandHandler class """
 
 from .handler import Handler
 from telegram import Update
 
 
 class CommandHandler(Handler):
+    """
+    Handler class to handle Telegram commands. Commands are Telegram messages
+    that start with ``/``, optionally followed by an @ and the bot's
+    name and/or some additional text.
+
+    Args:
+        command (str): The name of the command this handler should listen for.
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_args (optional[bool]): If the handler should be passed the
+            arguments passed to the command as a keyword argument called `
+            `args``. It will contain a list of strings, which is the text
+             following the command split on spaces. Default is ``False``
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
 
     def __init__(self, command, callback, pass_args=False,
                  pass_update_queue=False):
diff --git a/telegram/ext/filters.py b/telegram/ext/filters.py
@@ -1,2 +1,23 @@
+#!/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 the filters used by the MessageHandler class """
+
 TEXT, AUDIO, DOCUMENT, PHOTO, STICKER, VIDEO, VOICE, CONTACT, LOCATION, \
     VENUE, STATUS_UPDATE = range(11)
diff --git a/telegram/ext/handler.py b/telegram/ext/handler.py
@@ -22,6 +22,18 @@
 
 
 class Handler(object):
+    """
+    The base class for all update handlers. You can create your own handlers
+    by inheriting from this class.
+
+    Args:
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If the callback should be passed
+            the update queue as a keyword argument called ``update_queue``. It
+            can be used to insert updates. Default is ``False``
+    """
 
     def __init__(self, callback, pass_update_queue=False):
         self.callback = callback
diff --git a/telegram/ext/inlinequeryhandler.py b/telegram/ext/inlinequeryhandler.py
@@ -25,6 +25,17 @@
 
 
 class InlineQueryHandler(Handler):
+    """
+    Handler class to handle Telegram inline queries.
+
+    Args:
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
 
     def __init__(self, callback, pass_update_queue=False):
         super(Handler).__init__(callback, pass_update_queue)
diff --git a/telegram/ext/messagehandler.py b/telegram/ext/messagehandler.py
@@ -27,6 +27,23 @@
 
 
 class MessageHandler(Handler):
+    """
+    Handler class to handle telegram messages. Messages are Telegram Updates
+    that do not contain a command. They might contain text, media or status
+    updates.
+
+    Args:
+        filters (list): A list of filters defined in ``telegram.ext.filters``.
+            All messages that match at least one of those filters will be
+            accepted. If ``bool(filters)`` evaluates to ``False``, messages are
+            not filtered.
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
 
     def __init__(self, filters, callback, pass_update_queue=False):
         super(Handler).__init__(callback, pass_update_queue)
diff --git a/telegram/ext/regexhandler.py b/telegram/ext/regexhandler.py
@@ -27,6 +27,27 @@
 
 
 class RegexHandler(Handler):
+    """
+    Handler class to handle Telegram updates based on a regex. It uses a
+    regular expression to check text messages. Read the documentation of the
+    ``re`` module for more information. The ``re.match`` function is used to
+    determine if an update should be handled by this handler.
+
+    Args:
+        pattern (str or Pattern): The regex pattern.
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_groups (optional[bool]): If the callback should be passed the
+            result of ``re.match(pattern, text).groups()`` as a keyword
+            argument called ``groups``. Default is ``False``
+        pass_groupdict (optional[bool]): If the callback should be passed the
+            result of ``re.match(pattern, text).groupdict()`` as a keyword
+            argument called ``groupdict``. Default is ``False``
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
 
     def __init__(self, pattern, callback, pass_groups=False,
                  pass_groupdict=False, pass_update_queue=False):
diff --git a/telegram/ext/stringcommandhandler.py b/telegram/ext/stringcommandhandler.py
@@ -24,6 +24,23 @@
 
 
 class StringCommandHandler(Handler):
+    """
+    Handler class to handle string commands. Commands are string updates
+    that start with ``/``.
+
+    Args:
+        command (str): The name of the command this handler should listen for.
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_args (optional[bool]): If the handler should be passed the
+            arguments passed to the command as a keyword argument called `
+            `args``. It will contain a list of strings, which is the text
+             following the command split on spaces. Default is ``False``
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
 
     def __init__(self, command, callback, pass_args=False,
                  pass_update_queue=False):
diff --git a/telegram/ext/stringregexhandler.py b/telegram/ext/stringregexhandler.py
@@ -26,6 +26,27 @@
 
 
 class RegexHandler(Handler):
+    """
+    Handler class to handle string updates based on a regex. It uses a
+    regular expression to check update content. Read the documentation of the
+    ``re`` module for more information. The ``re.match`` function is used to
+    determine if an update should be handled by this handler.
+
+    Args:
+        pattern (str or Pattern): The regex pattern.
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_groups (optional[bool]): If the callback should be passed the
+            result of ``re.match(pattern, update).groups()`` as a keyword
+            argument called ``groups``. Default is ``False``
+        pass_groupdict (optional[bool]): If the callback should be passed the
+            result of ``re.match(pattern, update).groupdict()`` as a keyword
+            argument called ``groupdict``. Default is ``False``
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
 
     def __init__(self, pattern, callback, pass_groups=False,
                  pass_groupdict=False, pass_update_queue=False):
diff --git a/telegram/ext/typehandler.py b/telegram/ext/typehandler.py
@@ -24,13 +24,32 @@
 
 
 class TypeHandler(Handler):
-
-    def __init__(self, type, callback, pass_update_queue=False):
+    """
+    Handler class to handle updates of custom types.
+
+    Args:
+        type (type): The ``type`` of updates this handler should process, as
+            determined by ``isinstance``
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        strict (optional[bool]): Use ``type`` instead of ``isinstance``.
+            Default is ``False``
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, type, callback, strict=False, pass_update_queue=False):
         super(Handler).__init__(callback, pass_update_queue)
         self.type = type
+        self.strict = strict
 
     def checkUpdate(self, update):
-        return isinstance(update, self.type)
+        if not self.strict:
+            return isinstance(update, self.type)
+        else:
+            return type(update) is self.type
 
     def handleUpdate(self, update, dispatcher):
         optional_args = self.collectOptionalArgs(dispatcher)
