-
Notifications
You must be signed in to change notification settings - Fork 5.1k
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.
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
Fix typos in Filters #3272
Closed
rglsk
wants to merge
6
commits into
python-telegram-bot:doc-fixes
from
rglsk:3109-update-ext-filters
Closed
Fix typos in Filters #3272
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
043af1c
Update BaseFilter class docstring
rglsk 99c41f5
Fix typing in BaseFilter.check_update base method and ignore override
rglsk 6e08131
Fix typos in docstring in filters
rglsk 704b04f
Update class and methods docstring in filters to match the same conve…
rglsk 97453a7
Add optional return for dict in check_update docstring
rglsk 7358850
Update return value in check_update
rglsk File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -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: | ||||||
|
||||||
|
@@ -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)') | ||||||
|
@@ -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` | Dict[str, list] | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
""" | ||||||
if ( # Only message updates should be handled. | ||||||
update.channel_post | ||||||
or update.message | ||||||
|
@@ -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. | ||||||
|
@@ -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. | ||||||
|
@@ -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`. | ||||||
|
||||||
|
@@ -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. | ||||||
|
@@ -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. | ||||||
|
@@ -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. | ||||||
|
@@ -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: | ||||||
|
@@ -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: | ||||||
|
@@ -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 | ||||||
|
@@ -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)`` | ||||||
|
@@ -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 | ||||||
|
@@ -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 | ||||||
|
@@ -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. | ||||||
|
@@ -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. | ||||||
|
@@ -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. | ||||||
|
@@ -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. | ||||||
|
@@ -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. | ||||||
|
@@ -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. | ||||||
|
@@ -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. | ||||||
|
@@ -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")`` | ||||||
|
@@ -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. | ||||||
|
@@ -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`. | ||||||
|
||||||
|
@@ -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 | ||||||
|
@@ -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: | ||||||
|
||||||
|
@@ -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: | ||||||
|
@@ -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 | ||||||
|
@@ -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 | ||||||
|
@@ -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: | ||||||
|
@@ -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: | ||||||
|
@@ -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)`` | ||||||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.