Skip to content

Commit

Permalink
Update class and methods docstring in filters to match the same conve…
Browse files Browse the repository at this point in the history 
…ntion.

Most of the code bases there is convention to start docstring with a new
line.
  • Loading branch information
@rglsk
rglsk committed Oct 1, 2022
1 parent 9b9064f commit cbdbd57
Showing 1 changed file with 60 additions and 30 deletions.
90 changes: 60 additions & 30 deletions telegram/ext/filters.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,8 @@


class BaseFilter:
"""Base class for all Filters.
"""
Base class for all Filters.
Filters subclassing from this class can combined using bitwise operators:
Expand Down Expand Up @@ -234,7 +235,8 @@ def __repr__(self) -> str:


class MessageFilter(BaseFilter):
"""Base class for all Message Filters. In contrast to :class:`UpdateFilter`, the object passed
"""
Base class for all Message Filters. In contrast to :class:`UpdateFilter`, the object passed
to :meth:`filter` is :obj:`telegram.Update.effective_message`.
Please see :class:`BaseFilter` for details on how to create custom filters.
Expand All @@ -260,7 +262,8 @@ def check_update( # type: ignore[override]

@abstractmethod
def filter(self, message: Message) -> Optional[Union[bool, DataDict]]:
"""This method must be overwritten.
"""
This method must be overwritten.
Args:
message (:class:`telegram.Message`): The message that is tested.
Expand All @@ -272,7 +275,8 @@ def filter(self, message: Message) -> Optional[Union[bool, DataDict]]:


class UpdateFilter(BaseFilter):
"""Base class for all Update Filters. In contrast to :class:`MessageFilter`, the object
"""
Base class for all Update Filters. In contrast to :class:`MessageFilter`, the object
passed to :meth:`filter` is an instance of :class:`telegram.Update`, which allows to create
filters like :attr:`telegram.ext.filters.UpdateType.EDITED_MESSAGE`.
Expand All @@ -298,7 +302,8 @@ def check_update( # type: ignore[override]

@abstractmethod
def filter(self, update: Update) -> Optional[Union[bool, DataDict]]:
"""This method must be overwritten.
"""
This method must be overwritten.
Args:
update (:class:`telegram.Update`): The update that is tested.
Expand All @@ -310,7 +315,8 @@ def filter(self, update: Update) -> Optional[Union[bool, DataDict]]:


class _InvertedFilter(UpdateFilter):
"""Represents a filter that has been inverted.
"""
Represents a filter that has been inverted.
Args:
f: The filter to invert.
Expand All @@ -336,7 +342,8 @@ def name(self, name: str) -> NoReturn:


class _MergedFilter(UpdateFilter):
"""Represents a filter consisting of two other filters.
"""
Represents a filter consisting of two other filters.
Args:
base_filter: Filter 1 of the merged filter.
Expand Down Expand Up @@ -424,7 +431,8 @@ def name(self, name: str) -> NoReturn:


class _XORFilter(UpdateFilter):
"""Convenience filter acting as wrapper for :class:`MergedFilter` representing the XOR gate
"""
Convenience filter acting as wrapper for :class:`MergedFilter` representing the XOR gate
for two filters.
Args:
Expand Down Expand Up @@ -500,7 +508,8 @@ def filter(self, message: Message) -> bool:


class Caption(MessageFilter):
"""Messages with a caption. If a list of strings is passed, it filters messages to only
"""
Messages with a caption. If a list of strings is passed, it filters messages to only
allow those whose caption is appearing in the given list.
Examples:
Expand Down Expand Up @@ -664,7 +673,8 @@ def chat_ids(self, chat_id: SCT[int]) -> None:

@property
def usernames(self) -> FrozenSet[str]:
"""Which username(s) to allow through.
"""
Which username(s) to allow through.
Warning:
:attr:`usernames` will give a *copy* of the saved usernames as :obj:`frozenset`. This
Expand Down Expand Up @@ -759,7 +769,8 @@ def name(self, name: str) -> NoReturn:


class Chat(_ChatUserBaseFilter):
"""Filters messages to allow only those which are from a specified chat ID or username.
"""
Filters messages to allow only those which are from a specified chat ID or username.
Examples:
``MessageHandler(filters.Chat(-1234), callback_method)``
Expand Down Expand Up @@ -827,7 +838,8 @@ def filter(self, message: Message) -> bool:


class ChatType: # A convenience namespace for Chat types.
"""Subset for filtering the type of chat.
"""
Subset for filtering the type of chat.
Examples:
Use these filters like: ``filters.ChatType.CHANNEL`` or
Expand Down Expand Up @@ -972,7 +984,8 @@ def filter(self, message: Message) -> bool:


class Dice(_Dice):
"""Dice Messages. If an integer or a list of integers is passed, it filters messages to only
"""
Dice Messages. If an integer or a list of integers is passed, it filters messages to only
allow those whose dice value is appearing in the given list.
.. versionadded:: 13.4
Expand Down Expand Up @@ -1008,7 +1021,8 @@ class Dice(_Dice):
"""Dice messages with any value and any emoji."""

class Basketball(_Dice):
"""Dice messages with the emoji 🏀. Supports passing a list of integers.
"""
Dice messages with the emoji 🏀. Supports passing a list of integers.
Args:
values (:obj:`int` | Collection[:obj:`int`]): Which values to allow.
Expand All @@ -1023,7 +1037,8 @@ def __init__(self, values: SCT[int]):
"""Dice messages with the emoji 🏀. Matches any dice value."""

class Bowling(_Dice):
"""Dice messages with the emoji 🎳. Supports passing a list of integers.
"""
Dice messages with the emoji 🎳. Supports passing a list of integers.
Args:
values (:obj:`int` | Collection[:obj:`int`]): Which values to allow.
Expand All @@ -1038,7 +1053,8 @@ def __init__(self, values: SCT[int]):
"""Dice messages with the emoji 🎳. Matches any dice value."""

class Darts(_Dice):
"""Dice messages with the emoji 🎯. Supports passing a list of integers.
"""
Dice messages with the emoji 🎯. Supports passing a list of integers.
Args:
values (:obj:`int` | Collection[:obj:`int`]): Which values to allow.
Expand All @@ -1053,7 +1069,8 @@ def __init__(self, values: SCT[int]):
"""Dice messages with the emoji 🎯. Matches any dice value."""

class Dice(_Dice):
"""Dice messages with the emoji 🎲. Supports passing a list of integers.
"""
Dice messages with the emoji 🎲. Supports passing a list of integers.
Args:
values (:obj:`int` | Collection[:obj:`int`]): Which values to allow.
Expand All @@ -1068,7 +1085,8 @@ def __init__(self, values: SCT[int]):
"""Dice messages with the emoji 🎲. Matches any dice value."""

class Football(_Dice):
"""Dice messages with the emoji ⚽. Supports passing a list of integers.
"""
Dice messages with the emoji ⚽. Supports passing a list of integers.
Args:
values (:obj:`int` | Collection[:obj:`int`]): Which values to allow.
Expand All @@ -1083,7 +1101,8 @@ def __init__(self, values: SCT[int]):
"""Dice messages with the emoji ⚽. Matches any dice value."""

class SlotMachine(_Dice):
"""Dice messages with the emoji 🎰. Supports passing a list of integers.
"""
Dice messages with the emoji 🎰. Supports passing a list of integers.
Args:
values (:obj:`int` | Collection[:obj:`int`]): Which values to allow.
Expand Down Expand Up @@ -1123,7 +1142,8 @@ def filter(self, message: Message) -> bool:
"""Messages that contain a :attr:`telegram.Message.document`."""

class Category(MessageFilter):
"""Filters documents by their category in the mime-type attribute.
"""
Filters documents by their category in the mime-type attribute.
Args:
category (:obj:`str`): Category of the media you want to filter.
Expand Down Expand Up @@ -1161,7 +1181,8 @@ def filter(self, message: Message) -> bool:
"""Use as ``filters.Document.TEXT``."""

class FileExtension(MessageFilter):
"""This filter filters documents by their file ending/extension.
"""
This filter filters documents by their file ending/extension.
Args:
file_extension (:obj:`str` | :obj:`None`): Media file extension you want to filter.
Expand Down Expand Up @@ -1220,7 +1241,8 @@ def filter(self, message: Message) -> bool:
return filename.endswith(self._file_extension)

class MimeType(MessageFilter):
"""This Filter filters documents by their mime-type attribute.
"""
This Filter filters documents by their mime-type attribute.
Args:
mimetype (:obj:`str`): The mimetype to filter.
Expand Down Expand Up @@ -1315,7 +1337,8 @@ def filter(self, message: Message) -> bool:


class ForwardedFrom(_ChatUserBaseFilter):
"""Filters messages to allow only those which are forwarded from the specified chat ID(s)
"""
Filters messages to allow only those which are forwarded from the specified chat ID(s)
or username(s) based on :attr:`telegram.Message.forward_from` and
:attr:`telegram.Message.forward_from_chat`.
Expand Down Expand Up @@ -1433,7 +1456,8 @@ def filter(self, message: Message) -> bool:


class Language(MessageFilter):
"""Filters messages to only allow those which are from users with a certain language code.
"""
Filters messages to only allow those which are from users with a certain language code.
Note:
According to official Telegram Bot API documentation, not every single user has the
Expand Down Expand Up @@ -1578,7 +1602,8 @@ def filter(self, message: Message) -> bool:


class SenderChat(_ChatUserBaseFilter):
"""Filters messages to allow only those which are from a specified sender chat's chat ID or
"""
Filters messages to allow only those which are from a specified sender chat's chat ID or
username.
Examples:
Expand Down Expand Up @@ -1678,7 +1703,8 @@ def remove_chat_ids(self, chat_id: SCT[int]) -> None:


class StatusUpdate:
"""Subset for messages containing a status update.
"""
Subset for messages containing a status update.
Examples:
Use these filters like: ``filters.StatusUpdate.NEW_CHAT_MEMBERS`` etc. Or use just
Expand Down Expand Up @@ -1901,7 +1927,8 @@ def filter(self, message: Message) -> bool:


class Sticker:
"""Filters messages which contain a sticker.
"""
Filters messages which contain a sticker.
Examples:
Use this filter like: ``filters.Sticker.VIDEO``. Or, just use ``filters.Sticker.ALL`` for
Expand Down Expand Up @@ -1993,7 +2020,8 @@ def filter(self, message: Message) -> bool:


class Text(MessageFilter):
"""Text Messages. If a list of strings is passed, it filters messages to only allow those
"""
Text Messages. If a list of strings is passed, it filters messages to only allow those
whose text is appearing in the given list.
Examples:
Expand Down Expand Up @@ -2127,7 +2155,8 @@ def filter(self, update: Update) -> bool:


class User(_ChatUserBaseFilter):
"""Filters messages to allow only those which are from specified user ID(s) or
"""
Filters messages to allow only those which are from specified user ID(s) or
username(s).
Examples:
Expand Down Expand Up @@ -2263,7 +2292,8 @@ def filter(self, message: Message) -> bool:


class ViaBot(_ChatUserBaseFilter):
"""Filters messages to allow only those which are from specified via_bot ID(s) or username(s).
"""
Filters messages to allow only those which are from specified via_bot ID(s) or username(s).
Examples:
``MessageHandler(filters.ViaBot(1234), callback_method)``
Expand Down

0 comments on commit cbdbd57

Please sign in to comment.