From ae48ed973adf2f09774202581b4eeaacd15b181d Mon Sep 17 00:00:00 2001 From: Alex Root Junior Date: Fri, 4 Aug 2017 14:00:48 +0300 Subject: [PATCH] Fix docs. --- aiogram/bot/base.py | 6 ++-- aiogram/bot/bot.py | 45 ++++++++++++++------------- aiogram/dispatcher/__init__.py | 38 +++++++++++++++++++++- aiogram/dispatcher/state.py | 2 +- aiogram/types/message.py | 2 +- docs/source/bot/types.rst | 40 +++++++++++++++++++----- docs/source/conf.py | 12 +++---- docs/source/dispatcher/dispatcher.rst | 2 -- docs/source/features.rst | 6 ---- 9 files changed, 103 insertions(+), 50 deletions(-) diff --git a/aiogram/bot/base.py b/aiogram/bot/base.py index 3d85027e..dba39d1d 100644 --- a/aiogram/bot/base.py +++ b/aiogram/bot/base.py @@ -221,12 +221,12 @@ class BaseBot: Notes 1. You will not be able to receive updates using getUpdates for as long as an outgoing webhook - is set up. + is set up. 2. To use a self-signed certificate, you need to upload your public key certificate using certificate parameter. Please upload as InputFile, sending a String will not work. 3. Ports currently supported for Webhooks: 443, 80, 88, 8443. - NEW! If you're having any trouble setting up webhooks, please check out this amazing guide to - Webhooks. + NEW! If you're having any trouble setting up webhooks, please check out this amazing guide to + Webhooks. Source: https://core.telegram.org/bots/api#setwebhook diff --git a/aiogram/bot/bot.py b/aiogram/bot/bot.py index e6517d20..b5fa8d12 100644 --- a/aiogram/bot/bot.py +++ b/aiogram/bot/bot.py @@ -96,7 +96,7 @@ class Bot(BaseBot): Please note that this parameter doesn't affect updates created before the call to the getUpdates, so unwanted updates may be received for a short period of time. - :return: An Array of Update objects is returned. + :return: An Array of Update objects is returned. (serialized) """ raw = super(Bot, self).get_updates(offset=offset, limit=limit, timeout=timeout, allowed_updates=allowed_updates) @@ -110,7 +110,7 @@ class Bot(BaseBot): Source: https://core.telegram.org/bots/api#getwebhookinfo - :return: On success, returns a WebhookInfo object. + :return: On success, returns a WebhookInfo object. (serialized) """ raw = super(Bot, self).get_webhook_info() return self.prepare_object(types.WebhookInfo.deserialize(await raw)) @@ -125,7 +125,7 @@ class Bot(BaseBot): Source: https://core.telegram.org/bots/api#getme - :return: Returns basic information about the bot in form of a User object. + :return: Returns basic information about the bot in form of a User object. (serialized) """ raw = super(Bot, self).get_me() return self.prepare_object(types.User.deserialize(await raw)) @@ -155,7 +155,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_message(chat_id=chat_id, text=text, parse_mode=parse_mode, @@ -181,7 +181,7 @@ class Bot(BaseBot): :param disable_notification: Boolean (Optional) - Sends the message silently. Users will receive a notification with no sound. :param message_id: Integer - Message identifier in the chat specified in from_chat_id - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).forward_message(chat_id=chat_id, from_chat_id=from_chat_id, message_id=message_id, disable_notification=disable_notification) @@ -213,7 +213,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_photo(chat_id=chat_id, photo=photo, caption=caption, disable_notification=disable_notification, @@ -256,7 +256,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_audio(chat_id=chat_id, audio=audio, caption=caption, duration=duration, performer=performer, title=title, @@ -293,7 +293,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_document(chat_id=chat_id, document=document, caption=caption, disable_notification=disable_notification, @@ -336,7 +336,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_video(chat_id=chat_id, video=video, duration=duration, width=width, height=height, caption=caption, @@ -375,7 +375,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_voice(chat_id=chat_id, voice=voice, caption=caption, duration=duration, @@ -412,7 +412,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_video_note(chat_id=chat_id, video_note=video_note, duration=duration, length=length, disable_notification=disable_notification, @@ -441,7 +441,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_location(chat_id=chat_id, latitude=latitude, longitude=longitude, disable_notification=disable_notification, @@ -477,7 +477,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_venue(chat_id=chat_id, latitude=latitude, longitude=longitude, title=title, address=address, foursquare_id=foursquare_id, @@ -510,7 +510,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_contact(chat_id=chat_id, phone_number=phone_number, first_name=first_name, last_name=last_name, disable_notification=disable_notification, @@ -530,7 +530,7 @@ class Bot(BaseBot): By default, all photos are returned. :param limit: Integer (Optional) - Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100. - :return: Returns a UserProfilePhotos object. + :return: Returns a UserProfilePhotos object. (serialized) """ raw = super(Bot, self).get_user_profile_photos(user_id=user_id, offset=offset, limit=limit) return self.prepare_object(types.UserProfilePhotos.deserialize(await raw)) @@ -550,7 +550,7 @@ class Bot(BaseBot): Source: https://core.telegram.org/bots/api#getfile :param file_id: String - File identifier to get info about - :return: On success, a File object is returned. + :return: On success, a File object is returned. (serialized) """ raw = super(Bot, self).get_file(file_id=file_id) return self.prepare_object(types.File.deserialize(await raw)) @@ -582,7 +582,7 @@ class Bot(BaseBot): :param chat_id: Union[Integer, String] - Unique identifier for the target chat or username of the target supergroup or channel (in the format @channelusername) :return: On success, returns an Array of ChatMember objects that contains information about all - chat administrators except other bots. + chat administrators except other bots. (serialized) """ raw = super(Bot, self).get_chat_administrators(chat_id=chat_id) return [self.prepare_object(types.ChatMember.de_json(raw_chat_member)) for raw_chat_member in await raw] @@ -596,7 +596,7 @@ class Bot(BaseBot): :param chat_id: Union[Integer, String] - Unique identifier for the target chat or username of the target supergroup or channel (in the format @channelusername) :param user_id: Integer - Unique identifier of the target user - :return: Returns a ChatMember object on success. + :return: Returns a ChatMember object on success. (serialized) """ raw = super(Bot, self).get_chat_member(chat_id=chat_id, user_id=user_id) return self.prepare_object(types.ChatMember.deserialize(await raw)) @@ -628,7 +628,7 @@ class Bot(BaseBot): :param reply_markup: Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, Dict, String] (Optional) - Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_sticker(chat_id=chat_id, sticker=sticker, disable_notification=disable_notification, reply_to_message_id=reply_to_message_id, reply_markup=reply_markup) @@ -656,7 +656,7 @@ class Bot(BaseBot): :param user_id: Integer - User identifier of sticker file owner :param png_sticker: io.BytesIO - Png image with the sticker, must be up to 512 kilobytes in size, dimensions must not exceed 512px, and either width or height must be exactly 512px. - :return: Returns the uploaded File on success. + :return: Returns the uploaded File on success. (serialized) """ raw = super(Bot, self).upload_sticker_file(user_id=user_id, png_sticker=png_sticker) return self.prepare_object(types.File.deserialize(await raw)) @@ -718,7 +718,7 @@ class Bot(BaseBot): :param reply_to_message_id: Integer (Optional) - If the message is a reply, ID of the original message :param reply_markup: types.InlineKeyboardMarkup (Optional) - A JSON-serialized object for an inline keyboard. If empty, one 'Pay total price' button will be shown. If not empty, the first button must be a Pay button. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_invoice(chat_id=chat_id, title=title, description=description, payload=payload, provider_token=provider_token, start_parameter=start_parameter, @@ -751,7 +751,7 @@ class Bot(BaseBot): :param reply_to_message_id: Integer (Optional) - If the message is a reply, ID of the original message :param reply_markup: types.InlineKeyboardMarkup (Optional) - A JSON-serialized object for an inline keyboard. If empty, one ‘Play game_title’ button will be shown. If not empty, the first button must launch the game. - :return: On success, the sent Message is returned. + :return: On success, the sent Message is returned. (serialized) """ raw = super(Bot, self).send_game(chat_id=chat_id, game_short_name=game_short_name, disable_notification=disable_notification, @@ -786,6 +786,7 @@ class Bot(BaseBot): :param inline_message_id: String (Optional) - Required if chat_id and message_id are not specified. Identifier of the inline message :return: On success, if the message was sent by the bot, returns the edited Message, otherwise returns True. + (serialized) """ raw = await super(Bot, self).set_game_score(user_id=user_id, score=score, force=force, disable_edit_message=disable_edit_message, chat_id=chat_id, diff --git a/aiogram/dispatcher/__init__.py b/aiogram/dispatcher/__init__.py index 4b1fdffb..85e94565 100644 --- a/aiogram/dispatcher/__init__.py +++ b/aiogram/dispatcher/__init__.py @@ -2,13 +2,13 @@ import asyncio import logging import typing -from aiogram.utils.deprecated import deprecated from .filters import CommandsFilter, RegexpFilter, ContentTypeFilter, generate_default_filters from .handler import Handler, NextStepHandler from .storage import MemoryStorage, DisabledStorage, BaseStorage, FSMContext from .. import types from ..bot import Bot from ..types.message import ContentType +from ..utils.deprecated import deprecated log = logging.getLogger(__name__) @@ -153,6 +153,7 @@ class Dispatcher: You can register messages handler by this method .. code-block:: python3 + # This handler works only is state is None (by default). dp.register_message_handler(cmd_start, commands=['start', 'about']) dp.register_message_handler(entry_point, commands=['setup']) @@ -197,35 +198,48 @@ class Dispatcher: Examples: Simple commands handler: + .. code-block:: python3 + @dp.messages_handler(commands=['start', 'welcome', 'about']) async def cmd_handler(message: types.Message): Filter messages by regular expression: + .. code-block:: python3 + @dp.messages_handler(rexexp='^[a-z]+-[0-9]+') async def msg_handler(message: types.Message): Filter by content type: + .. code-block:: python3 + @dp.messages_handler(content_types=ContentType.PHOTO | ContentType.DOCUMENT) async def audio_handler(message: types.Message): Filter by custom function: + .. code-block:: python3 + @dp.messages_handler(func=lambda message: message.text and 'hello' in message.text.lower()) async def text_handler(message: types.Message): Use multiple filters: + .. code-block:: python3 + @dp.messages_handler(commands=['command'], content_types=ContentType.TEXT) async def text_handler(message: types.Message): Register multiple filters set for one handler: + .. code-block:: python3 + @dp.messages_handler(commands=['command']) @dp.messages_handler(func=lambda message: demojize(message.text) == ':new_moon_with_face:') async def text_handler(message: types.Message): + This handler will be called if the message starts with '/command' OR is some emoji By default content_type is :class:`ContentType.TEXT` @@ -286,7 +300,9 @@ class Dispatcher: Analog of message_handler but only for edited messages You can use combination of different handlers + .. code-block:: python3 + @dp.message_handler() @dp.edited_message_handler() async def msg_handler(message: types.Message): @@ -423,7 +439,9 @@ class Dispatcher: Handle inline query Example: + .. code-block:: python3 + @dp.inline_handler(func=lambda inline_query: True) async def handler(inline_query: types.InlineQuery) @@ -448,7 +466,9 @@ class Dispatcher: Handle inline query Example: + .. code-block:: python3 + @dp.inline_handler(func=lambda inline_query: True) async def handler(inline_query: types.InlineQuery) @@ -470,7 +490,9 @@ class Dispatcher: Register chosen inline handler Example: + .. code-block:: python3 + @dp.chosen_inline_handler(func=lambda chosen_inline_query: True) async def handler(chosen_inline_query: types.ChosenInlineResult) @@ -495,7 +517,9 @@ class Dispatcher: Register chosen inline handler Example: + .. code-block:: python3 + @dp.chosen_inline_handler(func=lambda chosen_inline_query: True) async def handler(chosen_inline_query: types.ChosenInlineResult) @@ -518,7 +542,9 @@ class Dispatcher: Add callback query handler Example: + .. code-block:: python3 + @dp.callback_query_handler(func=lambda callback_query: True) async def handler(callback_query: types.CallbackQuery) @@ -542,7 +568,9 @@ class Dispatcher: Add callback query handler Example: + .. code-block:: python3 + @dp.callback_query_handler(func=lambda callback_query: True) async def handler(callback_query: types.CallbackQuery) @@ -564,7 +592,9 @@ class Dispatcher: Add shipping query handler Example: + .. code-block:: python3 + @dp.shipping_query_handler(func=lambda shipping_query: True) async def handler(shipping_query: types.ShippingQuery) @@ -588,7 +618,9 @@ class Dispatcher: Add shipping query handler Example: + .. code-block:: python3 + @dp.shipping_query_handler(func=lambda shipping_query: True) async def handler(shipping_query: types.ShippingQuery) @@ -610,7 +642,9 @@ class Dispatcher: Add shipping query handler Example: + .. code-block:: python3 + @dp.shipping_query_handler(func=lambda shipping_query: True) async def handler(shipping_query: types.ShippingQuery) @@ -634,7 +668,9 @@ class Dispatcher: Add shipping query handler Example: + .. code-block:: python3 + @dp.shipping_query_handler(func=lambda shipping_query: True) async def handler(shipping_query: types.ShippingQuery) diff --git a/aiogram/dispatcher/state.py b/aiogram/dispatcher/state.py index a9ed0583..45339ace 100644 --- a/aiogram/dispatcher/state.py +++ b/aiogram/dispatcher/state.py @@ -1,9 +1,9 @@ import logging import os -from aiogram.utils.deprecated import deprecated from .handler import SkipHandler from ..utils import json +from ..utils.deprecated import deprecated log = logging.getLogger('aiogram.StateMachine') diff --git a/aiogram/types/message.py b/aiogram/types/message.py index e2ffaff1..d474da95 100644 --- a/aiogram/types/message.py +++ b/aiogram/types/message.py @@ -1,6 +1,5 @@ import datetime -from aiogram.utils.helper import Item, HelperMode, Helper, ListItem from .audio import Audio from .base import Deserializable from .chat import Chat @@ -19,6 +18,7 @@ from .video import Video from .video_note import VideoNote from .voice import Voice from ..exceptions import TelegramAPIError +from ..utils.helper import Item, HelperMode, Helper, ListItem class Message(Deserializable): diff --git a/docs/source/bot/types.rst b/docs/source/bot/types.rst index 9556f5e1..308948af 100644 --- a/docs/source/bot/types.rst +++ b/docs/source/bot/types.rst @@ -84,14 +84,6 @@ Document :members: :show-inheritance: -Sticker -------- -:class:`aiogram.types.Sticker` - -.. automodule:: aiogram.types.sticker - :members: - :show-inheritance: - Video ----- :class:`aiogram.types.Video` @@ -194,6 +186,14 @@ ForceReply :members: :show-inheritance: +ChatPhoto +--------- +:class:`aiogram.types.ChatPhoto` + +.. automodule:: aiogram.types.chat_photo + :members: + :show-inheritance: + ChatMember ---------- :class:`aiogram.types.ChatMember` @@ -210,6 +210,30 @@ ResponseParameters :members: :show-inheritance: +Sticker +------- +:class:`aiogram.types.Sticker` + +.. automodule:: aiogram.types.sticker + :members: + :show-inheritance: + +StickersSet +----------- +:class:`aiogram.types.StickersSet` + +.. automodule:: aiogram.types.stickers_set + :members: + :show-inheritance: + +MaskPosition +----------- +:class:`aiogram.types.MaskPosition` + +.. automodule:: aiogram.types.mask_position + :members: + :show-inheritance: + Inline mode objects ------------------- diff --git a/docs/source/conf.py b/docs/source/conf.py index a686f047..f243d23c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -157,9 +157,9 @@ texinfo_documents = [ autoclass_content = "both" autodoc_member_order = "bysource" -autodoc_default_flags = [ - "members", - "no-undoc-members", - "show-inheritance", - "inherited-members", -] +# autodoc_default_flags = [ +# "members", +# "no-undoc-members", +# "show-inheritance", +# "inherited-members", +# ] diff --git a/docs/source/dispatcher/dispatcher.rst b/docs/source/dispatcher/dispatcher.rst index 23287cbc..851097f9 100644 --- a/docs/source/dispatcher/dispatcher.rst +++ b/docs/source/dispatcher/dispatcher.rst @@ -1,8 +1,6 @@ Dispatcher ========== -Doc's for this module will be available soon.. - Dispatcher class ---------------- diff --git a/docs/source/features.rst b/docs/source/features.rst index 2a1aa3eb..37a76cd1 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -1,12 +1,6 @@ Features ======== -Dispatcher ----------- -.. automodule:: aiogram.dispatcher - :members: - :show-inheritance: - Markdown --------