Update Documentation

TelegramPlayGround · Feb 10, 2024 · 477f0a6 · 477f0a6
1 parent 7a2acaf
commit 477f0a6
Show file tree

Hide file tree

Showing 17 changed files with 86 additions and 42 deletions.
diff --git a/docs/source/api/storage/Storage.rst b/docs/source/api/storage/Storage.rst
@@ -0,0 +1,5 @@
+Storage
+=========
+
+.. autoclass:: pyrogram.storage.Storage()
+    :members:
diff --git a/docs/source/topics/storage-engines.rst → docs/source/api/storage/index.rst b/docs/source/topics/storage-engines.rst → docs/source/api/storage/index.rst
@@ -1,3 +1,6 @@
+Pyrogram Storage Engines
+===============
+
 Storage Engines
 ===============
 
@@ -84,3 +87,9 @@ login using the same session; the storage used will still be in-memory:
 
 Session strings are useful when you want to run authorized Pyrogram clients on platforms where their ephemeral
 filesystems makes it harder for a file-based storage engine to properly work as intended.
+
+
+Details
+-------
+
+.. autoclass:: pyrogram.storage.Storage()
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -121,6 +121,7 @@ Meta
     api/client
     api/methods/index
     api/types/index
+    api/storage/index
     api/bound-methods/index
     api/enums/index
     api/handlers
@@ -140,7 +141,6 @@ Meta
     topics/text-formatting
     topics/synchronous
     topics/smart-plugins
-    topics/storage-engines
     topics/serializing
     topics/proxy
     topics/scheduling

diff --git a/docs/source/releases/changes-in-this-fork.rst b/docs/source/releases/changes-in-this-fork.rst
@@ -25,7 +25,7 @@ it can take advantage of new goodies!
 - Renamed ``force_document`` to ``disable_content_type_detection`` in :obj:`~pyrogram.Client.send_document` and :obj:`~pyrogram.types.Message.reply_document`.
 - Added missing attributes ``added_to_attachment_menu``, ``is_attachment_menu_adding_available``, ``can_join_groups``, ``can_read_all_group_messages``, ``supports_inline_queries``, ``can_be_contacted_with_premium`` to the :obj:`~pyrogram.types.User`.
 - Migrate project to ``pyproject.toml`` from ``setup.py``.
-- PRs from upstream: `1305 <https://github.com/pyrogram/pyrogram/pull/1305>`_, `1288 <https://github.com/pyrogram/pyrogram/pull/1288>`_, `1262 <https://github.com/pyrogram/pyrogram/pull/1262>`_, `1253 <https://github.com/pyrogram/pyrogram/pull/1253>`_, `1143 <https://github.com/pyrogram/pyrogram/pull/1143>`_.
+- PRs from upstream: `1366 <https://github.com/pyrogram/pyrogram/pull/1366>`_, `1305 <https://github.com/pyrogram/pyrogram/pull/1305>`_, `1288 <https://github.com/pyrogram/pyrogram/pull/1288>`_, `1262 <https://github.com/pyrogram/pyrogram/pull/1262>`_, `1253 <https://github.com/pyrogram/pyrogram/pull/1253>`_, `1234 <https://github.com/pyrogram/pyrogram/pull/1234>`_, `1210 <https://github.com/pyrogram/pyrogram/pull/1210>`_, `1201 <https://github.com/pyrogram/pyrogram/pull/1201>`_, `1197 <https://github.com/pyrogram/pyrogram/pull/1197>`_, `1143 <https://github.com/pyrogram/pyrogram/pull/1143>`_, `1059 <https://github.com/pyrogram/pyrogram/pull/1059>`_.
 - Bug fix for :obj:`~pyrogram.Client.send_audio` and :obj:`~pyrogram.Client.send_voice`. (Thanks to `... <https://t.me/c/1220993104/1360174>`_).
 - Add `waveform` parameter to :obj:`~pyrogram.Client.send_voice`.
 - Added `view_once` parameter to :obj:`~pyrogram.Client.send_photo`, :obj:`~pyrogram.Client.send_video`, :obj:`~pyrogram.Client.send_video_note`, :obj:`~pyrogram.Client.send_voice`.
