Document raw methods with friendly variants

telethon_generator/parsers/methods.py

@@ -1,5 +1,6 @@
 import csv
 import enum
+import warnings
 
 
 class Usability(enum.Enum):
@@ -10,9 +11,10 @@ class Usability(enum.Enum):
 
 
 class MethodInfo:
-    def __init__(self, name, usability, errors):
+    def __init__(self, name, usability, errors, friendly):
         self.name = name
         self.errors = errors
+        self.friendly = friendly
         try:
             self.usability = {
                 'unknown': Usability.UNKNOWN,
@@ -25,11 +27,19 @@ class MethodInfo:
                              'unknown, not {}'.format(usability)) from None
 
 
-def parse_methods(csv_file, errors_dict):
+def parse_methods(csv_file, friendly_csv_file, errors_dict):
     """
     Parses the input CSV file with columns (method, usability, errors)
     and yields `MethodInfo` instances as a result.
     """
+    raw_to_friendly = {}
+    with friendly_csv_file.open(newline='') as f:
+        f = csv.reader(f)
+        next(f, None)  # header
+        for ns, friendly, raw_list in f:
+            for raw in raw_list.split():
+                raw_to_friendly[raw] = (ns, friendly)
+
     with csv_file.open(newline='') as f:
         f = csv.reader(f)
         next(f, None)  # header
@@ -40,4 +50,9 @@ def parse_methods(csv_file, errors_dict):
                 raise ValueError('Method {} references unknown errors {}'
                                  .format(method, errors)) from None
 
-            yield MethodInfo(method, usability, errors)
+            friendly = raw_to_friendly.pop(method, None)
+            yield MethodInfo(method, usability, errors, friendly)
+
+    if raw_to_friendly:
+        warnings.warn('note: unknown raw methods in friendly mapping: {}'
+                      .format(', '.join(raw_to_friendly)))

telethon_generator/parsers/tlobject/parser.py

@@ -58,10 +58,13 @@ def _from_line(line, is_function, method_info, layer):
     )
 
     name = match.group(1)
-    if name in method_info:
-        usability = method_info[name].usability
+    method_info = method_info.get(name)
+    if method_info:
+        usability = method_info.usability
+        friendly = method_info.friendly
     else:
         usability = Usability.UNKNOWN
+        friendly = None
 
     return TLObject(
         fullname=name,
@@ -70,6 +73,7 @@ def _from_line(line, is_function, method_info, layer):
         is_function=is_function,
         layer=layer,
         usability=usability,
+        friendly=friendly,
         args=[TLArg(name, arg_type, brace != '')
               for brace, name, arg_type in args_match]
     )

telethon_generator/parsers/tlobject/tlobject.py

@@ -14,7 +14,7 @@ WHITELISTED_MISMATCHING_IDS = {
 
 class TLObject:
     def __init__(self, fullname, object_id, args, result,
-                 is_function, usability, layer):
+                 is_function, usability, friendly, layer):
         """
         Initializes a new TLObject, given its properties.
 
@@ -25,6 +25,7 @@ class TLObject:
         :param result: The result type of the TL object
         :param is_function: Is the object a function or a type?
         :param usability: The usability for this method.
+        :param friendly: A tuple (namespace, friendly method name) if known.
         :param layer: The layer this TLObject belongs to.
         """
         # The name can or not have a namespace
@@ -38,6 +39,7 @@ class TLObject:
         self.result = result
         self.is_function = is_function
         self.usability = usability
+        self.friendly = friendly
         self.id = None
         if object_id is None:
             self.id = self.infer_id()