From 0b8a37b38aa0d5875673620697cb1af7bdee8b29 Mon Sep 17 00:00:00 2001 From: Alex Root Junior Date: Tue, 6 Jun 2017 15:02:27 +0300 Subject: [PATCH] Add some doc's --- aiogram/types/animation.py | 5 +- aiogram/types/audio.py | 5 + aiogram/types/callback_query.py | 13 + aiogram/types/chat_member.py | 5 + aiogram/types/chosen_inline_result.py | 5 + aiogram/types/contact.py | 5 + aiogram/types/document.py | 5 + aiogram/types/file.py | 10 + aiogram/types/force_reply.py | 10 + aiogram/types/game.py | 7 + aiogram/types/game_high_score.py | 5 + aiogram/types/inline_keyboard.py | 10 + aiogram/types/inline_query.py | 7 + aiogram/types/inline_query_result.py | 247 ++++++++++++++++++ aiogram/types/invoice.py | 5 + aiogram/types/labeled_price.py | 5 + aiogram/types/location.py | 5 + aiogram/types/order_info.py | 5 + aiogram/types/pre_checkout_query.py | 5 + aiogram/types/reply_keyboard.py | 25 ++ aiogram/types/response_parameters.py | 21 ++ aiogram/types/shipping_address.py | 5 + aiogram/types/shipping_option.py | 5 + aiogram/types/shipping_query.py | 5 + aiogram/types/sticker.py | 5 + aiogram/types/successful_payment.py | 5 + aiogram/types/update.py | 7 + aiogram/types/user_profile_photos.py | 5 + aiogram/types/venue.py | 5 + aiogram/types/video.py | 5 + aiogram/types/video_note.py | 5 + aiogram/types/voice.py | 5 + aiogram/types/webhook_info.py | 5 + .../{aiogram.bot.Bot.rst => aiogram.bot.rst} | 11 +- docs/source/aiogram.dispatcher.rst | 8 + docs/source/aiogram.rst | 4 +- docs/source/aiogram.types.rst | 8 + 37 files changed, 498 insertions(+), 5 deletions(-) create mode 100644 aiogram/types/response_parameters.py rename docs/source/{aiogram.bot.Bot.rst => aiogram.bot.rst} (63%) create mode 100644 docs/source/aiogram.dispatcher.rst diff --git a/aiogram/types/animation.py b/aiogram/types/animation.py index 41dbe580..07611517 100644 --- a/aiogram/types/animation.py +++ b/aiogram/types/animation.py @@ -4,7 +4,10 @@ from .photo_size import PhotoSize class Animation(Deserializable): """ - Represent an animation + You can provide an animation for your game so that it looks stylish in chats. + This object represents an animation file to be displayed in the message containing a game. + + https://core.telegram.org/bots/api#animation """ def __init__(self, file_id, thumb, file_name, mime_type, file_size): self.file_id: str = file_id diff --git a/aiogram/types/audio.py b/aiogram/types/audio.py index 97c0305b..c3566684 100644 --- a/aiogram/types/audio.py +++ b/aiogram/types/audio.py @@ -2,6 +2,11 @@ from .base import Deserializable class Audio(Deserializable): + """ + This object represents an audio file to be treated as music by the Telegram clients. + + https://core.telegram.org/bots/api#audio + """ def __init__(self, file_id, duration, performer, title, mime_type, file_size): self.file_id: str = file_id self.duration: int = duration diff --git a/aiogram/types/callback_query.py b/aiogram/types/callback_query.py index f4f2d5bb..ffbabef8 100644 --- a/aiogram/types/callback_query.py +++ b/aiogram/types/callback_query.py @@ -4,6 +4,19 @@ from .user import User class CallbackQuery(Deserializable): + """ + This object represents an incoming callback query from a callback button in an inline keyboard. + + If the button that originated the query was attached to a message sent by the bot, + the field message will be present. + + If the button was attached to a message sent via the bot (in inline mode), + the field inline_message_id will be present. + + Exactly one of the fields data or game_short_name will be present. + + https://core.telegram.org/bots/api#callbackquery + """ def __init__(self, id, from_user, message, inline_message_id, chat_instance, data, game_short_name): self.id: int = id self.from_user: User = from_user diff --git a/aiogram/types/chat_member.py b/aiogram/types/chat_member.py index 0b0b3b58..c61dd1fb 100644 --- a/aiogram/types/chat_member.py +++ b/aiogram/types/chat_member.py @@ -3,6 +3,11 @@ from .user import User class ChatMember(Deserializable): + """ + This object contains information about one member of the chat. + + https://core.telegram.org/bots/api#chatmember + """ def __init__(self, user, status): self.user: User = user self.status: str = status diff --git a/aiogram/types/chosen_inline_result.py b/aiogram/types/chosen_inline_result.py index b21817a2..5f308d09 100644 --- a/aiogram/types/chosen_inline_result.py +++ b/aiogram/types/chosen_inline_result.py @@ -4,6 +4,11 @@ from .user import User class ChosenInlineResult(Deserializable): + """ + Represents a result of an inline query that was chosen by the user and sent to their chat partner. + + https://core.telegram.org/bots/api#choseninlineresult + """ def __init__(self, result_id, from_user, location, inline_message_id, query): self.result_id: str = result_id self.from_user: User = from_user diff --git a/aiogram/types/contact.py b/aiogram/types/contact.py index 5de29fda..582909fa 100644 --- a/aiogram/types/contact.py +++ b/aiogram/types/contact.py @@ -2,6 +2,11 @@ from .base import Deserializable class Contact(Deserializable): + """ + This object represents a phone contact. + + https://core.telegram.org/bots/api#contact + """ def __init__(self, phone_number, first_name, last_name, user_id): self.phone_number: str = phone_number self.first_name: str = first_name diff --git a/aiogram/types/document.py b/aiogram/types/document.py index 03e2f878..fdcc5049 100644 --- a/aiogram/types/document.py +++ b/aiogram/types/document.py @@ -3,6 +3,11 @@ from .photo_size import PhotoSize class Document(Deserializable): + """ + This object represents a general file (as opposed to photos, voice messages and audio files). + + https://core.telegram.org/bots/api#document + """ 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/file.py b/aiogram/types/file.py index 7243797d..da10af51 100644 --- a/aiogram/types/file.py +++ b/aiogram/types/file.py @@ -2,6 +2,16 @@ from .base import Deserializable class File(Deserializable): + """ + This object represents a file ready to be downloaded. + + The file can be downloaded via the link https://api.telegram.org/file/bot/. + + It is guaranteed that the link will be valid for at least 1 hour. When the link expires, + a new one can be requested by calling getFile. + + https://core.telegram.org/bots/api#file + """ def __init__(self, file_id, file_size, file_path): self.file_id: str = file_id self.file_size: int = file_size diff --git a/aiogram/types/force_reply.py b/aiogram/types/force_reply.py index 4fc52ec4..048ebf2f 100644 --- a/aiogram/types/force_reply.py +++ b/aiogram/types/force_reply.py @@ -2,6 +2,16 @@ from .base import Serializable class ForceReply(Serializable): + """ + Upon receiving a message with this object, + Telegram clients will display a reply interface to the user + (act as if the user has selected the bot‘s message and tapped ’Reply'). + + This can be extremely useful if you want to create user-friendly step-by-step + interfaces without having to sacrifice privacy mode. + + https://core.telegram.org/bots/api#forcereply + """ def __init__(self, selective=None): self.selective = selective diff --git a/aiogram/types/game.py b/aiogram/types/game.py index 76a27cc8..5ac094f7 100644 --- a/aiogram/types/game.py +++ b/aiogram/types/game.py @@ -5,6 +5,13 @@ from .photo_size import PhotoSize class Game(Deserializable): + """ + This object represents a game. + + Use BotFather to create and edit games, their short names will act as unique identifiers. + + https://core.telegram.org/bots/api#game + """ def __init__(self, title, description, photo, text, text_entities, animation): self.title = title self.description = description diff --git a/aiogram/types/game_high_score.py b/aiogram/types/game_high_score.py index c000fa60..c17ad4b3 100644 --- a/aiogram/types/game_high_score.py +++ b/aiogram/types/game_high_score.py @@ -3,6 +3,11 @@ from .user import User class GameHighScore(Deserializable): + """ + This object represents one row of the high scores table for a game. + + https://core.telegram.org/bots/api#gamehighscore + """ def __init__(self, position, user, score): self.position: int = position self.user: User = user diff --git a/aiogram/types/inline_keyboard.py b/aiogram/types/inline_keyboard.py index 339a8287..9e3a2ee7 100644 --- a/aiogram/types/inline_keyboard.py +++ b/aiogram/types/inline_keyboard.py @@ -2,6 +2,11 @@ from .base import Serializable class InlineKeyboardMarkup(Serializable): + """ + This object represents an inline keyboard that appears right next to the message it belongs to. + + https://core.telegram.org/bots/api#inlinekeyboardmarkup + """ def __init__(self, row_width=3): self.row_width = row_width @@ -31,6 +36,11 @@ class InlineKeyboardMarkup(Serializable): class InlineKeyboardButton(Serializable): + """ + This object represents one button of an inline keyboard. You must use exactly one of the optional fields. + + https://core.telegram.org/bots/api#inlinekeyboardbutton + """ def __init__(self, text, url=None, callback_data=None, switch_inline_query=None, switch_inline_query_current_chat=None, callback_game=None, pay=None): self.text = text diff --git a/aiogram/types/inline_query.py b/aiogram/types/inline_query.py index 24e48fbf..eb20b951 100644 --- a/aiogram/types/inline_query.py +++ b/aiogram/types/inline_query.py @@ -4,6 +4,13 @@ from .user import User class InlineQuery(Deserializable): + """ + This object represents an incoming inline query. + + When the user sends an empty query, your bot could return some default or trending results. + + https://core.telegram.org/bots/api#inlinequery + """ def __init__(self, id, from_user, location, query, offset): self.id: int = id self.from_user: User = from_user diff --git a/aiogram/types/inline_query_result.py b/aiogram/types/inline_query_result.py index 433e281e..5f5139df 100644 --- a/aiogram/types/inline_query_result.py +++ b/aiogram/types/inline_query_result.py @@ -3,16 +3,77 @@ from .inline_keyboard import InlineKeyboardMarkup class InputMessageContent(Serializable): + """ + This object represents the content of a message to be sent as a result of an inline query. + + Telegram clients currently support the following 4 types: + + :class:`aiogram.types.InputTextMessageContent` + :class:`aiogram.types.InputLocationMessageContent` + :class:`aiogram.types.InputVenueMessageContent` + :class:`aiogram.types.InputContactMessageContent` + """ def to_json(self): return {k: v.to_json() if hasattr(v, 'to_json') else v for k, v in self.__dict__.items() if not k.startswith('_')} class InlineQueryResult(InputMessageContent): + """ + This object represents one result of an inline query. + + Telegram clients currently support results of the following 20 types: + + :class:`aiogram.types.InlineQueryResultCachedAudio` + + :class:`aiogram.types.InlineQueryResultCachedDocument` + + :class:`aiogram.types.InlineQueryResultCachedGif` + + :class:`aiogram.types.InlineQueryResultCachedMpeg4Gif` + + :class:`aiogram.types.InlineQueryResultCachedPhoto` + + :class:`aiogram.types.InlineQueryResultCachedSticker` + + :class:`aiogram.types.InlineQueryResultCachedVideo` + + :class:`aiogram.types.InlineQueryResultCachedVoice` + + :class:`aiogram.types.InlineQueryResultArticle` + + :class:`aiogram.types.InlineQueryResultAudio` + + :class:`aiogram.types.InlineQueryResultContact` + + :class:`aiogram.types.InlineQueryResultGame` + + :class:`aiogram.types.InlineQueryResultDocument` + + :class:`aiogram.types.InlineQueryResultGif` + + :class:`aiogram.types.InlineQueryResultLocation` + + :class:`aiogram.types.InlineQueryResultMpeg4Gif` + + :class:`aiogram.types.InlineQueryResultPhoto` + + :class:`aiogram.types.InlineQueryResultVenue` + + :class:`aiogram.types.InlineQueryResultVideo` + + :class:`aiogram.types.InlineQueryResultVoice` + + """ pass class InlineQueryResultArticle(InlineQueryResult): + """ + Represents a link to an article or web page. + + https://core.telegram.org/bots/api#inlinequeryresultarticle + """ def __init__(self, type: str, id: str, title: str, input_message_content: InputMessageContent, reply_markup: InlineKeyboardMarkup = None, url: str = None, hide_url: bool = None, description: str = None, thumb_url: str = None, thumb_width: int = None, thumb_height: int = None): @@ -30,6 +91,14 @@ class InlineQueryResultArticle(InlineQueryResult): class InlineQueryResultPhoto(InlineQueryResult): + """ + Represents a link to a photo. By default, this photo will be sent by the user with optional caption. + + Alternatively, you can use input_message_content to send a message with the specified content instead + of the photo. + + https://core.telegram.org/bots/api#inlinequeryresultphoto + """ def __init__(self, type: str, id: str, photo_url: str, thumb_url: str, photo_width: int = None, photo_height: int = None, title: str = None, description: str = None, caption: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): @@ -47,6 +116,16 @@ class InlineQueryResultPhoto(InlineQueryResult): class InlineQueryResultGif(InlineQueryResult): + """ + Represents a link to an animated GIF file. + + By default, this animated GIF file will be sent by the user with optional caption. + + Alternatively, you can use input_message_content to send a message with the specified + content instead of the animation. + + https://core.telegram.org/bots/api#inlinequeryresultgif + """ def __init__(self, type: str, id: str, gif_url: str, thumb_url: str, gif_width: int = None, gif_height: int = None, gif_duration: int = None, title: str = None, caption: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): @@ -64,6 +143,16 @@ class InlineQueryResultGif(InlineQueryResult): class InlineQueryResultMpeg4Gif(InlineQueryResult): + """ + Represents a link to a video animation (H.264/MPEG-4 AVC video without sound). + + By default, this animated MPEG-4 file will be sent by the user with optional caption. + + Alternatively, you can use input_message_content to send a message with the specified content + instead of the animation. + + https://core.telegram.org/bots/api#inlinequeryresultmpeg4gif + """ def __init__(self, type: str, id: str, mpeg4_url: str, thumb_url: str, mpeg4_width: int = None, mpeg4_height: int = None, mpeg4_duration: int = None, title: str = None, caption: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): @@ -81,6 +170,14 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult): class InlineQueryResultVideo(InlineQueryResult): + """ + Represents a link to a page containing an embedded video player or a video file. + By default, this video file will be sent by the user with an optional caption. + Alternatively, you can use input_message_content to send a message with the specified content + instead of the video. + + https://core.telegram.org/bots/api#inlinequeryresultvideo + """ def __init__(self, type: str, id: str, video_url: str, mime_type: str, thumb_url: str, title: str, caption: str = None, video_width: int = None, video_height: int = None, video_duration: int = None, description: str = None, reply_markup: InlineKeyboardMarkup = None, @@ -101,6 +198,12 @@ class InlineQueryResultVideo(InlineQueryResult): class InlineQueryResultAudio(InlineQueryResult): + """ + Represents a link to an mp3 audio file. By default, this audio file will be sent by the user. Alternatively, + you can use input_message_content to send a message with the specified content instead of the audio. + + https://core.telegram.org/bots/api#inlinequeryresultaudio + """ def __init__(self, type: str, id: str, audio_url: str, title: str, caption: str = None, performer: str = None, audio_duration: int = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): @@ -116,6 +219,16 @@ class InlineQueryResultAudio(InlineQueryResult): class InlineQueryResultVoice(InlineQueryResult): + """ + Represents a link to a voice recording in an .ogg container encoded with OPUS. + + By default, this voice recording will be sent by the user. + + Alternatively, you can use input_message_content to send a message with the specified content + instead of the the voice message. + + https://core.telegram.org/bots/api#inlinequeryresultvoice + """ def __init__(self, type: str, id: str, voice_url: str, title: str, caption: str = None, voice_duration: int = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): self.type: str = type @@ -129,6 +242,14 @@ class InlineQueryResultVoice(InlineQueryResult): class InlineQueryResultDocument(InlineQueryResult): + """ + Represents a link to a file. By default, this file will be sent by the user with an optional caption. + + Alternatively, you can use input_message_content to send a message with the specified content + instead of the file. Currently, only .PDF and .ZIP files can be sent using this method. + + https://core.telegram.org/bots/api#inlinequeryresultdocument + """ def __init__(self, type: str, id: str, title: str, document_url: str, mime_type: str, caption: str = None, description: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None, thumb_url: str = None, thumb_width: int = None, @@ -148,6 +269,13 @@ class InlineQueryResultDocument(InlineQueryResult): class InlineQueryResultLocation(InlineQueryResult): + """ + Represents a location on a map. By default, the location will be sent by the user. + Alternatively, you can use input_message_content to send a message with the specified content + instead of the location. + + https://core.telegram.org/bots/api#inlinequeryresultlocation + """ def __init__(self, type: str, id: str, latitude: float, longitude: float, title: str, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None, thumb_url: str = None, thumb_width: int = None, thumb_height: int = None): @@ -164,6 +292,13 @@ class InlineQueryResultLocation(InlineQueryResult): class InlineQueryResultVenue(InlineQueryResult): + """ + Represents a venue. By default, the venue will be sent by the user. + Alternatively, you can use input_message_content to send a message with the specified + content instead of the venue. + + https://core.telegram.org/bots/api#inlinequeryresultvenue + """ def __init__(self, type: str, id: str, latitude: float, longitude: float, title: str, address: str, foursquare_id: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None, thumb_url: str = None, thumb_width: int = None, @@ -183,6 +318,16 @@ class InlineQueryResultVenue(InlineQueryResult): class InlineQueryResultContact(InlineQueryResult): + """ + Represents a contact with a phone number. + + By default, this contact will be sent by the user. + + Alternatively, you can use input_message_content to send a message with the specified content instead + of the contact. + + https://core.telegram.org/bots/api#inlinequeryresultcontact + """ def __init__(self, type: str, id: str, phone_number: str, first_name: str, last_name: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None, thumb_url: str = None, thumb_width: int = None, thumb_height: int = None): @@ -199,6 +344,11 @@ class InlineQueryResultContact(InlineQueryResult): class InlineQueryResultGame(InlineQueryResult): + """ + Represents a Game. + + https://core.telegram.org/bots/api#inlinequeryresultgame + """ def __init__(self, type: str, id: str, game_short_name: str, reply_markup: InlineKeyboardMarkup = None): self.type: str = type self.id: str = id @@ -207,6 +357,16 @@ class InlineQueryResultGame(InlineQueryResult): class InlineQueryResultCachedPhoto(InlineQueryResult): + """ + Represents a link to a photo stored on the Telegram servers. + + By default, this photo will be sent by the user with an optional caption. + + Alternatively, you can use input_message_content to send a message with the specified + content instead of the photo. + + https://core.telegram.org/bots/api#inlinequeryresultcachedphoto + """ def __init__(self, type: str, id: str, photo_file_id: str, title: str = None, description: str = None, caption: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): @@ -221,6 +381,16 @@ class InlineQueryResultCachedPhoto(InlineQueryResult): class InlineQueryResultCachedGif(InlineQueryResult): + """ + Represents a link to an animated GIF file stored on the Telegram servers. + + By default, this animated GIF file will be sent by the user with an optional caption. + + Alternatively, you can use input_message_content to send a message with specified content + instead of the animation. + + https://core.telegram.org/bots/api#inlinequeryresultcachedgif + """ def __init__(self, type: str, id: str, gif_file_id: str, title: str = None, caption: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): self.type: str = type @@ -233,6 +403,16 @@ class InlineQueryResultCachedGif(InlineQueryResult): class InlineQueryResultCachedMpeg4Gif(InlineQueryResult): + """ + Represents a link to a video animation (H.264/MPEG-4 AVC video without sound) stored on the Telegram servers. + + By default, this animated MPEG-4 file will be sent by the user with an optional caption. + + Alternatively, you can use input_message_content to send a message with the specified content + instead of the animation. + + https://core.telegram.org/bots/api#inlinequeryresultcachedmpeg4gif + """ def __init__(self, type: str, id: str, mpeg4_file_id: str, title: str = None, caption: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): self.type: str = type @@ -245,6 +425,16 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult): class InlineQueryResultCachedSticker(InlineQueryResult): + """ + Represents a link to a sticker stored on the Telegram servers. + + By default, this sticker will be sent by the user. + + Alternatively, you can use input_message_content to send a message with the specified content + instead of the sticker. + + https://core.telegram.org/bots/api#inlinequeryresultcachedsticker + """ def __init__(self, type: str, id: str, sticker_file_id: str, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): self.type: str = type @@ -255,6 +445,16 @@ class InlineQueryResultCachedSticker(InlineQueryResult): class InlineQueryResultCachedDocument(InlineQueryResult): + """ + Represents a link to a file stored on the Telegram servers. + + By default, this file will be sent by the user with an optional caption. + + Alternatively, you can use input_message_content to send a message with the specified content + instead of the file. + + https://core.telegram.org/bots/api#inlinequeryresultcacheddocument + """ def __init__(self, type: str, id: str, title: str, document_file_id: str, description: str = None, caption: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): @@ -269,6 +469,14 @@ class InlineQueryResultCachedDocument(InlineQueryResult): class InlineQueryResultCachedVideo(InlineQueryResult): + """ + Represents a link to a video file stored on the Telegram servers. + By default, this video file will be sent by the user with an optional caption. + Alternatively, you can use input_message_content to send a message with the specified content instead + of the video. + + https://core.telegram.org/bots/api#inlinequeryresultcachedvideo + """ def __init__(self, type: str, id: str, video_file_id: str, title: str, description: str = None, caption: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): self.type: str = type @@ -282,6 +490,16 @@ class InlineQueryResultCachedVideo(InlineQueryResult): class InlineQueryResultCachedVoice(InlineQueryResult): + """ + Represents a link to a voice message stored on the Telegram servers. + + By default, this voice message will be sent by the user. + + Alternatively, you can use input_message_content to send a message with the specified content + instead of the voice message. + + https://core.telegram.org/bots/api#inlinequeryresultcachedvoice + """ def __init__(self, type: str, id: str, voice_file_id: str, title: str, caption: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): self.type: str = type @@ -294,6 +512,15 @@ class InlineQueryResultCachedVoice(InlineQueryResult): class InlineQueryResultCachedAudio(InlineQueryResult): + """ + Represents a link to an mp3 audio file stored on the Telegram servers. + + By default, this audio file will be sent by the user. + Alternatively, you can use input_message_content to send a message with the specified content + instead of the audio. + + https://core.telegram.org/bots/api#inlinequeryresultcachedaudio + """ def __init__(self, type: str, id: str, audio_file_id: str, caption: str = None, reply_markup: InlineKeyboardMarkup = None, input_message_content: InputMessageContent = None): self.type: str = type @@ -305,6 +532,11 @@ class InlineQueryResultCachedAudio(InlineQueryResult): class InputTextMessageContent(InputMessageContent): + """ + Represents the content of a text message to be sent as the result of an inline query. + + https://core.telegram.org/bots/api#inputtextmessagecontent + """ def __init__(self, message_text: str, parse_mode: str = None, disable_web_page_preview: bool = None): self.message_text: str = message_text self.parse_mode: str = parse_mode @@ -312,12 +544,22 @@ class InputTextMessageContent(InputMessageContent): class InputLocationMessageContent(InputMessageContent): + """ + Represents the content of a location message to be sent as the result of an inline query. + + https://core.telegram.org/bots/api#inputlocationmessagecontent + """ def __init__(self, latitude: float, longitude: float): self.latitude: float = latitude self.longitude: float = longitude class InputVenueMessageContent(InputMessageContent): + """ + Represents the content of a venue message to be sent as the result of an inline query. + + https://core.telegram.org/bots/api#inputvenuemessagecontent + """ def __init__(self, latitude: float, longitude: float, title: str, address: str, foursquare_id: str = None): self.latitude: float = latitude self.longitude: float = longitude @@ -327,6 +569,11 @@ class InputVenueMessageContent(InputMessageContent): class InputContactMessageContent(InputMessageContent): + """ + Represents the content of a contact message to be sent as the result of an inline query. + + https://core.telegram.org/bots/api#inputcontactmessagecontent + """ def __init__(self, phone_number: str, first_name: str, last_name: str = None): self.phone_number: str = phone_number self.first_name: str = first_name diff --git a/aiogram/types/invoice.py b/aiogram/types/invoice.py index 83477cce..1b1b7364 100644 --- a/aiogram/types/invoice.py +++ b/aiogram/types/invoice.py @@ -2,6 +2,11 @@ from .base import Deserializable class Invoice(Deserializable): + """ + This object contains basic information about an invoice. + + https://core.telegram.org/bots/api#invoice + """ def __init__(self, title, description, start_parameter, currency, total_amount): self.title: str = title self.description: str = description diff --git a/aiogram/types/labeled_price.py b/aiogram/types/labeled_price.py index f6c5db69..001d3af2 100644 --- a/aiogram/types/labeled_price.py +++ b/aiogram/types/labeled_price.py @@ -2,6 +2,11 @@ from .base import Serializable class LabeledPrice(Serializable): + """ + This object represents a portion of the price for goods or services. + + https://core.telegram.org/bots/api#labeledprice + """ def __init__(self, label, amount): self.label = label self.amount = amount diff --git a/aiogram/types/location.py b/aiogram/types/location.py index ecaa9e31..61b2f82c 100644 --- a/aiogram/types/location.py +++ b/aiogram/types/location.py @@ -2,6 +2,11 @@ from .base import Deserializable class Location(Deserializable): + """ + This object represents a point on the map. + + https://core.telegram.org/bots/api#location + """ def __init__(self, longitude, latitude): self.longitude = longitude self.latitude = latitude diff --git a/aiogram/types/order_info.py b/aiogram/types/order_info.py index 98e11792..863f52ce 100644 --- a/aiogram/types/order_info.py +++ b/aiogram/types/order_info.py @@ -3,6 +3,11 @@ from .shipping_address import ShippingAddress class OrderInfo(Deserializable): + """ + his object represents information about an order. + + https://core.telegram.org/bots/api#orderinfo + """ def __init__(self, name, phone_number, email, shipping_address): self.name: str = name self.phone_number: str = phone_number diff --git a/aiogram/types/pre_checkout_query.py b/aiogram/types/pre_checkout_query.py index 7c6fa859..2a534aea 100644 --- a/aiogram/types/pre_checkout_query.py +++ b/aiogram/types/pre_checkout_query.py @@ -4,6 +4,11 @@ from .user import User class PreCheckoutQuery(Deserializable): + """ + This object contains information about an incoming pre-checkout query. + + https://core.telegram.org/bots/api#precheckoutquery + """ def __init__(self, id, from_user, currency, total_amount, invoice_payload, shipping_option_id, order_info): self.id: str = id self.from_user: User = from_user diff --git a/aiogram/types/reply_keyboard.py b/aiogram/types/reply_keyboard.py index 94d02b35..adefd008 100644 --- a/aiogram/types/reply_keyboard.py +++ b/aiogram/types/reply_keyboard.py @@ -2,6 +2,11 @@ from .base import Serializable class ReplyKeyboardMarkup(Serializable): + """ + This object represents a custom keyboard with reply options + + https://core.telegram.org/bots/api#replykeyboardmarkup + """ def __init__(self, resize_keyboard=None, one_time_keyboard=None, selective=None, row_width=3): self.resize_keyboard = resize_keyboard self.one_time_keyboard = one_time_keyboard @@ -42,6 +47,15 @@ class ReplyKeyboardMarkup(Serializable): class KeyboardButton(Serializable): + """ + This object represents one button of the reply keyboard. + + For simple text buttons String can be used instead of this object to specify text of the button. + + Optional fields are mutually exclusive + + https://core.telegram.org/bots/api#keyboardbutton + """ def __init__(self, text, request_contact=None, request_location=None): self.text = text self.request_contact = request_contact @@ -52,6 +66,17 @@ class KeyboardButton(Serializable): class ReplyKeyboardRemove(Serializable): + """ + Upon receiving a message with this object, + Telegram clients will remove the current custom keyboard and display the default letter-keyboard. + + By default, custom keyboards are displayed until a new keyboard + is sent by a bot. + + An exception is made for one-time keyboards that are hidden immediately after the user presses a button + + https://core.telegram.org/bots/api#replykeyboardremove + """ def __init__(self, selective=None): self.selective = selective diff --git a/aiogram/types/response_parameters.py b/aiogram/types/response_parameters.py new file mode 100644 index 00000000..41ff2808 --- /dev/null +++ b/aiogram/types/response_parameters.py @@ -0,0 +1,21 @@ +from .base import Deserializable + + +class ResponseParameters(Deserializable): + """ + Contains information about why a request was unsuccessfull. + + https://core.telegram.org/bots/api#responseparameters + """ + def __init__(self, migrate_to_chat_id, retry_after): + self.migrate_to_chat_id = migrate_to_chat_id + self.retry_after = retry_after + + @classmethod + def de_json(cls, raw_data): + data = cls.check_json(raw_data) + + migrate_to_chat_id = data.get('migrate_to_chat_id') + retry_after = data.get('retry_after') + + return ResponseParameters(migrate_to_chat_id, retry_after) diff --git a/aiogram/types/shipping_address.py b/aiogram/types/shipping_address.py index 4d170556..588a3063 100644 --- a/aiogram/types/shipping_address.py +++ b/aiogram/types/shipping_address.py @@ -2,6 +2,11 @@ from .base import Deserializable class ShippingAddress(Deserializable): + """ + This object represents a shipping address. + + https://core.telegram.org/bots/api#shippingaddress + """ def __init__(self, country_code, state, city, street_line1, street_line2, post_code): self.country_code: str = country_code self.state: str = state diff --git a/aiogram/types/shipping_option.py b/aiogram/types/shipping_option.py index 5bc539bd..509dcebe 100644 --- a/aiogram/types/shipping_option.py +++ b/aiogram/types/shipping_option.py @@ -2,6 +2,11 @@ from .base import Serializable class ShippingOption(Serializable): + """ + This object represents one shipping option. + + https://core.telegram.org/bots/api#shippingoption + """ def __init__(self, id, title, prices): self.id = id self.title = title diff --git a/aiogram/types/shipping_query.py b/aiogram/types/shipping_query.py index 15ef1083..4ba2e787 100644 --- a/aiogram/types/shipping_query.py +++ b/aiogram/types/shipping_query.py @@ -4,6 +4,11 @@ from .user import User class ShippingQuery(Deserializable): + """ + This object contains information about an incoming shipping query. + + https://core.telegram.org/bots/api#shippingquery + """ def __init__(self, id, from_user, invoice_payload, shipping_address): self.id: str = id self.from_user: User = from_user diff --git a/aiogram/types/sticker.py b/aiogram/types/sticker.py index b1853d7b..62eb26be 100644 --- a/aiogram/types/sticker.py +++ b/aiogram/types/sticker.py @@ -3,6 +3,11 @@ from .photo_size import PhotoSize class Sticker(Deserializable): + """ + This object represents a sticker. + + https://core.telegram.org/bots/api#sticker + """ def __init__(self, file_id, width, height, thumb, emoji, file_size): self.file_id: str = file_id self.width: int = width diff --git a/aiogram/types/successful_payment.py b/aiogram/types/successful_payment.py index 713af3c2..a8c15547 100644 --- a/aiogram/types/successful_payment.py +++ b/aiogram/types/successful_payment.py @@ -3,6 +3,11 @@ from .order_info import OrderInfo class SuccessfulPayment(Deserializable): + """ + This object contains basic information about a successful payment. + + https://core.telegram.org/bots/api#successfulpayment + """ def __init__(self, currency, total_amount, invoice_payload, shipping_option_id, order_info, telegram_payment_charge_id, provider_payment_charge_id): self.currency: str = currency diff --git a/aiogram/types/update.py b/aiogram/types/update.py index 0f5fd348..1dc03f4b 100644 --- a/aiogram/types/update.py +++ b/aiogram/types/update.py @@ -8,6 +8,13 @@ from .shipping_query import ShippingQuery class Update(Deserializable): + """ + This object represents an incoming update. + + At most one of the optional parameters can be present in any given update. + + https://core.telegram.org/bots/api#update + """ def __init__(self, update_id, message, edited_message, channel_post, edited_channel_post, inline_query, chosen_inline_result, callback_query, shipping_query, pre_checkout_query): self.update_id: int = update_id diff --git a/aiogram/types/user_profile_photos.py b/aiogram/types/user_profile_photos.py index c97d3450..cb4f5fd7 100644 --- a/aiogram/types/user_profile_photos.py +++ b/aiogram/types/user_profile_photos.py @@ -3,6 +3,11 @@ from .photo_size import PhotoSize class UserProfilePhotos(Deserializable): + """ + This object represent a user's profile pictures. + + https://core.telegram.org/bots/api#userprofilephotos + """ def __init__(self, total_count, photos): self.total_count: int = total_count self.photos: [PhotoSize] = photos diff --git a/aiogram/types/venue.py b/aiogram/types/venue.py index d5f444e5..254f1050 100644 --- a/aiogram/types/venue.py +++ b/aiogram/types/venue.py @@ -3,6 +3,11 @@ from .location import Location class Venue(Deserializable): + """ + This object represents a venue. + + https://core.telegram.org/bots/api#venue + """ def __init__(self, location, title, address, foursquare_id): self.location: Location = location self.title: str = title diff --git a/aiogram/types/video.py b/aiogram/types/video.py index 576aadf6..3bbc3053 100644 --- a/aiogram/types/video.py +++ b/aiogram/types/video.py @@ -3,6 +3,11 @@ from .photo_size import PhotoSize class Video(Deserializable): + """ + This object represents a video file. + + https://core.telegram.org/bots/api#video + """ def __init__(self, file_id, width, height, duration, thumb, mime_type, file_size): self.file_id: str = file_id self.width: int = width diff --git a/aiogram/types/video_note.py b/aiogram/types/video_note.py index 5b34a318..b6542838 100644 --- a/aiogram/types/video_note.py +++ b/aiogram/types/video_note.py @@ -3,6 +3,11 @@ from .photo_size import PhotoSize class VideoNote(Deserializable): + """ + This object represents a video message. + + https://core.telegram.org/bots/api#videonote + """ def __init__(self, file_id, length, duration, thumb, file_size): self.file_id: str = file_id self.length: int = length diff --git a/aiogram/types/voice.py b/aiogram/types/voice.py index 48162e92..3086e625 100644 --- a/aiogram/types/voice.py +++ b/aiogram/types/voice.py @@ -2,6 +2,11 @@ from .base import Deserializable class Voice(Deserializable): + """ + This object represents a voice note. + + https://core.telegram.org/bots/api#voice + """ def __init__(self, file_id, duration, mime_type, file_size): self.file_id: str = file_id self.duration: int = duration diff --git a/aiogram/types/webhook_info.py b/aiogram/types/webhook_info.py index 77b31d89..b98a85c1 100644 --- a/aiogram/types/webhook_info.py +++ b/aiogram/types/webhook_info.py @@ -4,6 +4,11 @@ from .base import Deserializable class WebhookInfo(Deserializable): + """ + Contains information about the current status of a webhook. + + https://core.telegram.org/bots/api#webhookinfo + """ def __init__(self, url, has_custom_certificate, pending_update_count, last_error_date, last_error_message, max_connections, allowed_updates): self.url: str = url diff --git a/docs/source/aiogram.bot.Bot.rst b/docs/source/aiogram.bot.rst similarity index 63% rename from docs/source/aiogram.bot.Bot.rst rename to docs/source/aiogram.bot.rst index 749240ad..6747f9da 100644 --- a/docs/source/aiogram.bot.Bot.rst +++ b/docs/source/aiogram.bot.rst @@ -1,9 +1,16 @@ -aiogram.bot.Bot -=============== +Bot object +========== For detailed information about parameters read the official `Telegram Bot API reference `_ +BaseBot +------- +.. automodule:: aiogram.bot.base + :members: + :show-inheritance: +Bot +--- .. automodule:: aiogram.bot.bot :members: :show-inheritance: diff --git a/docs/source/aiogram.dispatcher.rst b/docs/source/aiogram.dispatcher.rst new file mode 100644 index 00000000..e36b2049 --- /dev/null +++ b/docs/source/aiogram.dispatcher.rst @@ -0,0 +1,8 @@ +Dispatcher +========== + +Doc's for this module will be available soon.. + +.. automodule:: aiogram.dispatcher + :members: + :show-inheritance: diff --git a/docs/source/aiogram.rst b/docs/source/aiogram.rst index a758a3e6..0e35222a 100644 --- a/docs/source/aiogram.rst +++ b/docs/source/aiogram.rst @@ -7,6 +7,6 @@ Submodules .. toctree:: - aiogram.bot.BaseBot - aiogram.bot.Bot + aiogram.bot aiogram.types + aiogram.dispatcher diff --git a/docs/source/aiogram.types.rst b/docs/source/aiogram.types.rst index 5327b14f..9556f5e1 100644 --- a/docs/source/aiogram.types.rst +++ b/docs/source/aiogram.types.rst @@ -202,6 +202,14 @@ ChatMember :members: :show-inheritance: +ResponseParameters +------------------ +:class:`aiogram.types.ResponseParameters` + +.. automodule:: aiogram.types.response_parameters + :members: + :show-inheritance: + Inline mode objects -------------------