Improve documentation of various types (#230)

Closes #229

Co-authored-by: gemini-code-assist[bot] <176961590@users.noreply.github.com>
Co-authored-by: KurimuzonAkuma <KurimuzonAkuma@users.noreply.github.com>

Author: 3 people

.github/workflows/build-docs.yml

@@ -11,13 +11,13 @@ jobs:
     name: build-doc
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 1
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
-        python-version: '3.10'
+        python-version: "3.10"
 
     - name: Install dependencies AND Build Documentation
       env:

docs/source/api/errors/index.rst

@@ -39,14 +39,14 @@ follow the usual *PascalCase* convention.
 .. admonition :: RPC Errors
     :class: tip
     
-    There isn't any official list of all possible RPC errors, so the list of known errors is provided on a best-effort basis. When new methods are available, the list may be lacking since we simply don't know what errors can raise from them. Pyrogram creates an `unknown_errors.txt` file in the root directory from where the `Client` is run.
+    There isn't any official list of all possible RPC errors, so the list of known errors is provided on a best-effort basis. When new methods are available, the list may be lacking since we simply don't know what errors can raise from them. Pyrogram creates an ``unknown_errors.txt`` file in the root directory from where the `Client` is run.
 
 .. admonition :: PLEASE DO NOT DO THIS
 
     .. tip::
 
-        If you do not want this file to be created, set the `PYROGRAM_DONOT_LOG_UNKNOWN_ERRORS` environment variable before running the Pyrogram `Client`.
+        If you want the file to be created in a different location, set the ``PYROGRAM_LOG_UNKNOWN_ERRORS_FILENAME`` environment variable to an absolute file path of your choice.
 
     .. tip::
 
-        If you want the file to be created in a different location, set the `PYROGRAM_LOG_UNKNOWN_ERRORS_FILENAME` to a file path of your choice.
+        If you do not want this file to be created, set the ``PYROGRAM_DONOT_LOG_UNKNOWN_ERRORS`` environment variable before running the Pyrogram `Client`.

docs/source/conf.py

@@ -16,6 +16,7 @@
 #  You should have received a copy of the GNU Lesser General Public License
 #  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
 
+import inspect
 import os
 import subprocess
 import sys
@@ -32,8 +33,11 @@
     "HEAD",
 ]).decode("UTF-8").strip()
 
+project_url = "https://github.com/TelegramPlayGround/Pyrogram"
+# --- SETUP: Define your repository root ---
+REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
 project = "pyrotgfork"
-copyright = "2017-present, Dan"
+copyright = "2017-2024, Dan"
 author = "Dan"
 version = f"{__version__} Layer {layer}"
 
@@ -45,6 +49,7 @@
     # "sphinx.ext.viewcode",
     "sphinx_copybutton",
     # "sphinx.ext.coverage",
+    "sphinx.ext.linkcode",
     "sphinx_llms_txt",
 ]
 
@@ -158,3 +163,57 @@
     "genindex",
     "modindex",
 ]
+
+def linkcode_resolve(domain, info):
+    """
+    Determine the URL corresponding to Python object
+    """
+    if domain != "py":
+        return None
+    if not info["module"]:
+        return None
+
+    # Attempt to find the exact line numbers using the inspect module
+    module = sys.modules.get(info["module"])
+    if module is None:
+        return None
+
+    # Traverse the object tree to find the specific class/function
+    obj = module
+    for part in info["fullname"].split("."):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError:
+            return None
+
+    # --- Unwrap decorators to bypass sync.py wrappers ---
+    try:
+        obj = inspect.unwrap(obj)
+    except:
+        pass # If it can't be unwrapped, just proceed with the original object
+
+    try:
+        # 1. Get the absolute path to the file locally
+        filepath = inspect.getsourcefile(obj)
+        if filepath is None:
+            return None
+        
+        # 2. Calculate the path relative to the root of your git repository
+        rel_filepath = os.path.relpath(filepath, start=REPO_ROOT)
+        
+        # Ensure forward slashes for the GitHub URL (important for Windows users)
+        rel_filepath = rel_filepath.replace(os.sep, "/")
+        
+        # 3. Get the line numbers
+        source, lineno = inspect.getsourcelines(obj)
+        
+        # Return the perfectly mapped GitHub URL
+        # Returns a link like: https://github.com/user/repo/blob/main/module.py#L10-L25
+        return f"{project_url}/blob/{commit_id}/{rel_filepath}#L{lineno}-L{lineno + len(source) - 1}"
+        
+    except (TypeError, OSError, ValueError):
+        # Fails safely if source cannot be inspected or path calculation fails
+        return None
+
+    # Fallback to just linking to the file if line numbers can't be resolved
+    return f"{project_url}/blob/{commit_id}/{filename}.py"

