Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix typos in Filters #3272

Closed
wants to merge 6 commits into from
Closed

Fix typos in Filters #3272

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
043af1c
Update BaseFilter class docstring
rglsk Oct 1, 2022
99c41f5
Fix typing in BaseFilter.check_update base method and ignore override
rglsk Oct 1, 2022
6e08131
Fix typos in docstring in filters
rglsk Oct 1, 2022
704b04f
Update class and methods docstring in filters to match the same conve…
rglsk Oct 1, 2022
97453a7
Add optional return for dict in check_update docstring
rglsk Oct 1, 2022
7358850
Update return value in check_update
rglsk Oct 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
110 changes: 74 additions & 36 deletions telegram/ext/filters.py
View file
Open in desktop
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.
Comment on lines +119 to +120
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TBH I don't really see any value in these changes - in this PR or even at all, that is.
True, some style guides suggest to start the docstring on a new line, but none of the styling tools that we currently use will report on these things. If we want to have docstrings start on a new line, I would rather like to make it a standalone issue to apply this to the whole code base.
I'm inclined to ask to revert these changes. Let's first hear what others think, though.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also agree to revert, they are rendered the same and PEP 257 does not comment on this design.


Filters subclassing from this class can combined using bitwise operators:

Expand All @@ -142,7 +143,7 @@ class BaseFilter:
filters.TEXT & (~ filters.FORWARDED)

Note:
Filters use the same short circuiting logic as python's :keyword:`and`, :keyword:`or` and
Filters use the same short-circuiting logic as python's :keyword:`and`, :keyword:`or` and
:keyword:`not`. This means that for example::

filters.Regex(r'(a?x)') | filters.Regex(r'(b?x)')
Expand Down Expand Up @@ -183,7 +184,15 @@ def __init__(self, name: str = None, data_filter: bool = False):
self._data_filter = data_filter

def check_update(self, update: Update) -> Optional[Union[bool, DataDict]]: # skipcq: PYL-R0201
"""Checks if the specified update is a message."""
"""
Checks if the specified update is a message.

Args:
update (:class:`telegram.Update`): Incoming update.

Returns:
:obj:`bool` | :obj:`Dict[str, list]`
harshil21 marked this conversation as resolved.
Show resolved Hide resolved
"""
if ( # Only message updates should be handled.
update.channel_post
or update.message
Expand Down Expand Up @@ -226,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 @@ -249,7 +259,8 @@ def check_update(self, update: Update) -> Optional[Union[bool, DataDict]]:

@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 @@ -261,7 +272,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 @@ -284,7 +296,8 @@ def check_update(self, update: Update) -> Optional[Union[bool, DataDict]]:

@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 @@ -296,7 +309,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 @@ -322,7 +336,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 @@ -410,7 +425,8 @@ def name(self, name: str) -> NoReturn:


class _XORFilter(UpdateFilter):
"""Convenience filter acting as wrapper for :class:`MergedFilter` representing the an XOR gate
"""
Convenience filter acting as wrapper for :class:`MergedFilter` representing the XOR gate
for two filters.

Args:
Expand Down Expand Up @@ -486,7 +502,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 @@ -650,7 +667,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 @@ -745,7 +763,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 @@ -813,7 +832,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 @@ -958,7 +978,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 @@ -994,7 +1015,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 @@ -1009,7 +1031,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 @@ -1024,7 +1047,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 @@ -1039,7 +1063,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 @@ -1054,7 +1079,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 @@ -1069,7 +1095,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 @@ -1109,7 +1136,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 @@ -1147,12 +1175,13 @@ 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.
case_sensitive (:obj:`bool`, optional): Pass :obj:`True` to make the filter case
sensitive. Default: :obj:`False`.
case_sensitive (:obj:`bool`, optional): Pass :obj:`True` to make the filter
case-sensitive. Default: :obj:`False`.

Example:
* ``filters.Document.FileExtension("jpg")``
Expand Down Expand Up @@ -1206,7 +1235,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 @@ -1301,7 +1331,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 @@ -1419,7 +1450,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 @@ -1512,11 +1544,11 @@ class Regex(MessageFilter):
Use ``MessageHandler(filters.Regex(r'help'), callback)`` to capture all messages that
contain the word 'help'. You can also use
``MessageHandler(filters.Regex(re.compile(r'help', re.IGNORECASE)), callback)`` if
you want your pattern to be case insensitive. This approach is recommended
you want your pattern to be case-insensitive. This approach is recommended
if you need to specify flags on your pattern.

Note:
Filters use the same short circuiting logic as python's :keyword:`and`, :keyword:`or` and
Filters use the same short-circuiting logic as python's :keyword:`and`, :keyword:`or` and
:keyword:`not`.
This means that for example:

Expand Down Expand Up @@ -1564,7 +1596,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 @@ -1664,7 +1697,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 @@ -1887,7 +1921,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 @@ -1979,7 +2014,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 @@ -2113,7 +2149,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 @@ -2249,7 +2286,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