From 0d0ad1334cb50f669b63f8f831b8931fea15ec5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jannes=20H=C3=B6ke?= Date: Sat, 16 Apr 2016 16:36:12 +0200 Subject: [PATCH] add documentation and minor stuff --- telegram/ext/callbackqueryhandler.py | 11 +++++++++++ telegram/ext/choseninlineresulthandler.py | 12 ++++++++++++ telegram/ext/commandhandler.py | 21 +++++++++++++++++++-- telegram/ext/filters.py | 21 +++++++++++++++++++++ telegram/ext/handler.py | 12 ++++++++++++ telegram/ext/inlinequeryhandler.py | 11 +++++++++++ telegram/ext/messagehandler.py | 17 +++++++++++++++++ telegram/ext/regexhandler.py | 21 +++++++++++++++++++++ telegram/ext/stringcommandhandler.py | 17 +++++++++++++++++ telegram/ext/stringregexhandler.py | 21 +++++++++++++++++++++ telegram/ext/typehandler.py | 23 +++++++++++++++++++++-- 11 files changed, 183 insertions(+), 4 deletions(-) diff --git a/telegram/ext/callbackqueryhandler.py b/telegram/ext/callbackqueryhandler.py index f82fc8764..beeb59f78 100644 --- a/telegram/ext/callbackqueryhandler.py +++ b/telegram/ext/callbackqueryhandler.py @@ -25,6 +25,17 @@ from telegram import Update 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 index 8d6897da7..ecffdfd04 100644 --- a/telegram/ext/choseninlineresulthandler.py +++ b/telegram/ext/choseninlineresulthandler.py @@ -25,6 +25,18 @@ from telegram import Update 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 index 1080966a8..9673cca51 100644 --- 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 index eb26da07a..8bebebe6e 100644 --- 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 +# +# 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 index 975243274..10646093b 100644 --- a/telegram/ext/handler.py +++ b/telegram/ext/handler.py @@ -22,6 +22,18 @@ Dispatcher """ 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 index a9b943b2a..67be6a624 100644 --- a/telegram/ext/inlinequeryhandler.py +++ b/telegram/ext/inlinequeryhandler.py @@ -25,6 +25,17 @@ from telegram import Update 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 index 862706275..6762d68f1 100644 --- a/telegram/ext/messagehandler.py +++ b/telegram/ext/messagehandler.py @@ -27,6 +27,23 @@ from .filters import * 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 index 5639025ec..44f44347d 100644 --- a/telegram/ext/regexhandler.py +++ b/telegram/ext/regexhandler.py @@ -27,6 +27,27 @@ from telegram import Update 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 index e52cd4470..41f1c78ce 100644 --- a/telegram/ext/stringcommandhandler.py +++ b/telegram/ext/stringcommandhandler.py @@ -24,6 +24,23 @@ from .handler import Handler 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 index 03720b75d..30a17c990 100644 --- a/telegram/ext/stringregexhandler.py +++ b/telegram/ext/stringregexhandler.py @@ -26,6 +26,27 @@ from .handler import Handler 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 index d41cae9f8..d1bedb06f 100644 --- a/telegram/ext/typehandler.py +++ b/telegram/ext/typehandler.py @@ -24,13 +24,32 @@ from .handler import Handler class TypeHandler(Handler): + """ + Handler class to handle updates of custom types. - def __init__(self, type, callback, pass_update_queue=False): + 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)