gyomu-python-analysis 0.2.0__py3-none-any.whl

gyomu_python_analysis/analysis/analyzers/docstring.py

@@ -0,0 +1,288 @@
+import ast
+import re
+from textwrap import dedent
+
+from griffe import (
+    Docstring,
+    DocstringNamedElement,
+    DocstringSectionAdmonition,
+    DocstringSectionKind,
+)
+from griffe import DocstringSection as GriffeSection
+from griffe import DocstringSectionExamples as GriffeSectionExamples
+from griffe import DocstringSectionParameters as GriffeSectionParameters
+from griffe import DocstringSectionRaises as GriffeSectionRaises
+from griffe import DocstringSectionReturns as GriffeSectionReturns
+from griffe import (
+    DocstringSectionText as GriffeSectionText,
+)
+from gyomu_infra.logger import logger
+from gyomu_schema.schemas.python.docstring import (
+    DocstringAnalysis,
+    DocstringCommon,
+    DocstringCustomSection,
+    DocstringExamplesSection,
+    DocstringExamplesSectionItem,
+    DocstringGyomuContextSection,
+    DocstringNotesSection,
+    DocstringParametersSection,
+    DocstringParametersSectionItem,
+    DocstringRaisesSection,
+    DocstringRaisesSectionItem,
+    DocstringReturnsSection,
+    DocstringReturnsSectionItem,
+    DocstringSection,
+    DocstringStyle,
+    DocstringTextSection,
+)
+
+from gyomu_python_analysis.analysis.analyzers.context import SymbolContext
+from gyomu_python_analysis.analysis.analyzers.types import analyze_type
+
+_CUSTOM_SECTION_PATTERN = re.compile(r"^(?P<name>[A-Za-z][A-Za-z0-9 _-]*):\s*$")
+
+
+def _analyze_parameters(
+    section: GriffeSectionParameters, context: SymbolContext
+) -> DocstringParametersSection:
+    parameters: list[DocstringParametersSectionItem] = []
+    for parameter in section.value:
+        param_type = analyze_type(parameter.annotation, context)
+        parameters.append(
+            DocstringParametersSectionItem(
+                name=parameter.name,
+                description=parameter.description,
+                type=param_type if param_type is None else param_type.text,
+            )
+        )
+    return DocstringParametersSection(items=tuple(parameters))
+
+
+def _analyze_raises(
+    section: GriffeSectionRaises, context: SymbolContext
+) -> DocstringRaisesSection:
+    raises: list[DocstringRaisesSectionItem] = []
+    for raiseItem in section.value:
+        raise_type = analyze_type(raiseItem.annotation, context)
+        raises.append(
+            DocstringRaisesSectionItem(
+                description=raiseItem.description,
+                type="" if raise_type is None else raise_type.text,
+            )
+        )
+    return DocstringRaisesSection(items=tuple(raises))
+
+
+def _analyze_examples(section: GriffeSectionExamples) -> DocstringExamplesSection:
+    examples: list[DocstringExamplesSectionItem] = []
+    for exampleItem in section.value:
+        for item in exampleItem:
+            item_text: str
+            if (
+                isinstance(item, str)
+                and item is not DocstringSectionKind.text
+                and item is not DocstringSectionKind.examples
+            ):
+                item_text = item
+                examples.append(DocstringExamplesSectionItem(value=item_text))
+    return DocstringExamplesSection(items=tuple(examples))
+
+
+def _analyze_returns(
+    section: GriffeSectionReturns, context: SymbolContext
+) -> DocstringReturnsSection:
+    # Gyomu models a Returns section as a single item.
+    # Google-style docstrings are expected to contain at most one return item.
+    if len(section.value) > 1:
+        logger.warning(
+            "Multiple return items are not supported; using the first item: %r",
+            section.value,
+        )
+
+    return_item = section.value[0]
+    print(return_item.as_dict())
+    return_type = analyze_type(return_item.annotation, context)
+
+    return DocstringReturnsSection(
+        item=DocstringReturnsSectionItem(
+            description=_extract_return_description(return_item.description),
+            type=return_type.text if return_type is not None else None,
+        )
+    )
+
+
+def _extract_return_description(description: str) -> str:
+    description = description.strip()
+
+    if ":" not in description:
+        return description
+
+    type_text, return_description = description.split(":", 1)
+    type_text = type_text.strip()
+    return_description = return_description.strip()
+
+    if not _looks_like_type(type_text):
+        return description
+
+    return return_description
+
+
+def _looks_like_type(text: str) -> bool:
+    try:
+        ast.parse(text, mode="eval")
+        return True
+    except SyntaxError:
+        return False
+
+
+def _analyze_admonition(section: DocstringSectionAdmonition) -> DocstringSection:
+    return _parse_custom_section(title=section.title, value=section.value.description)
+
+
+def _parse_custom_section(title: str | None, value: str) -> DocstringSection:
+    if title == "Notes":
+        return DocstringNotesSection(value=value)
+    elif title == "Gyomu Context":
+        return DocstringGyomuContextSection(value=value)
+    else:
+        return DocstringCustomSection(
+            title=title if title is not None else "",
+            value=value,
+        )
+
+
+def _is_indented(line: str) -> bool:
+    return bool(line) and line[0].isspace()
+
+
+def parse_text_section(
+    text: str,
+) -> tuple[str, str, list[DocstringSection]]:
+    lines = text.splitlines()
+
+    while lines and not lines[0].strip():
+        lines.pop(0)
+
+    while lines and not lines[-1].strip():
+        lines.pop()
+
+    if not lines:
+        return "", "", []
+
+    # First paragraph = summary.
+    summary_lines: list[str] = []
+
+    index = 0
+    while index < len(lines) and lines[index].strip():
+        summary_lines.append(lines[index])
+        index += 1
+
+    summary = "\n".join(summary_lines).strip()
+
+    # Skip blank lines between summary and the rest.
+    while index < len(lines) and not lines[index].strip():
+        index += 1
+
+    description_lines: list[str] = []
+    custom_sections: list[DocstringSection] = []
+
+    while index < len(lines):
+        match = _CUSTOM_SECTION_PATTERN.match(lines[index])
+
+        if match and index + 1 < len(lines) and _is_indented(lines[index + 1]):
+            name = match.group("name")
+            index += 1
+
+            section_lines: list[str] = []
+
+            while index < len(lines):
+                if (
+                    _CUSTOM_SECTION_PATTERN.match(lines[index])
+                    and index + 1 < len(lines)
+                    and _is_indented(lines[index + 1])
+                ):
+                    break
+
+                section_lines.append(lines[index])
+                index += 1
+
+            section_text = "\n".join(section_lines)
+            section_text = dedent(section_text).strip()
+
+            custom_sections.append(
+                _parse_custom_section(
+                    title=name,
+                    value=section_text,
+                )
+            )
+            continue
+
+        description_lines.append(lines[index])
+        index += 1
+
+    description = "\n".join(description_lines).strip()
+
+    return summary, description, (custom_sections)
+
+
+def analyze_docstring(
+    doc: Docstring | None,
+    doc_common: DocstringCommon,
+    context: SymbolContext,
+) -> DocstringAnalysis | None:
+    if doc is None:
+        return None
+
+    # print(doc.source)
+    sections = doc.parse(parser="auto")
+
+    text_section: DocstringTextSection | None = None
+    parsed_sections: list[DocstringSection] = []
+    for section in sections:
+        if isinstance(section, GriffeSectionText):
+            text_section = DocstringTextSection(value=section.value)
+        elif isinstance(section, GriffeSectionParameters):
+            parsed_sections.append(_analyze_parameters(section, context))
+        elif isinstance(section, GriffeSectionRaises):
+            parsed_sections.append(_analyze_raises(section, context))
+        elif isinstance(section, GriffeSectionExamples):
+            parsed_sections.append(_analyze_examples(section))
+        elif isinstance(section, GriffeSectionReturns):
+            parsed_sections.append(_analyze_returns(section, context))
+        elif isinstance(section, DocstringSectionAdmonition):
+            parsed_sections.append(_analyze_admonition(section))
+        else:
+            print("Unknown Section in Docstring")
+            value = section.value
+            if isinstance(value, str):
+                print(section.as_dict())
+            elif isinstance(value, list):
+                for item in value:
+                    print(f"Kind: {section.kind}, item is list")
+                    if isinstance(
+                        item,
+                        (GriffeSection, DocstringNamedElement, GriffeSectionRaises),
+                    ):
+                        print(item.as_dict())
+                    else:
+                        print(item)
+            else:
+                print(section.as_dict())
+    if text_section:
+        summary, description, sections2 = parse_text_section(text_section.value)
+        return DocstringAnalysis(
+            **doc_common,
+            raw=doc.source,
+            summary=None if summary == "" else summary,
+            description=None if description == "" else description,
+            sections=tuple(parsed_sections if len(parsed_sections) > 0 else sections2),
+            style=DocstringStyle.GOOGLE,
+        )
+    return DocstringAnalysis(
+        **doc_common,
+        raw=doc.source,
+        summary=None,
+        description=None,
+        sections=tuple(parsed_sections),
+        style=DocstringStyle.GOOGLE,
+    )

