snowykami/mbcp
1
0
Fork 0
mirror of https://github.com/snowykami/mbcp.git synced 2026-01-25 05:02:15 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

📝 测试文档部署

Browse Source
This commit is contained in:
远野千束
2024-08-28 12:02:30 +08:00
parent f5d91cafd5
commit e0a3ab605d
39 changed files with 2811 additions and 819 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
liteyuki_autodoc/__init__.py Normal file
View File

@@ -0,0 +1,10 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午12:52
@Author : snowykami
@Email : snowykami@outlook.com
@File : __init__.py.py
@Software: PyCharm
"""

46
liteyuki_autodoc/__main__.py Normal file
View File

@@ -0,0 +1,46 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午4:08
@Author : snowykami
@Email : snowykami@outlook.com
@File : __main__.py
@Software: PyCharm
"""
# command line tool
# args[0] path
# -o|--output output path
# -l|--lang zh-Hans en jp default zh-Hans
import argparse
import os
import sys
from liteyuki_autodoc.output import generate_from_module
def main():
parser = argparse.ArgumentParser(description="Generate documentation from Python modules.")
parser.add_argument("path", type=str, help="Path to the Python module or package.")
parser.add_argument("-o", "--output", default="doc-output", type=str, help="Output directory.")
parser.add_argument("-c", "--contain-top", action="store_true", help="Whether to contain top-level dir in output dir.")
parser.add_argument("-l", "--lang", nargs='+', default=["zh-Hans"], type=str, help="Languages of the document.")
args = parser.parse_args()
if not os.path.exists(args.path):
print(f"Error: The path {args.path} does not exist.")
sys.exit(1)
if not os.path.exists(args.output):
os.makedirs(args.output)
langs = args.lang
for lang in langs:
generate_from_module(args.path, args.output, with_top=args.contain_top, lang=lang)
if __name__ == '__main__':
main()

10
liteyuki_autodoc/docstring/__init__.py Normal file
View File

@@ -0,0 +1,10 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午1:46
@Author : snowykami
@Email : snowykami@outlook.com
@File : __init__.py.py
@Software: PyCharm
"""

150
liteyuki_autodoc/docstring/docstring.py Normal file
View File

@@ -0,0 +1,150 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午1:46
@Author : snowykami
@Email : snowykami@outlook.com
@File : docstring.py
@Software: PyCharm
"""
from typing import Optional
from pydantic import BaseModel, Field
from liteyuki_autodoc.i18n import get_text
class Attr(BaseModel):
name: str
type: str = ""
desc: str = ""
class Args(BaseModel):
name: str
type: str = ""
desc: str = ""
class Return(BaseModel):
desc: str = ""
class Exception_(BaseModel):
name: str
desc: str = ""
class Raise(BaseModel):
exceptions: list[Exception_] = []
class Example(BaseModel):
desc: str = ""
input: str = ""
output: str = ""
class Docstring(BaseModel):
desc: str = ""
args: list[Args] = []
attrs: list[Attr] = []
return_: Optional[Return] = None
raise_: list[Exception_] = []
example: list[Example] = []
def add_desc(self, desc: str):
if self.desc == "":
self.desc = desc
else:
self.desc += "\n" + desc
def add_arg(self, name: str, type_: str = "", desc: str = ""):
self.args.append(Args(name=name, type=type_, desc=desc))
def add_attrs(self, name: str, type_: str = "", desc: str = ""):
self.attrs.append(Attr(name=name, type=type_, desc=desc))
def add_return(self, desc: str = ""):
self.return_ = Return(desc=desc)
def add_raise(self, name: str, desc: str = ""):
self.raise_.append(Exception_(name=name, desc=desc))
def add_example(self, desc: str = "", input_: str = "", output: str = ""):
self.example.append(Example(desc=desc, input=input_, output=output))
def reduction(self) -> str:
"""
通过解析结果还原docstring
Args:
Returns:
"""
ret = ""
ret += self.desc + "\n"
if self.args:
ret += "Args:\n"
for arg in self.args:
ret += f" {arg.name}: {arg.type}\n {arg.desc}\n"
if self.attrs:
ret += "Attributes:\n"
for attr in self.attrs:
ret += f" {attr.name}: {attr.type}\n {attr.desc}\n"
if self.return_:
ret += "Returns:\n"
ret += f" {self.return_.desc}\n"
if self.raise_:
ret += "Raises:\n"
for exception in self.raise_:
ret += f" {exception.name}\n {exception.desc}\n"
if self.example:
ret += "Examples:\n"
for example in self.example:
ret += f" {example.desc}\n Input: {example.input}\n Output: {example.output}\n"
return ret
def markdown(self, lang: str, indent: int = 4, is_classmethod: bool = False) -> str:
"""
生成markdown文档
Args:
is_classmethod:
lang:
indent:
Returns:
"""
PREFIX = "" * indent
if is_classmethod:
PREFIX = " -"
ret = ""
ret += self.desc + "\n\n"
if self.args:
ret += PREFIX + f"{get_text(lang, 'docstring.args')}:\n\n"
for arg in self.args:
ret += PREFIX + f"{arg.name}: {arg.type} {arg.desc}\n\n"
if self.attrs:
ret += PREFIX + f"{get_text(lang, 'docstring.attrs')}:\n\n"
for attr in self.attrs:
ret += PREFIX + f"{attr.name}: {attr.type} {attr.desc}\n\n"
if self.return_:
ret += PREFIX + f"{get_text(lang, 'docstring.return')}:\n\n"
ret += PREFIX + f"{self.return_.desc}\n\n"
if self.raise_:
ret += PREFIX + f"{get_text(lang, 'docstring.raises')}:\n\n"
for exception in self.raise_:
ret += PREFIX + f"{exception.name} {exception.desc}\n\n"
if self.example:
ret += PREFIX + f"{get_text(lang, 'docstring.example')}:\n\n"
for example in self.example:
ret += PREFIX + f"{example.desc}\n Input: {example.input}\n Output: {example.output}\n\n"
return ret
def __str__(self):
return self.desc

