From 3244417f6178c21d9ce9814dd3a0ad019967e1de Mon Sep 17 00:00:00 2001 From: Jacob Bom Date: Sun, 25 Sep 2016 00:30:04 +0200 Subject: [PATCH] Add docs for filters. --- docs/source/telegram.ext.filters.rst | 7 +++ docs/source/telegram.ext.rst | 1 + telegram/ext/__init__.py | 4 +- telegram/ext/filters.py | 85 ++++++++++++++++------------ tests/test_filters.py | 2 +- 5 files changed, 61 insertions(+), 38 deletions(-) create mode 100644 docs/source/telegram.ext.filters.rst diff --git a/docs/source/telegram.ext.filters.rst b/docs/source/telegram.ext.filters.rst new file mode 100644 index 000000000..a04a2d1c1 --- /dev/null +++ b/docs/source/telegram.ext.filters.rst @@ -0,0 +1,7 @@ +telegram.ext.filters module +=========================== + +.. automodule:: telegram.ext.filters + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/telegram.ext.rst b/docs/source/telegram.ext.rst index 51c652e4f..3fa83b1b1 100644 --- a/docs/source/telegram.ext.rst +++ b/docs/source/telegram.ext.rst @@ -15,6 +15,7 @@ Submodules telegram.ext.commandhandler telegram.ext.inlinequeryhandler telegram.ext.messagehandler + telegram.ext.filters telegram.ext.regexhandler telegram.ext.stringcommandhandler telegram.ext.stringregexhandler diff --git a/telegram/ext/__init__.py b/telegram/ext/__init__.py index 618013475..451354abe 100644 --- a/telegram/ext/__init__.py +++ b/telegram/ext/__init__.py @@ -27,7 +27,7 @@ from .commandhandler import CommandHandler from .handler import Handler from .inlinequeryhandler import InlineQueryHandler from .messagehandler import MessageHandler -from .filters import Filters +from .filters import BaseFilter, Filters from .regexhandler import RegexHandler from .stringcommandhandler import StringCommandHandler from .stringregexhandler import StringRegexHandler @@ -36,5 +36,5 @@ from .conversationhandler import ConversationHandler __all__ = ('Dispatcher', 'JobQueue', 'Job', 'Updater', 'CallbackQueryHandler', 'ChosenInlineResultHandler', 'CommandHandler', 'Handler', 'InlineQueryHandler', - 'MessageHandler', 'Filters', 'RegexHandler', 'StringCommandHandler', + 'MessageHandler', 'BaseFilter', 'Filters', 'RegexHandler', 'StringCommandHandler', 'StringRegexHandler', 'TypeHandler', 'ConversationHandler') diff --git a/telegram/ext/filters.py b/telegram/ext/filters.py index 5a529b052..fabbe0870 100644 --- a/telegram/ext/filters.py +++ b/telegram/ext/filters.py @@ -16,11 +16,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 MessageHandler class """ +""" This module contains the Filters for use with the MessageHandler class """ class BaseFilter(object): - """Base class for all Message Filters""" + """Base class for all Message Filters + + Subclassing from this class filters to be combined using bitwise operators: + + And: + + >>> (Filters.text & Filters.entity(MENTION) + + Or: + + >>> (Filters.audio | Filters.video) + + Also works with more than two filters: + + >>> (Filters.text & (Filters.entity(URL |Filters.entity(TEXT_LINK)))) + + If you want to create your own filters create a class inheriting from this class and implement + a `filter` method that returns a boolean: `True` if the message should be handled, `False` + otherwise. Note that the filters work only as class instances, not actual class objects + (so remember to initialize your filter classes). + """ def __call__(self, message): return self.filter(message) @@ -52,88 +72,87 @@ class MergedFilter(BaseFilter): class Filters(object): """ - Convenient namespace (class) & methods for the filter funcs of the - MessageHandler class. + Predefined filters for use with the `filter` argument of :class:`telegram.ext.MessageHandler`. """ - class Text(BaseFilter): + class _Text(BaseFilter): def filter(self, message): return bool(message.text and not message.text.startswith('/')) - text = Text() + text = _Text() - class Command(BaseFilter): + class _Command(BaseFilter): def filter(self, message): return bool(message.text and message.text.startswith('/')) - command = Command() + command = _Command() - class Audio(BaseFilter): + class _Audio(BaseFilter): def filter(self, message): return bool(message.audio) - audio = Audio() + audio = _Audio() - class Document(BaseFilter): + class _Document(BaseFilter): def filter(self, message): return bool(message.document) - document = Document() + document = _Document() - class Photo(BaseFilter): + class _Photo(BaseFilter): def filter(self, message): return bool(message.photo) - photo = Photo() + photo = _Photo() - class Sticker(BaseFilter): + class _Sticker(BaseFilter): def filter(self, message): return bool(message.sticker) - sticker = Sticker() + sticker = _Sticker() - class Video(BaseFilter): + class _Video(BaseFilter): def filter(self, message): return bool(message.video) - video = Video() + video = _Video() - class Voice(BaseFilter): + class _Voice(BaseFilter): def filter(self, message): return bool(message.voice) - voice = Voice() + voice = _Voice() - class Contact(BaseFilter): + class _Contact(BaseFilter): def filter(self, message): return bool(message.contact) - contact = Contact() + contact = _Contact() - class Location(BaseFilter): + class _Location(BaseFilter): def filter(self, message): return bool(message.location) - location = Location() + location = _Location() - class Venue(BaseFilter): + class _Venue(BaseFilter): def filter(self, message): return bool(message.venue) - venue = Venue() + venue = _Venue() - class StatusUpdate(BaseFilter): + class _StatusUpdate(BaseFilter): def filter(self, message): return bool(message.new_chat_member or message.left_chat_member @@ -143,16 +162,16 @@ class Filters(object): or message.migrate_to_chat_id or message.migrate_from_chat_id or message.pinned_message) - status_update = StatusUpdate() + status_update = _StatusUpdate() - class Forwarded(BaseFilter): + class _Forwarded(BaseFilter): def filter(self, message): return bool(message.forward_date) - forwarded = Forwarded() + forwarded = _Forwarded() - class Entity(BaseFilter): + class entity(BaseFilter): """Filters messages to only allow those which have a :class:`telegram.MessageEntity` where their `type` matches `entity_type`. @@ -168,7 +187,3 @@ class Filters(object): def filter(self, message): return any([entity.type == self.entity_type for entity in message.entities]) - -# We don't initialize since this filter accepts arguments. - - entity = Entity diff --git a/tests/test_filters.py b/tests/test_filters.py index fc7f99715..a7208968e 100644 --- a/tests/test_filters.py +++ b/tests/test_filters.py @@ -17,7 +17,7 @@ # 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 module contains a object that represents Tests for MessageHandler.Filters +This module contains a object that represents Tests for Filters for use with MessageHandler """ import sys