diff --git a/docs/sitemap.py b/docs/sitemap.py index 87c27849..4def886f 100644 --- a/docs/sitemap.py +++ b/docs/sitemap.py @@ -23,11 +23,11 @@ canonical = "https://docs.pyrogram.org/" dirs = { ".": ("weekly", 1.0), - "intro": ("weekly", 0.8), - "start": ("weekly", 0.8), - "api": ("weekly", 0.6), - "topics": ("weekly", 0.6), - "telegram": ("weekly", 0.4) + "intro": ("weekly", 0.9), + "start": ("weekly", 0.9), + "api": ("weekly", 0.8), + "topics": ("weekly", 0.8), + "telegram": ("weekly", 0.6) } diff --git a/docs/source/api/bound-methods.rst b/docs/source/api/bound-methods.rst index d93497fe..0622e6b8 100644 --- a/docs/source/api/bound-methods.rst +++ b/docs/source/api/bound-methods.rst @@ -22,43 +22,65 @@ some of the required arguments. .. currentmodule:: pyrogram -- Message_ -- CallbackQuery_ -- InlineQuery_ - -.. _Message: +Index +----- Message +^^^^^^^ + +.. hlist:: + :columns: 3 + + - :meth:`~Message.click` + - :meth:`~Message.delete` + - :meth:`~Message.download` + - :meth:`~Message.edit` + - :meth:`~Message.edit_caption` + - :meth:`~Message.edit_media` + - :meth:`~Message.edit_reply_markup` + - :meth:`~Message.forward` + - :meth:`~Message.pin` + - :meth:`~Message.reply` + - :meth:`~Message.reply_animation` + - :meth:`~Message.reply_audio` + - :meth:`~Message.reply_cached_media` + - :meth:`~Message.reply_chat_action` + - :meth:`~Message.reply_contact` + - :meth:`~Message.reply_document` + - :meth:`~Message.reply_game` + - :meth:`~Message.reply_inline_bot_result` + - :meth:`~Message.reply_location` + - :meth:`~Message.reply_media_group` + - :meth:`~Message.reply_photo` + - :meth:`~Message.reply_poll` + - :meth:`~Message.reply_sticker` + - :meth:`~Message.reply_venue` + - :meth:`~Message.reply_video` + - :meth:`~Message.reply_video_note` + - :meth:`~Message.reply_voice` + +CallbackQuery +^^^^^^^^^^^^^ + +.. hlist:: + :columns: 2 + + - :meth:`~CallbackQuery.answer` + +InlineQuery +^^^^^^^^^^^ + +.. hlist:: + :columns: 2 + + - :meth:`~InlineQuery.answer` + +----- + +Details ------- -- :meth:`Message.click()` -- :meth:`Message.delete()` -- :meth:`Message.download()` -- :meth:`Message.edit()` -- :meth:`Message.edit_caption()` -- :meth:`Message.edit_media()` -- :meth:`Message.edit_reply_markup()` -- :meth:`Message.forward()` -- :meth:`Message.pin()` -- :meth:`Message.reply()` -- :meth:`Message.reply_animation()` -- :meth:`Message.reply_audio()` -- :meth:`Message.reply_cached_media()` -- :meth:`Message.reply_chat_action()` -- :meth:`Message.reply_contact()` -- :meth:`Message.reply_document()` -- :meth:`Message.reply_game()` -- :meth:`Message.reply_inline_bot_result()` -- :meth:`Message.reply_location()` -- :meth:`Message.reply_media_group()` -- :meth:`Message.reply_photo()` -- :meth:`Message.reply_poll()` -- :meth:`Message.reply_sticker()` -- :meth:`Message.reply_venue()` -- :meth:`Message.reply_video()` -- :meth:`Message.reply_video_note()` -- :meth:`Message.reply_voice()` - +.. Message .. automethod:: Message.click() .. automethod:: Message.delete() .. automethod:: Message.download() @@ -87,16 +109,8 @@ Message .. automethod:: Message.reply_video_note() .. automethod:: Message.reply_voice() -.. _CallbackQuery: - -CallbackQuery -------------- - +.. CallbackQuery .. automethod:: CallbackQuery.answer() -.. _InlineQuery: - -InlineQuery ------------ - -.. automethod:: InlineQuery.answer() \ No newline at end of file +.. InlineQuery +.. automethod:: InlineQuery.answer() diff --git a/docs/source/api/decorators.rst b/docs/source/api/decorators.rst index be8376f5..ff31cb27 100644 --- a/docs/source/api/decorators.rst +++ b/docs/source/api/decorators.rst @@ -1,13 +1,13 @@ Decorators ========== -While still being methods bound to the :obj:`Client ` class, decorators are of a special kind and thus deserve a -dedicated page. +While still being methods bound to the :class:`~pyrogram.Client` class, decorators are of a special kind and thus +deserve a dedicated page. Decorators are able to register callback functions for handling updates in a much easier and cleaner way compared to -`Handlers `_; they do so by instantiating the correct handler and calling -:meth:`add_handler() `, automatically. All you need to do is adding the decorators on top -of your functions. +:doc:`Handlers `; they do so by instantiating the correct handler and calling +:meth:`~pyrogram.Client.add_handler`, automatically. All you need to do is adding the decorators on top of your +functions. .. code-block:: python :emphasize-lines: 6 @@ -24,25 +24,34 @@ of your functions. app.run() -.. currentmodule:: pyrogram.Client +.. currentmodule:: pyrogram -.. autosummary:: - :nosignatures: +Index +----- - on_message - on_callback_query - on_inline_query - on_deleted_messages - on_user_status - on_poll - on_disconnect - on_raw_update +.. hlist:: + :columns: 3 -.. automethod:: pyrogram.Client.on_message() -.. automethod:: pyrogram.Client.on_callback_query() -.. automethod:: pyrogram.Client.on_inline_query() -.. automethod:: pyrogram.Client.on_deleted_messages() -.. automethod:: pyrogram.Client.on_user_status() -.. automethod:: pyrogram.Client.on_poll() -.. automethod:: pyrogram.Client.on_disconnect() -.. automethod:: pyrogram.Client.on_raw_update() \ No newline at end of file + - :meth:`~Client.on_message` + - :meth:`~Client.on_callback_query` + - :meth:`~Client.on_inline_query` + - :meth:`~Client.on_deleted_messages` + - :meth:`~Client.on_user_status` + - :meth:`~Client.on_poll` + - :meth:`~Client.on_disconnect` + - :meth:`~Client.on_raw_update` + +----- + +Details +------- + +.. Decorators +.. autodecorator:: pyrogram.Client.on_message() +.. autodecorator:: pyrogram.Client.on_callback_query() +.. autodecorator:: pyrogram.Client.on_inline_query() +.. autodecorator:: pyrogram.Client.on_deleted_messages() +.. autodecorator:: pyrogram.Client.on_user_status() +.. autodecorator:: pyrogram.Client.on_poll() +.. autodecorator:: pyrogram.Client.on_disconnect() +.. autodecorator:: pyrogram.Client.on_raw_update() \ No newline at end of file diff --git a/docs/source/api/handlers.rst b/docs/source/api/handlers.rst index 90c8e614..f91dd3d5 100644 --- a/docs/source/api/handlers.rst +++ b/docs/source/api/handlers.rst @@ -3,8 +3,8 @@ Update Handlers Handlers are used to instruct Pyrogram about which kind of updates you'd like to handle with your callback functions. -For a much more convenient way of registering callback functions have a look at `Decorators `_ instead. -In case you decided to manually create a handler, use :meth:`add_handler() ` to register +For a much more convenient way of registering callback functions have a look at :doc:`Decorators ` instead. +In case you decided to manually create a handler, use :class:`~pyrogram.Client.add_handler` to register it. .. code-block:: python @@ -25,18 +25,27 @@ it. .. currentmodule:: pyrogram -.. autosummary:: - :nosignatures: +Index +----- - MessageHandler - DeletedMessagesHandler - CallbackQueryHandler - InlineQueryHandler - UserStatusHandler - PollHandler - DisconnectHandler - RawUpdateHandler +.. hlist:: + :columns: 3 + - :class:`MessageHandler` + - :class:`DeletedMessagesHandler` + - :class:`CallbackQueryHandler` + - :class:`InlineQueryHandler` + - :class:`UserStatusHandler` + - :class:`PollHandler` + - :class:`DisconnectHandler` + - :class:`RawUpdateHandler` + +----- + +Details +------- + +.. Handlers .. autoclass:: MessageHandler() .. autoclass:: DeletedMessagesHandler() .. autoclass:: CallbackQueryHandler() diff --git a/docs/source/api/methods.rst b/docs/source/api/methods.rst index 7c061d3a..7614918e 100644 --- a/docs/source/api/methods.rst +++ b/docs/source/api/methods.rst @@ -1,7 +1,7 @@ Available Methods ================= -All Pyrogram methods listed here are bound to a :obj:`Client ` instance. +All Pyrogram methods listed here are bound to a :class:`~pyrogram.Client` instance. .. code-block:: python :emphasize-lines: 6 @@ -13,253 +13,249 @@ All Pyrogram methods listed here are bound to a :obj:`Client ` with app: app.send_message("haskell", "hi") -.. currentmodule:: pyrogram.Client +.. currentmodule:: pyrogram + +Index +----- Utilities ---------- +^^^^^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 4 - start - stop - restart - idle - run - add_handler - remove_handler - send - resolve_peer - save_file - stop_transmission + - :meth:`~Client.start` + - :meth:`~Client.stop` + - :meth:`~Client.restart` + - :meth:`~Client.idle` + - :meth:`~Client.run` + - :meth:`~Client.add_handler` + - :meth:`~Client.remove_handler` + - :meth:`~Client.send` + - :meth:`~Client.resolve_peer` + - :meth:`~Client.save_file` + - :meth:`~Client.stop_transmission` Messages --------- +^^^^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 3 - send_message - forward_messages - send_photo - send_audio - send_document - send_sticker - send_video - send_animation - send_voice - send_video_note - send_media_group - send_location - send_venue - send_contact - send_cached_media - send_chat_action - edit_message_text - edit_message_caption - edit_message_reply_markup - edit_message_media - delete_messages - get_messages - get_history - get_history_count - iter_history - send_poll - vote_poll - stop_poll - retract_vote - download_media + - :meth:`~Client.send_message` + - :meth:`~Client.forward_messages` + - :meth:`~Client.send_photo` + - :meth:`~Client.send_audio` + - :meth:`~Client.send_document` + - :meth:`~Client.send_sticker` + - :meth:`~Client.send_video` + - :meth:`~Client.send_animation` + - :meth:`~Client.send_voice` + - :meth:`~Client.send_video_note` + - :meth:`~Client.send_media_group` + - :meth:`~Client.send_location` + - :meth:`~Client.send_venue` + - :meth:`~Client.send_contact` + - :meth:`~Client.send_cached_media` + - :meth:`~Client.send_chat_action` + - :meth:`~Client.edit_message_text` + - :meth:`~Client.edit_message_caption` + - :meth:`~Client.edit_message_reply_markup` + - :meth:`~Client.edit_message_media` + - :meth:`~Client.delete_messages` + - :meth:`~Client.get_messages` + - :meth:`~Client.get_history` + - :meth:`~Client.get_history_count` + - :meth:`~Client.iter_history` + - :meth:`~Client.send_poll` + - :meth:`~Client.vote_poll` + - :meth:`~Client.stop_poll` + - :meth:`~Client.retract_vote` + - :meth:`~Client.download_media` Chats ------ +^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 3 - join_chat - leave_chat - kick_chat_member - unban_chat_member - restrict_chat_member - promote_chat_member - export_chat_invite_link - set_chat_photo - delete_chat_photo - set_chat_title - set_chat_description - pin_chat_message - unpin_chat_message - get_chat - get_chat_member - get_chat_members - get_chat_members_count - iter_chat_members - get_dialogs - iter_dialogs - get_dialogs_count - restrict_chat - update_chat_username + - :meth:`~Client.join_chat` + - :meth:`~Client.leave_chat` + - :meth:`~Client.kick_chat_member` + - :meth:`~Client.unban_chat_member` + - :meth:`~Client.restrict_chat_member` + - :meth:`~Client.promote_chat_member` + - :meth:`~Client.export_chat_invite_link` + - :meth:`~Client.set_chat_photo` + - :meth:`~Client.delete_chat_photo` + - :meth:`~Client.set_chat_title` + - :meth:`~Client.set_chat_description` + - :meth:`~Client.pin_chat_message` + - :meth:`~Client.unpin_chat_message` + - :meth:`~Client.get_chat` + - :meth:`~Client.get_chat_member` + - :meth:`~Client.get_chat_members` + - :meth:`~Client.get_chat_members_count` + - :meth:`~Client.iter_chat_members` + - :meth:`~Client.get_dialogs` + - :meth:`~Client.iter_dialogs` + - :meth:`~Client.get_dialogs_count` + - :meth:`~Client.restrict_chat` + - :meth:`~Client.update_chat_username` Users ------ +^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 2 - get_me - get_users - get_user_profile_photos - get_user_profile_photos_count - set_user_profile_photo - delete_user_profile_photos - update_username + - :meth:`~Client.get_me` + - :meth:`~Client.get_users` + - :meth:`~Client.get_user_profile_photos` + - :meth:`~Client.get_user_profile_photos_count` + - :meth:`~Client.set_user_profile_photo` + - :meth:`~Client.delete_user_profile_photos` + - :meth:`~Client.update_username` + - :meth:`~Client.get_user_dc` Contacts --------- +^^^^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 3 - add_contacts - get_contacts - get_contacts_count - delete_contacts + - :meth:`~Client.add_contacts` + - :meth:`~Client.get_contacts` + - :meth:`~Client.get_contacts_count` + - :meth:`~Client.delete_contacts` Password --------- +^^^^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 3 - enable_cloud_password - change_cloud_password - remove_cloud_password + - :meth:`~Client.enable_cloud_password` + - :meth:`~Client.change_cloud_password` + - :meth:`~Client.remove_cloud_password` Bots ----- +^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 3 - get_inline_bot_results - send_inline_bot_result - answer_callback_query - answer_inline_query - request_callback_answer - send_game - set_game_score - get_game_high_scores + - :meth:`~Client.get_inline_bot_results` + - :meth:`~Client.send_inline_bot_result` + - :meth:`~Client.answer_callback_query` + - :meth:`~Client.answer_inline_query` + - :meth:`~Client.request_callback_answer` + - :meth:`~Client.send_game` + - :meth:`~Client.set_game_score` + - :meth:`~Client.get_game_high_scores` + +----- + +Details +------- .. Utilities - --------- - -.. automethod:: pyrogram.Client.start() -.. automethod:: pyrogram.Client.stop() -.. automethod:: pyrogram.Client.restart() -.. automethod:: pyrogram.Client.idle() -.. automethod:: pyrogram.Client.run() -.. automethod:: pyrogram.Client.add_handler() -.. automethod:: pyrogram.Client.remove_handler() -.. automethod:: pyrogram.Client.send() -.. automethod:: pyrogram.Client.resolve_peer() -.. automethod:: pyrogram.Client.save_file() -.. automethod:: pyrogram.Client.stop_transmission() +.. automethod:: Client.start() +.. automethod:: Client.stop() +.. automethod:: Client.restart() +.. automethod:: Client.idle() +.. automethod:: Client.run() +.. automethod:: Client.add_handler() +.. automethod:: Client.remove_handler() +.. automethod:: Client.send() +.. automethod:: Client.resolve_peer() +.. automethod:: Client.save_file() +.. automethod:: Client.stop_transmission() .. Messages - -------- - -.. automethod:: pyrogram.Client.send_message() -.. automethod:: pyrogram.Client.forward_messages() -.. automethod:: pyrogram.Client.send_photo() -.. automethod:: pyrogram.Client.send_audio() -.. automethod:: pyrogram.Client.send_document() -.. automethod:: pyrogram.Client.send_sticker() -.. automethod:: pyrogram.Client.send_video() -.. automethod:: pyrogram.Client.send_animation() -.. automethod:: pyrogram.Client.send_voice() -.. automethod:: pyrogram.Client.send_video_note() -.. automethod:: pyrogram.Client.send_media_group() -.. automethod:: pyrogram.Client.send_location() -.. automethod:: pyrogram.Client.send_venue() -.. automethod:: pyrogram.Client.send_contact() -.. automethod:: pyrogram.Client.send_cached_media() -.. automethod:: pyrogram.Client.send_chat_action() -.. automethod:: pyrogram.Client.edit_message_text() -.. automethod:: pyrogram.Client.edit_message_caption() -.. automethod:: pyrogram.Client.edit_message_reply_markup() -.. automethod:: pyrogram.Client.edit_message_media() -.. automethod:: pyrogram.Client.delete_messages() -.. automethod:: pyrogram.Client.get_messages() -.. automethod:: pyrogram.Client.get_history() -.. automethod:: pyrogram.Client.get_history_count() -.. automethod:: pyrogram.Client.iter_history() -.. automethod:: pyrogram.Client.send_poll() -.. automethod:: pyrogram.Client.vote_poll() -.. automethod:: pyrogram.Client.stop_poll() -.. automethod:: pyrogram.Client.retract_vote() -.. automethod:: pyrogram.Client.download_media() +.. automethod:: Client.send_message() +.. automethod:: Client.forward_messages() +.. automethod:: Client.send_photo() +.. automethod:: Client.send_audio() +.. automethod:: Client.send_document() +.. automethod:: Client.send_sticker() +.. automethod:: Client.send_video() +.. automethod:: Client.send_animation() +.. automethod:: Client.send_voice() +.. automethod:: Client.send_video_note() +.. automethod:: Client.send_media_group() +.. automethod:: Client.send_location() +.. automethod:: Client.send_venue() +.. automethod:: Client.send_contact() +.. automethod:: Client.send_cached_media() +.. automethod:: Client.send_chat_action() +.. automethod:: Client.edit_message_text() +.. automethod:: Client.edit_message_caption() +.. automethod:: Client.edit_message_reply_markup() +.. automethod:: Client.edit_message_media() +.. automethod:: Client.delete_messages() +.. automethod:: Client.get_messages() +.. automethod:: Client.get_history() +.. automethod:: Client.get_history_count() +.. automethod:: Client.iter_history() +.. automethod:: Client.send_poll() +.. automethod:: Client.vote_poll() +.. automethod:: Client.stop_poll() +.. automethod:: Client.retract_vote() +.. automethod:: Client.download_media() .. Chats - ----- - -.. automethod:: pyrogram.Client.join_chat() -.. automethod:: pyrogram.Client.leave_chat() -.. automethod:: pyrogram.Client.kick_chat_member() -.. automethod:: pyrogram.Client.unban_chat_member() -.. automethod:: pyrogram.Client.restrict_chat_member() -.. automethod:: pyrogram.Client.promote_chat_member() -.. automethod:: pyrogram.Client.export_chat_invite_link() -.. automethod:: pyrogram.Client.set_chat_photo() -.. automethod:: pyrogram.Client.delete_chat_photo() -.. automethod:: pyrogram.Client.set_chat_title() -.. automethod:: pyrogram.Client.set_chat_description() -.. automethod:: pyrogram.Client.pin_chat_message() -.. automethod:: pyrogram.Client.unpin_chat_message() -.. automethod:: pyrogram.Client.get_chat() -.. automethod:: pyrogram.Client.get_chat_member() -.. automethod:: pyrogram.Client.get_chat_members() -.. automethod:: pyrogram.Client.get_chat_members_count() -.. automethod:: pyrogram.Client.iter_chat_members() -.. automethod:: pyrogram.Client.get_dialogs() -.. automethod:: pyrogram.Client.iter_dialogs() -.. automethod:: pyrogram.Client.get_dialogs_count() -.. automethod:: pyrogram.Client.restrict_chat() -.. automethod:: pyrogram.Client.update_chat_username() +.. automethod:: Client.join_chat() +.. automethod:: Client.leave_chat() +.. automethod:: Client.kick_chat_member() +.. automethod:: Client.unban_chat_member() +.. automethod:: Client.restrict_chat_member() +.. automethod:: Client.promote_chat_member() +.. automethod:: Client.export_chat_invite_link() +.. automethod:: Client.set_chat_photo() +.. automethod:: Client.delete_chat_photo() +.. automethod:: Client.set_chat_title() +.. automethod:: Client.set_chat_description() +.. automethod:: Client.pin_chat_message() +.. automethod:: Client.unpin_chat_message() +.. automethod:: Client.get_chat() +.. automethod:: Client.get_chat_member() +.. automethod:: Client.get_chat_members() +.. automethod:: Client.get_chat_members_count() +.. automethod:: Client.iter_chat_members() +.. automethod:: Client.get_dialogs() +.. automethod:: Client.iter_dialogs() +.. automethod:: Client.get_dialogs_count() +.. automethod:: Client.restrict_chat() +.. automethod:: Client.update_chat_username() .. Users - ----- - -.. automethod:: pyrogram.Client.get_me() -.. automethod:: pyrogram.Client.get_users() -.. automethod:: pyrogram.Client.get_user_profile_photos() -.. automethod:: pyrogram.Client.get_user_profile_photos_count() -.. automethod:: pyrogram.Client.set_user_profile_photo() -.. automethod:: pyrogram.Client.delete_user_profile_photos() -.. automethod:: pyrogram.Client.update_username() +.. automethod:: Client.get_me() +.. automethod:: Client.get_users() +.. automethod:: Client.get_user_profile_photos() +.. automethod:: Client.get_user_profile_photos_count() +.. automethod:: Client.set_user_profile_photo() +.. automethod:: Client.delete_user_profile_photos() +.. automethod:: Client.update_username() +.. automethod:: Client.get_user_dc() .. Contacts - -------- - -.. automethod:: pyrogram.Client.add_contacts() -.. automethod:: pyrogram.Client.get_contacts() -.. automethod:: pyrogram.Client.get_contacts_count() -.. automethod:: pyrogram.Client.delete_contacts() +.. automethod:: Client.add_contacts() +.. automethod:: Client.get_contacts() +.. automethod:: Client.get_contacts_count() +.. automethod:: Client.delete_contacts() .. Password - -------- - -.. automethod:: pyrogram.Client.enable_cloud_password() -.. automethod:: pyrogram.Client.change_cloud_password() -.. automethod:: pyrogram.Client.remove_cloud_password() +.. automethod:: Client.enable_cloud_password() +.. automethod:: Client.change_cloud_password() +.. automethod:: Client.remove_cloud_password() .. Bots - ---- - -.. automethod:: pyrogram.Client.get_inline_bot_results() -.. automethod:: pyrogram.Client.send_inline_bot_result() -.. automethod:: pyrogram.Client.answer_callback_query() -.. automethod:: pyrogram.Client.answer_inline_query() -.. automethod:: pyrogram.Client.request_callback_answer() -.. automethod:: pyrogram.Client.send_game() -.. automethod:: pyrogram.Client.set_game_score() -.. automethod:: pyrogram.Client.get_game_high_scores() +.. automethod:: Client.get_inline_bot_results() +.. automethod:: Client.send_inline_bot_result() +.. automethod:: Client.answer_callback_query() +.. automethod:: Client.answer_inline_query() +.. automethod:: Client.request_callback_answer() +.. automethod:: Client.send_game() +.. automethod:: Client.set_game_score() +.. automethod:: Client.get_game_high_scores() diff --git a/docs/source/api/types.rst b/docs/source/api/types.rst index d911520c..d264eaa2 100644 --- a/docs/source/api/types.rst +++ b/docs/source/api/types.rst @@ -15,102 +15,108 @@ All Pyrogram types listed here are accessible through the main package directly. .. currentmodule:: pyrogram +Index +----- + Users & Chats -------------- +^^^^^^^^^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 5 - User - UserStatus - Chat - ChatPreview - ChatPhoto - ChatMember - ChatMembers - ChatPermissions - Dialog - Dialogs + - :class:`User` + - :class:`UserStatus` + - :class:`Chat` + - :class:`ChatPreview` + - :class:`ChatPhoto` + - :class:`ChatMember` + - :class:`ChatMembers` + - :class:`ChatPermissions` + - :class:`Dialog` + - :class:`Dialogs` Messages & Media ----------------- +^^^^^^^^^^^^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 5 - Message - Messages - MessageEntity - Photo - PhotoSize - UserProfilePhotos - Audio - Document - Animation - Video - Voice - VideoNote - Contact - Location - Venue - Sticker - Game - Poll - PollOption + - :class:`Message` + - :class:`Messages` + - :class:`MessageEntity` + - :class:`Photo` + - :class:`PhotoSize` + - :class:`UserProfilePhotos` + - :class:`Audio` + - :class:`Document` + - :class:`Animation` + - :class:`Video` + - :class:`Voice` + - :class:`VideoNote` + - :class:`Contact` + - :class:`Location` + - :class:`Venue` + - :class:`Sticker` + - :class:`Game` + - :class:`Poll` + - :class:`PollOption` Keyboards ---------- +^^^^^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 4 - ReplyKeyboardMarkup - KeyboardButton - ReplyKeyboardRemove - InlineKeyboardMarkup - InlineKeyboardButton - ForceReply - CallbackQuery - GameHighScore - GameHighScores - CallbackGame + - :class:`ReplyKeyboardMarkup` + - :class:`KeyboardButton` + - :class:`ReplyKeyboardRemove` + - :class:`InlineKeyboardMarkup` + - :class:`InlineKeyboardButton` + - :class:`ForceReply` + - :class:`CallbackQuery` + - :class:`GameHighScore` + - :class:`GameHighScores` + - :class:`CallbackGame` Input Media ------------ +^^^^^^^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 4 - InputMedia - InputMediaPhoto - InputMediaVideo - InputMediaAudio - InputMediaAnimation - InputMediaDocument - InputPhoneContact + - :class:`InputMedia` + - :class:`InputMediaPhoto` + - :class:`InputMediaVideo` + - :class:`InputMediaAudio` + - :class:`InputMediaAnimation` + - :class:`InputMediaDocument` + - :class:`InputPhoneContact` Inline Mode ------------- +^^^^^^^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 3 - InlineQuery - InlineQueryResult - InlineQueryResultArticle + - :class:`InlineQuery` + - :class:`InlineQueryResult` + - :class:`InlineQueryResultArticle` InputMessageContent -------------------- +^^^^^^^^^^^^^^^^^^^ -.. autosummary:: - :nosignatures: +.. hlist:: + :columns: 3 - InputMessageContent - InputTextMessageContent + - :class:`InputMessageContent` + - :class:`InputTextMessageContent` + +----- + +Details +------- .. User & Chats - ------------ - .. autoclass:: User() .. autoclass:: UserStatus() .. autoclass:: Chat() @@ -123,8 +129,6 @@ InputMessageContent .. autoclass:: Dialogs() .. Messages & Media - ---------------- - .. autoclass:: Message() .. autoclass:: Messages() .. autoclass:: MessageEntity() @@ -146,8 +150,6 @@ InputMessageContent .. autoclass:: PollOption() .. Keyboards - --------- - .. autoclass:: ReplyKeyboardMarkup() .. autoclass:: KeyboardButton() .. autoclass:: ReplyKeyboardRemove() @@ -160,8 +162,6 @@ InputMessageContent .. autoclass:: CallbackGame() .. Input Media - ----------- - .. autoclass:: InputMedia() .. autoclass:: InputMediaPhoto() .. autoclass:: InputMediaVideo() @@ -171,14 +171,10 @@ InputMessageContent .. autoclass:: InputPhoneContact() .. Inline Mode - ----------- - .. autoclass:: InlineQuery() .. autoclass:: InlineQueryResult() .. autoclass:: InlineQueryResultArticle() .. InputMessageContent - ------------------- - .. autoclass:: InputMessageContent() .. autoclass:: InputTextMessageContent() diff --git a/docs/source/conf.py b/docs/source/conf.py index e079ec68..7ddeaa94 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -43,7 +43,6 @@ autodoc_member_order = "bysource" version = __version__ release = version -version_rst = ".. |version| replace:: {}".format(version) templates_path = ["_templates"] @@ -61,7 +60,8 @@ html_theme_options = { "collapse_navigation": True, "sticky_navigation": False, "logo_only": True, - "display_version": True + "display_version": True, + "style_external_links": True } html_logo = "_images/pyrogram.png" diff --git a/docs/source/faq.rst b/docs/source/faq.rst index b42332cd..7d7e9032 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -17,10 +17,9 @@ What is Pyrogram? **Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and C. It enables you to easily create custom applications for both user and bot identities (bot API alternative) via the -`MTProto API`_ with the Python programming language. +:doc:`MTProto API ` with the Python programming language. .. _Telegram: https://telegram.org -.. _MTProto API: topics/mtproto-vs-botapi#what-is-the-mtproto-api Where does the name come from? ------------------------------ @@ -47,19 +46,17 @@ Why Pyrogram? - **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted. - **Updated**, to make use of the latest Telegram API version and features. - **Bot API-like**: Similar to the Bot API in its simplicity, but much more powerful and detailed. -- **Pluggable**: The `Smart Plugin`_ system allows to write components with minimal boilerplate code. -- **Comprehensive**: Execute any `advanced action`_ an official client is able to do, and even more. +- **Pluggable**: The :doc:`Smart Plugin ` system allows to write components with minimal + boilerplate code. +- **Comprehensive**: Execute any :doc:`advanced action ` an official client is able to do, and + even more. .. _TgCrypto: https://github.com/pyrogram/tgcrypto -.. _Smart Plugin: topics/smart-plugins -.. _advanced action: topics/advanced-usage What can MTProto do more than the Bot API? ------------------------------------------ -For a detailed answer, please refer to the `MTProto vs. Bot API`_ page. - -.. _MTProto vs. Bot API: topics/mtproto-vs-botapi +For a detailed answer, please refer to the :doc:`MTProto vs. Bot API ` page. Why do I need an API key for bots? ---------------------------------- @@ -97,9 +94,9 @@ Telegram is slowly changing some server's internals and it's doing it in such a inevitably. Not only this, but it seems that the new, hypothetical, file ids could also possibly expire at anytime, thus losing the *persistence* feature. -This change will most likely affect the official `Bot API `_ too -(unless Telegram implements some workarounds server-side to keep backwards compatibility, which Pyrogram could in turn -make use of) and we can expect a proper notice from Telegram. +This change will most likely affect the official :doc:`Bot API ` too (unless Telegram +implements some workarounds server-side to keep backwards compatibility, which Pyrogram could in turn make use of) and +we can expect a proper notice from Telegram. Can I use multiple clients at once on the same account? ------------------------------------------------------- @@ -125,8 +122,8 @@ from the beginning every time, and use one separate session for each parallel cl I started a client and nothing happens! --------------------------------------- -If you are connecting from Russia, China or Iran `you need a proxy`_, because Telegram could be partially or -totally blocked in those countries. +If you are connecting from Russia, China or Iran :doc:`you need a proxy `, because Telegram could be +partially or totally blocked in those countries. Another possible cause might be network issues, either yours or Telegram's. To confirm this, add the following code on the top of your script and run it again. You should see some error mentioning a socket timeout or an unreachable network @@ -146,8 +143,6 @@ fails or not: - DC4: ``149.154.167.91`` - DC5: ``91.108.56.149`` -.. _you need a proxy: topics/proxy - I keep getting PEER_ID_INVALID error! ------------------------------------------- @@ -182,20 +177,5 @@ recover@telegram.org, contact `@smstelegram`_ on Twitter or use `this form`_. .. _@smstelegram: https://twitter.com/smstelegram .. _this form: https://telegram.org/support -About the License ------------------ - -.. image:: https://www.gnu.org/graphics/lgplv3-with-text-154x68.png - :align: left - -Pyrogram is free software and is currently licensed under the terms of the -`GNU Lesser General Public License v3 or later (LGPLv3+)`_. In short: you may use, redistribute and/or modify it -provided that modifications are described and licensed for free under LGPLv3+. - -In other words: you can use and integrate Pyrogram into your own code --- either open source, under the same or -different license, or even proprietary --- without being required to release the source code of your own applications. -However, any modifications to the library itself are required to be published for free under the same LGPLv3+ license. - -.. _GNU Lesser General Public License v3 or later (LGPLv3+): https://github.com/pyrogram/pyrogram/blob/develop/COPYING.lesser .. _Bug Report: https://github.com/pyrogram/pyrogram/issues/new?labels=bug&template=bug_report.md .. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst index 5f00cbfd..72d308b7 100644 --- a/docs/source/glossary.rst +++ b/docs/source/glossary.rst @@ -18,7 +18,7 @@ general. Some words may as well link to dedicated articles in case the topic is API key A secret code used to authenticate and/or authorize a specific application to Telegram in order for it to control how the API is being used, for example, to prevent abuses of the API. - `More on API keys `_. + :doc:`More on API keys `. DC Also known as *data center*, is a place where lots of computer systems are housed and used together in order to @@ -30,21 +30,21 @@ general. Some words may as well link to dedicated articles in case the topic is RPCError An error caused by an RPC which must be returned in place of the successful result in order to let the caller - know something went wrong. `More on RPCError `_. + know something went wrong. :doc:`More on RPCError `. MTProto The name of the custom-made, open and encrypted protocol by Telegram, implemented in Pyrogram. - `More on MTProto `_. + :doc:`More on MTProto `. MTProto API The Telegram main API Pyrogram makes use of, which is able to connect both users and normal bots to Telegram using MTProto as application layer protocol and execute any method Telegram provides from its public TL-schema. - `More on MTProto API `_. + :doc:`More on MTProto API `. Bot API The Telegram Bot API that is able to only connect normal bots only to Telegram using HTTP as application layer protocol and allows to execute a sub-set of the main Telegram API. - `More on Bot API `_. + :doc:`More on Bot API `. Pyrogrammer A developer that uses Pyrogram to build Telegram applications. @@ -65,11 +65,11 @@ general. Some words may as well link to dedicated articles in case the topic is Handler An object that wraps around a callback function that is *actually meant* to be registered into the framework, which will then be able to handle a specific kind of events, such as a new incoming message, for example. - `More on Handlers `_. + :doc:`More on Handlers `. Decorator Also known as *function decorator*, in Python, is a callable object that is used to modify another function. Decorators in Pyrogram are used to automatically register callback functions for handling updates. - `More on Decorators `_. + :doc:`More on Decorators `. .. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md diff --git a/docs/source/index.rst b/docs/source/index.rst index de91015f..b99fcf3d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -42,10 +42,9 @@ Welcome to Pyrogram **Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and C. It enables you to easily create custom apps for both user and bot identities (bot API alternative) via the -`MTProto API`_. +:doc:`MTProto API `. .. _Telegram: https://telegram.org -.. _MTProto API: topics/mtproto-vs-botapi#what-is-the-mtproto-api How the Documentation is Organized ---------------------------------- @@ -60,15 +59,10 @@ First Steps .. hlist:: :columns: 2 - - `Quick Start`_: Overview to get you started quickly. - - `Calling Methods`_: How to call Pyrogram's methods. - - `Handling Updates`_: How to handle Telegram updates. - - `Error Handling`_: How to handle API errors correctly. - -.. _Quick Start: intro/quickstart -.. _Calling Methods: start/invoking -.. _Handling Updates: start/updates -.. _Error Handling: start/errors + - :doc:`Quick Start `: Overview to get you started quickly. + - :doc:`Calling Methods `: How to call Pyrogram's methods. + - :doc:`Handling Updates `: How to handle Telegram updates. + - :doc:`Error Handling `: How to handle API errors correctly. API Reference ------------- @@ -76,15 +70,10 @@ API Reference .. hlist:: :columns: 2 - - `Pyrogram Client`_: Reference details about the Client class. - - `Available Methods`_: List of available high-level methods. - - `Available Types`_: List of available high-level types. - - `Bound Methods`_: List of convenient bound methods. - -.. _Pyrogram Client: ./api/client -.. _Available Methods: api/methods -.. _Available Types: api/types -.. _Bound Methods: api/bound-methods + - :doc:`Pyrogram Client `: Reference details about the Client class. + - :doc:`Available Methods `: List of available high-level methods. + - :doc:`Available Types `: List of available high-level types. + - :doc:`Bound Methods `: List of convenient bound methods. Meta ---- @@ -92,17 +81,12 @@ Meta .. hlist:: :columns: 2 - - `Pyrogram FAQ`_: Answers to common Pyrogram questions. - - `Pyrogram Glossary`_: List of words with brief explanations. - - `Release Notes`_: Release notes for Pyrogram releases. - - `Powered by Pyrogram`_: Collection of Pyrogram Projects. - - `Support Pyrogram`_: Ways to show your appreciation. - -.. _Pyrogram FAQ: faq -.. _Pyrogram Glossary: glossary -.. _Release Notes: releases -.. _Powered by Pyrogram: powered-by -.. _Support Pyrogram: support-pyrogram + - :doc:`Pyrogram FAQ `: Answers to common Pyrogram questions. + - :doc:`Pyrogram Glossary `: List of words with brief explanations. + - :doc:`Release Notes `: Release notes for Pyrogram releases. + - :doc:`Powered by Pyrogram `: Collection of Pyrogram Projects. + - :doc:`Support Pyrogram `: Ways to show your appreciation. + - :doc:`About the License `: Information about the Project license. .. toctree:: :hidden: @@ -163,10 +147,13 @@ Meta releases powered-by support-pyrogram + license .. toctree:: :hidden: :caption: Telegram API telegram/functions/index - telegram/types/index \ No newline at end of file + telegram/types/index + +Last updated on |today| \ No newline at end of file diff --git a/docs/source/intro/install.rst b/docs/source/intro/install.rst index fe804e79..82ab4c0b 100644 --- a/docs/source/intro/install.rst +++ b/docs/source/intro/install.rst @@ -20,7 +20,7 @@ Install Pyrogram $ pip3 install -U pyrogram -- or, with TgCrypto_ as extra requirement (recommended): +- or, with :doc:`TgCrypto <../topics/tgcrypto>` as extra requirement (recommended): .. code-block:: text @@ -89,5 +89,4 @@ If no error shows up you are good to go. >>> pyrogram.__version__ '|version|' -.. _TgCrypto: ../topics/tgcrypto .. _`Github repo`: http://github.com/pyrogram/pyrogram diff --git a/docs/source/intro/quickstart.rst b/docs/source/intro/quickstart.rst index 1aa7989e..a7a7e377 100644 --- a/docs/source/intro/quickstart.rst +++ b/docs/source/intro/quickstart.rst @@ -43,7 +43,7 @@ Enjoy the API That was just a quick overview that barely scratched the surface! In the next few pages of the introduction, we'll take a much more in-depth look of what we have just done above. -Feeling eager to continue? You can take a shortcut to `Calling Methods`_ and come back later to learn some more details. +Feeling eager to continue? You can take a shortcut to :doc:`Calling Methods <../start/invoking>` and come back later to +learn some more details. .. _community: //t.me/Pyrogram -.. _Calling Methods: ../start/invoking \ No newline at end of file diff --git a/docs/source/intro/setup.rst b/docs/source/intro/setup.rst index 9c0cc6d4..6273b2b2 100644 --- a/docs/source/intro/setup.rst +++ b/docs/source/intro/setup.rst @@ -1,8 +1,8 @@ Project Setup ============= -We have just `installed Pyrogram`_. In this page we'll discuss what you need to do in order to set up a project with -the library. Let's see how it's done. +We have just :doc:`installed Pyrogram `. In this page we'll discuss what you need to do in order to set up a +project with the library. Let's see how it's done. API Keys -------- @@ -26,7 +26,7 @@ The very first step requires you to obtain a valid Telegram API key (API id/hash Configuration ------------- -Having the API key from the `previous step <#api-keys>`_ in handy, we can now begin to configure a Pyrogram project. +Having the API key from the previous step in handy, we can now begin to configure a Pyrogram project. There are two ways to do so, and you can choose what fits better for you: - First option (recommended): create a new ``config.ini`` file at the root of your working directory, copy-paste the @@ -57,5 +57,3 @@ There are two ways to do so, and you can choose what fits better for you: To keep code snippets clean and concise, from now on it is assumed you are making use of the ``config.ini`` file, thus, the *api_id* and *api_hash* parameters usage won't be shown anymore. - -.. _installed Pyrogram: install.html diff --git a/docs/source/license.rst b/docs/source/license.rst new file mode 100644 index 00000000..1c8d99d1 --- /dev/null +++ b/docs/source/license.rst @@ -0,0 +1,15 @@ +About the License +================= + +.. image:: https://www.gnu.org/graphics/lgplv3-with-text-154x68.png + :align: left + +Pyrogram is free software and is currently licensed under the terms of the +`GNU Lesser General Public License v3 or later (LGPLv3+)`_. In short: you may use, redistribute and/or modify it +provided that modifications are described and licensed for free under LGPLv3+. + +In other words: you can use and integrate Pyrogram into your own code --- either open source, under the same or +different license, or even proprietary --- without being required to release the source code of your own applications. +However, any modifications to the library itself are required to be published for free under the same LGPLv3+ license. + +.. _GNU Lesser General Public License v3 or later (LGPLv3+): https://github.com/pyrogram/pyrogram/blob/develop/COPYING.lesser \ No newline at end of file diff --git a/docs/source/start/auth.rst b/docs/source/start/auth.rst index e00b08a0..79264bfa 100644 --- a/docs/source/start/auth.rst +++ b/docs/source/start/auth.rst @@ -1,7 +1,7 @@ Authorization ============= -Once a `project is set up`_, you will still have to follow a few steps before you can actually use Pyrogram to make +Once a :doc:`project is set up <../intro/setup>`, you will still have to follow a few steps before you can actually use Pyrogram to make API calls. This section provides all the information you need in order to authorize yourself as user or bot. User Authorization @@ -9,8 +9,8 @@ User Authorization In order to use the API, Telegram requires that users be authorized via their phone numbers. Pyrogram automatically manages this process, all you need to do is create an instance of the -:class:`Client ` class by passing to it a ``session_name`` of your choice (e.g.: "my_account") and call -the :meth:`run() ` method: +:class:`~pyrogram.Client` class by passing to it a ``session_name`` of your choice (e.g.: "my_account") and call +the :meth:`~pyrogram.Client.run` method: .. code-block:: python @@ -47,7 +47,7 @@ Bot Authorization Bots are a special kind of users that are authorized via their tokens (instead of phone numbers), which are created by the `Bot Father`_. Bot tokens replace the users' phone numbers only — you still need to -`configure a Telegram API key <../intro/setup#configuration>`_ with Pyrogram, even when using bots. +:doc:`configure a Telegram API key <../intro/setup>` with Pyrogram, even when using bots. The authorization process is automatically managed. All you need to do is choose a ``session_name`` (can be anything, usually your bot username) and pass your bot token using the ``bot_token`` parameter. The session file will be named @@ -64,6 +64,5 @@ after the session name, which will be ``my_bot.session`` for the example below. app.run() -.. _project is set up: ../intro/setup .. _Country Code: https://en.wikipedia.org/wiki/List_of_country_calling_codes .. _Bot Father: https://t.me/botfather \ No newline at end of file diff --git a/docs/source/start/invoking.rst b/docs/source/start/invoking.rst index ef9bc373..1357cd7b 100644 --- a/docs/source/start/invoking.rst +++ b/docs/source/start/invoking.rst @@ -1,8 +1,8 @@ Calling Methods =============== -At this point, we have successfully `installed Pyrogram`_ and authorized_ our account; we are now aiming towards the -core of the library. It's time to start playing with the API! +At this point, we have successfully :doc:`installed Pyrogram <../intro/install>` and :doc:`authorized ` our +account; we are now aiming towards the core of the library. It's time to start playing with the API! Basic Usage ----------- @@ -63,8 +63,8 @@ Context Manager --------------- You can also use Pyrogram's Client in a context manager with the ``with`` statement. The client will automatically -:meth:`start() ` and :meth:`stop() ` gracefully, even in case of unhandled -exceptions in your code. The example above can be therefore rewritten in a much nicer way: +:meth:`~pyrogram.Client.start` and :meth:`~pyrogram.Client.stop` gracefully, even in case of unhandled exceptions in +your code. The example above can be therefore rewritten in a much nicer way: .. code-block:: python @@ -79,6 +79,3 @@ exceptions in your code. The example above can be therefore rewritten in a much app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI") More examples can be found on `GitHub `_. - -.. _installed Pyrogram: ../intro/install.html -.. _authorized: ../intro/setup.html diff --git a/docs/source/start/updates.rst b/docs/source/start/updates.rst index a0f2ca0c..b6838ad3 100644 --- a/docs/source/start/updates.rst +++ b/docs/source/start/updates.rst @@ -1,8 +1,8 @@ Handling Updates ================ -Calling `API methods`_ sequentially is cool, but how to react when, for example, a new message arrives? This page deals -with updates and how to handle such events in Pyrogram. Let's have a look at how they work. +Calling :doc:`API methods ` sequentially is cool, but how to react when, for example, a new message arrives? +This page deals with updates and how to handle such events in Pyrogram. Let's have a look at how they work. Defining Updates ---------------- @@ -10,7 +10,7 @@ Defining Updates First, let's define what are these updates. As hinted already, updates are simply events that happen in your Telegram account (incoming messages, new members join, bot button presses, etc...), which are meant to notify you about a new specific state that has changed. These updates are handled by registering one or more callback functions in your app -using `Handlers <../api/handlers>`_. +using :doc:`Handlers <../api/handlers>`. Each handler deals with a specific event and once a matching update arrives from Telegram, your registered callback function will be called back by the framework and its body executed. @@ -18,17 +18,16 @@ function will be called back by the framework and its body executed. Registering a Handler --------------------- -To explain how handlers work let's have a look at the most used one, the -:obj:`MessageHandler `, which will be in charge for handling :obj:`Message ` -updates coming from all around your chats. Every other handler shares the same setup logic; you should not have troubles -settings them up once you learn from this section. +To explain how handlers work let's have a look at the most used one, the :class:`~pyrogram.MessageHandler`, which will +be in charge for handling :class:`~pyrogram.Message` updates coming from all around your chats. Every other handler shares +the same setup logic; you should not have troubles settings them up once you learn from this section. Using add_handler() ------------------- -The :meth:`add_handler() ` method takes any handler instance that wraps around your defined -callback function and registers it in your Client. Here's a full example that prints out the content of a message as -soon as it arrives: +The :meth:`~pyrogram.Client.add_handler` method takes any handler instance that wraps around your defined callback +function and registers it in your Client. Here's a full example that prints out the content of a message as soon as it +arrives: .. code-block:: python @@ -55,24 +54,23 @@ call that function by passing the client instance and the new message instance a def my_function(client, message): print(message) -Second one: the :obj:`MessageHandler `. This object tells Pyrogram the function we defined -above must only handle updates that are in form of a :obj:`Message `: +Second one: the :class:`~pyrogram.MessageHandler`. This object tells Pyrogram the function we defined above must only +handle updates that are in form of a :class:`~pyrogram.Message`: .. code-block:: python my_handler = MessageHandler(my_function) -Third: the method :meth:`add_handler() `. This method is used to actually register the -handler and let Pyrogram know it needs to be taken into consideration when new updates arrive and the internal -dispatching phase begins. +Third: the method :meth:`~pyrogram.Client.add_handler`. This method is used to actually register the handler and let +Pyrogram know it needs to be taken into consideration when new updates arrive and the internal dispatching phase begins. .. code-block:: python app.add_handler(my_handler) -Last one, the :meth:`run() ` method. What this does is simply call -:meth:`start() ` and a special method :meth:`idle() ` that keeps your main -scripts alive until you press ``CTRL+C``; the client will be automatically stopped after that. +Last one, the :meth:`~pyrogram.Client.run` method. What this does is simply call :meth:`~pyrogram.Client.start` and a +special method :meth:`~pyrogram.Client.idle` that keeps your main scripts alive until you press ``CTRL+C``; the client +will be automatically stopped after that. .. code-block:: python @@ -82,7 +80,7 @@ Using Decorators ---------------- All of the above will become quite verbose, especially in case you have lots of handlers to register. A much nicer way -to do so is by decorating your callback function with the :meth:`on_message() ` decorator. +to do so is by decorating your callback function with the :meth:`~pyrogram.Client.on_message` decorator. .. code-block:: python @@ -108,5 +106,3 @@ to do so is by decorating your callback function with the :meth:`on_message()

