LonamiWebs/Telethon
1
1
Fork 0
mirror of https://github.com/LonamiWebs/Telethon.git synced 2025-10-31 16:07:44 +03:00
Code Issues Packages Projects Releases Wiki Activity

Make complete use of pathlib (fix up 8224e5a)

Browse Source
This commit is contained in:
Lonami Exo 2018-12-21 18:18:18 +01:00
parent 8224e5aabf
commit aefa429236
2 changed files with 110 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
telethon_generator/docswriter.py
View File

@ -3,25 +3,25 @@ import re
class DocsWriter: class DocsWriter:
"""Utility class used to write the HTML files used on the documentation"""
def __init__(self, filename, type_to_path):
"""Initializes the writer to the specified output file,
creating the parent directories when used if required.
'type_to_path_function' should be a function which, given a type
name and a named argument relative_to, returns the file path for
the specified type, relative to the given filename
""" """
Utility class used to write the HTML files used on the documentation.
"""
def __init__(self, root, filename, type_to_path):
"""
Initializes the writer to the specified output file,
creating the parent directories when used if required.
"""
self.root = root
self.filename = filename self.filename = filename
self._parent = str(self.filename.parent)
self.handle = None self.handle = None
self.title = ''
# Should be set before calling adding items to the menu # Should be set before calling adding items to the menu
self.menu_separator_tag = None self.menu_separator_tag = None
# Utility functions TODO There must be a better way # Utility functions
self.type_to_path = lambda t: type_to_path( self.type_to_path = lambda t: self._rel(type_to_path(t))
t, relative_to=self.filename
)
# Control signals # Control signals
self.menu_began = False self.menu_began = False
@ -30,11 +30,20 @@ class DocsWriter:
self.write_copy_script = False self.write_copy_script = False
self._script = '' self._script = ''
def _rel(self, path):
"""
Get the relative path for the given path from the current
file by working around https://bugs.python.org/issue20012.
"""
return os.path.relpath(str(path), self._parent)
# High level writing # High level writing
def write_head(self, title, relative_css_path, default_css): def write_head(self, title, css_path, default_css):
"""Writes the head part for the generated document, """Writes the head part for the generated document,
with the given title and CSS with the given title and CSS
""" """
#
self.title = title
self.write( self.write(
'''<!DOCTYPE html> '''<!DOCTYPE html>
<html> <html>
@ -54,17 +63,17 @@ class DocsWriter:
<body> <body>
<div id="main_div">''', <div id="main_div">''',
title=title, title=title,
rel_css=str(relative_css_path).rstrip('/'), rel_css=self._rel(css_path),
def_css=default_css def_css=default_css
) )
def set_menu_separator(self, relative_image_path): def set_menu_separator(self, img):
"""Sets the menu separator. """Sets the menu separator.
Must be called before adding entries to the menu Must be called before adding entries to the menu
""" """
if relative_image_path: if img:
self.menu_separator_tag = \ self.menu_separator_tag = '<img src="{}" alt="/" />'.format(
'<img src="{}" alt="/" />'.format(relative_image_path) self._rel(img))
else: else:
self.menu_separator_tag = None self.menu_separator_tag = None
@ -80,7 +89,7 @@ class DocsWriter:
self.write('<li>') self.write('<li>')
if link: if link:
self.write('<a href="{}">', link) self.write('<a href="{}">', self._rel(link))
# Write the real menu entry text # Write the real menu entry text
self.write(name) self.write(name)
@ -210,7 +219,7 @@ class DocsWriter:
if bold: if bold:
self.write('<b>') self.write('<b>')
if link: if link:
self.write('<a href="{}">', link) self.write('<a href="{}">', self._rel(link))
# Finally write the real table data, the given text # Finally write the real table data, the given text
self.write(text) self.write(text)

206
telethon_generator/generators/docs.py
View File