@@ -40,22 +40,22 @@ it can take advantage of new goodies!
 - Added support for voice, photo, video, animation messages that could be played once.
 - Added ``_raw`` to the :obj:`~pyrogram.types.Chat` object.
 - Added the field ``via_chat_folder_invite_link`` to the class :obj:`~pyrogram.types.ChatMemberUpdated`.
-- **BOTS ONLY**: Added updates about a reaction change on a message with non-anonymous reactions, represented by the class :obj:`~pyrogram.types.MessageReactionUpdated` and the field ``message_reaction`` in the class Update.
-- **BOTS ONLY**: Added updates about reaction changes on a message with anonymous reactions, represented by the class :obj:`~pyrogram.types.MessageReactionCountUpdated` and the field ``message_reaction_count`` in the class Update.
+- **BOTS ONLY**: Added updates about a reaction change on a message with non-anonymous reactions, represented by the class :obj:`~pyrogram.handlers.MessageReactionUpdatedHandler` and the field ``message_reaction`` in the class Update.
+- **BOTS ONLY**: Added updates about reaction changes on a message with anonymous reactions, represented by the class :obj:`~pyrogram.handlers.MessageReactionCountUpdatedHandler` and the field ``message_reaction_count`` in the class Update.
 - Replaced the parameter ``disable_web_page_preview`` with :obj:`~pyrogram.types.LinkPreviewOptions` in the methods sendMessage and editMessageText.
 - Replaced the field ``disable_web_page_preview`` with :obj:`~pyrogram.types.LinkPreviewOptions` in the class InputTextMessageContent.
 - Added missing parameters to :obj:`~pyrogram.Client.forward_messages`.
-- Added the class :obj:`~pyrogram.types.ReplyParameters` and replaced parameters ``reply_to_message_id`` in the methods :obj:`~pyrogram.Client.copy_message`, :obj:`~pyrogram.Client.send_message`, :obj:`~pyrogram.Client.send_photo`, :obj:`~pyrogram.Client.send_video`, :obj:`~pyrogram.Client.send_animation`, :obj:`~pyrogram.Client.send_audio`, :obj:`~pyrogram.Client.send_document`, :obj:`~pyrogram.Client.send_sticker`, :obj:`~pyrogram.Client.send_video_note`, :obj:`~pyrogram.Client.send_voice`, :obj:`~pyrogram.Client.send_location`, :obj:`~pyrogram.Client.send_venue`, :obj:`~pyrogram.Client.send_contact`, :obj:`~pyrogram.Client.send_poll`, :obj:`~pyrogram.Client.send_dice`, :obj:`~pyrogram.Client.send_invoice`, :obj:`~pyrogram.Client.send_game`, :obj:`~pyrogram.Client.send_media_group`, :obj:`~pyrogram.Client.copy_media_group`, :obj:`~pyrogram.Client.send_inline_bot_result`, :obj:`~pyrogram.Client.send_cached_media`,, and the corresponding reply_* methods with the field ``reply_parameters`` of type :obj:`~pyrogram.types.ReplyParameters`.
+- Added the class :obj:`~pyrogram.types.ReplyParameters` and replaced parameters ``reply_to_message_id`` in the methods :obj:`~pyrogram.Client.copy_message`, :obj:`~pyrogram.Client.send_message`, :obj:`~pyrogram.Client.send_photo`, :obj:`~pyrogram.Client.send_video`, :obj:`~pyrogram.Client.send_animation`, :obj:`~pyrogram.Client.send_audio`, :obj:`~pyrogram.Client.send_document`, :obj:`~pyrogram.Client.send_sticker`, :obj:`~pyrogram.Client.send_video_note`, :obj:`~pyrogram.Client.send_voice`, :obj:`~pyrogram.Client.send_location`, :obj:`~pyrogram.Client.send_venue`, :obj:`~pyrogram.Client.send_contact`, :obj:`~pyrogram.Client.send_poll`, :obj:`~pyrogram.Client.send_dice`, :obj:`~pyrogram.Client.send_game`, :obj:`~pyrogram.Client.send_media_group`, :obj:`~pyrogram.Client.copy_media_group`, :obj:`~pyrogram.Client.send_inline_bot_result`, :obj:`~pyrogram.Client.send_cached_media`, and the corresponding reply_* methods with the field ``reply_parameters`` of type :obj:`~pyrogram.types.ReplyParameters`.
 - Bug fixes for sending ``ttl_seconds`` and ``has_spoiler``.
 
 +------------------------+
 | Scheme layer used: 169 |
 +------------------------+
 