` and facade +:doc:`types <../api/types>`, exists to provide a much easier interface to the undocumented and often confusing Telegram +API. In this section, you'll be shown the alternative way of communicating with Telegram using Pyrogram: the main "raw" Telegram API with its functions and types. @@ -11,7 +12,7 @@ Telegram Raw API ---------------- If you can't find a high-level method for your needs or if you want complete, low-level access to the whole -Telegram API, you have to use the raw :mod:`functions ` and :mod:`types `. +Telegram API, you have to use the raw :mod:`~pyrogram.api.functions` and :mod:`~pyrogram.api.types`. As already hinted, raw functions and types can be really confusing, mainly because people don't realize soon enough they accept *only* the right types and that all required parameters must be filled in. This section will therefore explain @@ -21,24 +22,25 @@ some pitfalls to take into consideration when working with the raw API. Every available high-level methods in Pyrogram is built on top of these raw functions. - Nothing stops you from using the raw functions only, but they are rather complex and `plenty of them`_ are already - re-implemented by providing a much simpler and cleaner interface which is very similar to the Bot API (yet much more - powerful). + Nothing stops you from using the raw functions only, but they are rather complex and + :doc:`plenty of them <../api/methods>` are already re-implemented by providing a much simpler and cleaner interface + which is very similar to the Bot API (yet much more powerful). If you think a raw function should be wrapped and added as a high-level method, feel free to ask in our Community_! Invoking Functions ^^^^^^^^^^^^^^^^^^ -Unlike the methods_ found in Pyrogram's API, which can be called in the usual simple way, functions to be invoked from -the raw Telegram API have a different way of usage and are more complex. +Unlike the :doc:`methods <../api/methods>` found in Pyrogram's API, which can be called in the usual simple way, +functions to be invoked from the raw Telegram API have a different way of usage and are more complex. -First of all, both `raw functions`_ and `raw types`_ live in their respective packages (and sub-packages): -``pyrogram.api.functions``, ``pyrogram.api.types``. They all exist as Python classes, meaning you need to create an -instance of each every time you need them and fill them in with the correct values using named arguments. +First of all, both :doc:`raw functions <../telegram/functions/index>` and :doc:`raw types <../telegram/types/index>` live in their +respective packages (and sub-packages): ``pyrogram.api.functions``, ``pyrogram.api.types``. They all exist as Python +classes, meaning you need to create an instance of each every time you need them and fill them in with the correct +values using named arguments. -Next, to actually invoke the raw function you have to use the :meth:`send() ` method provided by -the Client class and pass the function object you created. +Next, to actually invoke the raw function you have to use the :meth:`~pyrogram.Client.send` method provided by the +Client class and pass the function object you created. Here's some examples: @@ -101,12 +103,12 @@ sending messages with IDs only thanks to cached access hashes. There are three different InputPeer types, one for each kind of Telegram entity. Whenever an InputPeer is needed you must pass one of these: - - :obj:`InputPeerUser <../telegram/types/InputPeerUser>` - Users - - :obj:`InputPeerChat <../telegram/types/InputPeerChat>` - Basic Chats - - :obj:`InputPeerChannel <../telegram/types/InputPeerChannel>` - Either Channels or Supergroups + - :class:`~pyrogram.api.types.InputPeerUser` - Users + - :class:`~pyrogram.api.types.InputPeerChat` - Basic Chats + - :class:`~pyrogram.api.types.InputPeerChannel` - Either Channels or Supergroups But you don't necessarily have to manually instantiate each object because, luckily for you, Pyrogram already provides -:meth:`resolve_peer() ` as a convenience utility method that returns the correct InputPeer +:meth:`~pyrogram.Client.resolve_peer` as a convenience utility method that returns the correct InputPeer by accepting a peer ID only. Another thing to take into consideration about chat IDs is the way they are represented: they are all integers and @@ -125,9 +127,4 @@ For example, given the ID *123456789*, here's how Pyrogram can tell entities apa So, every time you take a raw ID, make sure to translate it into the correct ID when you want to use it with an high-level method. -.. _methods: ../api/methods -.. _types: ../api/types -.. _plenty of them: ../api/methods -.. _raw functions: ../telegram/functions -.. _raw types: ../telegram/types .. _Community: https://t.me/Pyrogram \ No newline at end of file diff --git a/docs/source/topics/auto-auth.rst b/docs/source/topics/auto-auth.rst index b5f3a94a..abeaf1fb 100644 --- a/docs/source/topics/auto-auth.rst +++ b/docs/source/topics/auto-auth.rst @@ -3,7 +3,7 @@ Auto Authorization Manually writing phone number, phone code and password on the terminal every time you want to login can be tedious. Pyrogram is able to automate both **Log In** and **Sign Up** processes, all you need to do is pass the relevant -parameters when creating a new :class:`Client `. +parameters when creating a new :class:`~pyrogram.Client`. .. note:: If you omit any of the optional parameter required for the authorization, Pyrogram will ask you to manually write it. For instance, if you don't want to set a ``last_name`` when creating a new account you diff --git a/docs/source/topics/bots-interaction.rst b/docs/source/topics/bots-interaction.rst index de7925a2..ad993050 100644 --- a/docs/source/topics/bots-interaction.rst +++ b/docs/source/topics/bots-interaction.rst @@ -7,8 +7,7 @@ Inline Bots ----------- - If a bot accepts inline queries, you can call it by using - :meth:`get_inline_bot_results() ` to get the list of its inline results - for a query: + :meth:`~pyrogram.Client.get_inline_bot_results` to get the list of its inline results for a query: .. code-block:: python @@ -24,7 +23,7 @@ Inline Bots results list. - After you retrieved the bot results, you can use - :meth:`send_inline_bot_result() ` to send a chosen result to any chat: + :meth:`~pyrogram.Client.send_inline_bot_result` to send a chosen result to any chat: .. code-block:: python diff --git a/docs/source/topics/filters.rst b/docs/source/topics/filters.rst index cb2e2a4c..7ff02ffc 100644 --- a/docs/source/topics/filters.rst +++ b/docs/source/topics/filters.rst @@ -4,7 +4,7 @@ Using Filters So far we've seen how to register a callback function that executes every time a specific update comes from the server, but there's much more than that to come. -Here we'll discuss about :class:`Filters `. Filters enable a fine-grain control over what kind of +Here we'll discuss about :class:`~pyrogram.Filters`. Filters enable a fine-grain control over what kind of updates are allowed or not to be passed in your callback functions, based on their inner details. Single Filters @@ -12,7 +12,7 @@ Single Filters Let's start right away with a simple example: -- This example will show you how to **only** handle messages containing an :obj:`Audio ` object and +- This example will show you how to **only** handle messages containing an :class:`~pyrogram.Audio` object and ignore any other message. Filters are passed as the first argument of the decorator: .. code-block:: python @@ -69,7 +69,7 @@ Here are some examples: Advanced Filters ---------------- -Some filters, like :meth:`command() ` or :meth:`regex() ` +Some filters, like :meth:`~pyrogram.Filters.command` or :meth:`~pyrogram.Filters.regex` can also accept arguments: - Message is either a */start* or */help* **command**. @@ -109,18 +109,18 @@ More handlers using different filters can also live together. Custom Filters -------------- -Pyrogram already provides lots of built-in :class:`Filters ` to work with, but in case you can't find +Pyrogram already provides lots of built-in :class:`~pyrogram.Filters` to work with, but in case you can't find a specific one for your needs or want to build a custom filter by yourself (to be used in a different kind of handler, -for example) you can use :meth:`Filters.create() `. +for example) you can use :meth:`~pyrogram.Filters.create`. .. note:: - At the moment, the built-in filters are intended to be used with the :obj:`MessageHandler ` - only. + + At the moment, the built-in filters are intended to be used with the :class:`~pyrogram.MessageHandler` only. An example to demonstrate how custom filters work is to show how to create and use one for the -:obj:`CallbackQueryHandler `. Note that callback queries updates are only received by -bots; create and `authorize your bot <../start/Setup.html#bot-authorization>`_, then send a message with an inline -keyboard to yourself. This allows you to test your filter by pressing the inline button: +:class:`~pyrogram.CallbackQueryHandler`. Note that callback queries updates are only received by bots; create and +:doc:`authorize your bot <../start/auth>`, then send a message with an inline keyboard to yourself. This allows you to +test your filter by pressing the inline button: .. code-block:: python @@ -137,7 +137,7 @@ keyboard to yourself. This allows you to test your filter by pressing the inline Basic Filters ^^^^^^^^^^^^^ -For this basic filter we will be using only the first two parameters of :meth:`Filters.create() `. +For this basic filter we will be using only the first two parameters of :meth:`~pyrogram.Filters.create`. The code below creates a simple filter for hardcoded, static callback data. This filter will only allow callback queries containing "Pyrogram" as data, that is, the function *func* you pass returns True in case the callback query data @@ -175,7 +175,7 @@ Filters with Arguments ^^^^^^^^^^^^^^^^^^^^^^ A much cooler filter would be one that accepts "Pyrogram" or any other data as argument at usage time. -A dynamic filter like this will make use of the third parameter of :meth:`Filters.create() `. +A dynamic filter like this will make use of the third parameter of :meth:`~pyrogram.Filters.create`. This is how a dynamic custom filter looks like: diff --git a/docs/source/topics/more-on-updates.rst b/docs/source/topics/more-on-updates.rst index cb319ee1..c3737b38 100644 --- a/docs/source/topics/more-on-updates.rst +++ b/docs/source/topics/more-on-updates.rst @@ -1,7 +1,8 @@ More on Updates =============== -Here we'll show some advanced usages when working with `update handlers`_ and `filters`_. +Here we'll show some advanced usages when working with :doc:`update handlers <../start/updates>` and +:doc:`filters `. Handler Groups -------------- @@ -44,7 +45,7 @@ Or, if you want ``just_text`` to be fired *before* ``text_or_sticker`` (note ``- def just_text(client, message): print("Just Text") -With :meth:`add_handler() ` (without decorators) the same can be achieved with: +With :meth:`~pyrogram.Client.add_handler` (without decorators) the same can be achieved with: .. code-block:: python @@ -217,6 +218,3 @@ The output of both (equivalent) examples will be: 0 1 2 - -.. _`update handlers`: ../start/updates -.. _`filters`: filters \ No newline at end of file diff --git a/docs/source/topics/serialize.rst b/docs/source/topics/serialize.rst index 32208199..a238f8dc 100644 --- a/docs/source/topics/serialize.rst +++ b/docs/source/topics/serialize.rst @@ -9,7 +9,8 @@ For Humans - str(obj) --------------------- If you want a nicely formatted, human readable JSON representation of any object in the API -- namely, any object from -`Pyrogram types`_, `raw functions`_ and `raw types`_ -- you can use use ``str(obj)``. +:doc:`Pyrogram types <../api/types>`, :doc:`raw functions <../telegram/functions/index>` and +:doc:`raw types <../telegram/types/index>` -- you can use use ``str(obj)``. .. code-block:: python @@ -25,10 +26,6 @@ If you want a nicely formatted, human readable JSON representation of any object When using ``print()`` you don't actually need to use ``str()`` on the object because it is called automatically, we have done that above just to show you how to explicitly convert a Pyrogram object to JSON. -.. _Pyrogram types: ../api/types -.. _raw functions: ../telegram/functions -.. _raw types: ../telegram/types - For Machines - repr(obj) ------------------------ diff --git a/docs/source/topics/session-settings.rst b/docs/source/topics/session-settings.rst index 91e3f050..dd777bda 100644 --- a/docs/source/topics/session-settings.rst +++ b/docs/source/topics/session-settings.rst @@ -5,7 +5,7 @@ As you may probably know, Telegram allows users (and bots) having more than one in the system at the same time. Briefly explaining, sessions are simply new logins in your account. They can be reviewed in the settings of an official -app (or by invoking `GetAuthorizations <../telegram/functions/account/GetAuthorizations.html>`_ with Pyrogram). They +app (or by invoking :class:`~pyrogram.api.functions.account.GetAuthorizations` with Pyrogram). They store some useful information such as the client who's using them and from which country and IP address. .. figure:: https://i.imgur.com/YaqtMLO.png diff --git a/docs/source/topics/smart-plugins.rst b/docs/source/topics/smart-plugins.rst index 9f1592d1..8e59b971 100644 --- a/docs/source/topics/smart-plugins.rst +++ b/docs/source/topics/smart-plugins.rst @@ -65,8 +65,8 @@ after importing your modules, like this: app.run() This is already nice and doesn't add *too much* boilerplate code, but things can get boring still; you have to -manually ``import``, manually :meth:`add_handler() ` and manually instantiate each -:obj:`MessageHandler ` object because **you can't use those cool decorators** for your +manually ``import``, manually :meth:`~pyrogram.Client.add_handler` and manually instantiate each +:class:`~pyrogram.MessageHandler` object because **you can't use those cool decorators** for your functions. So, what if you could? Smart Plugins solve this issue by taking care of handlers registration automatically. Using Smart Plugins @@ -80,7 +80,7 @@ Setting up your Pyrogram project to accommodate Smart Plugins is pretty straight .. note:: - This is the same example application `as shown above <#introduction>`_, written using the Smart Plugin system. + This is the same example application as shown above, written using the Smart Plugin system. .. code-block:: text :emphasize-lines: 2, 3 @@ -156,7 +156,7 @@ found inside each module will be, instead, loaded in the order they are defined, .. note:: Remember: there can be at most one handler, within a group, dealing with a specific update. Plugins with overlapping - filters included a second time will not work. Learn more at `More on Updates `_. + filters included a second time will not work. Learn more at :doc:`More on Updates `. This default loading behaviour is usually enough, but sometimes you want to have more control on what to include (or exclude) and in which exact order to load plugins. The way to do this is to make use of ``include`` and ``exclude`` @@ -288,9 +288,8 @@ also organized in subfolders: Load/Unload Plugins at Runtime ------------------------------ -In the `previous section <#specifying-the-plugins-to-include>`_ we've explained how to specify which plugins to load and -which to ignore before your Client starts. Here we'll show, instead, how to unload and load again a previously -registered plugin at runtime. +In the previous section we've explained how to specify which plugins to load and which to ignore before your Client +starts. Here we'll show, instead, how to unload and load again a previously registered plugin at runtime. Each function decorated with the usual ``on_message`` decorator (or any other decorator that deals with Telegram updates ) will be modified in such a way that, when you reference them later on, they will be actually pointing to a tuple of @@ -318,7 +317,7 @@ Unloading ^^^^^^^^^ In order to unload a plugin, or any other handler, all you need to do is obtain a reference to it by importing the -relevant module and call :meth:`remove_handler() ` Client's method with your function +relevant module and call :meth:`~pyrogram.Client.remove_handler` Client's method with your function name preceded by the star ``*`` operator as argument. Example: - ``main.py`` @@ -343,7 +342,7 @@ Loading ^^^^^^^ Similarly to the unloading process, in order to load again a previously unloaded plugin you do the same, but this time -using :meth:`add_handler() ` instead. Example: +using :meth:`~pyrogram.Client.add_handler` instead. Example: - ``main.py`` diff --git a/docs/source/topics/text-formatting.rst b/docs/source/topics/text-formatting.rst index 8f2292d0..bc74d562 100644 --- a/docs/source/topics/text-formatting.rst +++ b/docs/source/topics/text-formatting.rst @@ -12,7 +12,7 @@ Markdown Style -------------- To use this mode, pass "markdown" in the *parse_mode* field when using -:obj:`send_message() `. Use the following syntax in your message: +:meth:`~pyrogram.Client.send_message`. Use the following syntax in your message: .. code-block:: text @@ -34,7 +34,7 @@ To use this mode, pass "markdown" in the *parse_mode* field when using HTML Style ---------- -To use this mode, pass "html" in the *parse_mode* field when using :obj:`send_message() `. +To use this mode, pass "html" in the *parse_mode* field when using :meth:`~pyrogram.Client.send_message`. The following tags are currently supported: .. code-block:: text diff --git a/pyrogram/client/methods/chats/set_chat_photo.py b/pyrogram/client/methods/chats/set_chat_photo.py index 4a2f6cf1..79cceb7e 100644 --- a/pyrogram/client/methods/chats/set_chat_photo.py +++ b/pyrogram/client/methods/chats/set_chat_photo.py @@ -51,7 +51,7 @@ class SetChatPhoto(BaseClient): Raises: RPCError: In case of a Telegram RPC error. - ``ValueError`` if a chat_id belongs to user. + ValueError: if a chat_id belongs to user. """ peer = self.resolve_peer(chat_id) diff --git a/pyrogram/client/types/messages_and_media/message.py b/pyrogram/client/types/messages_and_media/message.py index 09cb9ca3..f8d161c2 100644 --- a/pyrogram/client/types/messages_and_media/message.py +++ b/pyrogram/client/types/messages_and_media/message.py @@ -110,7 +110,7 @@ class Message(PyrogramType, Update): new_chat_photo, delete_chat_photo, group_chat_created, supergroup_chat_created, channel_chat_created, migrate_to_chat_id, migrate_from_chat_id, pinned_message. - media (``bool`` *optional*): + media (``bool``, *optional*): The message is a media message. A media message has one and only one of these fields set: audio, document, photo, sticker, video, animation, voice, video_note, contact, location, venue.