diff --git a/aiogram/types/__init__.py b/aiogram/types/__init__.py index c706a915..52ad44fe 100644 --- a/aiogram/types/__init__.py +++ b/aiogram/types/__init__.py @@ -47,7 +47,6 @@ from .webhook_info import WebhookInfo __all__ = [ 'Animation', 'Audio', - 'Base', 'CallbackQuery', 'Chat', 'ChatActions', diff --git a/aiogram/types/animation.py b/aiogram/types/animation.py index 7233e2a2..41dbe580 100644 --- a/aiogram/types/animation.py +++ b/aiogram/types/animation.py @@ -3,6 +3,9 @@ from .photo_size import PhotoSize class Animation(Deserializable): + """ + Represent an animation + """ def __init__(self, file_id, thumb, file_name, mime_type, file_size): self.file_id: str = file_id self.thumb: PhotoSize = thumb diff --git a/aiogram/types/base.py b/aiogram/types/base.py index c1cb0e67..a0e0ca69 100644 --- a/aiogram/types/base.py +++ b/aiogram/types/base.py @@ -4,21 +4,39 @@ import time def deserialize(deserializable, data): + """ + Deserialize object if have data + + :param deserializable: :class:`aiogram.types.Deserializable` + :param data: + :return: + """ if data: return deserializable.de_json(data) def deserialize_array(deserializable, array): + """ + Deserialize array of objects + + :param deserializable: + :param array: + :return: + """ if array: return [deserialize(deserializable, item) for item in array] class Serializable: + """ + Subclasses of this class are guaranteed to be able to be created from a json-style dict. + """ + def to_json(self): """ - Returns a JSON string representation of this class. + Returns a JSON representation of this class. - :return: a JSON. + :return: dict """ return {k: v.to_json() if hasattr(v, 'to_json') else v for k, v in self.__dict__.items() if not k.startswith('_')} @@ -44,6 +62,9 @@ class Deserializable: @property def bot(self): + """ + Bot instance + """ if not hasattr(self, '_bot'): raise AttributeError(f"{self.__class__.__name__} is not configured.") return getattr(self, '_bot') @@ -57,6 +78,9 @@ class Deserializable: @property def parent(self): + """ + Parent object + """ return getattr(self, '_parent', None) @parent.setter diff --git a/aiogram/types/chat.py b/aiogram/types/chat.py index a2627d53..52040cc1 100644 --- a/aiogram/types/chat.py +++ b/aiogram/types/chat.py @@ -2,6 +2,12 @@ from .base import Deserializable class Chat(Deserializable): + """ + This object represents a chat. + + https://core.telegram.org/bots/api#chat + """ + def __init__(self, id, type, title, username, first_name, last_name, all_members_are_administrators): self.id: int = id self.type: str = type @@ -36,6 +42,9 @@ class Chat(Deserializable): @property def mention(self): + """ + Get mention if dialog have username or full name if this is Private dialog otherwise None + """ if self.username: return '@' + self.username if self.type == ChatType.PRIVATE: @@ -44,6 +53,15 @@ class Chat(Deserializable): class ChatType: + """ + List of chat types + + :key: PRIVATE + :key: GROUP + :key: SUPER_GROUP + :key: CHANNEL + """ + PRIVATE = 'private' GROUP = 'group' SUPER_GROUP = 'supergroup' @@ -51,6 +69,21 @@ class ChatType: class ChatActions: + """ + List of chat actions + + :key: TYPING + :key: UPLOAD_PHOTO + :key: RECORD_VIDEO + :key: UPLOAD_VIDEO + :key: RECORD_AUDIO + :key: UPLOAD_AUDIO + :key: UPLOAD_DOCUMENT + :key: FIND_LOCATION + :key: RECORD_VIDEO_NOTE + :key: UPLOAD_VIDEO_NOTE + """ + TYPING = 'typing' UPLOAD_PHOTO = 'upload_photo' RECORD_VIDEO = 'record_video' diff --git a/aiogram/types/message.py b/aiogram/types/message.py index 4bcd216e..3cd85eee 100644 --- a/aiogram/types/message.py +++ b/aiogram/types/message.py @@ -21,6 +21,12 @@ from ..exceptions import TelegramAPIError class Message(Deserializable): + """ + This object represents a message. + + https://core.telegram.org/bots/api#message + """ + def __init__(self, message_id, from_user, date, chat, forward_from, forward_from_chat, forward_from_message_id, forward_date, reply_to_message, edit_date, text, entities, audio, document, game, photo, sticker, video, voice, video_note, new_chat_members, caption, contact, location, venue, left_chat_member, @@ -148,9 +154,17 @@ class Message(Deserializable): successful_payment, content_type) def is_command(self): + """ + Check message text is command + :return: bool + """ return self.text and self.text.startswith('/') def get_full_command(self): + """ + Split command and args + :return: tuple of (command, args) + """ if self.is_command(): command, _, args = self.text.partition(' ') return command, args @@ -167,13 +181,35 @@ class Message(Deserializable): async def reply(self, text, parse_mode=None, disable_web_page_preview=None, disable_notification=None, reply_markup=None) -> 'Message': + """ + Reply to this message + + :param text: str + :param parse_mode: str + :param disable_web_page_preview: bool + :param disable_notification: bool + :param reply_markup: + :return: :class:`aoigram.types.Message` + """ return await self.bot.send_message(self.chat.id, text, parse_mode, disable_web_page_preview, disable_notification, self.message_id, reply_markup) async def forward(self, chat_id, disable_notification=None) -> 'Message': + """ + Forward this message + + :param chat_id: + :param disable_notification: + :return: + """ return await self.bot.forward_message(chat_id, self.chat.id, self.message_id, disable_notification) async def delete(self): + """ + Delete this message + + :return: bool + """ try: await self.bot.delete_message(self.chat.id, self.message_id) except TelegramAPIError: @@ -182,6 +218,24 @@ class Message(Deserializable): class ContentType: + """ + List of message content types + + :key: TEXT + :key: AUDIO + :key: DOCUMENT + :key: GAME + :key: PHOTO + :key: STICKER + :key: VIDEO + :key: VOICE + :key: NEW_CHAT_MEMBERS + :key: LEFT_CHAT_MEMBER + :key: INVOICE + :key: SUCCESSFUL_PAYMENT + :key: UNKNOWN + """ + TEXT = 'text' AUDIO = 'audio' DOCUMENT = 'document' @@ -199,5 +253,12 @@ class ContentType: class ParseMode: + """ + Parse modes + + :key: MARKDOWN + :key: HTML + """ + MARKDOWN = 'markdown' HTML = 'html' diff --git a/aiogram/types/message_entity.py b/aiogram/types/message_entity.py index f9ce5471..cac0a192 100644 --- a/aiogram/types/message_entity.py +++ b/aiogram/types/message_entity.py @@ -3,6 +3,11 @@ from .user import User class MessageEntity(Deserializable): + """ + This object represents one special entity in a text message. For example, hashtags, usernames, URLs, etc. + + https://core.telegram.org/bots/api#messageentity + """ def __init__(self, type, offset, length, url, user): self.type: str = type self.offset: int = offset @@ -24,6 +29,22 @@ class MessageEntity(Deserializable): class MessageEntityType: + """ + List of entity types + + :key: MENTION + :key: HASHTAG + :key: BOT_COMMAND + :key: URL + :key: EMAIL + :key: BOLD + :key: ITALIC + :key: CODE + :key: PRE + :key: TEXT_LINK + :key: TEXT_MENTION + """ + MENTION = 'mention' # @username HASHTAG = 'hashtag' BOT_COMMAND = 'bot_command' diff --git a/aiogram/types/photo_size.py b/aiogram/types/photo_size.py index 77199564..9b514706 100644 --- a/aiogram/types/photo_size.py +++ b/aiogram/types/photo_size.py @@ -2,6 +2,11 @@ from .base import deserialize, Deserializable class PhotoSize(Deserializable): + """ + This object represents one size of a photo or a file / sticker thumbnail. + + https://core.telegram.org/bots/api#photosize + """ def __init__(self, file_id, width, height, file_size): self.file_id: str = file_id self.width: int = width diff --git a/aiogram/types/user.py b/aiogram/types/user.py index d4031cd8..5822d6d1 100644 --- a/aiogram/types/user.py +++ b/aiogram/types/user.py @@ -7,6 +7,11 @@ from .base import Deserializable class User(Deserializable): + """ + This object represents a Telegram user or bot. + + https://core.telegram.org/bots/api#user + """ def __init__(self, id, first_name, last_name, username, language_code): self.id: int = id self.first_name: str = first_name @@ -28,6 +33,11 @@ class User(Deserializable): @property def full_name(self): + """ + You can get full name of user. + + :return: str + """ full_name = self.first_name if self.last_name: full_name += ' ' + self.last_name @@ -35,12 +45,23 @@ class User(Deserializable): @property def mention(self): + """ + You can get menthion to user (If user have username, otherwise return full name) + + :return: str + """ if self.username: return '@' + self.username return self.full_name @property def locale(self) -> babel.core.Locale or None: + """ + This property require `Babel `_ module + + :return: :class:`babel.core.Locale` + :raise: ImportError: when babel is not installed. + """ if not babel: raise ImportError('Babel is not installed!') if not self.language_code: diff --git a/docs/source/api.rst b/docs/source/aiogram.bot.Bot.rst similarity index 72% rename from docs/source/api.rst rename to docs/source/aiogram.bot.Bot.rst index aed6a907..749240ad 100644 --- a/docs/source/api.rst +++ b/docs/source/aiogram.bot.Bot.rst @@ -1,9 +1,9 @@ -API Reference -============= +aiogram.bot.Bot +=============== For detailed information about parameters read the official `Telegram Bot API reference `_ -.. automodule:: aiogram.bot +.. automodule:: aiogram.bot.bot :members: :show-inheritance: diff --git a/docs/source/aiogram.rst b/docs/source/aiogram.rst new file mode 100644 index 00000000..a758a3e6 --- /dev/null +++ b/docs/source/aiogram.rst @@ -0,0 +1,12 @@ +API Reference +============= + +Submodules +---------- + + +.. toctree:: + + aiogram.bot.BaseBot + aiogram.bot.Bot + aiogram.types diff --git a/docs/source/aiogram.types.rst b/docs/source/aiogram.types.rst new file mode 100644 index 00000000..5327b14f --- /dev/null +++ b/docs/source/aiogram.types.rst @@ -0,0 +1,269 @@ +Data types +========== + +Bases +----- +:class:`aiogram.types.base.Serializable` + +:class:`aiogram.types.base.Deserializable` + +.. automodule:: aiogram.types.base + :members: + :show-inheritance: + +Update +------ +:class:`aiogram.types.Update` + +.. automodule:: aiogram.types.update + :members: + :show-inheritance: + +WebhookInfo +----------- +:class:`aiogram.types.WebhookInfo` + +.. automodule:: aiogram.types.webhook_info + :members: + :show-inheritance: + +User +---- +:class:`aiogram.types.User` + +.. automodule:: aiogram.types.user + :members: + :show-inheritance: + +Chat +---- +:class:`aiogram.types.Chat` + +.. automodule:: aiogram.types.chat + :members: + :show-inheritance: + +Message +------- +:class:`aiogram.types.Message` + +.. automodule:: aiogram.types.message + :members: + :show-inheritance: + +MessageEntity +------------- +:class:`aiogram.types.MessageEntity` + +.. automodule:: aiogram.types.message_entity + :members: + :show-inheritance: + + +PhotoSize +--------- +:class:`aiogram.types.PhotoSize` + +.. automodule:: aiogram.types.photo_size + :members: + :show-inheritance: + +Audio +----- +:class:`aiogram.types.Audio` + +.. automodule:: aiogram.types.audio + :members: + :show-inheritance: + +Document +-------- +:class:`aiogram.types.Document` + +.. automodule:: aiogram.types.document + :members: + :show-inheritance: + +Sticker +------- +:class:`aiogram.types.Sticker` + +.. automodule:: aiogram.types.sticker + :members: + :show-inheritance: + +Video +----- +:class:`aiogram.types.Video` + +.. automodule:: aiogram.types.video + :members: + :show-inheritance: + +Voice +----- +:class:`aiogram.types.Voice` + +.. automodule:: aiogram.types.voice + :members: + :show-inheritance: + +VideoNote +--------- +:class:`aiogram.types.VideoNote` + +.. automodule:: aiogram.types.video_note + :members: + :show-inheritance: + +Contact +------- +:class:`aiogram.types.Contact` + +.. automodule:: aiogram.types.contact + :members: + :show-inheritance: + +Location +-------- +:class:`aiogram.types.Location` + +.. automodule:: aiogram.types.location + :members: + :show-inheritance: + +Venue +----- +:class:`aiogram.types.Venue` + +.. automodule:: aiogram.types.venue + :members: + :show-inheritance: + +UserProfilePhotos +----------------- +:class:`aiogram.types.UserProfilePhotos` + +.. automodule:: aiogram.types.user_profile_photos + :members: + :show-inheritance: + +File +---- +:class:`aiogram.types.File` + +.. automodule:: aiogram.types.file + :members: + :show-inheritance: + +ReplyKeyboardMarkup & KeyboardButton & ReplyKeyboardRemove +---------------------------------------------------------- +:class:`aiogram.types.ReplyKeyboardMarkup` + +:class:`aiogram.types.KeyboardButton` + +:class:`aiogram.types.ReplyKeyboardRemove` + +.. automodule:: aiogram.types.reply_keyboard + :members: + :show-inheritance: + +InlineKeyboardMarkup & InlineKeyboardButton +------------------------------------------- +:class:`aiogram.types.InlineKeyboardMarkup` + +:class:`aiogram.types.InlineKeyboardButton` + +.. automodule:: aiogram.types.inline_keyboard + :members: + :show-inheritance: + +CallbackQuery +------------- +:class:`aiogram.types.CallbackQuery` + +.. automodule:: aiogram.types.callback_query + :members: + :show-inheritance: + +ForceReply +---------- +:class:`aiogram.types.ForceReply` + +.. automodule:: aiogram.types.force_reply + :members: + :show-inheritance: + +ChatMember +---------- +:class:`aiogram.types.ChatMember` + +.. automodule:: aiogram.types.chat_member + :members: + :show-inheritance: + +Inline mode objects +------------------- + +.. automodule:: aiogram.types.inline_query + :members: + :show-inheritance: + +.. automodule:: aiogram.types.chosen_inline_result + :members: + :show-inheritance: + +.. automodule:: aiogram.types.inline_query_result + :members: + :show-inheritance: + +Payments +-------- + +.. automodule:: aiogram.types.labeled_price + :members: + :show-inheritance: + +.. automodule:: aiogram.types.invoice + :members: + :show-inheritance: + +.. automodule:: aiogram.types.shipping_address + :members: + :show-inheritance: + +.. automodule:: aiogram.types.order_info + :members: + :show-inheritance: + +.. automodule:: aiogram.types.shipping_option + :members: + :show-inheritance: + +.. automodule:: aiogram.types.successful_payment + :members: + :show-inheritance: + +.. automodule:: aiogram.types.shipping_query + :members: + :show-inheritance: + +.. automodule:: aiogram.types.pre_checkout_query + :members: + :show-inheritance: + + +Games +----- + +.. automodule:: aiogram.types.game + :members: + :show-inheritance: + +.. automodule:: aiogram.types.animation + :members: + :show-inheritance: + +.. automodule:: aiogram.types.game_high_score + :members: + :show-inheritance: diff --git a/docs/source/index.rst b/docs/source/index.rst index fafa1c3c..9771c6e0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -53,7 +53,7 @@ Contents .. toctree:: install quick_start - api + aiogram features