gyomu-docstring 0.2.0__py3-none-any.whl

gyomu_docstring/update/apply_file_update.py

@@ -0,0 +1,21 @@
+from gyomu_docstring.update.docstring.file_update_plan import FileUpdatePlan
+
+
+def apply_file_update_plan(
+    source: str,
+    plan: FileUpdatePlan,
+) -> str:
+    result = source
+
+    for item in sorted(
+        plan.items,
+        key=lambda item: item.location.start_offset,
+        reverse=True,
+    ):
+        result = (
+            result[: item.location.start_offset]
+            + item.new_text
+            + result[item.location.end_offset :]
+        )
+
+    return result

gyomu_docstring/update/apply_merge.py

@@ -0,0 +1,407 @@
+from gyomu_python_analysis.error.update import UpdateError
+from gyomu_schema.schemas.python.docstring import (
+    DocstringAnalysis,
+    DocstringParametersSection,
+    DocstringParametersSectionItem,
+    DocstringRaisesSection,
+    DocstringRaisesSectionItem,
+    DocstringReturnsSection,
+    DocstringReturnsSectionItem,
+    DocstringSection,
+    DocstringStyle,
+)
+from gyomu_schema.schemas.python.file_analysis import FileAnalysisContext
+from gyomu_schema.schemas.python.location import SourceLocation
+from gyomu_schema.schemas.python.symbol_base import DeclarationKind
+from gyomu_schema.schemas.python.types import DeclarationIdentity, PythonPath
+from returns.result import Failure, Result, Success
+
+from gyomu_docstring.update.docstring.merge_plan import (
+    DeleteAction,
+    MergeAction,
+    MergePlan,
+    ParamMergePlan,
+    PreserveAction,
+    RaiseMergePlan,
+    ReplaceAction,
+    ReturnActionValue,
+)
+from gyomu_docstring.update.docstring.updated_docstring import UpdatedDocstring
+
+
+def apply_merge_plans(
+    context: FileAnalysisContext, plans: tuple[MergePlan, ...]
+) -> Result[tuple[UpdatedDocstring, ...], UpdateError]:
+    results: list[UpdatedDocstring] = []
+
+    for plan in plans:
+        result = apply_merge_plan(context, plan)
+
+        if isinstance(result, Failure):
+            return result
+
+        results.append(result.unwrap())
+
+    return Success(tuple(results))
+
+
+def apply_merge_plan(
+    context: FileAnalysisContext, plan: MergePlan
+) -> Result[UpdatedDocstring, UpdateError]:
+    existing_docstring = context.metadata.parsed_docstring.get(plan.identity)
+    existing_symbol_or_method = context.metadata.symbols.get(plan.identity)
+
+    if existing_symbol_or_method is None:
+        return Failure(
+            UpdateError(
+                "Symbol/Method not found",
+                file_path=context.analysis.module_name,
+                phase="apply-merge",
+                identity=plan.identity,
+            )
+        )
+    if (
+        existing_symbol_or_method.location is None
+        or existing_symbol_or_method.indent is None
+    ):
+        return Failure(
+            UpdateError(
+                "Constructor private variable should not be here",
+                file_path=context.analysis.module_name,
+                phase="apply-merge",
+                identity=plan.identity,
+            )
+        )
+
+    summary = _merge_summary(plan.summary, existing_docstring)
+    description = _merge_description(plan.description, existing_docstring)
+
+    arguments_result = _merge_arguments(
+        file_path=context.analysis.module_name,
+        identity=plan.identity,
+        plans=plan.params,
+        existing_docstring=existing_docstring,
+    )
+    if isinstance(arguments_result, Failure):
+        return arguments_result
+
+    returns = _merge_returns(
+        plan.returns,
+        existing_docstring,
+    )
+
+    raises_result = _merge_raises(
+        file_path=context.analysis.module_name,
+        identity=plan.identity,
+        plans=plan.raises,
+        existing_docstring=existing_docstring,
+    )
+    if isinstance(raises_result, Failure):
+        return raises_result
+
+    sections = _merge_sections(
+        existing_docstring=existing_docstring,
+        arguments=arguments_result.unwrap(),
+        returns=returns,
+        raises=raises_result.unwrap(),
+    )
+    new_location = (
+        existing_docstring.location if existing_docstring is not None else None
+    )
+    if new_location is None:
+        new_location = SourceLocation(
+            start_line=existing_symbol_or_method.location.start_line,
+            end_line=existing_symbol_or_method.location.end_line,
+            start_offset=existing_symbol_or_method.location.end_offset,
+            end_offset=existing_symbol_or_method.location.end_offset,
+            start_column=existing_symbol_or_method.location.start_column,
+            end_column=existing_symbol_or_method.location.start_column,
+        )
+
+    new_indent = existing_docstring.indent if existing_docstring is not None else None
+
+    if new_indent is None:
+        if existing_symbol_or_method.kind in (
+            DeclarationKind.CLASS,
+            DeclarationKind.FUNCTION,
+            DeclarationKind.METHOD,
+        ):
+            new_indent = existing_symbol_or_method.indent + 4
+        else:
+            new_indent = existing_symbol_or_method.indent
+
+    updated_docstring = DocstringAnalysis(
+        raw=existing_docstring.raw if existing_docstring is not None else "",
+        summary=summary,
+        description=description,
+        style=(
+            existing_docstring.style
+            if existing_docstring is not None
+            else DocstringStyle.GOOGLE
+        ),
+        location=new_location,
+        sections=sections,
+        indent=new_indent,
+    )
+
+    return Success(
+        UpdatedDocstring(
+            identity=plan.identity,
+            docstring=updated_docstring,
+        )
+    )
+
+
+def _merge_sections(
+    existing_docstring: DocstringAnalysis | None,
+    arguments: tuple[DocstringParametersSectionItem, ...],
+    returns: DocstringReturnsSectionItem | None,
+    raises: tuple[DocstringRaisesSectionItem, ...],
+) -> tuple[DocstringSection, ...]:
+    existing_sections = (
+        existing_docstring.sections if existing_docstring is not None else ()
+    )
+
+    sections: list[DocstringSection] = []
+
+    arguments_added = False
+    returns_added = False
+    raises_added = False
+
+    for section in existing_sections:
+        match section:
+            case DocstringParametersSection():
+                if arguments:
+                    sections.append(DocstringParametersSection(items=arguments))
+                arguments_added = True
+
+            case DocstringReturnsSection():
+                if returns is not None:
+                    sections.append(DocstringReturnsSection(item=returns))
+                returns_added = True
+
+            case DocstringRaisesSection():
+                if raises:
+                    sections.append(DocstringRaisesSection(items=raises))
+                raises_added = True
+
+            case _:
+                sections.append(section)
+
+    if arguments and not arguments_added:
+        sections.append(DocstringParametersSection(items=arguments))
+
+    if returns is not None and not returns_added:
+        sections.append(DocstringReturnsSection(item=returns))
+
+    if raises and not raises_added:
+        sections.append(DocstringRaisesSection(items=raises))
+
+    return tuple(sections)
+
+
+def _merge_summary(
+    plan: MergeAction[str], existing_docstring: DocstringAnalysis | None
+) -> str | None:
+    match plan.type:
+        case "preserve":
+            if existing_docstring is None:
+                return None
+            return existing_docstring.summary
+        case "delete":
+            return None
+        case "replace":
+            return plan.value
+
+
+def _merge_description(
+    plan: MergeAction[str], existing_docstring: DocstringAnalysis | None
+) -> str | None:
+    match plan.type:
+        case "preserve":
+            if existing_docstring is None:
+                return None
+            return existing_docstring.description
+        case "delete":
+            return None
+        case "replace":
+            return plan.value
+
+
+def _find_section[T: DocstringSection](
+    existing_docstring: DocstringAnalysis | None, section_type: type[T]
+) -> T | None:
+    if existing_docstring is None:
+        return None
+    existing_parameters = next(
+        (
+            section
+            for section in existing_docstring.sections
+            if isinstance(section, section_type)
+        ),
+        None,
+    )
+    return existing_parameters
+
+
+def _merge_arguments(
+    file_path: PythonPath,
+    identity: DeclarationIdentity,
+    plans: tuple[ParamMergePlan, ...],
+    existing_docstring: DocstringAnalysis | None,
+) -> Result[
+    tuple[DocstringParametersSectionItem, ...],
+    UpdateError,
+]:
+    parameters_section = _find_section(existing_docstring, DocstringParametersSection)
+    existing_parameters_by_name = (
+        {item.name: item for item in parameters_section.items}
+        if parameters_section is not None
+        else {}
+    )
+
+    merged: list[tuple[int, DocstringParametersSectionItem]] = []
+
+    for plan in plans:
+        existing_param = existing_parameters_by_name.get(plan.name)
+
+        match plan.action:
+            case PreserveAction():
+                if existing_param is not None:
+                    merged.append((plan.sort_order, existing_param))
+
+            case DeleteAction():
+                pass
+
+            case ReplaceAction(value=value):
+                if (
+                    existing_param is None
+                    and value.parameter_type is None
+                    and value.description is None
+                ):
+                    return Failure(
+                        UpdateError(
+                            file_path=file_path,
+                            message="Planned Argument doesn not have valid Argument",
+                            phase="update-plan",
+                            details={"plannedParameter": plan},
+                            identity=identity,
+                        )
+                    )
+
+                merged.append(
+                    (
+                        plan.sort_order,
+                        DocstringParametersSectionItem(
+                            name=plan.name,
+                            type=(
+                                value.parameter_type
+                                if value.parameter_type is not None
+                                else existing_param.type
+                                if existing_param is not None
+                                else None
+                            ),
+                            description=(
+                                value.description
+                                if value.description is not None
+                                else existing_param.description
+                                if existing_param is not None
+                                else ""
+                            ),
+                        ),
+                    )
+                )
+
+    merged.sort(key=lambda item: item[0])
+
+    return Success(tuple(item for _, item in merged))
+
+
+def _merge_returns(
+    plan: MergeAction[ReturnActionValue], existing_docstring: DocstringAnalysis | None
+) -> DocstringReturnsSectionItem | None:
+    returns_section = _find_section(existing_docstring, DocstringReturnsSection)
+    existing_item = returns_section.item if returns_section is not None else None
+    match plan.type:
+        case "preserve":
+            if existing_item is None:
+                return None
+            return existing_item
+        case "delete":
+            return None
+        case "replace":
+            new_value = plan.value
+            return (
+                DocstringReturnsSectionItem(
+                    description=new_value.description,
+                    type=new_value.return_type
+                    if new_value.return_type is not None
+                    else existing_item.type
+                    if existing_item is not None
+                    else None,
+                )
+                if new_value.description is not None
+                else existing_item
+            )
+
+
+def _merge_raises(
+    file_path: PythonPath,
+    identity: DeclarationIdentity,
+    plans: tuple[RaiseMergePlan, ...],
+    existing_docstring: DocstringAnalysis | None,
+) -> Result[
+    tuple[DocstringRaisesSectionItem, ...],
+    UpdateError,
+]:
+    raises_section = _find_section(existing_docstring, DocstringRaisesSection)
+    existing_raises_by_type = (
+        {item.type: item for item in raises_section.items}
+        if raises_section is not None
+        else {}
+    )
+
+    merged: list[tuple[int, DocstringRaisesSectionItem]] = []
+
+    for plan in plans:
+        existing_raise = existing_raises_by_type.get(plan.exception_type)
+
+        match plan.action:
+            case PreserveAction():
+                if existing_raise is not None:
+                    merged.append((plan.sort_order, existing_raise))
+
+            case DeleteAction():
+                pass
+
+            case ReplaceAction(value=value):
+                if existing_raise is None and value.description is None:
+                    return Failure(
+                        UpdateError(
+                            file_path=file_path,
+                            message="Planned Raises doesn not have valid Raise Item",
+                            phase="update-plan",
+                            details={"plannedParameter": plan},
+                            identity=identity,
+                        )
+                    )
+
+                merged.append(
+                    (
+                        plan.sort_order,
+                        DocstringRaisesSectionItem(
+                            type=(value.exception_type),
+                            description=(
+                                value.description
+                                if value.description is not None
+                                else existing_raise.description
+                                if existing_raise is not None
+                                else ""
+                            ),
+                        ),
+                    )
+                )
+
+    merged.sort(key=lambda item: item[0])
+
+    return Success(tuple(item for _, item in merged))