docs/source/releases/changes-in-this-fork.rst

@@ -1,7 +1,4 @@
 
-Changes in this Fork
-=====================
-
 .. admonition :: A Word of Warning
     :class: tip
     
@@ -17,15 +14,15 @@ it can take advantage of new goodies!
 
 If you found any issue or have any suggestions, feel free to make `an issue <https://github.com/TelegramPlayGround/pyrogram/issues>`__ on github.
 
-Breaking Changes in this Fork
-==============================
+.. admonition :: Breaking Changes in this Fork
+    :class: tip
 
-- In :meth:`~pyrogram.Client.copy_message`, ``ValueError`` is raised instead of ``logging`` it.
-- In :meth:`~pyrogram.Client.download_media`, if the message is a :obj:`~pyrogram.types.PaidMediaInfo` with more than one ``paid_media`` **and** ``idx`` was not specified, then a list of paths or binary file-like objects is returned.
-- PR `#115 <https://github.com/TelegramPlayGround/pyrogram/pull/115>`_ This `change <https://github.com/pyrogram/pyrogram/pull/966#issuecomment-1108858881>`_ breaks some usages with offset-naive and offset-aware datetimes.
-- PR from upstream: `#1411 <https://github.com/pyrogram/pyrogram/pull/1411>`_ without attribution.
-- If you relied on internal types like ``import pyrogram.file_id`` OR ``import pyrogram.utils``, Then read this full document to know where `else <https://t.me/PyrogramChat/42497>`_ your code will break.
-- :obj:`~pyrogram.types.InlineKeyboardButton` only accepts keyword arguments instead of positional arguments.
+    - In :meth:`~pyrogram.Client.copy_message`, ``ValueError`` is raised instead of ``logging`` it.
+    - In :meth:`~pyrogram.Client.download_media`, if the message is a :obj:`~pyrogram.types.PaidMediaInfo` with more than one ``paid_media`` **and** ``idx`` was not specified, then a list of paths or binary file-like objects is returned.
+    - PR `#115 <https://github.com/TelegramPlayGround/pyrogram/pull/115>`_ This `change <https://github.com/pyrogram/pyrogram/pull/966#issuecomment-1108858881>`_ breaks some usages with offset-naive and offset-aware datetimes.
+    - PR from upstream: `#1411 <https://github.com/pyrogram/pyrogram/pull/1411>`_ without attribution.
+    - If you relied on internal types like ``import pyrogram.file_id`` OR ``import pyrogram.utils``, Then read this full document to know where `else <https://t.me/PyrogramChat/42497>`_ your code will break.
+    - :obj:`~pyrogram.types.InlineKeyboardButton` only accepts keyword arguments instead of positional arguments.
 
 
 Changes in this Fork
@@ -55,6 +52,7 @@ Changes in this Fork
 | Scheme layer used: 223 |
 +------------------------+
 
+- Added the method :meth:`~pyrogram.Client.send_message_draft`, allowing bots to stream partial messages to a user while being generated. (contributed by @sudo-py-dev in `#231 <https://github.com/TelegramPlayground/pyrogram/pull/231>`__).
 - Added the :obj:`~pyrogram.types.MessageEntity` type :obj:`~pyrogram.enums.MessageEntityType.DATE_TIME`, allowing to show a formatted date and time to the user.
 - Added the fields ``chat_owner_left``, ``chat_owner_changed``, ``chat_has_protected_content_toggled`` and ``chat_has_protected_content_disable_requested`` to the class :obj:`~pyrogram.types.Message`.
 - Added the field ``can_edit_tag`` to the class :obj:`~pyrogram.types.ChatPermissions`.