gyomu_python_analysis/analysis/analyzers/expression/expr.py

@@ -0,0 +1,400 @@
+import ast
+
+from griffe import (
+    Expr,
+    ExprAttribute,
+    ExprBinOp,
+    ExprCall,
+    ExprConstant,
+    ExprDict,
+    ExprKeyword,
+    ExprList,
+    ExprName,
+    ExprSet,
+    ExprSubscript,
+    ExprTuple,
+)
+from gyomu_schema.schemas.python.type.structure import (
+    EllipsisStructureAnalysis,
+    LiteralValue,
+    NameStructureAnalysis,
+    NoneStructureAnalysis,
+    TypeStructureKind,
+    UnknownStructureAnalysis,
+)
+from gyomu_schema.schemas.python.type.type_analysis import (
+    ArrayStructureAnalysis,
+    AttributeStructureAnalysis,
+    CallableStructureAnalysis,
+    CallStructureAnalysis,
+    DictionaryStructureAnalysis,
+    ExpressionAnalysis,
+    GenericsStructureAnalysis,
+    KeywordStructureAnalysis,
+    LiteralStructureAnalysis,
+    SetStructureAnalysis,
+    TupleStructureAnalysis,
+    TypeExpression,
+    UnionStructureAnalysis,
+)
+
+from gyomu_python_analysis.analysis.analyzers.context import SymbolContext
+from gyomu_python_analysis.analysis.analyzers.dependency import register_dependency
+
+
+def analyze_expression(
+    expression: Expr, context: SymbolContext, need_registration_dependency: bool = True
+) -> ExpressionAnalysis:
+    if isinstance(expression, ExprName):
+        return analyze_expression_name(
+            expression, context, need_registration_dependency
+        )
+    if isinstance(expression, ExprBinOp):
+        return _analyze_expression_binary_operation(expression, context)
+    if isinstance(expression, ExprSubscript):
+        return analyze_subscript(expression, context)
+    if isinstance(expression, ExprAttribute):
+        return _analyze_expression_attribute(expression, context)
+    if isinstance(expression, ExprTuple):
+        return analyze_tuple(expression, context)
+    if isinstance(expression, ExprList):
+        return analyze_array(expression, context)
+    if isinstance(expression, ExprDict):
+        return analyze_dictionary(expression, context)
+    if isinstance(expression, ExprSet):
+        return analyze_set(expression, context)
+    if isinstance(expression, ExprKeyword):
+        return _analyze_keyword(expression, context)
+    if isinstance(expression, ExprCall):
+        return _analyze_call(expression, context)
+
+    else:
+        print(f"Unsupported expression type: {type(expression)}")
+        print(expression.as_dict())
+        return UnknownStructureAnalysis()
+    # elif isinstance(expression, ExprSubscript):
+    #     return analyze_expression_subscript(expression)
+    # else:
+    #     raise ValueError(f"Unsupported expression type: {type(expression)}")
+
+
+def analyze_expression_constant(
+    expression: ExprConstant, context: SymbolContext
+) -> TypeExpression:
+    return analyze_type_expression(expression.value, context)
+
+
+def _analyze_expression_attribute(
+    expression: ExprAttribute, context: SymbolContext
+) -> AttributeStructureAnalysis:
+    # print(
+    #     dict(
+    #         canonical_path=expression.canonical_path,
+    #         values=expression.values,
+    #         path=expression.path,
+    #         canonical_name=expression.canonical_name,
+    #         is_classvar=expression.is_classvar,
+    #         is_generator=expression.is_generator,
+    #         is_iterator=expression.is_iterator,
+    #         is_tuple=expression.is_tuple,
+    #     )
+    # )
+    return AttributeStructureAnalysis(
+        values=tuple(
+            analyzed
+            for index, value in enumerate(expression.values)
+            if (
+                analyzed := analyze_type_expression(
+                    value,
+                    context,
+                    need_registration_dependency=index == 0,
+                )
+            )
+            is not None
+        )
+    )
+
+
+def _analyze_expression_binary_operation(
+    expression: ExprBinOp, context: SymbolContext
+) -> UnionStructureAnalysis | UnknownStructureAnalysis:
+    # print(
+    #     dict(
+    #         name=expression.name,
+    #         member=expression.member,
+    #         path=expression.path,
+    #         canonical_name=expression.canonical_name,
+    #         is_enum_class=expression.is_enum_class,
+    #         is_enum_instance=expression.is_enum_instance,
+    #         is_enum_value=expression.is_enum_value,
+    #         is_type_parameter=expression.is_type_parameter,
+    #     )
+    # )
+    match expression.operator:
+        case "|":
+            return _analyze_union(expression, context)
+        case _:
+            print(f"Unsupported operation: {type(expression)}")
+            print(expression.as_dict())
+            return UnknownStructureAnalysis()
+
+
+def _analyze_union(
+    expression: ExprBinOp, context: SymbolContext
+) -> UnionStructureAnalysis:
+    types: list[TypeExpression] = []
+
+    def append_union_types(value: str | Expr) -> None:
+        if isinstance(value, ExprBinOp) and value.operator == "|":
+            append_union_types(value.left)
+            append_union_types(value.right)
+            return
+
+        analyzed = analyze_type_expression(value, context)
+        types.append(analyzed)
+
+    append_union_types(expression)
+
+    return UnionStructureAnalysis(
+        types=tuple(types),
+    )
+
+
+# def _analyze_type_internal(annotation: str | Expr) -> TypeAnalysis:
+#     if isinstance(annotation, str):
+#         print(annotation)
+#         if annotation == "None":
+#             return TypeAnalysis(text=annotation, structure=NoneStructureAnalysis())
+#         return TypeAnalysis(text=annotation)
+#     if isinstance(annotation, Expr):
+#         text = str(annotation)
+#         print(annotation.as_dict())
+#         return TypeAnalysis(text=text, structure=analyze_expression(annotation))
+
+
+def analyze_subscript(
+    expression: ExprSubscript, context: SymbolContext
+) -> ExpressionAnalysis:
+    # print(expression.as_dict())
+    # print(f"canonical_name  : {expression.canonical_name}")
+    # print(f"canonical_path  : {expression.canonical_path}")
+    # print(f"classname : {expression.classname}")
+    # print(f"is_classvar: {expression.is_classvar}")
+    # print(f"is_generator: {expression.is_generator}")
+    # print(f"is_iterator: {expression.is_iterator}")
+    # print(f"is_tuple : {expression.is_tuple}")
+
+    left = expression.left
+    slice = expression.slice
+    if isinstance(left, ExprName):
+        if left.name == "Literal":
+            return analyze_literal(slice, context)
+        elif left.name == "list":
+            return _analyze_array_from_subscript(slice, context)
+        elif left.name == "dict":
+            return _analyze_dictionary_from_subscript(slice, context)
+        elif left.name == "Callable":
+            return _analyze_callable_from_subscript(slice, context)
+        elif left.name == "tuple":
+            return _analyze_tuple_from_subscript(slice, context)
+        elif left.name == "set":
+            return _analyze_set_from_subscript(slice, context)
+
+    param = analyze_type_expression(slice, context)
+    if not isinstance(param, LiteralValue):
+        parameters: list[TypeExpression] = []
+        if isinstance(param, TupleStructureAnalysis):
+            parameters = list(param.elements)
+        elif isinstance(param, NameStructureAnalysis):
+            parameters.append(param)
+        else:
+            parameters.append(param)
+        return GenericsStructureAnalysis(
+            base=analyze_type_expression(left, context), parameters=tuple(parameters)
+        )
+    print(f"Unsupported expression type in subscript: {type(expression)}")
+    print(expression.as_dict())
+    return UnknownStructureAnalysis()
+
+
+def analyze_dictionary(
+    expression: ExprDict, context: SymbolContext
+) -> DictionaryStructureAnalysis:
+    assert len(expression.keys) == 1
+    assert expression.keys[0]
+    assert len(expression.values) == 1
+    return DictionaryStructureAnalysis(
+        keys=analyze_type_expression(expression.keys[0], context),
+        values=analyze_type_expression(expression.values[0], context),
+    )
+
+
+def _analyze_dictionary_from_subscript(
+    slice: str | Expr, context: SymbolContext
+) -> DictionaryStructureAnalysis:
+    assert isinstance(slice, ExprTuple)
+    assert len(slice.elements) == 2
+    return DictionaryStructureAnalysis(
+        keys=analyze_type_expression(slice.elements[0], context),
+        values=analyze_type_expression(slice.elements[1], context),
+    )
+
+
+def analyze_array(
+    expression: ExprList, context: SymbolContext
+) -> ArrayStructureAnalysis:
+    return ArrayStructureAnalysis(
+        element=analyze_type_expression(expression.elements[0], context)
+    )
+
+
+def _analyze_callable_from_subscript(
+    slice: str | Expr, context: SymbolContext
+) -> CallableStructureAnalysis:
+    assert isinstance(slice, ExprTuple)
+    assert len(slice.elements) == 2
+    parameters_expression = slice.elements[0]
+    if isinstance(parameters_expression, ExprList):
+        parameters: list[TypeExpression] = []
+        for expression in parameters_expression.elements:
+            analyzed = analyze_type_expression(expression, context)
+            parameters.append(analyzed)
+
+        return CallableStructureAnalysis(
+            parameters=tuple(parameters),
+            return_type=analyze_type_expression(slice.elements[1], context),
+        )
+    assert isinstance(parameters_expression, str)
+    assert parameters_expression == "..."
+    return CallableStructureAnalysis(
+        parameters=None,
+        return_type=analyze_type_expression(slice.elements[1], context),
+    )
+
+
+def _analyze_array_from_subscript(
+    slice: str | Expr, context: SymbolContext
+) -> ArrayStructureAnalysis:
+    return ArrayStructureAnalysis(element=analyze_type_expression(slice, context))
+
+
+def analyze_literal(
+    slice: str | Expr, context: SymbolContext
+) -> LiteralStructureAnalysis:
+
+    return LiteralStructureAnalysis(value=analyze_type_expression(slice, context))
+
+
+def analyze_type_expression(
+    value: str | Expr, context: SymbolContext, need_registration_dependency: bool = True
+) -> TypeExpression:
+    if isinstance(value, str):
+        parsed = ast.literal_eval(value)
+        if parsed is None:
+            return NoneStructureAnalysis()
+        if parsed is Ellipsis:
+            return EllipsisStructureAnalysis()
+        return LiteralValue(value=parse_literal_value(value))
+    return analyze_expression(value, context, need_registration_dependency)
+
+
+def parse_literal_value(value: str) -> str | int | bool:
+    parsed = ast.literal_eval(value)
+    if isinstance(parsed, bool):
+        return parsed
+
+    if isinstance(parsed, int):
+        return parsed
+
+    if isinstance(parsed, str):
+        return parsed
+
+    raise ValueError(f"Unsupported literal value: {value}")
+
+
+def _analyze_tuple_from_subscript(
+    slice: str | Expr, context: SymbolContext
+) -> TupleStructureAnalysis:
+    assert isinstance(slice, ExprTuple)
+
+    return analyze_tuple(slice, context)
+
+
+def analyze_tuple(
+    expression: ExprTuple, context: SymbolContext
+) -> TupleStructureAnalysis:
+    variable_length = False
+    elements: list[TypeExpression] = []
+
+    for value in expression.elements:
+        if value == "...":
+            variable_length = True
+            continue
+
+        analyzed = analyze_type_expression(value, context)
+        if analyzed is not None:
+            elements.append(analyzed)
+
+    return TupleStructureAnalysis(
+        elements=tuple(elements),
+        variable_length=variable_length,
+    )
+
+
+def _analyze_set_from_subscript(
+    slice: str | Expr, context: SymbolContext
+) -> SetStructureAnalysis:
+    return SetStructureAnalysis(element_type=analyze_type_expression(slice, context))
+
+
+def analyze_set(expression: ExprSet, context: SymbolContext) -> SetStructureAnalysis:
+    return SetStructureAnalysis(
+        element_type=analyze_type_expression(expression.elements[0], context)
+    )
+
+
+def analyze_expression_name(
+    expression: ExprName, context: SymbolContext, need_registration_dependency: bool
+) -> NameStructureAnalysis | NoneStructureAnalysis:
+    # print(
+    #     dict(
+    #         name=expression.name,
+    #         member=expression.member,
+    #         path=expression.path,
+    #         canonical_name=expression.canonical_name,
+    #         is_enum_class=expression.is_enum_class,
+    #         is_enum_instance=expression.is_enum_instance,
+    #         is_enum_value=expression.is_enum_value,
+    #         is_type_parameter=expression.is_type_parameter,
+    #     )
+    # )
+    if expression.name == "None":
+        return NoneStructureAnalysis(
+            kind=TypeStructureKind.NONE,
+        )
+    if need_registration_dependency:
+        register_dependency(context.declaration, expression.name, context)
+    return NameStructureAnalysis(
+        name=expression.name,
+    )
+
+
+def _analyze_keyword(
+    expression: ExprKeyword, context: SymbolContext
+) -> KeywordStructureAnalysis:
+    name = expression.name
+    value = analyze_type_expression(expression.value, context)
+    return KeywordStructureAnalysis(name=name, value=value)
+
+
+def _analyze_call(
+    expression: ExprCall, context: SymbolContext
+) -> CallStructureAnalysis:
+    func = analyze_expression(expression.function, context)
+    arguments: list[TypeExpression] = []
+
+    for value in expression.arguments:
+        analyzed = analyze_type_expression(value, context)
+        arguments.append(analyzed)
+
+    return CallStructureAnalysis(function=func, arguments=tuple(arguments))