@ -1,6 +1,5 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
import functools import functools
import os
import re import re
import shutil import shutil
from collections import defaultdict from collections import defaultdict
@ -35,6 +34,7 @@ def get_import_code(tlobject):
def _get_create_path_for(root, tlobject, make=True): def _get_create_path_for(root, tlobject, make=True):
"""Creates and returns the path for the given TLObject at root.""" """Creates and returns the path for the given TLObject at root."""
# TODO Can we pre-create all required directories?
out_dir = root / ('methods' if tlobject.is_function else 'constructors') out_dir = root / ('methods' if tlobject.is_function else 'constructors')
if tlobject.namespace: if tlobject.namespace:
out_dir /= tlobject.namespace out_dir /= tlobject.namespace
@ -45,33 +45,22 @@ def _get_create_path_for(root, tlobject, make=True):
return out_dir / _get_file_name(tlobject) return out_dir / _get_file_name(tlobject)
def _get_path_for_type(root, type_, relative_to='.'): def _get_path_for_type(type_):
"""Similar to `_get_create_path_for` but for only type names.""" """Similar to `_get_create_path_for` but for only type names."""
if type_.lower() in CORE_TYPES: if type_.lower() in CORE_TYPES:
path = 'index.html#%s' % type_.lower() return Path('index.html#%s' % type_.lower())
elif '.' in type_: elif '.' in type_:
namespace, name = type_.split('.') namespace, name = type_.split('.')
path = 'types/%s/%s' % (namespace, _get_file_name(name)) return Path('types', namespace, _get_file_name(name))
else: else:
path = 'types/%s' % _get_file_name(type_) return Path('types', _get_file_name(type_))
return _get_relative_path(root / path, relative_to)
def _get_relative_path(destination, relative_to, folder=False):
"""Return the relative path to destination from relative_to."""
relative_to = Path(relative_to)
if not folder:
relative_to = relative_to.parent
# TODO Use pathlib here
return Path(os.path.relpath(destination, start=relative_to))
def _find_title(html_file): def _find_title(html_file):
"""Finds the <title> for the given HTML file, or (Unknown).""" """Finds the <title> for the given HTML file, or (Unknown)."""
with open(html_file, 'r') as fp: # TODO Is it necessary to read files like this?
for line in fp: with html_file.open() as f:
for line in f:
if '<title>' in line: if '<title>' in line:
# + 7 to skip len('<title>') # + 7 to skip len('<title>')
return line[line.index('<title>') + 7:line.index('</title>')] return line[line.index('<title>') + 7:line.index('</title>')]
@ -79,25 +68,27 @@ def _find_title(html_file):
return '(Unknown)' return '(Unknown)'
def _build_menu(docs, filename, root, relative_main_index): def _build_menu(docs):
"""Builds the menu using the given DocumentWriter up to 'filename', """
which must be a file (it cannot be a directory)""" Builds the menu used for the current ``DocumentWriter``.
filename = _get_relative_path(filename, root) """
docs.add_menu('API', relative_main_index)
items = str(filename).split('/') paths = []
for i in range(len(items) - 1): current = docs.filename
item = items[i] while current != docs.root:
link = '../' * (len(items) - (i + 2)) current = current.parent
link += 'index.html' paths.append(current)
docs.add_menu(item.title(), link=link)
for path in reversed(paths):
docs.add_menu(path.stem.title(), link=path / 'index.html')
if docs.filename.stem != 'index':
docs.add_menu(docs.title, link=docs.filename)
if items[-1] != 'index.html':
docs.add_menu(os.path.splitext(items[-1])[0])
docs.end_menu() docs.end_menu()
def _generate_index(folder, original_paths, root, def _generate_index(root, folder, paths,
bots_index=False, bots_index_paths=()): bots_index=False, bots_index_paths=()):
"""Generates the index file for the specified folder""" """Generates the index file for the specified folder"""
# Determine the namespaces listed here (as sub folders) # Determine the namespaces listed here (as sub folders)
@ -107,39 +98,23 @@ def _generate_index(folder, original_paths, root,
INDEX = 'index.html' INDEX = 'index.html'
BOT_INDEX = 'botindex.html' BOT_INDEX = 'botindex.html'
if not bots_index: for item in (bots_index_paths or folder.iterdir()):
for item in folder.iterdir():
if item.is_dir(): if item.is_dir():
namespaces.append(item) namespaces.append(item)
elif item not in (INDEX, BOT_INDEX): elif item.name not in (INDEX, BOT_INDEX):
files.append(item) files.append(item)
else:
# bots_index_paths should be a list of "namespace/method.html"
# or "method.html"
for item in bots_index_paths:
dirname = item.parent
if dirname and dirname not in namespaces:
namespaces.append(dirname)
elif not dirname and item not in (INDEX, BOT_INDEX):
files.append(item)
paths = {k: _get_relative_path(v, folder, folder=True)
for k, v in original_paths.items()}
# Now that everything is setup, write the index.html file # Now that everything is setup, write the index.html file
filename = folder / (BOT_INDEX if bots_index else INDEX) filename = folder / (BOT_INDEX if bots_index else INDEX)
with DocsWriter(filename, type_to_path=_get_path_for_type) as docs: with DocsWriter(root, filename, _get_path_for_type) as docs:
# Title should be the current folder name # Title should be the current folder name
docs.write_head(str(folder).title(), docs.write_head(str(folder).title(),
relative_css_path=paths['css'], css_path=paths['css'],
default_css=original_paths['default_css']) default_css=paths['default_css'])
docs.set_menu_separator(paths['arrow']) docs.set_menu_separator(paths['arrow'])
_build_menu(docs, filename, root, _build_menu(docs)
relative_main_index=paths['index_all']) docs.write_title(str(filename.parent.relative_to(root)).title())
docs.write_title(str(
_get_relative_path(folder, root, folder=True)).title())
if bots_index: if bots_index:
docs.write_text('These are the methods that you may be able to ' docs.write_text('These are the methods that you may be able to '
@ -157,23 +132,22 @@ def _generate_index(folder, original_paths, root,
namespace_paths = [] namespace_paths = []
if bots_index: if bots_index:
for item in bots_index_paths: for item in bots_index_paths:
# TODO .name? or not if item.parent == namespace:
if item.parent.name == namespace: namespace_paths.append(item)
namespace_paths.append(item.name)
_generate_index(folder / namespace, _generate_index(root, namespace, paths,
original_paths, root,
bots_index, namespace_paths) bots_index, namespace_paths)
if bots_index:
docs.add_row(namespace.title(), link=namespace / BOT_INDEX) docs.add_row(
else: namespace.stem.title(),
docs.add_row(namespace.title(), link=namespace / INDEX) link=namespace / (BOT_INDEX if bots_index else INDEX))
docs.end_table() docs.end_table()
docs.write_title('Available items') docs.write_title('Available items')
docs.begin_table(2) docs.begin_table(2)
files = [(f, _find_title(folder / f)) for f in files] files = [(f, _find_title(f)) for f in files]
files.sort(key=lambda t: t[1]) files.sort(key=lambda t: t[1])
for file, title in files: for file, title in files:
@ -234,7 +208,7 @@ def _copy_replace(src, dst, replacements):
)) ))
def _write_html_pages(tlobjects, methods, layer, input_res, output_dir): def _write_html_pages(root, tlobjects, methods, layer, input_res):
""" """
Generates the documentation HTML files from from ``scheme.tl`` Generates the documentation HTML files from from ``scheme.tl``
to ``/methods`` and ``/constructors``, etc. to ``/methods`` and ``/constructors``, etc.
@ -242,19 +216,18 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
# Save 'Type: [Constructors]' for use in both: # Save 'Type: [Constructors]' for use in both:
# * Seeing the return type or constructors belonging to the same type. # * Seeing the return type or constructors belonging to the same type.
# * Generating the types documentation, showing available constructors. # * Generating the types documentation, showing available constructors.
original_paths = { paths = {k: root / v for k, v in (
'css': 'css', ('css', 'css'),
'arrow': 'img/arrow.svg', ('arrow', 'img/arrow.svg'),
'search.js': 'js/search.js', ('search.js', 'js/search.js'),
'404': '404.html', ('404', '404.html'),
'index_all': 'index.html', ('index_all', 'index.html'),
'bot_index': 'botindex.html', ('bot_index', 'botindex.html'),
'index_types': 'types/index.html', ('index_types', 'types/index.html'),
'index_methods': 'methods/index.html', ('index_methods', 'methods/index.html'),
'index_constructors': 'constructors/index.html' ('index_constructors', 'constructors/index.html')
} )}
original_paths = {k: output_dir / v for k, v in original_paths.items()} paths['default_css'] = 'light' # docs.<name>.css, local path
original_paths['default_css'] = 'light' # docs.<name>.css, local path
type_to_constructors = defaultdict(list) type_to_constructors = defaultdict(list)
type_to_functions = defaultdict(list) type_to_functions = defaultdict(list)
for tlobject in tlobjects: for tlobject in tlobjects:
@ -267,24 +240,20 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
methods = {m.name: m for m in methods} methods = {m.name: m for m in methods}
# Since the output directory is needed everywhere partially apply it now # Since the output directory is needed everywhere partially apply it now
create_path_for = functools.partial(_get_create_path_for, output_dir) create_path_for = functools.partial(_get_create_path_for, root)
path_for_type = functools.partial(_get_path_for_type, output_dir) path_for_type = lambda t: root / _get_path_for_type(t)
bot_docs_paths = [] bot_docs_paths = []
for tlobject in tlobjects: for tlobject in tlobjects:
filename = create_path_for(tlobject) filename = create_path_for(tlobject)
paths = {k: _get_relative_path(v, filename) with DocsWriter(root, filename, path_for_type) as docs:
for k, v in original_paths.items()}
with DocsWriter(filename, type_to_path=path_for_type) as docs:
docs.write_head(title=tlobject.class_name, docs.write_head(title=tlobject.class_name,
relative_css_path=paths['css'], css_path=paths['css'],
default_css=original_paths['default_css']) default_css=paths['default_css'])
# Create the menu (path to the current TLObject) # Create the menu (path to the current TLObject)
docs.set_menu_separator(paths['arrow']) docs.set_menu_separator(paths['arrow'])
_build_menu(docs, filename, output_dir, _build_menu(docs)
relative_main_index=paths['index_all'])
# Create the page title # Create the page title
docs.write_title(tlobject.class_name) docs.write_title(tlobject.class_name)
@ -334,9 +303,7 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
inner = tlobject.result inner = tlobject.result
docs.begin_table(column_count=1) docs.begin_table(column_count=1)
docs.add_row(inner, link=path_for_type( docs.add_row(inner, link=path_for_type(inner))
inner, relative_to=filename
))
docs.end_table() docs.end_table()
cs = type_to_constructors.get(inner, []) cs = type_to_constructors.get(inner, [])
@ -350,7 +317,6 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
docs.begin_table(column_count=2) docs.begin_table(column_count=2)
for constructor in cs: for constructor in cs:
link = create_path_for(constructor) link = create_path_for(constructor)
link = _get_relative_path(link, relative_to=filename)
docs.add_row(constructor.class_name, link=link) docs.add_row(constructor.class_name, link=link)
docs.end_table() docs.end_table()
@ -381,8 +347,8 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
docs.add_row('!' + friendly_type, align='center') docs.add_row('!' + friendly_type, align='center')
else: else:
docs.add_row( docs.add_row(
friendly_type, align='center', link= friendly_type, align='center',
path_for_type(arg.type, relative_to=filename) link=path_for_type(arg.type)
) )
# Add a description for this argument # Add a description for this argument
@ -442,12 +408,6 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
docs.add_script(relative_src=paths['search.js']) docs.add_script(relative_src=paths['search.js'])
docs.end_body() docs.end_body()
temp = []
for item in bot_docs_paths:
# TODO What?
temp.append(os.path.sep.join(str(item).split(os.path.sep)[2:]))
bot_docs_paths = temp
# Find all the available types (which are not the same as the constructors) # Find all the available types (which are not the same as the constructors)
# Each type has a list of constructors associated to it, hence is a map # Each type has a list of constructors associated to it, hence is a map
for t, cs in type_to_constructors.items(): for t, cs in type_to_constructors.items():
@ -462,17 +422,13 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
else: else:
namespace, name = None, t namespace, name = None, t
paths = {k: _get_relative_path(v, out_dir, folder=True) with DocsWriter(root, filename, path_for_type) as docs:
for k, v in original_paths.items()}
with DocsWriter(filename, type_to_path=path_for_type) as docs:
docs.write_head(title=snake_to_camel_case(name), docs.write_head(title=snake_to_camel_case(name),
relative_css_path=paths['css'], css_path=paths['css'],
default_css=original_paths['default_css']) default_css=paths['default_css'])
docs.set_menu_separator(paths['arrow']) docs.set_menu_separator(paths['arrow'])
_build_menu(docs, filename, output_dir, _build_menu(docs)
relative_main_index=paths['index_all'])
# Main file title # Main file title
docs.write_title(snake_to_camel_case(name)) docs.write_title(snake_to_camel_case(name))
@ -491,7 +447,6 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
for constructor in cs: for constructor in cs:
# Constructor full name # Constructor full name
link = create_path_for(constructor) link = create_path_for(constructor)
link = _get_relative_path(link, relative_to=filename)
docs.add_row(constructor.class_name, link=link) docs.add_row(constructor.class_name, link=link)
docs.end_table() docs.end_table()
@ -511,7 +466,6 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
docs.begin_table(2) docs.begin_table(2)
for func in functions: for func in functions:
link = create_path_for(func) link = create_path_for(func)
link = _get_relative_path(link, relative_to=filename)
docs.add_row(func.class_name, link=link) docs.add_row(func.class_name, link=link)
docs.end_table() docs.end_table()
@ -536,7 +490,6 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
docs.begin_table(2) docs.begin_table(2)
for ot in other_methods: for ot in other_methods:
link = create_path_for(ot) link = create_path_for(ot)
link = _get_relative_path(link, relative_to=filename)
docs.add_row(ot.class_name, link=link) docs.add_row(ot.class_name, link=link)
docs.end_table() docs.end_table()
@ -562,7 +515,6 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
docs.begin_table(2) docs.begin_table(2)
for ot in other_types: for ot in other_types:
link = create_path_for(ot) link = create_path_for(ot)
link = _get_relative_path(link, relative_to=filename)
docs.add_row(ot.class_name, link=link) docs.add_row(ot.class_name, link=link)
docs.end_table() docs.end_table()
docs.end_body() docs.end_body()
@ -572,11 +524,10 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
# information that we have available, simply a file listing all the others # information that we have available, simply a file listing all the others
# accessible by clicking on their title # accessible by clicking on their title
for folder in ['types', 'methods', 'constructors']: for folder in ['types', 'methods', 'constructors']:
_generate_index(output_dir / folder, original_paths, _generate_index(root, root / folder, paths)
output_dir)
_generate_index(output_dir / 'methods', original_paths, _generate_index(root, root / 'methods', paths, True,
output_dir, True, bot_docs_paths) bot_docs_paths)
# Write the final core index, the main index for the rest of files # Write the final core index, the main index for the rest of files
types = set() types = set()
@ -598,9 +549,8 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
methods = sorted(methods, key=lambda m: m.name) methods = sorted(methods, key=lambda m: m.name)
cs = sorted(cs, key=lambda c: c.name) cs = sorted(cs, key=lambda c: c.name)
shutil.copy(str(input_res / '404.html'), str(original_paths['404'])) shutil.copy(str(input_res / '404.html'), str(paths['404']))
_copy_replace(input_res / 'core.html', _copy_replace(input_res / 'core.html', paths['index_all'], {
original_paths['index_all'], {
'{type_count}': len(types), '{type_count}': len(types),
'{method_count}': len(methods), '{method_count}': len(methods),
'{constructor_count}': len(tlobjects) - len(methods), '{constructor_count}': len(tlobjects) - len(methods),
@ -626,15 +576,15 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
type_names = fmt(types, formatter=lambda x: x) type_names = fmt(types, formatter=lambda x: x)
# Local URLs shouldn't rely on the output's root, so set empty root # Local URLs shouldn't rely on the output's root, so set empty root
create_path_for = functools.partial(_get_create_path_for, '', make=False) create_path_for = functools.partial(
path_for_type = functools.partial(_get_path_for_type, '') _get_create_path_for, Path(), make=False)
request_urls = fmt(methods, create_path_for) request_urls = fmt(methods, create_path_for)
type_urls = fmt(types, path_for_type) type_urls = fmt(types, _get_path_for_type)
constructor_urls = fmt(cs, create_path_for) constructor_urls = fmt(cs, create_path_for)
original_paths['search.js'].parent.mkdir(parents=True, exist_ok=True) paths['search.js'].parent.mkdir(parents=True, exist_ok=True)
_copy_replace(input_res / 'js/search.js', _copy_replace(input_res / 'js/search.js', paths['search.js'], {
original_paths['search.js'], {
'{request_names}': request_names, '{request_names}': request_names,
'{type_names}': type_names, '{type_names}': type_names,
'{constructor_names}': constructor_names, '{constructor_names}': constructor_names,
@ -655,5 +605,5 @@ def _copy_resources(res_dir, out_dir):
def generate_docs(tlobjects, methods, layer, input_res, output_dir): def generate_docs(tlobjects, methods, layer, input_res, output_dir):
output_dir.mkdir(parents=True, exist_ok=True) output_dir.mkdir(parents=True, exist_ok=True)
_write_html_pages(tlobjects, methods, layer, input_res, output_dir) _write_html_pages(output_dir, tlobjects, methods, layer, input_res)
_copy_resources(input_res, output_dir) _copy_resources(input_res, output_dir)