docs/source/start/errors.rst

@@ -80,11 +80,11 @@ whole category of errors and be sure to also handle these unknown errors.
 .. admonition :: RPC Errors
     :class: tip
     
-    There isn't any official list of all possible RPC errors, so the list of known errors is provided on a best-effort basis. When new methods are available, the list may be lacking since we simply don't know what errors can raise from them. Pyrogram creates an `unknown_errors.txt` file in the root directory from where the `Client` is run.
+    There isn't any official list of all possible RPC errors, so the list of known errors is provided on a best-effort basis. When new methods are available, the list may be lacking since we simply don't know what errors can raise from them. Pyrogram creates an ``unknown_errors.txt`` file in the root directory from where the `Client` is run.
 
 .. admonition :: `... <https://t.me/pyrogramchat/607757>`__
 
-    If you want the file to be created in a different location, set the ``PYROGRAM_LOG_UNKNOWN_ERRORS_FILENAME`` to an absolute file path of your choice.
+    If you want the file to be created in a different location, set the ``PYROGRAM_LOG_UNKNOWN_ERRORS_FILENAME`` environment variable to an absolute file path of your choice.
 
 
 Errors with Values

docs/source/topics/message-identifiers.rst

@@ -40,11 +40,9 @@ Let's look at a concrete example.
 Every account and channel has just been created.
 This means everyone has a message counter of one.
 
-First, User-A will sent a welcome message to both User-B and User-C::
+.. First, User-A will sent a welcome message to both User-B and User-C::
 
-..
     User-A → User-B: Hey, welcome!
-
     User-A → User-C: ¡Bienvenido!
 
 * For User-A, "Hey, welcome!" will have the message identifier 1. The message with "¡Bienvenido!" will have an ID of 2.
@@ -57,11 +55,10 @@ First, User-A will sent a welcome message to both User-B and User-C::
    "Hey, welcome!", 1, 1, "", "", ""
    "¡Bienvenido!", 2, "", 1, "", ""
 
-Next, User-B and User-C will respond to User-A::
 
-..
-    User-B → User-A: Thanks!
+.. Next, User-B and User-C will respond to User-A::
 
+    User-B → User-A: Thanks!
     User-C → User-A: Gracias :)
 
 .. csv-table:: Message identifiers
@@ -74,9 +71,8 @@ Next, User-B and User-C will respond to User-A::
 
 Notice how for each message, the counter goes up by one, and they are independent.
 
-Let's see what happens when User-B sends a message to Group-S::
+.. Let's see what happens when User-B sends a message to Group-S::
 
-..
     User-B → Group-S: Nice group
 
 .. csv-table:: Message identifiers
@@ -92,9 +88,7 @@ While the message was sent to a different chat, the group itself doesn't have a
 The message identifiers are still unique for each account.
 The chat where the message was sent can be completely ignored.
 
-Megagroups behave differently::
-
-..
+.. Megagroups behave differently::
     User-C → Group-M: Buen grupo
 
 .. csv-table:: Message identifiers

docs/source/topics/text-formatting.rst

@@ -160,13 +160,12 @@ To strictly use this mode, pass :obj:`~pyrogram.enums.ParseMode.MARKDOWN` to the
     >Block quotation continued
     >The last line of the block quotation
 
-    **>
-    The expandable block quotation started right after the previous block quotation
-    It is separated from the previous block quotation by expandable syntax 
-    Expandable block quotation continued
-    Hidden by default part of the expandable block quotation started
-    Expandable block quotation continued
-    The last line of the expandable block quotation with the expandability mark<**
+    **>The expandable block quotation started right after the previous block quotation
+    >It is separated from the previous block quotation by expandable syntax 
+    >Expandable block quotation continued
+    >Hidden by default part of the expandable block quotation started
+    >Expandable block quotation continued
+    >The last line of the expandable block quotation with the expandability mark||
 
     `inline fixed-width code`
 
@@ -215,13 +214,12 @@ To strictly use this mode, pass :obj:`~pyrogram.enums.ParseMode.MARKDOWN` to the
             ">Block quotation continued\n"
             ">The last line of the block quotation"
 