gyomu_docstring/update/build_file_update.py

@@ -0,0 +1,286 @@
+import io
+import tokenize
+
+from gyomu_python_analysis.error.update import UpdateError
+from gyomu_schema.error.validation import ValidationError
+from gyomu_schema.schemas.python.class_analysis import ClassAnalysis, InnerClassAnalysis
+from gyomu_schema.schemas.python.file_analysis import FileAnalysisContext
+from gyomu_schema.schemas.python.function_analysis import FunctionAnalysis
+from gyomu_schema.schemas.python.method_analysis import MethodAnalysis
+from gyomu_schema.schemas.python.symbol import MemberAnalysis, SymbolAnalysis
+from returns.result import Failure, Result, Success
+
+from gyomu_docstring.update.docstring.file_update_plan import (
+    FileUpdatePlan,
+    FileUpdatePlanEntry,
+)
+from gyomu_docstring.update.docstring.rendered_symbol import (
+    RenderedSymbolDocstring,
+)
+
+
+def build_file_update_plan(
+    context: FileAnalysisContext,
+    rendered_docstrings: tuple[RenderedSymbolDocstring, ...],
+    source: str,
+) -> Result[FileUpdatePlan, UpdateError]:
+    entries_result = _build_file_update_plan_entries(
+        context=context,
+        rendered_docstrings=rendered_docstrings,
+        source=source,
+    )
+
+    if isinstance(entries_result, Failure):
+        return entries_result.alt(
+            UpdateError(
+                "fail to build file update plan entry",
+                file_path=context.analysis.module_name,
+                phase="update-plan",
+                identity=None,
+            ).chain
+        )
+
+    entries = entries_result.unwrap()
+
+    validation_result = validate_file_update_plan_entries(entries)
+
+    if isinstance(validation_result, Failure):
+        return validation_result.alt(
+            UpdateError(
+                "fail to validate file update plan entry",
+                file_path=context.analysis.module_name,
+                phase="update-plan",
+                identity=None,
+            ).chain
+        )
+
+    return Success(FileUpdatePlan(items=entries))
+
+
+def _build_file_update_plan_entries(
+    context: FileAnalysisContext,
+    rendered_docstrings: tuple[RenderedSymbolDocstring, ...],
+    source: str,
+) -> Result[tuple[FileUpdatePlanEntry, ...], ValidationError]:
+    entries: list[FileUpdatePlanEntry] = []
+
+    for rendered in rendered_docstrings:
+        result = build_file_update_plan_entry(
+            source=source,
+            context=context,
+            rendered=rendered,
+        )
+
+        if isinstance(result, Failure):
+            return result
+
+        entries.append(result.unwrap())
+
+    return Success(tuple(entries))
+
+
+def validate_file_update_plan_entries(
+    entries: tuple[FileUpdatePlanEntry, ...],
+) -> Result[None, ValidationError]:
+    sorted_entries = sorted(
+        entries,
+        key=lambda entry: entry.location.start_offset,
+    )
+
+    for entry in sorted_entries:
+        location = entry.location
+
+        if location.start_offset > location.end_offset:
+            return Failure(
+                ValidationError(
+                    f"Invalid file update range for "
+                    f"{entry.identity}: "
+                    f"start_offset ({location.start_offset}) is greater than "
+                    f"end_offset ({location.end_offset}).",
+                    context="gyomu_docstring.update.build_file_update.validate_file_update_plan_entries",
+                )
+            )
+
+    for previous, current in zip(sorted_entries, sorted_entries[1:], strict=False):
+        previous_end = previous.location.end_offset
+        current_start = current.location.start_offset
+
+        if current_start < previous_end:
+            return Failure(
+                ValidationError(
+                    f"Overlapping file update ranges: "
+                    f"{previous.identity} "
+                    f"[{previous.location.start_offset}, {previous_end}) and "
+                    f"{current.identity} "
+                    f"[{current_start}, {current.location.end_offset}).",
+                    context="gyomu_docstring.update.build_file_update.validate_file_update_plan_entries",
+                )
+            )
+
+    return Success(None)
+
+
+def build_file_update_plan_entry(
+    source: str,
+    context: FileAnalysisContext,
+    rendered: RenderedSymbolDocstring,
+) -> Result[FileUpdatePlanEntry, ValidationError]:
+    analysis = context.metadata.symbols.get(rendered.identity)
+
+    if analysis is None:
+        return Failure(
+            ValidationError(
+                message="Declaration Item Not Found",
+                context="gyomu_docstring.update.build_file_update.build_file_update_plan_entry",
+                details={"identity": rendered.identity},
+            )
+        )
+
+    if analysis.location is None or analysis.indent is None:
+        return Failure(
+            ValidationError(
+                message="Declation Item is constructor parameter",
+                context="gyomu_docstring.update.build_file_update.build_file_update_plan_entry",
+                details={"identity": rendered.identity},
+            )
+        )
+
+    if rendered.location.start_offset == rendered.location.end_offset:
+        return build_addition_entry(
+            source=source,
+            analysis=analysis,
+            rendered=rendered,
+        )
+
+    if rendered.docstring == "" or rendered.docstring is None:
+        return Success(
+            build_deletion_entry(
+                source=source,
+                rendered=rendered,
+            )
+        )
+
+    return Success(build_replacement_entry(rendered))
+
+
+def build_addition_entry(
+    source: str,
+    analysis: SymbolAnalysis | MemberAnalysis,
+    rendered: RenderedSymbolDocstring,
+) -> Result[FileUpdatePlanEntry, ValidationError]:
+    assert rendered.docstring
+    assert analysis.location
+
+    # TODO: 追加するdocstringはシンボルの直前ではなく、
+    # 定義ヘッダの直後に挿入する位置を計算する。
+    location = rendered.location
+    new_location = location.model_copy()
+    new_location.start_offset = location.start_offset
+
+    new_text = "\n" + rendered.docstring
+    if isinstance(
+        analysis, ClassAnalysis | FunctionAnalysis | InnerClassAnalysis | MethodAnalysis
+    ):
+        end_result = _get_declaration_definition_end_offset(source, analysis)
+        if isinstance(end_result, Failure):
+            return end_result
+        new_location.start_offset = end_result.unwrap()
+    new_location.end_offset = new_location.start_offset
+    return Success(
+        FileUpdatePlanEntry(
+            identity=rendered.identity, location=new_location, new_text=new_text
+        )
+    )
+
+
+def _get_declaration_definition_end_offset(
+    source: str,
+    analysis: ClassAnalysis | FunctionAnalysis | InnerClassAnalysis | MethodAnalysis,
+) -> Result[int, ValidationError]:
+    assert analysis.location
+
+    declaration_source = source[
+        analysis.location.start_offset : analysis.location.end_offset
+    ]
+
+    depth = 0
+
+    tokens = tokenize.generate_tokens(io.StringIO(declaration_source).readline)
+
+    for token in tokens:
+        if token.type != tokenize.OP:
+            continue
+
+        if token.string in ("(", "[", "{"):
+            depth += 1
+            continue
+
+        if token.string in (")", "]", "}"):
+            depth -= 1
+            continue
+
+        if token.string == ":" and depth == 0:
+            relative_offset = _get_line_offset(
+                declaration_source,
+                token.end,
+            )
+
+            # ':' の直後から改行までの空白・タブを飛ばす
+            while (
+                relative_offset < len(declaration_source)
+                and declaration_source[relative_offset] not in "\r\n"
+            ):
+                relative_offset += 1
+
+            return Success(analysis.location.start_offset + relative_offset)
+
+    return Failure(
+        ValidationError(
+            message="Declaration definition end not found",
+            context="gyomu_docstring.update.build_file_update._get_declaration_definition_end_offset",
+            details={"identity": analysis.identity},
+        )
+    )
+
+
+def _get_line_offset(
+    source: str,
+    position: tuple[int, int],
+) -> int:
+    row, column = position
+
+    lines = source.splitlines(keepends=True)
+
+    return sum(len(line) for line in lines[: row - 1]) + column
+
+
+def build_deletion_entry(
+    source: str, rendered: RenderedSymbolDocstring
+) -> FileUpdatePlanEntry:
+    location = rendered.location.model_copy()
+
+    start = location.start_offset
+    while start > 0 and source[start - 1] in " \t":
+        start -= 1
+
+    end = location.end_offset
+    while end < len(source) and source[end] in " \t":
+        end += 1
+
+    location.start_offset = start
+    location.end_offset = end
+
+    return FileUpdatePlanEntry(
+        identity=rendered.identity,
+        location=location,
+        new_text="",
+    )
+
+
+def build_replacement_entry(rendered: RenderedSymbolDocstring) -> FileUpdatePlanEntry:
+    assert rendered.docstring
+    return FileUpdatePlanEntry(
+        identity=rendered.identity,
+        location=rendered.location,
+        new_text=rendered.docstring,
+    )

