mirror of
https://github.com/LonamiWebs/Telethon.git
synced 2024-11-22 09:26:37 +03:00
Document raw methods with friendly variants
This commit is contained in:
parent
4ebf825c43
commit
e5485f3d54
5
setup.py
5
setup.py
|
@ -46,6 +46,9 @@ ERRORS_OUT = LIBRARY_DIR / 'errors/rpcerrorlist.py'
|
|||
|
||||
METHODS_IN = GENERATOR_DIR / 'data/methods.csv'
|
||||
|
||||
# Which raw API methods are covered by *friendly* methods in the client?
|
||||
FRIENDLY_IN = GENERATOR_DIR / 'data/friendly.csv'
|
||||
|
||||
TLOBJECT_IN_TLS = [Path(x) for x in GENERATOR_DIR.glob('data/*.tl')]
|
||||
TLOBJECT_OUT = LIBRARY_DIR / 'tl'
|
||||
IMPORT_DEPTH = 2
|
||||
|
@ -63,7 +66,7 @@ def generate(which, action='gen'):
|
|||
|
||||
layer = next(filter(None, map(find_layer, TLOBJECT_IN_TLS)))
|
||||
errors = list(parse_errors(ERRORS_IN))
|
||||
methods = list(parse_methods(METHODS_IN, {e.str_code: e for e in errors}))
|
||||
methods = list(parse_methods(METHODS_IN, FRIENDLY_IN, {e.str_code: e for e in errors}))
|
||||
|
||||
tlobjects = list(itertools.chain(*(
|
||||
parse_tl(file, layer, methods) for file in TLOBJECT_IN_TLS)))
|
||||
|
|
|
@ -271,6 +271,10 @@ class AuthMethods(MessageParseMethods, UserMethods):
|
|||
|
||||
This method will send the code if it's not provided.
|
||||
|
||||
.. note::
|
||||
|
||||
In most cases, you should simply use `start()` and not this method.
|
||||
|
||||
Arguments
|
||||
phone (`str` | `int`):
|
||||
The phone to send the code to if no code was provided,
|
||||
|
|
25
telethon_generator/data/friendly.csv
Normal file
25
telethon_generator/data/friendly.csv
Normal file
|
@ -0,0 +1,25 @@
|
|||
ns,friendly,raw
|
||||
account.AccountMethods,takeout,invokeWithTakeout account.initTakeoutSession account.finishTakeoutSession
|
||||
auth.AuthMethods,sign_in,auth.signIn auth.importBotAuthorization
|
||||
auth.AuthMethods,sign_up,auth.signUp
|
||||
auth.AuthMethods,send_code_request,auth.sendCode auth.resendCode
|
||||
auth.AuthMethods,log_out,auth.logOut
|
||||
auth.AuthMethods,edit_2fa,account.updatePasswordSettings
|
||||
bots.BotMethods,inline_query,messages.getInlineBotResults
|
||||
chats.ChatMethods,action,messages.setTyping
|
||||
chats.ChatMethods,iter_participants,channels.getParticipants
|
||||
chats.ChatMethods,iter_admin_log,channels.getAdminLog
|
||||
dialogs.DialogMethods,iter_dialogs,messages.getDialogs
|
||||
dialogs.DialogMethods,iter_drafts,messages.getAllDrafts
|
||||
dialogs.DialogMethods,edit_folder,folders.deleteFolder folders.editPeerFolders
|
||||
downloads.DownloadMethods,download_media,upload.getFile
|
||||
messages.MessageMethods,iter_messages,messages.searchGlobal messages.search messages.getHistory channels.getMessages messages.getMessages
|
||||
messages.MessageMethods,send_message,messages.sendMessage
|
||||
messages.MessageMethods,forward_messages,messages.forwardMessages
|
||||
messages.MessageMethods,edit_message,messages.editInlineBotMessage messages.editMessage
|
||||
messages.MessageMethods,delete_messages,channels.deleteMessages messages.deleteMessages
|
||||
messages.MessageMethods,send_read_acknowledge,messages.readMentions channels.readHistory messages.readHistory
|
||||
updates.UpdateMethods,catch_up,updates.getDifference updates.getChannelDifference
|
||||
uploads.UploadMethods,send_file,messages.sendMedia messages.sendMultiMedia messages.uploadMedia
|
||||
uploads.UploadMethods,upload_file,upload.saveFilePart upload.saveBigFilePart
|
||||
users.UserMethods,get_entity,users.getUsers messages.getChats channels.getChannels contacts.resolveUsername
|
|
|
@ -58,6 +58,7 @@ auth.dropTempAuthKeys,both,
|
|||
auth.exportAuthorization,both,DC_ID_INVALID
|
||||
auth.importAuthorization,both,AUTH_BYTES_INVALID USER_ID_INVALID
|
||||
auth.importBotAuthorization,both,ACCESS_TOKEN_EXPIRED ACCESS_TOKEN_INVALID API_ID_INVALID
|
||||
auth.logOut,both,
|
||||
auth.recoverPassword,user,CODE_EMPTY
|
||||
auth.requestPasswordRecovery,user,PASSWORD_EMPTY
|
||||
auth.resendCode,user,PHONE_NUMBER_INVALID
|
||||
|
|
|
|
@ -380,6 +380,24 @@ def _write_html_pages(root, tlobjects, methods, layer, input_res):
|
|||
'<code>telethon.errors</code>.')
|
||||
|
||||
docs.write_title('Example', id='examples')
|
||||
if tlobject.friendly:
|
||||
ns, friendly = tlobject.friendly
|
||||
docs.write_text(
|
||||
'Please refer to the documentation of <a href="'
|
||||
'https://docs.telethon.dev/en/latest/modules/client.html'
|
||||
'#telethon.client.{0}.{1}"><code>client.{1}()</code></a> '
|
||||
'to learn about the parameters and see several code '
|
||||
'examples on how to use it.'
|
||||
.format(ns, friendly)
|
||||
)
|
||||
docs.write_text(
|
||||
'The method above is the recommended way to do it. '
|
||||
'If you need more control over the parameters or want '
|
||||
'to learn how it is implemented, open the details by '
|
||||
'clicking on the "Details" text.'
|
||||
)
|
||||
docs.write('<details>')
|
||||
|
||||
docs.write('''<pre>\
|
||||
<strong>from</strong> telethon.sync <strong>import</strong> TelegramClient
|
||||
<strong>from</strong> telethon <strong>import</strong> functions, types
|
||||
|
@ -399,6 +417,8 @@ def _write_html_pages(root, tlobjects, methods, layer, input_res):
|
|||
docs.write('.stringify()')
|
||||
|
||||
docs.write(')</pre>')
|
||||
if tlobject.friendly:
|
||||
docs.write('</details>')
|
||||
|
||||
depth = '../' * (2 if tlobject.namespace else 1)
|
||||
docs.add_script(src='prependPath = "{}";'.format(depth))
|
||||
|
|
|
@ -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)))
|
||||
|
|
|
@ -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]
|
||||
)
|
||||
|
|
|
@ -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()
|
||||
|
|
Loading…
Reference in New Issue
Block a user