178
liteyuki_autodoc/docstring/parser.py Normal file
View File

@@ -0,0 +1,178 @@
"""
Google docstring parser for Python.
"""
from typing import Optional
from liteyuki_autodoc.docstring.docstring import Docstring
class Parser:
...
class GoogleDocstringParser(Parser):
_tokens = {
"Args" : "args",
"Arguments" : "args",
"参数" : "args",
"Return" : "return",
"Returns" : "return",
"返回" : "return",
"Attribute" : "attribute",
"Attributes" : "attribute",
"属性" : "attribute",
"Raises" : "raises",
"Raise" : "raises",
"引发" : "raises",
"Example" : "example",
"Examples" : "example",
"示例" : "example",
"Yields" : "yields",
"Yield" : "yields",
"产出" : "yields",
"Requires" : "requires",
"Require" : "requires",
"需要" : "requires",
"FrontMatter": "front_matter",
"前言" : "front_matter",
}
def __init__(self, docstring: str, indent: int = 4):
self.lines = docstring.splitlines()
self.indent = indent
self.lineno = 0 # Current line number
self.char = 0 # Current character position
self.docstring = Docstring()
def match_token(self) -> Optional[str]:
for token in self._tokens:
if self.lines[self.lineno][self.char:].startswith(token):
self.char += len(token)
return self._tokens[token]
return None
def parse_args(self):
"""
依次解析后面的参数行，直到缩进小于等于当前行的缩进
"""
while line := self.match_next_line():
if ":" in line:
name, desc = line.split(":", 1)
self.docstring.add_arg(name.strip(), desc.strip())
else:
self.docstring.add_arg(line.strip())
def parse_return(self):
"""
解析返回值行
"""
if line := self.match_next_line():
self.docstring.add_return(line.strip())
def parse_raises(self):
"""
解析异常行
"""
while line := self.match_next_line():
if ":" in line:
name, desc = line.split(":", 1)
self.docstring.add_raise(name.strip(), desc.strip())
else:
self.docstring.add_raise(line.strip())
def parse_example(self):
"""
解析示例行
"""
while line := self.match_next_line():
if ":" in line:
name, desc = line.split(":", 1)
self.docstring.add_example(name.strip(), desc.strip())
else:
self.docstring.add_example(line.strip())
def parse_attrs(self):
"""
解析属性行
"""
while line := self.match_next_line():
if ":" in line:
name, desc = line.split(":", 1)
self.docstring.add_attrs(name.strip(), desc.strip())
else:
self.docstring.add_attrs(line.strip())
def match_next_line(self) -> Optional[str]:
"""
在一个子解析器中，解析下一行，直到缩进小于等于当前行的缩进
Returns:
"""
while self.lineno + 1 < len(self.lines):
line = self.lines[self.lineno + 1]
if line.startswith(" " * self.indent):
line = line[self.indent:]
else:
return None
if not line:
return None
self.lineno += 1
return line
def parse(self) -> Docstring:
"""
逐行解析，直到遇到EOS
最开始未解析到的内容全部加入desc
Returns:
"""
add_desc = True
while self.lineno < len(self.lines):
token = self.match_token()
if token is None and add_desc:
self.docstring.add_desc(self.lines[self.lineno].strip())
if token is not None:
add_desc = False
match token:
case "args":
self.parse_args()
case "return":
self.parse_return()
case "attribute":
self.parse_attrs()
case "raises":
self.parse_raises()
case "example":
self.parse_example()
case _:
self.lineno += 1
return self.docstring
class NumpyDocstringParser(Parser):
...
class ReStructuredParser(Parser):
...
def parse(docstring: str, parser: str = "google", indent: int = 4) -> Docstring:
if parser == "google":
return GoogleDocstringParser(docstring, indent).parse()
else:
raise ValueError(f"Unknown parser: {parser}")

