Clarify who can use methods in the documentation

setup.py

@@ -63,11 +63,10 @@ def generate(which):
     layer = find_layer(TLOBJECT_IN_TL)
     errors = list(parse_errors(ERRORS_IN))
     methods = list(parse_methods(METHODS_IN, {e.str_code: e for e in errors}))
-    invalid_bot_methods = {m.name for m in methods if m.usability == 'user'}
 
     tlobjects = list(itertools.chain(
-        parse_tl(TLOBJECT_IN_CORE_TL, layer, invalid_bot_methods),
+        parse_tl(TLOBJECT_IN_CORE_TL, layer, methods),
-        parse_tl(TLOBJECT_IN_TL, layer, invalid_bot_methods)))
+        parse_tl(TLOBJECT_IN_TL, layer, methods)))
 
     if not which:
         which.extend(('tl', 'errors'))

telethon_generator/generators/docs.py

@@ -7,7 +7,7 @@ import shutil
 from collections import defaultdict
 
 from ..docswriter import DocsWriter
-from ..parsers import TLObject
+from ..parsers import TLObject, Usability
 from ..utils import snake_to_camel_case
 
 CORE_TYPES = {
@@ -138,8 +138,8 @@ def _generate_index(folder, original_paths, root,
 
         docs.write_title(_get_relative_path(folder, root, folder=True).title())
         if bots_index:
-            docs.write_text('These are the methods that you can use as a bot. '
+            docs.write_text('These are the methods that you may be able to '
-                            'Click <a href="{}">here</a> to '
+                            'use as a bot. Click <a href="{}">here</a> to '
                             'view them all.'.format(INDEX))
         else:
             docs.write_text('Click <a href="{}">here</a> to view the methods '
@@ -289,11 +289,21 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
             docs.write_title(tlobject.class_name)
 
             if tlobject.is_function:
-                docs.write_text('Bots <strong>can{}</strong> use this method. '
+                if tlobject.usability == Usability.USER:
-                                '<a href="#examples">See code examples.</a>'
+                    start = '<strong>Only users</strong> can'
-                                .format("" if tlobject.bot_usable else "'t"))
+                elif tlobject.usability == Usability.BOT:
-                if tlobject.is_function and tlobject.bot_usable:
                     bot_docs_paths.append(filename)
+                    start = '<strong>Only bots</strong> can'
+                elif tlobject.usability == Usability.BOTH:
+                    bot_docs_paths.append(filename)
+                    start = '<strong>Both users and bots</strong> can'
+                else:
+                    bot_docs_paths.append(filename)
+                    start = \
+                        'Both users and bots <strong>may</strong> be able to'
+
+                docs.write_text('{} use this method. <a href="#examples">'
+                                'See code examples.</a>'.format(start))
 
             # Write the code definition for this TLObject
             docs.write_code(tlobject)

telethon_generator/parsers/__init__.py

@@ -1,3 +1,3 @@
 from .errors import Error, parse_errors
-from .methods import MethodInfo, parse_methods
+from .methods import MethodInfo, Usability, parse_methods
 from .tlobject import TLObject, parse_tl, find_layer

telethon_generator/parsers/tlobject/parser.py

@@ -3,9 +3,10 @@ import re
 
 from .tlarg import TLArg
 from .tlobject import TLObject
+from ..methods import Usability
 
 
-def _from_line(line, is_function, layer):
+def _from_line(line, is_function, method_info, layer):
     match = re.match(
         r'^([\w.]+)'                     # 'name'
         r'(?:#([0-9a-fA-F]+))?'          # '#optionalcode'
@@ -26,27 +27,33 @@ def _from_line(line, is_function, layer):
         r'}?',
         line
     )
+
+    name = match.group(1)
+    if name in method_info:
+        usability = method_info[name].usability
+    else:
+        usability = Usability.UNKNOWN
+
     return TLObject(
-        fullname=match.group(1),
+        fullname=name,
         object_id=match.group(2),
         result=match.group(3),
         is_function=is_function,
         layer=layer,
+        usability=usability,
         args=[TLArg(name, arg_type, brace != '')
               for brace, name, arg_type in args_match]
     )
 
 
-def parse_tl(file_path, layer, invalid_bot_methods=None):
+def parse_tl(file_path, layer, methods=None):
     """
     This method yields TLObjects from a given .tl file.
 
     Note that the file is parsed completely before the function yields
     because references to other objects may appear later in the file.
     """
-    if invalid_bot_methods is None:
+    method_info = {m.name: m for m in (methods or [])}
-        invalid_bot_methods = set()
-
     obj_all = []
     obj_by_name = {}
     obj_by_type = collections.defaultdict(list)
@@ -68,8 +75,9 @@ def parse_tl(file_path, layer, invalid_bot_methods=None):
                 continue
 
             try:
-                result = _from_line(line, is_function, layer=layer)
+                result = _from_line(
-                result.bot_usable = result.fullname not in invalid_bot_methods
+                    line, is_function, method_info, layer=layer)
+
                 obj_all.append(result)
                 if not result.is_function:
                     obj_by_name[result.fullname] = result

telethon_generator/parsers/tlobject/tlobject.py

@@ -14,7 +14,8 @@ for i in range(77, 83):
 
 
 class TLObject:
-    def __init__(self, fullname, object_id, args, result, is_function, layer):
+    def __init__(self, fullname, object_id, args, result,
+                 is_function, usability, layer):
         """
         Initializes a new TLObject, given its properties.
 
@@ -24,6 +25,7 @@ class TLObject:
         :param args: The arguments, if any, of the TL object
         :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 layer: The layer this TLObject belongs to.
         """
         # The name can or not have a namespace
@@ -36,7 +38,7 @@ class TLObject:
         self.args = args
         self.result = result
         self.is_function = is_function
-        self.bot_usable = None
+        self.usability = usability
         self.id = None
         if object_id is None:
             self.id = self.infer_id()