gyomu_docstring/update/docstring/file_update_plan.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+from gyomu_schema.schemas.python.location import SourceLocation
+from gyomu_schema.schemas.python.types import DeclarationIdentity
+
+
+@dataclass
+class FileUpdatePlanEntry:
+    identity: DeclarationIdentity
+    location: SourceLocation
+    new_text: str
+
+
+@dataclass
+class FileUpdatePlan:
+    items: tuple[FileUpdatePlanEntry, ...]

gyomu_docstring/update/docstring/line.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class DocstringText:
+    text: str
+    type: Literal["text"] = "text"
+
+
+@dataclass(frozen=True)
+class DocstringBlank:
+    type: Literal["blank"] = "blank"
+
+
+@dataclass(frozen=True)
+class DocstringSectionItem:
+    text: str
+    type: Literal["section"] = "section"
+
+
+type DocstringLine = DocstringText | DocstringSectionItem | DocstringBlank

gyomu_docstring/update/docstring/merge_plan.py

@@ -0,0 +1,109 @@
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Literal
+
+from gyomu_schema.schemas.python.types import DeclarationIdentity
+from pydantic import BaseModel, Field
+
+
+@dataclass(frozen=True)
+class ReplaceAction[T]:
+    value: T
+    type: Literal["replace"] = "replace"
+
+
+@dataclass(frozen=True)
+class DeleteAction:
+    type: Literal["delete"] = "delete"
+
+
+@dataclass(frozen=True)
+class PreserveAction:
+    type: Literal["preserve"] = "preserve"
+
+
+type MergeAction[T] = ReplaceAction[T] | DeleteAction | PreserveAction
+
+
+class ConflictType(StrEnum):
+    HUMAN_EDITED = "human-edited"
+    MISSING_IN_NEW = "missing-in-new"
+    STRUCTURAL_MISMATCH = "structural-mismatch"
+
+
+# 一時的な定義（後でLLM側に）
+class ParamActionValue(BaseModel):
+    parameter_type: str | None = Field(description="Type hint of parameter")
+    description: str | None = Field(
+        description=(
+            "Complete replacement parameter metadata. "
+            "When using replace, provide the final parameter "
+            "documentation to be written."
+        )
+    )
+
+
+# 一時的な定義（後でLLM側に）
+class ReturnActionValue(BaseModel):
+    return_type: str | None = Field(description="Type hint of return")
+    description: str | None = Field(
+        description=(
+            "Complete replacement parameter metadata. "
+            "When using replace, provide the final return "
+            "documentation to be written."
+        )
+    )
+
+
+# 一時的な定義（後でLLM側に）
+class RaiseActionValue(BaseModel):
+    exception_type: str = Field(description="Type hint of exception")
+    description: str | None = Field(
+        description=(
+            "Complete replacement parameter metadata. "
+            "When using replace, provide the final raise "
+            "documentation to be written."
+        )
+    )
+
+
+@dataclass(frozen=True)
+class RaiseMergePlan:
+    exception_type: str
+    sort_order: int
+    action: MergeAction[RaiseActionValue]
+
+
+@dataclass(frozen=True)
+class ParamMergePlan:
+    name: str
+    sort_order: int
+    action: MergeAction[ParamActionValue]
+
+
+@dataclass(frozen=True)
+class MergeConflict:
+    symbol: str
+    type: ConflictType
+    message: str
+
+
+@dataclass(frozen=True)
+class MergePlan:
+    identity: DeclarationIdentity
+
+    summary: MergeAction[str]
+
+    description: MergeAction[str]
+
+    params: tuple[ParamMergePlan, ...]
+
+    returns: MergeAction[ReturnActionValue]
+
+    raises: tuple[RaiseMergePlan, ...]
+
+    conflicts: tuple[MergeConflict, ...]
+
+    confidence: float
+
+    average_confidence: float