-- Changed condition in ``join_chat`` and ``get_chat``.
-- Added ``nosound_video`` parameter to ``InputMediaVideo``.
-- Added ``has_spoiler`` parameter to ``copy_message``.
-- Improved ``get_chat_history``: add ``min_id`` and ``max_id`` params.
+- Changed condition in :meth:`~pyrogram.Client.join_chat` and :meth:`~pyrogram.Client.get_chat`.
+- Added ``nosound_video`` parameter to :obj:`~pyrogram.types.InputMediaVideo`.
+- Added ``has_spoiler`` parameter to :meth:`~pyrogram.Client.copy_message`.
+- Improved :meth:`~pyrogram.Client.get_chat_history`: add ``min_id`` and ``max_id`` params.
 - Improved ``send_reaction`` for Telegram Premium Users.
 - `Prevent connection to dc every time in get_file <https://github.com/TelegramPlayGround/pyrogram/commit/f2581fd7ab84ada7685645a6f80475fbea5e743a>`_
 - Added ``_raw`` to the :obj:`~pyrogram.types.Chat`, :obj:`~pyrogram.types.Dialog`, and :obj:`~pyrogram.types.User` objects.
@@ -80,7 +80,7 @@ it can take advantage of new goodies!
 | Scheme layer used: 161 |
 +------------------------+
 
-- Added ``my_stories_from`` to the :obj:`~pyrogram.Client.block_user` and :obj:`~pyrogram.Client.unblock_user` methods.
+- Added ``my_stories_from`` to the :meth:`~pyrogram.Client.block_user` and :meth:`~pyrogram.Client.unblock_user` methods.
 
 +------------------------+
 | Scheme layer used: 160 |

diff --git a/docs/source/start/examples/bot_keyboards.rst b/docs/source/start/examples/bot_keyboards.rst
@@ -6,8 +6,10 @@ This example will show you how to send normal and inline keyboards (as bot).
 You must log-in as a regular bot in order to send keyboards (use the token from @BotFather).
 Any attempt in sending keyboards with a user account will be simply ignored by the server.
 
-send_message() is used as example, but a keyboard can be sent with any other send_* methods,
-like send_audio(), send_document(), send_location(), etc...
+:meth:`~pyrogram.Client.send_message` is used as example, but a keyboard can be sent with any other send_* methods,
+like :meth:`~pyrogram.Client.send_audio`, :meth:`~pyrogram.Client.send_document`, :meth:`~pyrogram.Client.send_location`, etc...
+
+.. include:: /_includes/usable-by/bots.rst
 
 .. code-block:: python
 