123
liteyuki_autodoc/i18n.py Normal file
View File

@@ -0,0 +1,123 @@
# -*- coding: utf-8 -*-
"""
Internationalization module.
"""
from typing import Optional, TypeAlias
NestedDict: TypeAlias = dict[str, 'str | NestedDict']
i18n_dict: dict[str, NestedDict] = {
"en" : {
"docstring": {
"args" : "Args",
"return" : "Return",
"attribute": "Attribute",
"raises" : "Raises",
"example" : "Examples",
"yields" : "Yields",
},
"src": "Source code",
},
"zh-Hans": {
"docstring": {
"args" : "参数",
"return" : "返回",
"attribute": "属性",
"raises" : "引发",
"example" : "示例",
"yields" : "产出",
},
"src": "源码",
},
"zh-Hant": {
"docstring": {
"args" : "參數",
"return" : "返回",
"attribute": "屬性",
"raises" : "引發",
"example" : "示例",
"yields" : "產出",
},
"src": "源碼",
},
"ja" : {
"docstring": {
"args" : "引数",
"return" : "戻り値",
"attribute": "属性",
"raises" : "例外",
"example" : "例",
"yields" : "生成",
},
"src": "ソースコード",
},
}
def flat_i18n_dict(data: dict[str, NestedDict]) -> dict[str, dict[str, str]]:
"""
Flatten i18n_dict.
Examples:
```python
{
"en": {
"docs": {
"key1": "val1",
"key2": "val2",
}
}
}
```
to
```python
{
"en": {
"docs.key1": "val1",
"docs.key2": "val2",
}
}
```
Returns:
"""
ret: dict[str, dict[str, str]] = {}
def _flat(_lang_data: NestedDict) -> dict[str, str]:
res = {}
for k, v in _lang_data.items():
if isinstance(v, dict):
for kk, vv in _flat(v).items():
res[f"{k}.{kk}"] = vv
else:
res[k] = v
return res
for lang, lang_data in data.items():
ret[lang] = _flat(lang_data)
return ret
i18n_flat_dict = flat_i18n_dict(i18n_dict)
def get_text(lang: str, key: str, default: Optional[str] = None, fallback: Optional[str] = "en") -> str:
"""
Get text from i18n_dict.
Args:
lang: language name
key: text key
default: default text, if None return fallback language or key
fallback: fallback language, priority is higher than default
Returns:
str: text
"""
if lang in i18n_flat_dict:
if key in i18n_flat_dict[lang]:
return i18n_flat_dict[lang][key]
if fallback is not None:
return i18n_flat_dict.get(fallback, {}).get(key, default or key)
else:
return default or key

107
liteyuki_autodoc/output.py Normal file
View File

