Merge branch 'new-api' into new-api-docs

# Conflicts: # compiler/api/compiler.py # docs/source/pyrogram/index.rst
2025-08-31 14:25:55 +00:00 · 2018-04-11 03:29:47 +02:00
parent 144a0103e4 398858acc1
commit 5e5289596b
27 changed files with 1672 additions and 147 deletions
--- a/compiler/api/compiler.py
+++ b/compiler/api/compiler.py
@@ -25,7 +25,7 @@ DESTINATION = "pyrogram/api"
 NOTICE_PATH = "NOTICE"
 SECTION_RE = re.compile(r"---(\w+)---")
 LAYER_RE = re.compile(r"//\sLAYER\s(\d+)")
-COMBINATOR_RE = re.compile(r"^([\w.]+)#([0-9a-f]+)\s(?:.*)=\s([\w<>.]+);$", re.MULTILINE)
+COMBINATOR_RE = re.compile(r"^([\w.]+)#([0-9a-f]+)\s(?:.*)=\s([\w<>.]+);(?: // Docs: (.+))?$", re.MULTILINE)
 ARGS_RE = re.compile("[^{](\w+):([\w?!.<>]+)")
 FLAGS_RE = re.compile(r"flags\.(\d+)\?")
 FLAGS_RE_2 = re.compile(r"flags\.(\d+)\?([\w<>.]+)")
@@ -38,7 +38,7 @@ types_to_functions = {}
 constructors_to_functions = {}


-def get_docstring_arg_type(t: str, is_list: bool = False):
+def get_docstring_arg_type(t: str, is_list: bool = False, is_pyrogram_type: bool = False):
    if t in core_types:
        if t == "long":
            return "``int`` ``64-bit``"
@@ -60,11 +60,17 @@ def get_docstring_arg_type(t: str, is_list: bool = False):
    elif t.startswith("Vector"):
        return "List of " + get_docstring_arg_type(t.split("<")[1][:-1], is_list=True)
    else:
+        if is_pyrogram_type:
+            t = "pyrogram." + t
+
        t = types_to_constructors.get(t, [t])
        n = len(t) - 1

        t = (("e" if is_list else "E") + "ither " if n else "") + ", ".join(
-            ":obj:`{0} <pyrogram.api.types.{0}>`".format(i)
+            ":obj:`{1} <pyrogram.api.types.{0}{1}>`".format(
+                "pyrogram." if is_pyrogram_type else "",
+                i.lstrip("pyrogram.")
+            )
            for i in t
        )

@@ -94,7 +100,15 @@ def get_references(t: str):


 class Combinator:
-    def __init__(self, section: str, namespace: str, name: str, id: str, args: list, has_flags: bool, return_type: str):
+    def __init__(self,
+                 section: str,
+                 namespace: str,
+                 name: str,
+                 id: str,
+                 args: list,
+                 has_flags: bool,
+                 return_type: str,
+                 docs: str):
        self.section = section
        self.namespace = namespace
        self.name = name
@@ -102,6 +116,7 @@ class Combinator:
        self.args = args
        self.has_flags = has_flags
        self.return_type = return_type
+        self.docs = docs


 def snek(s: str):
@@ -131,11 +146,15 @@ def start():

    with open("{}/source/auth_key.tl".format(HOME), encoding="utf-8") as auth, \
            open("{}/source/sys_msgs.tl".format(HOME), encoding="utf-8") as system, \
-            open("{}/source/main_api.tl".format(HOME), encoding="utf-8") as api:
-        schema = (auth.read() + system.read() + api.read()).splitlines()
+            open("{}/source/main_api.tl".format(HOME), encoding="utf-8") as api, \
+            open("{}/source/pyrogram.tl".format(HOME), encoding="utf-8") as pyrogram:
+        schema = (auth.read() + system.read() + api.read() + pyrogram.read()).splitlines()

-    with open("{}/template/class.txt".format(HOME), encoding="utf-8") as f:
-        template = f.read()
+    with open("{}/template/mtproto.txt".format(HOME), encoding="utf-8") as f:
+        mtproto_template = f.read()
+
+    with open("{}/template/pyrogram.txt".format(HOME), encoding="utf-8") as f:
+        pyrogram_template = f.read()

    with open(NOTICE_PATH, encoding="utf-8") as f:
        notice = []
@@ -165,9 +184,9 @@ def start():

        combinator = COMBINATOR_RE.match(line)
        if combinator:
-            name, id, return_type = combinator.groups()
+            name, id, return_type, docs = combinator.groups()
            namespace, name = name.split(".") if "." in name else ("", name)
-            args = ARGS_RE.findall(line)
+            args = ARGS_RE.findall(line.split(" //")[0])

            # Pingu!
            has_flags = not not FLAGS_RE_3.findall(line)