gyomu_docstring/update/docstring/rendered_symbol.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+from gyomu_schema.schemas.python.location import SourceLocation
+from gyomu_schema.schemas.python.types import DeclarationIdentity
+
+
+@dataclass
+class RenderedSymbolDocstring:
+    identity: DeclarationIdentity
+    docstring: str | None
+    location: SourceLocation

gyomu_docstring/update/docstring/updated_docstring.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+from gyomu_schema.schemas.python.docstring import DocstringAnalysis
+from gyomu_schema.schemas.python.types import DeclarationIdentity
+
+
+@dataclass
+class UpdatedDocstring:
+    identity: DeclarationIdentity
+    docstring: DocstringAnalysis

gyomu_docstring/update/internal/render_line.py

@@ -0,0 +1,159 @@
+from gyomu_schema.schemas.python.docstring import (
+    DocstringCustomSection,
+    DocstringExamplesSection,
+    DocstringGyomuContextSection,
+    DocstringNotesSection,
+    DocstringParametersSection,
+    DocstringParametersSectionItem,
+    DocstringRaisesSection,
+    DocstringRaisesSectionItem,
+    DocstringReturnsSection,
+    DocstringSectionKind,
+    DocstringStyle,
+)
+
+from gyomu_docstring.update.docstring.line import (
+    DocstringBlank,
+    DocstringLine,
+    DocstringSectionItem,
+    DocstringText,
+)
+from gyomu_docstring.update.docstring.updated_docstring import UpdatedDocstring
+
+
+def render_docstring_lines(updated: UpdatedDocstring) -> tuple[DocstringLine, ...]:
+    lines: list[DocstringLine] = []
+    docstring = updated.docstring
+    if docstring.summary is not None:
+        lines.append(DocstringText(text=docstring.summary))
+
+    if docstring.description is not None:
+        lines.append(DocstringBlank())
+        lines.append(DocstringText(text=docstring.description))
+
+    for section in docstring.sections:
+        lines.append(DocstringBlank())
+        match section.kind:
+            case DocstringSectionKind.ARGS:
+                compute_args_tag(section, lines, docstring.style)
+            case DocstringSectionKind.RETURNS:
+                compute_returns_tag(section, lines, docstring.style)
+            case DocstringSectionKind.RAISES:
+                compute_raises_tag(section, lines, docstring.style)
+            case DocstringSectionKind.NOTES:
+                compute_notes_tag(section, lines, docstring.style)
+            case DocstringSectionKind.EXAMPLES:
+                compute_examples_tag(section, lines, docstring.style)
+            case DocstringSectionKind.GYOMU_CONTEXT:
+                compute_gyomu_context(section, lines, docstring.style)
+            case DocstringSectionKind.CUSTOM:
+                computeCustom_tag(section, lines, docstring.style)
+    return tuple(lines)
+
+
+def computeCustom_tag(
+    section: DocstringCustomSection,
+    lines: list[DocstringLine],
+    style: DocstringStyle,
+) -> None:
+    match style:
+        case DocstringStyle.GOOGLE:
+            lines.append(DocstringSectionItem(text=section.title + ":"))
+            lines.append(DocstringText(f"    {section.value}"))
+
+
+def compute_gyomu_context(
+    section: DocstringGyomuContextSection,
+    lines: list[DocstringLine],
+    style: DocstringStyle,
+) -> None:
+    match style:
+        case DocstringStyle.GOOGLE:
+            lines.append(DocstringSectionItem(text="Gyomu Context:"))
+            lines.append(DocstringText(f"    {section.value}"))
+
+
+def compute_examples_tag(
+    section: DocstringExamplesSection, lines: list[DocstringLine], style: DocstringStyle
+) -> None:
+
+    match style:
+        case DocstringStyle.GOOGLE:
+            lines.append(DocstringSectionItem(text="Examples:"))
+            for item in section.items:
+                lines.append(DocstringText(f"    {item.value}"))
+                lines.append(DocstringBlank())
+
+
+def compute_notes_tag(
+    section: DocstringNotesSection, lines: list[DocstringLine], style: DocstringStyle
+) -> None:
+    match style:
+        case DocstringStyle.GOOGLE:
+            lines.append(DocstringSectionItem(text="Notes:"))
+            lines.append(DocstringText(f"    {section.value}"))
+
+
+def compute_raises_tag(
+    section: DocstringRaisesSection, lines: list[DocstringLine], style: DocstringStyle
+) -> None:
+    if len(section.items) == 0:
+        return
+
+    lines.append(DocstringSectionItem(text=_get_raises_section_name(style)))
+    for item in section.items:
+        lines.append(DocstringText(_compute_raises_item(item, style)))
+
+
+def _get_raises_section_name(style: DocstringStyle) -> str:
+    match style:
+        case DocstringStyle.GOOGLE:
+            return "Raises:"
+
+
+def _compute_raises_item(
+    item: DocstringRaisesSectionItem, style: DocstringStyle
+) -> str:
+    match style:
+        case DocstringStyle.GOOGLE:
+            raise_type = f"{item.type}: " if item.type else ""
+            return f"    {raise_type}{item.description}"
+
+
+def compute_returns_tag(
+    section: DocstringReturnsSection, lines: list[DocstringLine], style: DocstringStyle
+) -> None:
+    item = section.item
+    match style:
+        case DocstringStyle.GOOGLE:
+            lines.append(DocstringSectionItem(text="Returns:"))
+            return_type = f"{item.type}: " if item.type else ""
+            lines.append(DocstringText(f"    {return_type}{item.description}"))
+
+
+def compute_args_tag(
+    section: DocstringParametersSection,
+    lines: list[DocstringLine],
+    style: DocstringStyle,
+) -> None:
+    if len(section.items) == 0:
+        return
+
+    lines.append(DocstringSectionItem(text=_get_args_section_name(style)))
+    for parameter in section.items:
+        lines.append(DocstringText(_compute_args_item(parameter, style)))
+
+
+def _get_args_section_name(style: DocstringStyle) -> str:
+    match style:
+        case DocstringStyle.GOOGLE:
+            return "Args:"
+
+
+def _compute_args_item(
+    parameter: DocstringParametersSectionItem, style: DocstringStyle
+) -> str:
+    match style:
+        case DocstringStyle.GOOGLE:
+            param_type = f" ({parameter.type})" if parameter.type else ""
+            return f"    {parameter.name}{param_type}: {parameter.description}"