-            "**>\n"
-            "The expandable block quotation started right after the previous block quotation\n"
-            "It is separated from the previous block quotation by expandable syntax\n"
-            "Expandable block quotation continued\n"
-            "Hidden by default part of the expandable block quotation started\n"
-            "Expandable block quotation continued\n"
-            "The last line of the expandable block quotation with the expandability mark<**"
+            "**>The expandable block quotation started right after the previous block quotation\n"
+            ">It is separated from the previous block quotation by expandable syntax\n"
+            ">Expandable block quotation continued\n"
+            ">Hidden by default part of the expandable block quotation started\n"
+            ">Expandable block quotation continued\n"
+            ">The last line of the expandable block quotation with the expandability mark||"
 
         ),
         parse_mode=ParseMode.MARKDOWN

pyrogram/file_id.py

@@ -307,25 +307,25 @@ class FileIdCached:
     _encoded: typing.Optional[str] = None
 
     def __init__(
-            self, *,
-            major: int = MAJOR,
-            minor: int = MINOR,
-            file_type: FileType,
-            dc_id: int,
-            file_reference: bytes = b"",
-            url: str = None,
-            media_id: int = None,
-            access_hash: int = None,
-            volume_id: int = None,
-            thumbnail_source: ThumbnailSource = None,
-            thumbnail_file_type: FileType = None,
-            thumbnail_size: str = "",
-            secret: int = None,
-            local_id: int = None,
-            chat_id: int = None,
-            chat_access_hash: int = None,
-            sticker_set_id: int = None,
-            sticker_set_access_hash: int = None
+        self, *,
+        major: int = MAJOR,
+        minor: int = MINOR,
+        file_type: FileType,
+        dc_id: int,
+        file_reference: bytes = b"",
+        url: str = None,
+        media_id: int = None,
+        access_hash: int = None,
+        volume_id: int = None,
+        thumbnail_source: ThumbnailSource = None,
+        thumbnail_file_type: FileType = None,
+        thumbnail_size: str = "",
+        secret: int = None,
+        local_id: int = None,
+        chat_id: int = None,
+        chat_access_hash: int = None,
+        sticker_set_id: int = None,
+        sticker_set_access_hash: int = None
     ):
         self.major = major
         self.minor = minor
@@ -416,7 +416,7 @@ def encode(self, *, major: int = None, minor: int = None):
         return self._encoded
 
     def __str__(self):
-        return str({k: v for k, v in self.__dict__.items() if v is not None})
+        return str({k: v for k, v in self.__dict__.items() if k != "_encoded" and v is not None})
 
 
 class FileUniqueType(IntEnum):
@@ -477,12 +477,12 @@ class FileUniqueIdCached:
     _encoded: typing.Optional[str] = None
 
     def __init__(
-            self, *,
-            file_unique_type: FileUniqueType,
-            url: str = None,
-            media_id: int = None,
-            volume_id: int = None,
-            local_id: int = None
+        self, *,
+        file_unique_type: FileUniqueType,
+        url: str = None,
+        media_id: int = None,
+        volume_id: int = None,
+        local_id: int = None
     ):
         self.file_unique_type = file_unique_type
         self.url = url
@@ -513,4 +513,4 @@ def encode(self):
         return self._encoded
 
     def __str__(self):
-        return str({k: v for k, v in self.__dict__.items() if v is not None})
+        return str({k: v for k, v in self.__dict__.items() if k != "_encoded" and v is not None})

pyrogram/methods/advanced/invoke.py

@@ -68,7 +68,8 @@ async def invoke(
             ``RawType``: The raw type response generated by the query.
 
         Raises:
-            RPCError: In case of a Telegram RPC error.
+            :obj:`~pyrogram.errors.RPCError`: In case of a Telegram RPC error.
+
         """
         if not self.is_connected:
             raise ConnectionError("Client has not been started yet")

pyrogram/methods/advanced/resolve_peer.py

@@ -53,6 +53,7 @@ async def resolve_peer(
 
         Raises:
             KeyError: In case the peer doesn't exist in the internal database.
+
         """
         if not self.is_connected:
             raise ConnectionError("Client has not been started yet")