@@ -195,7 +214,8 @@ def start():
                    ".".join(
                        return_type.split(".")[:-1]
                        + [capit(return_type.split(".")[-1])]
-                    )
+                    ),
+                    docs
                )
            )

@@ -254,6 +274,7 @@ def start():
        ) if c.args else "pass"

        docstring_args = []
+        docs = c.docs.split("|")[1:] if c.docs else None

        for i, arg in enumerate(sorted_args):
            arg_name, arg_type = arg
@@ -261,13 +282,23 @@ def start():
            flag_number = is_optional.group(1) if is_optional else -1
            arg_type = arg_type.split("?")[-1]

-            docstring_args.append(
-                "{}{}: {}".format(
-                    arg_name,
-                    " (optional)".format(flag_number) if is_optional else "",
-                    get_docstring_arg_type(arg_type)
+            if docs:
+                docstring_args.append(
+                    "{} ({}{}):\n            {}\n".format(
+                        arg_name,
+                        get_docstring_arg_type(arg_type, is_pyrogram_type=True),
+                        ", optional" if "Optional" in docs[i] else "",
+                        re.sub("Optional\. ", "", docs[i].split("§")[1].rstrip(".") + ".")
+                    )
+                )
+            else:
+                docstring_args.append(
+                    "{}: {}{}".format(
+                        arg_name,
+                        "``optional`` ".format(flag_number) if is_optional else "",
+                        get_docstring_arg_type(arg_type, is_pyrogram_type=c.namespace == "pyrogram")
+                    )
                )
-            )

        if docstring_args:
            docstring_args = "Args:\n        " + "\n        ".join(docstring_args)
@@ -370,22 +401,38 @@ def start():
                    read_types += "\n        "
                    read_types += "{} = Object.read(b)\n        ".format(arg_name)

+        if c.docs:
+            description = c.docs.split("|")[0].split("§")[1]
+            docstring_args = description + "\n\n    " + docstring_args
+
        with open("{}/{}.py".format(path, snek(c.name)), "w", encoding="utf-8") as f:
-            f.write(
-                template.format(
-                    notice=notice,
-                    class_name=capit(c.name),
-                    docstring_args=docstring_args,
-                    object_id=c.id,
-                    arguments=arguments,
-                    fields=fields,
-                    read_flags=read_flags,
-                    read_types=read_types,
-                    write_flags=write_flags,
-                    write_types=write_types,
-                    return_arguments=", ".join([i[0] for i in sorted_args])
+            if c.docs:
+                f.write(
+                    pyrogram_template.format(
+                        notice=notice,
+                        class_name=capit(c.name),
+                        docstring_args=docstring_args,
+                        object_id=c.id,
+                        arguments=arguments,
+                        fields=fields
+                    )
+                )
+            else:
+                f.write(
+                    mtproto_template.format(
+                        notice=notice,
+                        class_name=capit(c.name),
+                        docstring_args=docstring_args,
+                        object_id=c.id,
+                        arguments=arguments,
+                        fields=fields,
+                        read_flags=read_flags,
+                        read_types=read_types,
+                        write_flags=write_flags,
+                        write_types=write_types,
+                        return_arguments=", ".join([i[0] for i in sorted_args])
+                    )
                )
-            )

    with open("{}/all.py".format(DESTINATION), "w", encoding="utf-8") as f:
        f.write(notice + "\n\n")
--- a/compiler/api/source/pyrogram.tl
+++ b/compiler/api/source/pyrogram.tl
@@ -0,0 +1,22 @@
+// Pyrogram
+
+---types---
+
+pyrogram.update#b0700000 flags:# update_id:int message:flags.0?Message edited_message:flags.1?Message channel_post:flags.2?Message edited_channel_post:flags.3?Message inline_query:flags.4?InlineQuery chosen_inline_result:flags.5?ChosenInlineResult callback_query:flags.6?CallbackQuery shipping_query:flags.7?ShippingQuery pre_checkout_query:flags.8?PreCheckoutQuery = pyrogram.Update;
+pyrogram.user#b0700001 flags:# id:int is_bot:Bool first_name:string last_name:flags.0?string username:flags.1?string language_code:flags.2?string phone_number:flags.3?string = pyrogram.User;
+pyrogram.chat#b0700002 flags:# id:int type:string title:flags.0?string username:flags.1?string first_name:flags.2?string last_name:flags.3?string all_members_are_administrators:flags.4?Bool photo:flags.5?ChatPhoto description:flags.6?string invite_link:flags.7?string pinned_message:flags.8?Message sticker_set_name:flags.9?string can_set_sticker_set:flags.10?Bool = pyrogram.Chat;
+pyrogram.message#b0700003 flags:# message_id:int from_user:flags.0?User date:int chat:Chat forward_from:flags.1?User forward_from_chat:flags.2?Chat forward_from_message_id:flags.3?int forward_signature:flags.4?string forward_date:flags.5?int reply_to_message:flags.6?Message edit_date:flags.7?int media_group_id:flags.8?string author_signature:flags.9?string text:flags.10?string entities:flags.11?Vector<MessageEntity> caption_entities:flags.12?Vector<MessageEntity> audio:flags.13?Audio document:flags.14?Document game:flags.15?Game photo:flags.16?Vector<PhotoSize> sticker:flags.17?Sticker video:flags.18?Video voice:flags.19?Voice video_note:flags.20?VideoNote caption:flags.21?string contact:flags.22?Contact location:flags.23?Location venue:flags.24?Venue new_chat_members:flags.25?Vector<User> left_chat_member:flags.26?User new_chat_title:flags.27?string new_chat_photo:flags.28?Vector<PhotoSize> delete_chat_photo:flags.29?true group_chat_created:flags.30?true supergroup_chat_created:flags.31?true channel_chat_created:flags.32?true migrate_to_chat_id:flags.33?int migrate_from_chat_id:flags.34?int pinned_message:flags.35?Message invoice:flags.36?Invoice successful_payment:flags.37?SuccessfulPayment connected_website:flags.38?string views:flags.39?int via_bot:flags.40?User = pyrogram.Message;
+pyrogram.messageEntity#b0700004 flags:# type:string offset:int length:int url:flags.0?string user:flags.1?User = pyrogram.MessageEntity;
+pyrogram.photoSize#b0700005 flags:# file_id:string width:int height:int file_size:flags.0?int = pyrogram.PhotoSize;
+pyrogram.audio#b0700006 flags:# file_id:string duration:int performer:flags.0?string title:flags.1?string mime_type:flags.2?string file_size:flags.3?int = pyrogram.Audio;
+pyrogram.document#b0700007 flags:# file_id:string thumb:flags.0?PhotoSize file_name:flags.1?string mime_type:flags.2?string file_size:flags.3?int = pyrogram.Document;
+pyrogram.video#b0700008 flags:# file_id:string width:int height:int duration:int thumb:flags.0?PhotoSize mime_type:flags.1?string file_size:flags.2?int = pyrogram.Video;
+pyrogram.voice#b0700009 flags:# file_id:string duration:int mime_type:flags.0?string file_size:flags.1?int = pyrogram.Voice;
+pyrogram.videoNote#b0700010 flags:# file_id:string length:int duration:int thumb:flags.0?PhotoSize file_size:flags.1?int = pyrogram.VideoNote;
+pyrogram.contact#b0700011 flags:# phone_number:string first_name:string last_name:flags.0?string user_id:flags.1?int = pyrogram.Contact;
+pyrogram.location#b0700012 longitude:double latitude:double = pyrogram.Location;
+pyrogram.venue#b0700013 flags:# location:Location title:string address:string foursquare_id:flags.0?string = pyrogram.Venue;
+pyrogram.userProfilePhotos#b0700014 total_count:int photos:Vector<Vector<PhotoSize>> = pyrogram.UserProfilePhotos;
+pyrogram.chatPhoto#b0700015 small_file_id:string big_file_id:string = pyrogram.ChatPhoto;
+pyrogram.chatMember#b0700016 flags:# user:User status:string until_date:flags.0?int can_be_edited:flags.1?Bool can_change_info:flags.2?Bool can_post_messages:flags.3?Bool can_edit_messages:flags.4?Bool can_delete_messages:flags.5?Bool can_invite_users:flags.6?Bool can_restrict_members:flags.7?Bool can_pin_messages:flags.8?Bool can_promote_members:flags.9?Bool can_send_messages:flags.10?Bool can_send_media_messages:flags.11?Bool can_send_other_messages:flags.12?Bool can_add_web_page_previews:flags.13?Bool = pyrogram.ChatMember;
+pyrogram.sticker#b0700017 flags:# file_id:string width:int height:int thumb:flags.0?PhotoSize emoji:flags.1?string set_name:flags.2?string mask_position:flags.3?MaskPosition file_size:flags.4?int = pyrogram.Sticker;
--- a/compiler/api/template/mtproto.txt
+++ b/compiler/api/template/mtproto.txt
@@ -6,8 +6,7 @@ from pyrogram.api.core import *


 class {class_name}(Object):
-    """
-    {docstring_args}
+    """{docstring_args}
    """
    ID = {object_id}

--- a/compiler/api/template/pyrogram.txt
+++ b/compiler/api/template/pyrogram.txt
@@ -0,0 +1,11 @@
+{notice}
+
+from pyrogram.api.core import Object
+
+class {class_name}(Object):
+    """{docstring_args}
+    """
+    ID = {object_id}
+
+    def __init__(self{arguments}):
+        {fields}