@@ -0,0 +1,107 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午3:59
@Author : snowykami
@Email : snowykami@outlook.com
@File : output.py
@Software: PyCharm
"""
import os.path
from liteyuki_autodoc.style.markdown import generate
from liteyuki_autodoc.syntax.astparser import AstParser
def write_to_file(content: str, output: str) -> None:
"""
Write content to file.
Args:
content: str, content to write.
output: str, path to output file.
"""
if not os.path.exists(os.path.dirname(output)):
os.makedirs(os.path.dirname(output))
with open(output, "w", encoding="utf-8") as f:
f.write(content)
def get_file_list(module_folder: str):
file_list = []
for root, dirs, files in os.walk(module_folder):
for file in files:
if file.endswith((".py", ".pyi")):
file_list.append(os.path.join(root, file))
return file_list
def get_relative_path(base_path: str, target_path: str) -> str:
"""
获取相对路径
Args:
base_path: 基础路径
target_path: 目标路径
"""
return os.path.relpath(target_path, base_path)
def generate_from_module(module_folder: str, output_dir: str, with_top: bool = False, lang: str = "zh-Hans", ignored_paths=None):
"""
生成文档
Args:
module_folder: 模块文件夹
output_dir: 输出文件夹
with_top: 是否包含顶层文件夹 False时例如docs/api/module_a, docs/api/module_b， True时例如docs/api/module/module_a.md， docs/api/module/module_b.md
ignored_paths: 忽略的路径
lang: 语言
"""
if ignored_paths is None:
ignored_paths = []
file_data: dict[str, str] = {} # 路径 -> 字串
file_list = get_file_list(module_folder)
# 清理输出目录
if not os.path.exists(output_dir):
os.makedirs(output_dir)
replace_data = {
"__init__": "index",
".py" : ".md",
}
for pyfile_path in file_list:
if any(ignored_path.replace("\\", "/") in pyfile_path.replace("\\", "/") for ignored_path in ignored_paths):
continue
no_module_name_pyfile_path = get_relative_path(module_folder, pyfile_path) # 去头路径
# markdown相对路径
rel_md_path = pyfile_path if with_top else no_module_name_pyfile_path
for rk, rv in replace_data.items():
rel_md_path = rel_md_path.replace(rk, rv)
abs_md_path = os.path.join(output_dir, rel_md_path)
# 获取模块信息
ast_parser = AstParser(open(pyfile_path, "r", encoding="utf-8").read())
# 生成markdown
front_matter = {
"title" : pyfile_path.replace("\\", "/").
replace("/", ".").
replace(".py", "").
replace(".__init__", ""),
}
md_content = generate(ast_parser, lang=lang, frontmatter=front_matter)
print(f"Generate {pyfile_path} -> {abs_md_path}")
file_data[abs_md_path] = md_content
for fn, content in file_data.items():
write_to_file(content, fn)

10
liteyuki_autodoc/style/__init__.py Normal file
View File

@@ -0,0 +1,10 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午3:39
@Author : snowykami
@Email : snowykami@outlook.com
@File : __init__.py.py
@Software: PyCharm
"""

61
liteyuki_autodoc/style/markdown.py Normal file
View File