gyomu_docstring/update/internal/render_string.py

@@ -0,0 +1,63 @@
+from gyomu_docstring.update.docstring.line import (
+    DocstringBlank,
+    DocstringLine,
+    DocstringSectionItem,
+    DocstringText,
+)
+
+
+def render_docstring_string(
+    lines: tuple[DocstringLine, ...],
+    is_added: bool,
+    indent: int,
+) -> str | None:
+    if not lines:
+        return None
+
+    prefix = " " * indent
+
+    if _is_single_line_docstring(lines):
+        assert lines[0].type == "text"
+        text = lines[0].text
+        result = f'{prefix}"""{text}"""'
+    else:
+        first_line = compute_docstring_line(lines[0], prefix)
+        start = f'{prefix}"""{first_line.removeprefix(prefix)}'
+
+        string_lines = [
+            start,
+            *(compute_docstring_line(line, prefix) for line in lines[1:]),
+            f'{prefix}"""',
+        ]
+
+        result = "\n".join(string_lines)
+
+    if is_added:
+        result += "\n"
+
+    return result
+
+
+def compute_docstring_line(
+    line: DocstringLine,
+    prefix: str,
+) -> str:
+    match line:
+        case DocstringBlank():
+            return prefix
+
+        case DocstringText(text=text):
+            return "\n".join(f"{prefix}{part}" for part in text.split("\n"))
+
+        case DocstringSectionItem(text=text):
+            return "\n".join(f"{prefix}{part}" for part in text.split("\n"))
+
+
+def _is_single_line_docstring(
+    lines: tuple[DocstringLine, ...],
+) -> bool:
+    return (
+        len(lines) == 1
+        and isinstance(lines[0], DocstringText)
+        and "\n" not in lines[0].text
+    )

