From 59aa26c46a297657588ee490d1b92fe814afaf99 Mon Sep 17 00:00:00 2001 From: NikitaPirate Date: Mon, 12 Oct 2020 16:59:00 +0300 Subject: [PATCH 1/5] Move all constants to constants.py and documentation refactor. --- AUTHORS.rst | 1 + telegram/chat.py | 18 +-- telegram/chataction.py | 41 +++---- telegram/chatmember.py | 27 +++-- telegram/constants.py | 168 ++++++++++++++++++++++++++++ telegram/dice.py | 14 +-- telegram/ext/basepersistence.py | 7 +- telegram/ext/conversationhandler.py | 18 +-- telegram/files/inputfile.py | 5 +- telegram/files/sticker.py | 18 +-- telegram/messageentity.py | 62 +++++----- telegram/parsemode.py | 14 ++- telegram/poll.py | 10 +- telegram/utils/request.py | 5 +- 14 files changed, 292 insertions(+), 116 deletions(-) diff --git a/AUTHORS.rst b/AUTHORS.rst index f49a3b99247..38ae9a74ab4 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -62,6 +62,7 @@ The following wonderful people contributed directly or indirectly to this projec - `Mischa KrΓΌger `_ - `naveenvhegde `_ - `neurrone `_ +- `NikitaPirate `_ - `njittam `_ - `Noam Meltzer `_ - `Oleg Shlyazhko `_ diff --git a/telegram/chat.py b/telegram/chat.py index 88e38b86c2c..5ffd8dd5b85 100644 --- a/telegram/chat.py +++ b/telegram/chat.py @@ -19,7 +19,7 @@ # along with this program. If not, see [http://www.gnu.org/licenses/]. """This module contains an object that represents a Telegram Chat.""" -from telegram import TelegramObject, ChatPhoto +from telegram import TelegramObject, ChatPhoto, constants from .chatpermissions import ChatPermissions from telegram.utils.types import JSONDict @@ -92,14 +92,14 @@ class Chat(TelegramObject): """ - PRIVATE: str = 'private' - """:obj:`str`: 'private'""" - GROUP: str = 'group' - """:obj:`str`: 'group'""" - SUPERGROUP: str = 'supergroup' - """:obj:`str`: 'supergroup'""" - CHANNEL: str = 'channel' - """:obj:`str`: 'channel'""" + PRIVATE: str = constants.CHAT_PRIVATE + """:const:`telegram.constants.CHAT_PRIVATE`""" + GROUP: str = constants.CHAT_GROUP + """:const:`telegram.constants.CHAT_GROUP`""" + SUPERGROUP: str = constants.CHAT_SUPERGROUP + """:const:`telegram.constants.CHAT_SUPERGROUP`""" + CHANNEL: str = constants.CHAT_CHANNEL + """:const:`telegram.constants.CHAT_CHANNEL`""" def __init__( self, diff --git a/telegram/chataction.py b/telegram/chataction.py index b8bb3de32c3..3d797a47a3c 100644 --- a/telegram/chataction.py +++ b/telegram/chataction.py @@ -18,28 +18,29 @@ # 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 an object that represents a Telegram ChatAction.""" +from telegram import constants class ChatAction: """Helper class to provide constants for different chat actions.""" - FIND_LOCATION: str = 'find_location' - """:obj:`str`: 'find_location'""" - RECORD_AUDIO: str = 'record_audio' - """:obj:`str`: 'record_audio'""" - RECORD_VIDEO: str = 'record_video' - """:obj:`str`: 'record_video'""" - RECORD_VIDEO_NOTE: str = 'record_video_note' - """:obj:`str`: 'record_video_note'""" - TYPING: str = 'typing' - """:obj:`str`: 'typing'""" - UPLOAD_AUDIO: str = 'upload_audio' - """:obj:`str`: 'upload_audio'""" - UPLOAD_DOCUMENT: str = 'upload_document' - """:obj:`str`: 'upload_document'""" - UPLOAD_PHOTO: str = 'upload_photo' - """:obj:`str`: 'upload_photo'""" - UPLOAD_VIDEO: str = 'upload_video' - """:obj:`str`: 'upload_video'""" - UPLOAD_VIDEO_NOTE: str = 'upload_video_note' - """:obj:`str`: 'upload_video_note'""" + FIND_LOCATION: str = constants.CHATACTION_FIND_LOCATION + """:const:`telegram.constants.CHATACTION_FIND_LOCATION`""" + RECORD_AUDIO: str = constants.CHATACTION_RECORD_AUDIO + """:const:`telegram.constants.CHATACTION_RECORD_AUDIO`""" + RECORD_VIDEO: str = constants.CHATACTION_RECORD_VIDEO + """:const:`telegram.constants.CHATACTION_RECORD_VIDEO`""" + RECORD_VIDEO_NOTE: str = constants.CHATACTION_RECORD_VIDEO_NOTE + """:const:`telegram.constants.CHATACTION_RECORD_VIDEO_NOTE`""" + TYPING: str = constants.CHATACTION_TYPING + """:const:`telegram.constants.CHATACTION_TYPING`""" + UPLOAD_AUDIO: str = constants.CHATACTION_UPLOAD_AUDIO + """:const:`telegram.constants.CHATACTION_UPLOAD_AUDIO`""" + UPLOAD_DOCUMENT: str = constants.CHATACTION_UPLOAD_DOCUMENT + """:const:`telegram.constants.CHATACTION_UPLOAD_DOCUMENT`""" + UPLOAD_PHOTO: str = constants.CHATACTION_UPLOAD_PHOTO + """:const:`telegram.constants.CHATACTION_UPLOAD_PHOTO`""" + UPLOAD_VIDEO: str = constants.CHATACTION_UPLOAD_VIDEO + """:const:`telegram.constants.CHATACTION_UPLOAD_VIDEO`""" + UPLOAD_VIDEO_NOTE: str = constants.CHATACTION_UPLOAD_VIDEO_NOTE + """:const:`telegram.constants.CHATACTION_UPLOAD_VIDEO_NOTE`""" diff --git a/telegram/chatmember.py b/telegram/chatmember.py index cd63829defc..95d0f2028dd 100644 --- a/telegram/chatmember.py +++ b/telegram/chatmember.py @@ -19,7 +19,7 @@ """This module contains an object that represents a Telegram ChatMember.""" import datetime -from telegram import User, TelegramObject +from telegram import User, TelegramObject, constants from telegram.utils.helpers import to_timestamp, from_timestamp from telegram.utils.types import JSONDict @@ -111,19 +111,18 @@ class ChatMember(TelegramObject): may add web page previews to his messages. """ - - ADMINISTRATOR: str = 'administrator' - """:obj:`str`: 'administrator'""" - CREATOR: str = 'creator' - """:obj:`str`: 'creator'""" - KICKED: str = 'kicked' - """:obj:`str`: 'kicked'""" - LEFT: str = 'left' - """:obj:`str`: 'left'""" - MEMBER: str = 'member' - """:obj:`str`: 'member'""" - RESTRICTED: str = 'restricted' - """:obj:`str`: 'restricted'""" + ADMINISTRATOR: str = constants.CHATMEMBER_ADMINISTRATOR + """:const:`telegram.constants.CHATMEMBER_ADMINISTRATOR`""" + CREATOR: str = constants.CHATMEMBER_CREATOR + """:const:`telegram.constants.CHATMEMBER_CREATOR`""" + KICKED: str = constants.CHATMEMBER_KICKED + """:const:`telegram.constants.CHATMEMBER_KICKED`""" + LEFT: str = constants.CHATMEMBER_LEFT + """:const:`telegram.constants.CHATMEMBER_LEFT`""" + MEMBER: str = constants.CHATMEMBER_MEMBER + """:const:`telegram.constants.CHATMEMBER_MEMBER`""" + RESTRICTED: str = constants.CHATMEMBER_RESTRICTED + """:const:`telegram.constants.CHATMEMBER_RESTRICTED`""" def __init__( self, diff --git a/telegram/constants.py b/telegram/constants.py index 6e9816cf9fc..afa2ba9c668 100644 --- a/telegram/constants.py +++ b/telegram/constants.py @@ -39,6 +39,110 @@ MAX_MESSAGE_ENTITIES (:obj:`int`): 100 (Beyond this cap telegram will simply ignore further formatting styles) +The following constants are attributes of classes: + +:class:`telegram.Chat`: + +Attributes: + CHAT_PRIVATE (:obj:`str`): 'private' + CHAT_GROUP (:obj:`str`): 'group' + CHAT_SUPERGROUP (:obj:`str`): 'supergroup' + CHAT_CHANNEL (:obj:`str`): 'channel' + +:class:`telegram.ChatAction`: + +Attributes: + CHATACTION_FIND_LOCATION (:obj:`str`): 'find_location' + CHATACTION_RECORD_AUDIO (:obj:`str`): 'record_audio' + CHATACTION_RECORD_VIDEO (:obj:`str`): 'record_video' + CHATACTION_RECORD_VIDEO_NOTE (:obj:`str`): 'record_video_note' + CHATACTION_TYPING (:obj:`str`): 'typing' + CHATACTION_UPLOAD_AUDIO (:obj:`str`): 'upload_audio' + CHATACTION_UPLOAD_DOCUMENT (:obj:`str`): 'upload_document' + CHATACTION_UPLOAD_PHOTO (:obj:`str`): 'upload_photo' + CHATACTION_UPLOAD_VIDEO (:obj:`str`): 'upload_video' + CHATACTION_UPLOAD_VIDEO_NOTE (:obj:`str`): 'upload_video_note' + +:class:`telegram.ChatMember`: + +Attributes: + CHATMEMBER_ADMINISTRATOR (:obj:`str`): 'administrator' + CHATMEMBER_CREATOR (:obj:`str`): 'creator' + CHATMEMBER_KICKED (:obj:`str`): 'kicked' + CHATMEMBER_LEFT (:obj:`str`): 'left' + CHATMEMBER_MEMBER (:obj:`str`): 'member' + CHATMEMBER_RESTRICTED (:obj:`str`): 'restricted' + +:class:`telegram.Dice`: + +Attributes: + DICE_DICE (:obj:`str`): '🎲' + DICE_DARTS (:obj:`str`): '🎯' + DICE_BASKETBALL (:obj:`str`): 'πŸ€' + +:class:`telegram.MessageEntity`: + +Attributes: + MESSAGEENTITY_MENTION (:obj:`str`): 'mention' + MESSAGEENTITY_HASHTAG (:obj:`str`): 'hashtag' + MESSAGEENTITY_CASHTAG (:obj:`str`): 'cashtag' + MESSAGEENTITY_PHONE_NUMBER (:obj:`str`): 'phone_number' + MESSAGEENTITY_BOT_COMMAND (:obj:`str`): 'bot_command' + MESSAGEENTITY_URL (:obj:`str`): 'url' + MESSAGEENTITY_EMAIL (:obj:`str`): 'email' + MESSAGEENTITY_BOLD (:obj:`str`): 'bold' + MESSAGEENTITY_ITALIC (:obj:`str`): 'italic' + MESSAGEENTITY_CODE (:obj:`str`): 'code' + MESSAGEENTITY_PRE (:obj:`str`): 'pre' + MESSAGEENTITY_TEXT_LINK (:obj:`str`): 'text_link' + MESSAGEENTITY_TEXT_MENTION (:obj:`str`): 'text_mention' + MESSAGEENTITY_UNDERLINE (:obj:`str`): 'underline' + MESSAGEENTITY_STRIKETHROUGH (:obj:`str`): 'strikethrough' + +:class:`telegram.ParseMode`: + +Attributes: + PARSEMODE_MARKDOWN (:obj:`str`): 'Markdown' + PARSEMODE_MARKDOWN_V2 (:obj:`str`): 'MarkdownV2' + PARSEMODE_HTML (:obj:`str`): 'HTML' + +:class:`telegram.Poll`: + +Attributes: + POLL_REGULAR (:obj:`str`): 'regular' + POLL_QUIZ (:obj:`str`): 'quiz' + + + +:class:`telegram.ext.ConversationHandler`: + +Attributes: + CONVERSATIONHANDLER_END (:obj:`int`): -1 + CONVERSATIONHANDLER_TIMEOUT (:obj:`int`): -2 + CONVERSATIONHANDLER_WAITING (:obj:`int`): -3 + +:class:`telegram.files.MaskPosition`: + +Attributes: + STICKER_FOREHEAD (:obj:`str`): 'forehead' + STICKER_EYES (:obj:`str`): 'eyes' + STICKER_MOUTH (:obj:`str`): 'mouth' + STICKER_CHIN (:obj:`str`): 'chin' + +:class:`telegram.ext.BasePersistence`: + +Attributes: + BASEPERSISTENCE_REPLACED_BOT (:obj:`str`): 'bot_instance_replaced_by_ptb_persistence' + +Other constants: + +Attributes: + + INPUTFILE_DEFAULT_MIME_TYPE (:obj:`str`): 'application/octet-stream' + REQUEST_USER_AGENT (:obj:`str`):Python Telegram Bot \ + (https://github.com/python-telegram-bot/python-telegram-bot) + + """ from typing import List @@ -56,3 +160,67 @@ MAX_MESSAGES_PER_MINUTE_PER_GROUP: int = 20 MAX_MESSAGE_ENTITIES: int = 100 MAX_INLINE_QUERY_RESULTS: int = 50 + +CHAT_PRIVATE: str = 'private' +CHAT_GROUP: str = 'group' +CHAT_SUPERGROUP: str = 'supergroup' +CHAT_CHANNEL: str = 'channel' + +CHATACTION_FIND_LOCATION: str = 'find_location' +CHATACTION_RECORD_AUDIO: str = 'record_audio' +CHATACTION_RECORD_VIDEO: str = 'record_video' +CHATACTION_RECORD_VIDEO_NOTE: str = 'record_video_note' +CHATACTION_TYPING: str = 'typing' +CHATACTION_UPLOAD_AUDIO: str = 'upload_audio' +CHATACTION_UPLOAD_DOCUMENT: str = 'upload_document' +CHATACTION_UPLOAD_PHOTO: str = 'upload_photo' +CHATACTION_UPLOAD_VIDEO: str = 'upload_video' +CHATACTION_UPLOAD_VIDEO_NOTE: str = 'upload_video_note' + +CHATMEMBER_ADMINISTRATOR: str = 'administrator' +CHATMEMBER_CREATOR: str = 'creator' +CHATMEMBER_KICKED: str = 'kicked' +CHATMEMBER_LEFT: str = 'left' +CHATMEMBER_MEMBER: str = 'member' +CHATMEMBER_RESTRICTED: str = 'restricted' + +DICE_DICE: str = '🎲' +DICE_DARTS: str = '🎯' +DICE_BASKETBALL: str = 'πŸ€' + +MESSAGEENTITY_MENTION: str = 'mention' +MESSAGEENTITY_HASHTAG: str = 'hashtag' +MESSAGEENTITY_CASHTAG: str = 'cashtag' +MESSAGEENTITY_PHONE_NUMBER: str = 'phone_number' +MESSAGEENTITY_BOT_COMMAND: str = 'bot_command' +MESSAGEENTITY_URL: str = 'url' +MESSAGEENTITY_EMAIL: str = 'email' +MESSAGEENTITY_BOLD: str = 'bold' +MESSAGEENTITY_ITALIC: str = 'italic' +MESSAGEENTITY_CODE: str = 'code' +MESSAGEENTITY_PRE: str = 'pre' +MESSAGEENTITY_TEXT_LINK: str = 'text_link' +MESSAGEENTITY_TEXT_MENTION: str = 'text_mention' +MESSAGEENTITY_UNDERLINE: str = 'underline' +MESSAGEENTITY_STRIKETHROUGH: str = 'strikethrough' + +PARSEMODE_MARKDOWN: str = 'Markdown' +PARSEMODE_MARKDOWN_V2: str = 'MarkdownV2' +PARSEMODE_HTML: str = 'HTML' + +POLL_REGULAR: str = 'regular' +POLL_QUIZ: str = 'quiz' + +CONVERSATIONHANDLER_END = -1 +CONVERSATIONHANDLER_TIMEOUT = -2 +CONVERSATIONHANDLER_WAITING = -3 + +STICKER_FOREHEAD: str = 'forehead' +STICKER_EYES: str = 'eyes' +STICKER_MOUTH: str = 'mouth' +STICKER_CHIN: str = 'chin' + +BASEPERSISTENCE_REPLACED_BOT = 'bot_instance_replaced_by_ptb_persistence' +INPUTFILE_DEFAULT_MIME_TYPE = 'application/octet-stream' +REQUEST_USER_AGENT = 'Python Telegram Bot ' \ + '(https://github.com/python-telegram-bot/python-telegram-bot)' diff --git a/telegram/dice.py b/telegram/dice.py index 36ef615556b..d775ffc99fc 100644 --- a/telegram/dice.py +++ b/telegram/dice.py @@ -18,7 +18,7 @@ # 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 an object that represents a Telegram Dice.""" -from telegram import TelegramObject +from telegram import TelegramObject, constants from typing import Any, List @@ -55,12 +55,12 @@ def __init__(self, value: int, emoji: str, **kwargs: Any): self._id_attrs = (self.value, self.emoji) - DICE: str = '🎲' - """:obj:`str`: '🎲'""" - DARTS: str = '🎯' - """:obj:`str`: '🎯'""" - BASKETBALL = 'πŸ€' - """:obj:`str`: 'πŸ€'""" + DICE: str = constants.DICE_DICE + """:const:`telegram.constants.DICE_DICE`""" + DARTS: str = constants.DICE_DARTS + """:const:`telegram.constants.DICE_DARTS`""" + BASKETBALL: str = constants.DICE_BASKETBALL + """:const:`telegram.constants.DICE_BASKETBALL`""" ALL_EMOJI: List[str] = [DICE, DARTS, BASKETBALL] """List[:obj:`str`]: List of all supported base emoji. Currently :attr:`DICE`, :attr:`DARTS` and :attr:`BASKETBALL`.""" diff --git a/telegram/ext/basepersistence.py b/telegram/ext/basepersistence.py index e7be4d7e6e0..bf63892e9c6 100644 --- a/telegram/ext/basepersistence.py +++ b/telegram/ext/basepersistence.py @@ -22,7 +22,7 @@ from collections import defaultdict from copy import copy -from telegram import Bot +from telegram import Bot, constants from typing import DefaultDict, Dict, Any, Tuple, Optional, cast from telegram.utils.types import ConversationDict @@ -302,5 +302,6 @@ def flush(self) -> None: """ pass - REPLACED_BOT = 'bot_instance_replaced_by_ptb_persistence' - """:obj:`str`: Placeholder for :class:`telegram.Bot` instances replaced in saved data.""" + REPLACED_BOT = constants.BASEPERSISTENCE_REPLACED_BOT + """:const:`telegram.constants.BASEPERSISTENCE_REPLACED_BOT`\n + Placeholder for :class:`telegram.Bot` instances replaced in saved data.""" diff --git a/telegram/ext/conversationhandler.py b/telegram/ext/conversationhandler.py index bee391ccd50..bb8caae8d2c 100644 --- a/telegram/ext/conversationhandler.py +++ b/telegram/ext/conversationhandler.py @@ -22,7 +22,7 @@ import warnings from threading import Lock -from telegram import Update +from telegram import Update, constants from telegram.ext import ( Handler, CallbackQueryHandler, @@ -168,13 +168,15 @@ class ConversationHandler(Handler): ValueError """ - - END = -1 - """:obj:`int`: Used as a constant to return when a conversation is ended.""" - TIMEOUT = -2 - """:obj:`int`: Used as a constant to handle state when a conversation is timed out.""" - WAITING = -3 - """:obj:`int`: Used as a constant to handle state when a conversation is still waiting on the + END = constants.CONVERSATIONHANDLER_END + """:const:`telegram.constants.CONVERSATIONHANDLER_END`\n + Used as a constant to return when a conversation is ended.""" + TIMEOUT = constants.CONVERSATIONHANDLER_TIMEOUT + """:const:`telegram.constants.CONVERSATIONHANDLER_TIMEOUT`\n + Used as a constant to handle state when a conversation is timed out.""" + WAITING = constants.CONVERSATIONHANDLER_WAITING + """:const:`telegram.constants.CONVERSATIONHANDLER_WAITING`\n + Used as a constant to handle state when a conversation is still waiting on the previous ``@run_sync`` decorated running handler to finish.""" def __init__( diff --git a/telegram/files/inputfile.py b/telegram/files/inputfile.py index 97e4eaf0c5d..8d85deadcff 100644 --- a/telegram/files/inputfile.py +++ b/telegram/files/inputfile.py @@ -24,11 +24,12 @@ import os from uuid import uuid4 -from telegram import TelegramError +from telegram import TelegramError, constants from typing import IO, Tuple, Optional -DEFAULT_MIME_TYPE = 'application/octet-stream' +DEFAULT_MIME_TYPE = constants.INPUTFILE_DEFAULT_MIME_TYPE +""":const:`telegram.constants.INPUTFILE_DEFAULT_MIME_TYPE`""" class InputFile: diff --git a/telegram/files/sticker.py b/telegram/files/sticker.py index c59251cfbf8..4d3eb3faeb8 100644 --- a/telegram/files/sticker.py +++ b/telegram/files/sticker.py @@ -18,7 +18,7 @@ # along with this program. If not, see [http://www.gnu.org/licenses/]. """This module contains objects that represents stickers.""" -from telegram import PhotoSize, TelegramObject +from telegram import PhotoSize, TelegramObject, constants from telegram.utils.types import JSONDict from typing import Any, Optional, List, TYPE_CHECKING @@ -233,14 +233,14 @@ class MaskPosition(TelegramObject): """ - FOREHEAD: str = 'forehead' - """:obj:`str`: 'forehead'""" - EYES: str = 'eyes' - """:obj:`str`: 'eyes'""" - MOUTH: str = 'mouth' - """:obj:`str`: 'mouth'""" - CHIN: str = 'chin' - """:obj:`str`: 'chin'""" + FOREHEAD: str = constants.STICKER_FOREHEAD + """:const:`telegram.constants.STICKER_FOREHEAD`""" + EYES: str = constants.STICKER_EYES + """:const:`telegram.constants.STICKER_EYES`""" + MOUTH: str = constants.STICKER_MOUTH + """:const:`telegram.constants.STICKER_MOUTH`""" + CHIN: str = constants.STICKER_CHIN + """:const:`telegram.constants.STICKER_CHIN`""" def __init__(self, point: str, x_shift: float, y_shift: float, scale: float, **kwargs: Any): self.point = point diff --git a/telegram/messageentity.py b/telegram/messageentity.py index 3b2119219b2..6093eca7c9f 100644 --- a/telegram/messageentity.py +++ b/telegram/messageentity.py @@ -18,7 +18,7 @@ # along with this program. If not, see [http://www.gnu.org/licenses/]. """This module contains an object that represents a Telegram MessageEntity.""" -from telegram import User, TelegramObject +from telegram import User, TelegramObject, constants from telegram.utils.types import JSONDict from typing import Any, Optional, List, TYPE_CHECKING @@ -90,36 +90,36 @@ def de_json(cls, data: Optional[JSONDict], bot: 'Bot') -> Optional['MessageEntit return cls(**data) - MENTION: str = 'mention' - """:obj:`str`: 'mention'""" - HASHTAG: str = 'hashtag' - """:obj:`str`: 'hashtag'""" - CASHTAG: str = 'cashtag' - """:obj:`str`: 'cashtag'""" - PHONE_NUMBER: str = 'phone_number' - """:obj:`str`: 'phone_number'""" - BOT_COMMAND: str = 'bot_command' - """:obj:`str`: 'bot_command'""" - URL: str = 'url' - """:obj:`str`: 'url'""" - EMAIL: str = 'email' - """:obj:`str`: 'email'""" - BOLD: str = 'bold' - """:obj:`str`: 'bold'""" - ITALIC: str = 'italic' - """:obj:`str`: 'italic'""" - CODE: str = 'code' - """:obj:`str`: 'code'""" - PRE: str = 'pre' - """:obj:`str`: 'pre'""" - TEXT_LINK: str = 'text_link' - """:obj:`str`: 'text_link'""" - TEXT_MENTION: str = 'text_mention' - """:obj:`str`: 'text_mention'""" - UNDERLINE: str = 'underline' - """:obj:`str`: 'underline'""" - STRIKETHROUGH: str = 'strikethrough' - """:obj:`str`: 'strikethrough'""" + MENTION: str = constants.MESSAGEENTITY_MENTION + """:const:`telegram.constants.MESSAGEENTITY_MENTION`""" + HASHTAG: str = constants.MESSAGEENTITY_HASHTAG + """:const:`telegram.constants.MESSAGEENTITY_HASHTAG`""" + CASHTAG: str = constants.MESSAGEENTITY_CASHTAG + """:const:`telegram.constants.MESSAGEENTITY_CASHTAG`""" + PHONE_NUMBER: str = constants.MESSAGEENTITY_PHONE_NUMBER + """:const:`telegram.constants.MESSAGEENTITY_PHONE_NUMBER`""" + BOT_COMMAND: str = constants.MESSAGEENTITY_BOT_COMMAND + """:const:`telegram.constants.MESSAGEENTITY_BOT_COMMAND`""" + URL: str = constants.MESSAGEENTITY_URL + """:const:`telegram.constants.MESSAGEENTITY_URL`""" + EMAIL: str = constants.MESSAGEENTITY_EMAIL + """:const:`telegram.constants.MESSAGEENTITY_EMAIL`""" + BOLD: str = constants.MESSAGEENTITY_BOLD + """:const:`telegram.constants.MESSAGEENTITY_BOLD`""" + ITALIC: str = constants.MESSAGEENTITY_ITALIC + """:const:`telegram.constants.MESSAGEENTITY_ITALIC`""" + CODE: str = constants.MESSAGEENTITY_CODE + """:const:`telegram.constants.MESSAGEENTITY_CODE`""" + PRE: str = constants.MESSAGEENTITY_PRE + """:const:`telegram.constants.MESSAGEENTITY_PRE`""" + TEXT_LINK: str = constants.MESSAGEENTITY_TEXT_LINK + """:const:`telegram.constants.MESSAGEENTITY_TEXT_LINK`""" + TEXT_MENTION: str = constants.MESSAGEENTITY_TEXT_MENTION + """:const:`telegram.constants.MESSAGEENTITY_TEXT_MENTION`""" + UNDERLINE: str = constants.MESSAGEENTITY_UNDERLINE + """:const:`telegram.constants.MESSAGEENTITY_UNDERLINE`""" + STRIKETHROUGH: str = constants.MESSAGEENTITY_STRIKETHROUGH + """:const:`telegram.constants.MESSAGEENTITY_STRIKETHROUGH`""" ALL_TYPES: List[str] = [ MENTION, HASHTAG, diff --git a/telegram/parsemode.py b/telegram/parsemode.py index ee8ad8ef5ec..e86796e69f9 100644 --- a/telegram/parsemode.py +++ b/telegram/parsemode.py @@ -19,18 +19,20 @@ # along with this program. If not, see [http://www.gnu.org/licenses/]. """This module contains an object that represents a Telegram Message Parse Modes.""" +from telegram import constants + class ParseMode: """This object represents a Telegram Message Parse Modes.""" - MARKDOWN: str = 'Markdown' - """:obj:`str`: 'Markdown' + MARKDOWN: str = constants.PARSEMODE_MARKDOWN + """:const:`telegram.constants.PARSEMODE_MARKDOWN`\n Note: :attr:`MARKDOWN` is a legacy mode, retained by Telegram for backward compatibility. You should use :attr:`MARKDOWN_V2` instead. """ - MARKDOWN_V2: str = 'MarkdownV2' - """:obj:`str`: 'MarkdownV2'""" - HTML: str = 'HTML' - """:obj:`str`: 'HTML'""" + MARKDOWN_V2: str = constants.PARSEMODE_MARKDOWN_V2 + """:const:`telegram.constants.PARSEMODE_MARKDOWN_V2`""" + HTML: str = constants.PARSEMODE_HTML + """:const:`telegram.constants.PARSEMODE_HTML`""" diff --git a/telegram/poll.py b/telegram/poll.py index 470cdf3cca7..9216a22ac3e 100644 --- a/telegram/poll.py +++ b/telegram/poll.py @@ -22,7 +22,7 @@ import sys import datetime -from telegram import TelegramObject, User, MessageEntity +from telegram import TelegramObject, User, MessageEntity, constants from telegram.utils.helpers import to_timestamp, from_timestamp from telegram.utils.types import JSONDict from typing import Any, Dict, Optional, List, TYPE_CHECKING @@ -259,7 +259,7 @@ def parse_explanation_entities(self, types: List[str] = None) -> Dict[MessageEnt if entity.type in types } - REGULAR: str = "regular" - """:obj:`str`: 'regular'""" - QUIZ: str = "quiz" - """:obj:`str`: 'quiz'""" + REGULAR: str = constants.POLL_REGULAR + """:const:`telegram.constants.POLL_REGULAR`""" + QUIZ: str = constants.POLL_QUIZ + """:const:`telegram.constants.POLL_QUIZ`""" diff --git a/telegram/utils/request.py b/telegram/utils/request.py index ea45d214707..c6a7ccf6c74 100644 --- a/telegram/utils/request.py +++ b/telegram/utils/request.py @@ -56,7 +56,7 @@ raise -from telegram import InputFile, TelegramError, InputMedia +from telegram import InputFile, TelegramError, InputMedia, constants from telegram.error import ( Unauthorized, NetworkError, @@ -87,7 +87,8 @@ def _render_part(self: RequestField, name: str, value: str) -> str: logging.getLogger('urllib3').setLevel(logging.WARNING) -USER_AGENT = 'Python Telegram Bot (https://github.com/python-telegram-bot/python-telegram-bot)' +USER_AGENT = constants.REQUEST_USER_AGENT +""":const:`telegram.constants.REQUEST_USER_AGENT`""" class Request: From aeffbc9851ab9d6e5130088cb9fbe1d25a709aa6 Mon Sep 17 00:00:00 2001 From: NikitaPirate Date: Mon, 12 Oct 2020 19:44:35 +0300 Subject: [PATCH 2/5] Move all constants to constants.py and documentation refactor. --- telegram/constants.py | 34 ++--------------------------- telegram/ext/basepersistence.py | 7 +++--- telegram/ext/conversationhandler.py | 17 ++++++--------- telegram/files/inputfile.py | 5 ++--- telegram/utils/request.py | 5 ++--- 5 files changed, 16 insertions(+), 52 deletions(-) diff --git a/telegram/constants.py b/telegram/constants.py index afa2ba9c668..59961b3ff3b 100644 --- a/telegram/constants.py +++ b/telegram/constants.py @@ -39,7 +39,8 @@ MAX_MESSAGE_ENTITIES (:obj:`int`): 100 (Beyond this cap telegram will simply ignore further formatting styles) -The following constants are attributes of classes: +The following constants are related to specific classes and are also available +as attributes of those classes: :class:`telegram.Chat`: @@ -112,15 +113,6 @@ POLL_REGULAR (:obj:`str`): 'regular' POLL_QUIZ (:obj:`str`): 'quiz' - - -:class:`telegram.ext.ConversationHandler`: - -Attributes: - CONVERSATIONHANDLER_END (:obj:`int`): -1 - CONVERSATIONHANDLER_TIMEOUT (:obj:`int`): -2 - CONVERSATIONHANDLER_WAITING (:obj:`int`): -3 - :class:`telegram.files.MaskPosition`: Attributes: @@ -129,20 +121,6 @@ STICKER_MOUTH (:obj:`str`): 'mouth' STICKER_CHIN (:obj:`str`): 'chin' -:class:`telegram.ext.BasePersistence`: - -Attributes: - BASEPERSISTENCE_REPLACED_BOT (:obj:`str`): 'bot_instance_replaced_by_ptb_persistence' - -Other constants: - -Attributes: - - INPUTFILE_DEFAULT_MIME_TYPE (:obj:`str`): 'application/octet-stream' - REQUEST_USER_AGENT (:obj:`str`):Python Telegram Bot \ - (https://github.com/python-telegram-bot/python-telegram-bot) - - """ from typing import List @@ -211,16 +189,8 @@ POLL_REGULAR: str = 'regular' POLL_QUIZ: str = 'quiz' -CONVERSATIONHANDLER_END = -1 -CONVERSATIONHANDLER_TIMEOUT = -2 -CONVERSATIONHANDLER_WAITING = -3 STICKER_FOREHEAD: str = 'forehead' STICKER_EYES: str = 'eyes' STICKER_MOUTH: str = 'mouth' STICKER_CHIN: str = 'chin' - -BASEPERSISTENCE_REPLACED_BOT = 'bot_instance_replaced_by_ptb_persistence' -INPUTFILE_DEFAULT_MIME_TYPE = 'application/octet-stream' -REQUEST_USER_AGENT = 'Python Telegram Bot ' \ - '(https://github.com/python-telegram-bot/python-telegram-bot)' diff --git a/telegram/ext/basepersistence.py b/telegram/ext/basepersistence.py index bf63892e9c6..e7be4d7e6e0 100644 --- a/telegram/ext/basepersistence.py +++ b/telegram/ext/basepersistence.py @@ -22,7 +22,7 @@ from collections import defaultdict from copy import copy -from telegram import Bot, constants +from telegram import Bot from typing import DefaultDict, Dict, Any, Tuple, Optional, cast from telegram.utils.types import ConversationDict @@ -302,6 +302,5 @@ def flush(self) -> None: """ pass - REPLACED_BOT = constants.BASEPERSISTENCE_REPLACED_BOT - """:const:`telegram.constants.BASEPERSISTENCE_REPLACED_BOT`\n - Placeholder for :class:`telegram.Bot` instances replaced in saved data.""" + REPLACED_BOT = 'bot_instance_replaced_by_ptb_persistence' + """:obj:`str`: Placeholder for :class:`telegram.Bot` instances replaced in saved data.""" diff --git a/telegram/ext/conversationhandler.py b/telegram/ext/conversationhandler.py index bb8caae8d2c..7acd324d56c 100644 --- a/telegram/ext/conversationhandler.py +++ b/telegram/ext/conversationhandler.py @@ -22,7 +22,7 @@ import warnings from threading import Lock -from telegram import Update, constants +from telegram import Update from telegram.ext import ( Handler, CallbackQueryHandler, @@ -168,15 +168,12 @@ class ConversationHandler(Handler): ValueError """ - END = constants.CONVERSATIONHANDLER_END - """:const:`telegram.constants.CONVERSATIONHANDLER_END`\n - Used as a constant to return when a conversation is ended.""" - TIMEOUT = constants.CONVERSATIONHANDLER_TIMEOUT - """:const:`telegram.constants.CONVERSATIONHANDLER_TIMEOUT`\n - Used as a constant to handle state when a conversation is timed out.""" - WAITING = constants.CONVERSATIONHANDLER_WAITING - """:const:`telegram.constants.CONVERSATIONHANDLER_WAITING`\n - Used as a constant to handle state when a conversation is still waiting on the + END = -1 + """:obj:`int`: Used as a constant to return when a conversation is ended.""" + TIMEOUT = -2 + """:obj:`int`: Used as a constant to handle state when a conversation is timed out.""" + WAITING = -3 + """:obj:`int`: Used as a constant to handle state when a conversation is still waiting on the previous ``@run_sync`` decorated running handler to finish.""" def __init__( diff --git a/telegram/files/inputfile.py b/telegram/files/inputfile.py index 8d85deadcff..97e4eaf0c5d 100644 --- a/telegram/files/inputfile.py +++ b/telegram/files/inputfile.py @@ -24,12 +24,11 @@ import os from uuid import uuid4 -from telegram import TelegramError, constants +from telegram import TelegramError from typing import IO, Tuple, Optional -DEFAULT_MIME_TYPE = constants.INPUTFILE_DEFAULT_MIME_TYPE -""":const:`telegram.constants.INPUTFILE_DEFAULT_MIME_TYPE`""" +DEFAULT_MIME_TYPE = 'application/octet-stream' class InputFile: diff --git a/telegram/utils/request.py b/telegram/utils/request.py index c6a7ccf6c74..ea45d214707 100644 --- a/telegram/utils/request.py +++ b/telegram/utils/request.py @@ -56,7 +56,7 @@ raise -from telegram import InputFile, TelegramError, InputMedia, constants +from telegram import InputFile, TelegramError, InputMedia from telegram.error import ( Unauthorized, NetworkError, @@ -87,8 +87,7 @@ def _render_part(self: RequestField, name: str, value: str) -> str: logging.getLogger('urllib3').setLevel(logging.WARNING) -USER_AGENT = constants.REQUEST_USER_AGENT -""":const:`telegram.constants.REQUEST_USER_AGENT`""" +USER_AGENT = 'Python Telegram Bot (https://github.com/python-telegram-bot/python-telegram-bot)' class Request: From 4a7b13161132640706a8e5125231d87de19efbc9 Mon Sep 17 00:00:00 2001 From: NikitaPirate Date: Mon, 12 Oct 2020 23:47:41 +0300 Subject: [PATCH 3/5] Overhaul constants --- telegram/constants.py | 20 ++++++++++++++++++++ telegram/dice.py | 6 +++--- telegram/ext/conversationhandler.py | 1 + telegram/messageentity.py | 21 +++------------------ 4 files changed, 27 insertions(+), 21 deletions(-) diff --git a/telegram/constants.py b/telegram/constants.py index 59961b3ff3b..dd14b11ada1 100644 --- a/telegram/constants.py +++ b/telegram/constants.py @@ -80,6 +80,7 @@ DICE_DICE (:obj:`str`): '🎲' DICE_DARTS (:obj:`str`): '🎯' DICE_BASKETBALL (:obj:`str`): 'πŸ€' + DICE_ALL_EMOJI (List[:obj:`str`]): List of all supported base emoji. :class:`telegram.MessageEntity`: @@ -99,6 +100,7 @@ MESSAGEENTITY_TEXT_MENTION (:obj:`str`): 'text_mention' MESSAGEENTITY_UNDERLINE (:obj:`str`): 'underline' MESSAGEENTITY_STRIKETHROUGH (:obj:`str`): 'strikethrough' + MESSAGEENTITY_ALL_TYPES (List[:obj:`str`]): List of all the types of message entity. :class:`telegram.ParseMode`: @@ -165,6 +167,7 @@ DICE_DICE: str = '🎲' DICE_DARTS: str = '🎯' DICE_BASKETBALL: str = 'πŸ€' +DICE_ALL_EMOJI: List[str] = [DICE_DICE, DICE_DARTS, DICE_BASKETBALL] MESSAGEENTITY_MENTION: str = 'mention' MESSAGEENTITY_HASHTAG: str = 'hashtag' @@ -181,6 +184,23 @@ MESSAGEENTITY_TEXT_MENTION: str = 'text_mention' MESSAGEENTITY_UNDERLINE: str = 'underline' MESSAGEENTITY_STRIKETHROUGH: str = 'strikethrough' +MESSAGEENTITY_ALL_TYPES: List[str] = [ + MESSAGEENTITY_MENTION, + MESSAGEENTITY_HASHTAG, + MESSAGEENTITY_CASHTAG, + MESSAGEENTITY_PHONE_NUMBER, + MESSAGEENTITY_BOT_COMMAND, + MESSAGEENTITY_URL, + MESSAGEENTITY_EMAIL, + MESSAGEENTITY_BOLD, + MESSAGEENTITY_ITALIC, + MESSAGEENTITY_CODE, + MESSAGEENTITY_PRE, + MESSAGEENTITY_TEXT_LINK, + MESSAGEENTITY_TEXT_MENTION, + MESSAGEENTITY_UNDERLINE, + MESSAGEENTITY_STRIKETHROUGH, +] PARSEMODE_MARKDOWN: str = 'Markdown' PARSEMODE_MARKDOWN_V2: str = 'MarkdownV2' diff --git a/telegram/dice.py b/telegram/dice.py index d775ffc99fc..2fa3deba53b 100644 --- a/telegram/dice.py +++ b/telegram/dice.py @@ -61,6 +61,6 @@ def __init__(self, value: int, emoji: str, **kwargs: Any): """:const:`telegram.constants.DICE_DARTS`""" BASKETBALL: str = constants.DICE_BASKETBALL """:const:`telegram.constants.DICE_BASKETBALL`""" - ALL_EMOJI: List[str] = [DICE, DARTS, BASKETBALL] - """List[:obj:`str`]: List of all supported base emoji. Currently :attr:`DICE`, - :attr:`DARTS` and :attr:`BASKETBALL`.""" + ALL_EMOJI: List[str] = constants.DICE_ALL_EMOJI + """:const:`telegram.constants.DICE_ALL_EMOJI`\n + List of all supported base emoji""" diff --git a/telegram/ext/conversationhandler.py b/telegram/ext/conversationhandler.py index 7acd324d56c..bee391ccd50 100644 --- a/telegram/ext/conversationhandler.py +++ b/telegram/ext/conversationhandler.py @@ -168,6 +168,7 @@ class ConversationHandler(Handler): ValueError """ + END = -1 """:obj:`int`: Used as a constant to return when a conversation is ended.""" TIMEOUT = -2 diff --git a/telegram/messageentity.py b/telegram/messageentity.py index 6093eca7c9f..ffdc39b3518 100644 --- a/telegram/messageentity.py +++ b/telegram/messageentity.py @@ -120,21 +120,6 @@ def de_json(cls, data: Optional[JSONDict], bot: 'Bot') -> Optional['MessageEntit """:const:`telegram.constants.MESSAGEENTITY_UNDERLINE`""" STRIKETHROUGH: str = constants.MESSAGEENTITY_STRIKETHROUGH """:const:`telegram.constants.MESSAGEENTITY_STRIKETHROUGH`""" - ALL_TYPES: List[str] = [ - MENTION, - HASHTAG, - CASHTAG, - PHONE_NUMBER, - BOT_COMMAND, - URL, - EMAIL, - BOLD, - ITALIC, - CODE, - PRE, - TEXT_LINK, - TEXT_MENTION, - UNDERLINE, - STRIKETHROUGH, - ] - """List[:obj:`str`]: List of all the types.""" + ALL_TYPES: List[str] = constants.MESSAGEENTITY_ALL_TYPES + """:const:`telegram.constants.MESSAGEENTITY_ALL_TYPES`\n + List of all the types""" From 1f53b86dd56af1cb345fdaf4e5cc775c53bab01a Mon Sep 17 00:00:00 2001 From: NikitaPirate Date: Tue, 13 Oct 2020 00:04:46 +0300 Subject: [PATCH 4/5] Overhaul constants --- telegram/constants.py | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/telegram/constants.py b/telegram/constants.py index dd14b11ada1..669ce0ba425 100644 --- a/telegram/constants.py +++ b/telegram/constants.py @@ -185,21 +185,21 @@ MESSAGEENTITY_UNDERLINE: str = 'underline' MESSAGEENTITY_STRIKETHROUGH: str = 'strikethrough' MESSAGEENTITY_ALL_TYPES: List[str] = [ - MESSAGEENTITY_MENTION, - MESSAGEENTITY_HASHTAG, - MESSAGEENTITY_CASHTAG, - MESSAGEENTITY_PHONE_NUMBER, - MESSAGEENTITY_BOT_COMMAND, - MESSAGEENTITY_URL, - MESSAGEENTITY_EMAIL, - MESSAGEENTITY_BOLD, - MESSAGEENTITY_ITALIC, - MESSAGEENTITY_CODE, - MESSAGEENTITY_PRE, - MESSAGEENTITY_TEXT_LINK, - MESSAGEENTITY_TEXT_MENTION, - MESSAGEENTITY_UNDERLINE, - MESSAGEENTITY_STRIKETHROUGH, + MESSAGEENTITY_MENTION, + MESSAGEENTITY_HASHTAG, + MESSAGEENTITY_CASHTAG, + MESSAGEENTITY_PHONE_NUMBER, + MESSAGEENTITY_BOT_COMMAND, + MESSAGEENTITY_URL, + MESSAGEENTITY_EMAIL, + MESSAGEENTITY_BOLD, + MESSAGEENTITY_ITALIC, + MESSAGEENTITY_CODE, + MESSAGEENTITY_PRE, + MESSAGEENTITY_TEXT_LINK, + MESSAGEENTITY_TEXT_MENTION, + MESSAGEENTITY_UNDERLINE, + MESSAGEENTITY_STRIKETHROUGH, ] PARSEMODE_MARKDOWN: str = 'Markdown' From 40eae2da60675ebb6a5201e7b4e359a1e3d7a3a7 Mon Sep 17 00:00:00 2001 From: Hinrich Mahler Date: Tue, 13 Oct 2020 17:48:45 +0200 Subject: [PATCH 5/5] Minor docstring change --- telegram/dice.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/telegram/dice.py b/telegram/dice.py index 2fa3deba53b..47a3e6a42a1 100644 --- a/telegram/dice.py +++ b/telegram/dice.py @@ -62,5 +62,4 @@ def __init__(self, value: int, emoji: str, **kwargs: Any): BASKETBALL: str = constants.DICE_BASKETBALL """:const:`telegram.constants.DICE_BASKETBALL`""" ALL_EMOJI: List[str] = constants.DICE_ALL_EMOJI - """:const:`telegram.constants.DICE_ALL_EMOJI`\n - List of all supported base emoji""" + """:const:`telegram.constants.DICE_ALL_EMOJI`"""