@@ -0,0 +1,61 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午3:39
@Author : snowykami
@Email : snowykami@outlook.com
@File : markdown.py
@Software: PyCharm
"""
from typing import Optional
from liteyuki_autodoc.syntax.astparser import AstParser
from liteyuki_autodoc.syntax.node import *
from liteyuki_autodoc.i18n import get_text
def generate(parser: AstParser, lang: str, frontmatter: Optional[dict] = None) -> str:
"""
Generate markdown style document from ast
You can modify this function to generate markdown style that enjoys you
Args:
parser:
lang: language
frontmatter:
Returns:
markdown style document
"""
print(parser.variables)
if frontmatter is not None:
md = "---\n"
for k, v in frontmatter.items():
md += f"{k}: {v}\n"
md += "---\n"
else:
md = ""
# var > func > class
for var in parser.variables:
if var.type == TypeHint.NO_TYPEHINT:
md += f"### ***var*** `{var.name} = {var.value}`\n\n"
else:
md += f"### ***var*** `{var.name}: {var.type} = {var.value}`\n\n"
for func in parser.functions:
md += func.markdown(lang)
for cls in parser.classes:
md += f"### ***class*** `{cls.name}`\n\n"
for mtd in cls.methods:
md += mtd.markdown(lang, 2, True)
for attr in cls.attrs:
if attr.type == TypeHint.NO_TYPEHINT:
md += f"#### ***attr*** `{attr.name} = {attr.value}`\n\n"
else:
md += f"#### ***attr*** `{attr.name}: {attr.type} = {attr.value}`\n\n"
return md

198
liteyuki_autodoc/syntax/astparser.py Normal file
View File

@@ -0,0 +1,198 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午2:13
@Author : snowykami
@Email : snowykami@outlook.com
@File : astparser.py
@Software: PyCharm
"""
import ast
from .node import *
from ..docstring.parser import parse
class AstParser:
def __init__(self, code: str):
self.code = code
self.tree = ast.parse(code)
self.classes: list[ClassNode] = []
self.functions: list[FunctionNode] = []
self.variables: list[AssignNode] = []
self.parse()
def parse(self):
for node in ast.walk(self.tree):
if isinstance(node, ast.ClassDef):
if not self._is_module_level_class(node):
continue
class_node = ClassNode(
name=node.name,
docs=parse(ast.get_docstring(node)) if ast.get_docstring(node) else None,
inherits=[ast.unparse(base) for base in node.bases]
)
self.classes.append(class_node)
# 继续遍历类内部的函数
for sub_node in node.body:
if isinstance(sub_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
class_node.methods.append(FunctionNode(
name=sub_node.name,
docs=parse(ast.get_docstring(sub_node)) if ast.get_docstring(sub_node) else None,
posonlyargs=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in sub_node.args.posonlyargs
],
args=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in sub_node.args.args
],
kwonlyargs=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in sub_node.args.kwonlyargs
],
kw_defaults=[
ConstantNode(
value=ast.unparse(default).strip() if default else TypeHint.NO_DEFAULT
)
for default in sub_node.args.kw_defaults
],
defaults=[
ConstantNode(
value=ast.unparse(default).strip() if default else TypeHint.NO_DEFAULT
)
for default in sub_node.args.defaults
],
return_=ast.unparse(sub_node.returns).strip() if sub_node.returns else TypeHint.NO_RETURN,
decorators=[ast.unparse(decorator).strip() for decorator in sub_node.decorator_list],
is_async=isinstance(sub_node, ast.AsyncFunctionDef),
src=ast.unparse(sub_node).strip()
))
elif isinstance(sub_node, (ast.Assign, ast.AnnAssign)):
if isinstance(sub_node, ast.Assign):
class_node.attrs.append(AttrNode(
name=sub_node.targets[0].id, # type: ignore
type=TypeHint.NO_TYPEHINT,
value=ast.unparse(sub_node.value).strip()
))
elif isinstance(sub_node, ast.AnnAssign):
class_node.attrs.append(AttrNode(
name=sub_node.target.id,
type=ast.unparse(sub_node.annotation).strip(),
value=ast.unparse(sub_node.value).strip() if sub_node.value else TypeHint.NO_DEFAULT
))
else:
raise ValueError(f"Unsupported node type: {type(sub_node)}")
elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
# 仅打印模块级别的函数
if not self._is_module_level_function(node):
continue
self.functions.append(FunctionNode(
name=node.name,
docs=parse(ast.get_docstring(node)) if ast.get_docstring(node) else None,
posonlyargs=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in node.args.posonlyargs
],
args=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg, default in zip(node.args.args, node.args.defaults)
],
kwonlyargs=[
ArgNode(
name=arg.arg,
type=ast.unparse(arg.annotation).strip() if arg.annotation else TypeHint.NO_TYPEHINT,
)
for arg in node.args.kwonlyargs
],
kw_defaults=[
ConstantNode(
value=ast.unparse(default).strip() if default else TypeHint.NO_DEFAULT
)
for default in node.args.kw_defaults
],
defaults=[
ConstantNode(
value=ast.unparse(default).strip() if default else TypeHint.NO_DEFAULT
)
for default in node.args.defaults
],
return_=ast.unparse(node.returns).strip() if node.returns else TypeHint.NO_TYPEHINT,
decorators=[ast.unparse(decorator).strip() for decorator in node.decorator_list],
is_async=isinstance(node, ast.AsyncFunctionDef),
src=ast.unparse(node).strip()
))
elif isinstance(node, (ast.Assign, ast.AnnAssign)):
if not self._is_module_level_variable(node):
# print("变量不在模块级别", ast.unparse(node))
continue
else:
print("变量在模块级别", ast.unparse(node))
if isinstance(node, ast.Assign):
for target in node.targets:
if isinstance(target, ast.Name):
self.variables.append(AssignNode(
name=target.id,
value=ast.unparse(node.value).strip(),
type=ast.unparse(node.annotation).strip() if isinstance(node, ast.AnnAssign) else TypeHint.NO_TYPEHINT
))
elif isinstance(node, ast.AnnAssign):
self.variables.append(AssignNode(
name=node.target.id,
value=ast.unparse(node.value).strip() if node.value else TypeHint.NO_DEFAULT,
type=ast.unparse(node.annotation).strip()
))
def _is_module_level_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef):
for parent in ast.walk(self.tree):
if isinstance(parent, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
if node in parent.body:
return False
return True
def _is_module_level_class(self, node: ast.ClassDef):
for parent in ast.walk(self.tree):
if isinstance(parent, ast.ClassDef):
if node in parent.body:
return False
return True
def _is_module_level_variable(self, node: ast.Assign):
for parent in ast.walk(self.tree):
if isinstance(parent, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
if node in parent.body:
return False
return True
def __str__(self):
s = ""
for cls in self.classes:
s += f"class {cls.name}:\n"
for func in self.functions:
s += f"def {func.name}:\n"
for var in self.variables:
s += f"{var.name} = {var.value}\n"
return s

258
liteyuki_autodoc/syntax/node.py Normal file
View File

@@ -0,0 +1,258 @@
# -*- coding: utf-8 -*-
"""
Copyright (C) 2020-2024 LiteyukiStudio. All Rights Reserved
@Time : 2024/8/28 下午2:14
@Author : snowykami
@Email : snowykami@outlook.com
@File : node.py
@Software: PyCharm
"""
from typing import Literal, Optional
from enum import Enum
from pydantic import BaseModel, Field
from liteyuki_autodoc.docstring.docstring import Docstring
from liteyuki_autodoc.i18n import get_text
class TypeHint:
NO_TYPEHINT = "NO_TYPE_HINT"
NO_DEFAULT = "NO_DEFAULT"
NO_RETURN = "NO_RETURN"
class AssignNode(BaseModel):
"""
AssignNode is a pydantic model that represents an assignment.
Attributes:
name: str
The name of the assignment.
type: str = ""
The type of the assignment.
value: str
The value of the assignment.
"""
name: str
type: str = ""
value: str
class ArgNode(BaseModel):
"""
ArgNode is a pydantic model that represents an argument.
Attributes:
name: str
The name of the argument.
type: str = ""
The type of the argument.
default: str = ""
The default value of the argument.
"""
name: str
type: str = TypeHint.NO_TYPEHINT
class AttrNode(BaseModel):
"""
AttrNode is a pydantic model that represents an attribute.
Attributes:
name: str
The name of the attribute.
type: str = ""
The type of the attribute.
value: str = ""
The value of the attribute
"""
name: str
type: str = ""
value: str = ""
class ImportNode(BaseModel):
"""
ImportNode is a pydantic model that represents an import statement.
Attributes:
name: str
The name of the import statement.
as_: str = ""
The alias of the import
"""
name: str
as_: str = ""
class ConstantNode(BaseModel):
"""
ConstantNode is a pydantic model that represents a constant.
Attributes:
value: str
The value of the constant.
"""
value: str
class FunctionNode(BaseModel):
"""
FunctionNode is a pydantic model that represents a function.
Attributes:
name: str
The name of the function.
docs: str = ""
The docstring of the function.
args: list[ArgNode] = []
The arguments of the function.
return_: ReturnNode = None
The return value of the function.
decorators: list[str] = []
The decorators of the function.
is_async: bool = False
Whether the function is asynchronous.
"""
name: str
docs: Optional[Docstring] = None
posonlyargs: list[ArgNode] = []
args: list[ArgNode] = []
kwonlyargs: list[ArgNode] = []
kw_defaults: list[ConstantNode] = []
defaults: list[ConstantNode] = []
return_: str = Field(TypeHint.NO_RETURN, alias="return")
decorators: list[str] = []
src: str
is_async: bool = False
def is_private(self):
"""
Check if the function or method is private.
Returns:
bool: True if the function or method is private, False otherwise.
"""
return self.name.startswith("_")
def is_builtin(self):
"""
Check if the function or method is a builtin function or method.
Returns:
bool: True if the function or method is a builtin function or method, False otherwise.
"""
return self.name.startswith("__") and self.name.endswith("__")
def markdown(self, lang: str, indent: int = 0, is_classmethod: bool = False) -> str:
"""
Args:
indent: int
The number of spaces to indent the markdown.
is_classmethod: bool
lang: str
The language of the
Returns:
markdown style document
"""
self.complete_default_args()
PREFIX = "" * indent
if is_classmethod:
PREFIX = "- #"
md = ""
# 装饰器部分
if len(self.decorators) > 0:
for decorator in self.decorators:
md += PREFIX + f"### `@{decorator}`\n"
if self.is_async:
md += PREFIX + "### *async def* "
else:
md += PREFIX + "### *def* "
md += f"`{self.name}(" # code start
# 配对位置参数和位置参数默认值，无默认值用TypeHint.NO_DEFAULT
args: list[str] = [] # 可直接", ".join(args)得到位置参数部分
arg_i = 0
if len(self.posonlyargs) > 0:
for arg in self.posonlyargs:
arg_text = f"{arg.name}"
if arg.type != TypeHint.NO_TYPEHINT:
arg_text += f": {arg.type}"
arg_default = self.defaults[arg_i].value
if arg_default != TypeHint.NO_DEFAULT:
arg_text += f" = {arg_default}"
args.append(arg_text)
arg_i += 1
# 加位置参数分割符 /
args.append("/")
for arg in self.args:
arg_text = f"{arg.name}"
if arg.type != TypeHint.NO_TYPEHINT:
arg_text += f": {arg.type}"
arg_default = self.defaults[arg_i].value
if arg_default != TypeHint.NO_DEFAULT:
arg_text += f" = {arg_default}"
args.append(arg_text)
arg_i += 1
if len(self.kwonlyargs) > 0:
# 加关键字参数分割符 *
args.append("*")
for arg, kw_default in zip(self.kwonlyargs, self.kw_defaults):
arg_text = f"{arg.name}"
if arg.type != TypeHint.NO_TYPEHINT:
arg_text += f": {arg.type}"
if kw_default.value != TypeHint.NO_DEFAULT:
arg_text += f" = {kw_default.value}"
args.append(arg_text)
md += ", ".join(args) + ")"
md += "`\n\n" # code end
"""此处预留docstring"""
if self.docs is not None:
md += f"\n{self.docs.markdown(lang, indent)}\n"
else:
pass
# 源码展示
md += PREFIX + f"\n<details>\n<summary>{get_text(lang, 'src')}</summary>\n\n```python\n{self.src}\n```\n</details>\n\n"
return md
def complete_default_args(self):
"""
补全位置参数默认值，用无默认值插入
Returns:
"""
num = len(self.args) + len(self.posonlyargs) - len(self.defaults)
self.defaults = [ConstantNode(value=TypeHint.NO_DEFAULT) for _ in range(num)] + self.defaults
def __str__(self):
return f"def {self.name}({', '.join([f'{arg.name}: {arg.type} = {arg.default}' for arg in self.args])}) -> {self.return_}"
class ClassNode(BaseModel):
"""
ClassNode is a pydantic model that represents a class.
Attributes:
name: str
The name of the class.
docs: str = ""
The docstring of the class.
attrs: list[AttrNode] = []
The attributes of the class.
methods: list[MethodNode] = []
The methods of the class.
inherit: list["ClassNode"] = []
The classes that the class inherits from
"""
name: str
docs: Optional[Docstring] = None
attrs: list[AttrNode] = []
methods: list[FunctionNode] = []
inherit: list["ClassNode"] = []