gyomu_docstring/update/render_docstring.py

@@ -0,0 +1,40 @@
+from gyomu_docstring.update.docstring.rendered_symbol import (
+    RenderedSymbolDocstring,
+)
+from gyomu_docstring.update.docstring.updated_docstring import UpdatedDocstring
+from gyomu_docstring.update.internal.render_line import render_docstring_lines
+from gyomu_docstring.update.internal.render_string import render_docstring_string
+
+
+def render_docstring(updated: UpdatedDocstring) -> RenderedSymbolDocstring:
+    lines = render_docstring_lines(updated)
+
+    document = render_docstring_string(
+        lines,
+        updated.docstring.location.start_offset
+        == updated.docstring.location.end_offset,
+        updated.docstring.indent,
+    )
+
+    is_added = (
+        updated.docstring.location.start_offset == updated.docstring.location.end_offset
+    )
+
+    location = updated.docstring.location.model_copy()
+
+    location.start_offset -= updated.docstring.indent
+
+    if is_added:
+        location.end_offset -= updated.docstring.indent
+
+    return RenderedSymbolDocstring(
+        identity=updated.identity,
+        docstring=document,
+        location=location,
+    )
+
+
+def render_docstrings(
+    updated_list: tuple[UpdatedDocstring, ...],
+) -> tuple[RenderedSymbolDocstring, ...]:
+    return tuple(render_docstring(updated) for updated in updated_list)

gyomu_docstring-0.2.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.5
+Name: gyomu-docstring
+Version: 0.2.0
+Summary: Gyomu docstring
+Requires-Python: >=3.13
+Requires-Dist: gyomu-infra
+Requires-Dist: gyomu-python-analysis
+Requires-Dist: gyomu-schema
+Requires-Dist: returns>=0.29.0
+Description-Content-Type: text/markdown
+
+# gyomu-docstring
+
+docstring components for Gyomu Python.

gyomu_docstring-0.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+gyomu_docstring/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gyomu_docstring/update/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gyomu_docstring/update/apply_file_update.py,sha256=v4sXzY1n5_06oeRqsYCSl3QuAsS6VZU2fbcNkAbm29Q,481
+gyomu_docstring/update/apply_merge.py,sha256=NgNLED37kAYoLzFnEchKccDJ8aJNtAZFdnlekEsgzGw,13409
+gyomu_docstring/update/build_file_update.py,sha256=zQLvosc7Pe8zJvGJ-rwOWgIP2P1SSbbWNOg80ZT8-EM,9047
+gyomu_docstring/update/render_docstring.py,sha256=gYYZear0NlcsD-U6uNkAm-2pWS5Vkh0ZoeCwyB3ztHw,1269
+gyomu_docstring/update/docstring/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gyomu_docstring/update/docstring/file_update_plan.py,sha256=-Jckt8B0IwESoLkKJxIeGxD4xjrgsXv7pY2NgDiC0KU,364
+gyomu_docstring/update/docstring/line.py,sha256=77areFAFYRww4l2yu-XZg5XPVHQgvMZ2bG3OYH05g9g,428
+gyomu_docstring/update/docstring/merge_plan.py,sha256=ukgZf5b9RsbWRxTccPsOpcfDVrlPzzkLz0WKujxdI9I,2580
+gyomu_docstring/update/docstring/rendered_symbol.py,sha256=B9ziDv3uvBVEKjkrvZ2LdJvrR60ggSlWxX7y_uWm4F8,298
+gyomu_docstring/update/docstring/updated_docstring.py,sha256=2smj8x6uKAktUuQKhjirC1yhbi8g9FRPl8sprerNEYk,273
+gyomu_docstring/update/internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gyomu_docstring/update/internal/render_line.py,sha256=YeGyzWYZhEOa_-gWU8vbR_qr_Y-U5ywt8shmSCroQTM,5280
+gyomu_docstring/update/internal/render_string.py,sha256=qbc9VF852YWhqbj85cY4qe-yiBXDYWoAl4mJXztqLO4,1480
+gyomu_docstring-0.2.0.dist-info/METADATA,sha256=txj_wg4zyY6WQTTFkvuMZwSKPWXIsZSiQo0SMzYs384,330
+gyomu_docstring-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+gyomu_docstring-0.2.0.dist-info/RECORD,,

gyomu_docstring-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any