@@ -22,7 +24,7 @@ like send_audio(), send_document(), send_location(), etc...
     async def main():
         async with app:
             await app.send_message(
-                chat_id="me",  # Edit this
+                chat_id="@PyrogramChat",  # Edit this
                 text="This is a ReplyKeyboardMarkup example",
                 reply_markup=ReplyKeyboardMarkup(
                     [
@@ -36,7 +38,7 @@ like send_audio(), send_document(), send_location(), etc...
             )
 
             await app.send_message(
-                chat_id="me",  # Edit this
+                chat_id="@PyrogramChat",  # Edit this
                 text="This is a InlineKeyboardMarkup example",
                 reply_markup=InlineKeyboardMarkup(
                     [
@@ -65,4 +67,4 @@ like send_audio(), send_document(), send_location(), etc...
             )
 
 
-    app.run(main())
+    app.run(main())
diff --git a/docs/source/start/examples/callback_queries.rst b/docs/source/start/examples/callback_queries.rst
@@ -2,7 +2,9 @@ callback_queries
 ================
 
 This example shows how to handle callback queries, i.e.: queries coming from inline button presses.
-It uses the @on_callback_query decorator to register a CallbackQueryHandler.
+It uses the :meth:`~pyrogram.Client.on_callback_query` decorator to register a :obj:`~pyrogram.handlers.CallbackQueryHandler`.
+
+.. include:: /_includes/usable-by/bots.rst
 
 .. code-block:: python
 

diff --git a/docs/source/start/examples/echo_bot.rst b/docs/source/start/examples/echo_bot.rst
@@ -3,9 +3,11 @@ echo_bot
 
 This simple echo bot replies to every private text message.
 
-It uses the ``@on_message`` decorator to register a ``MessageHandler`` and applies two filters on it:
+It uses the :meth:`~pyrogram.Client.on_message` decorator to register a :obj:`~pyrogram.handlers.MessageHandler` and applies two filters on it:
 ``filters.text`` and ``filters.private`` to make sure it will reply to private text messages only.
 
+.. include:: /_includes/usable-by/users-bots.rst
+
 .. code-block:: python
 
     from pyrogram import Client, filters
@@ -18,4 +20,4 @@ It uses the ``@on_message`` decorator to register a ``MessageHandler`` and appli
         await message.reply(message.text)
 
 
-    app.run()  # Automatically start() and idle()
+    app.run()  # Automatically start() and idle()
diff --git a/docs/source/start/examples/get_chat_history.rst b/docs/source/start/examples/get_chat_history.rst
@@ -3,6 +3,8 @@ get_history
 
 This example shows how to get the full message history of a chat, starting from the latest message.
 
+.. include:: /_includes/usable-by/users.rst
+
 .. code-block:: python
 
     from pyrogram import Client

diff --git a/docs/source/start/examples/get_chat_members.rst b/docs/source/start/examples/get_chat_members.rst
@@ -3,6 +3,8 @@ get_chat_members
 
 This example shows how to get all the members of a chat.
 
+.. include:: /_includes/usable-by/users-bots.rst
+
 .. code-block:: python
 
     from pyrogram import Client

diff --git a/docs/source/start/examples/get_dialogs.rst b/docs/source/start/examples/get_dialogs.rst
@@ -3,6 +3,8 @@ get_dialogs
 
 This example shows how to get the full dialogs list (as user).
 
+.. include:: /_includes/usable-by/users.rst
+
 .. code-block:: python
 
     from pyrogram import Client

diff --git a/docs/source/start/examples/hello_world.rst b/docs/source/start/examples/hello_world.rst
@@ -3,6 +3,8 @@ hello_world
 
 This example demonstrates a basic API usage
 
+.. include:: /_includes/usable-by/users.rst
+
 .. code-block:: python
 
     from pyrogram import Client

diff --git a/docs/source/start/examples/inline_queries.rst b/docs/source/start/examples/inline_queries.rst
@@ -4,7 +4,9 @@ inline_queries
 This example shows how to handle inline queries.
 
 Two results are generated when users invoke the bot inline mode, e.g.: @pyrogrambot hi.
-It uses the @on_inline_query decorator to register an InlineQueryHandler.
+It uses the :meth:`~pyrogram.Client.on_inline_query` decorator to register an :obj:`~pyrogram.handlers.InlineQueryHandler`.
+
+.. include:: /_includes/usable-by/bots.rst
 
 .. code-block:: python
 

diff --git a/docs/source/start/examples/raw_updates.rst b/docs/source/start/examples/raw_updates.rst
@@ -3,6 +3,8 @@ raw_updates
 
 This example shows how to handle raw updates.
 
+.. include:: /_includes/usable-by/users-bots.rst
+
 .. code-block:: python
 
     from pyrogram import Client

diff --git a/docs/source/start/examples/use_inline_bots.rst b/docs/source/start/examples/use_inline_bots.rst
@@ -3,6 +3,8 @@ use_inline_bots
 
 This example shows how to query an inline bot (as user).
 
+.. include:: /_includes/usable-by/users.rst
+
 .. code-block:: python
 
     from pyrogram import Client

diff --git a/docs/source/start/examples/welcome_bot.rst b/docs/source/start/examples/welcome_bot.rst
@@ -4,6 +4,8 @@ welcome_bot
 This example uses the ``emoji`` module to easily add emoji in your text messages and ``filters``
 to make it only work for specific messages in a specific chat.
 
+.. include:: /_includes/usable-by/bots.rst
+
 .. code-block:: python
 
     from pyrogram import Client, emoji, filters
@@ -17,12 +19,16 @@ to make it only work for specific messages in a specific chat.
 
 
     # Filter in only new_chat_members updates generated in TARGET chat
-    @app.on_message(filters.chat(TARGET) & filters.new_chat_members)
-    async def welcome(client, message):
+    @app.on_chat_member_updated(filters.chat(TARGET) & filters.new_chat_members)
+    async def welcome(client, chat_member_updated):
         # Build the new members list (with mentions) by using their first_name
-        new_members = [u.mention for u in message.new_chat_members]
+        new_member = chat_member_updated.new_chat_member.user.mention
         # Build the welcome message by using an emoji and the list we built above
-        text = MESSAGE.format(emoji.SPARKLES, ", ".join(new_members))
-
-
-    app.run()  # Automatically start() and idle()
+        text = MESSAGE.format(emoji.SPARKLES, new_member)
+        # send a message to the chat
+        await client.send_message(
+            chat_id=chat_member_updated.chat.id,
+            text=text
+        )
+
+    app.run()  # Automatically start() and idle()
diff --git a/docs/source/topics/text-formatting.rst b/docs/source/topics/text-formatting.rst
@@ -28,17 +28,20 @@ list of the basic styles currently supported by Pyrogram.
 
 - **bold**
 - *italic*
-- :strike:`strike`
 - :underline:`underline`
-- spoiler
-- `text URL <https://pyrogrammod.github.io>`_
-- `user text mention <tg://user?id=123456789>`_
+- :strike:`strike`
+- blockquote
 - ``inline fixed-width code``
 - .. code-block:: text
 
     pre-formatted
       fixed-width
         code block
+- spoiler
+- `text URL <https://docs.pyrogram.org>`_
+- `user text mention <tg://user?id=123456789>`_
+
+
 
 Markdown Style
 --------------
@@ -56,11 +59,7 @@ To strictly use this mode, pass :obj:`~pyrogram.enums.ParseMode.MARKDOWN` to the
 
     ~~strike~~
 
-    ||spoiler||
-
-    [text URL](https://pyrogrammod.github.io/)
-
-    [text user mention](tg://user?id=123456789)
+    > blockquote
 
     `inline fixed-width code`
 
@@ -70,7 +69,12 @@ To strictly use this mode, pass :obj:`~pyrogram.enums.ParseMode.MARKDOWN` to the
         code block
     ```
 
-    > Quoted text
+    ||spoiler||
+
+    [text URL](https://docs.pyrogram.org/)
+
+    [text user mention](tg://user?id=123456789)
+
 
 **Example**:
 
@@ -86,7 +90,7 @@ To strictly use this mode, pass :obj:`~pyrogram.enums.ParseMode.MARKDOWN` to the
             "--underline--, "
             "~~strike~~, "
             "||spoiler||, "
-            "[URL](https://pyrogrammod.github.io), "
+            "[URL](https://docs.pyrogram.org), "
             "`code`, "
             "```"
             "for i in range(10):\n"
@@ -114,15 +118,15 @@ To strictly use this mode, pass :obj:`~pyrogram.enums.HTML` to the *parse_mode*
 
     <spoiler>spoiler</spoiler>
 
-    <a href="https://pyrogrammod.github.io/">text URL</a>
+    <a href="https://docs.pyrogram.org">text URL</a>
 
     <a href="tg://user?id=123456789">inline mention</a>
 
     <code>inline fixed-width code</code>
 
     <emoji id="12345678901234567890">🔥</emoji>
 
-    <pre>
+    <pre language="py">
     pre-formatted
       fixed-width
         code block
@@ -142,9 +146,9 @@ To strictly use this mode, pass :obj:`~pyrogram.enums.HTML` to the *parse_mode*
             "<u>underline</u>, "
             "<s>strike</s>, "
             "<spoiler>spoiler</spoiler>, "
-            "<a href=\"https://pyrogrammod.github.io/\">URL</a>, "
+            "<a href=\"https://docs.pyrogram.org\">URL</a>, "
             "<code>code</code>\n\n"
-            "<pre>"
+            "<pre language='py'>"
             "for i in range(10):\n"
             "    print(i)"
             "</pre>"

diff --git a/pyrogram/types/messages_and_media/message.py b/pyrogram/types/messages_and_media/message.py
@@ -3438,7 +3438,7 @@ async def copy(
                 disable_notification=disable_notification,
                 protect_content=protect_content,
                 reply_parameters=reply_parameters,
-                reply_markup=self.reply_markup if reply_markup is object else reply_markup
+                reply_markup=self.reply_markup if reply_markup is object else reply_markup,
                 schedule_date=schedule_date
             )
         elif self.media: