pyopenapi-gen 0.8.3__py3-none-any.whl

pyopenapi_gen/core/writers/documentation_writer.py

@@ -0,0 +1,222 @@
+"""
+DocumentationWriter: Utility for generating well-formatted, Google-style Python docstrings.
+
+This module provides the DocumentationWriter and DocumentationBlock classes, which are responsible
+for building comprehensive, type-rich docstrings for generated Python code. It supports argument
+alignment, line wrapping, and section formatting for Args, Returns, and Raises.
+"""
+
+from typing import List, Optional, Tuple, Union
+
+from .line_writer import LineWriter
+
+
+class DocumentationBlock:
+    """
+    Data container for docstring content.
+
+    Attributes:
+        summary (Optional[str]): The summary line for the docstring.
+        description (Optional[str]): The detailed description.
+        args (Optional[List[Union[Tuple[str, str, str], Tuple[str, str]]]]):
+            List of arguments as (name, type, desc) or (type, desc) tuples.
+        returns (Optional[Tuple[str, str]]): The return type and description.
+        raises (Optional[List[Tuple[str, str]]]): List of (exception type, description) tuples.
+    """
+
+    def __init__(
+        self,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        args: Optional[List[Union[Tuple[str, str, str], Tuple[str, str]]]] = None,
+        returns: Optional[Tuple[str, str]] = None,
+        raises: Optional[List[Tuple[str, str]]] = None,
+    ) -> None:
+        """
+        Initialize a DocumentationBlock.
+
+        Args:
+            summary (Optional[str]): The summary line.
+            description (Optional[str]): The detailed description.
+            args (Optional[List[Union[Tuple[str, str, str], Tuple[str, str]]]]): Arguments.
+            returns (Optional[Tuple[str, str]]): Return type and description.
+            raises (Optional[List[Tuple[str, str]]]): Exceptions.
+        """
+        self.summary: Optional[str] = summary
+        self.description: Optional[str] = description
+        self.args: List[Union[Tuple[str, str, str], Tuple[str, str]]] = args or []
+        self.returns: Optional[Tuple[str, str]] = returns
+        self.raises: List[Tuple[str, str]] = raises or []
+
+
+class DocumentationFormatter:
+    """
+    Handles low-level formatting, wrapping, and alignment for docstring lines using LineWriter.
+    """
+
+    def __init__(self, width: int = 88, min_desc_col: int = 30) -> None:
+        self.width: int = width
+        self.min_desc_col: int = min_desc_col
+
+    def wrap(self, text: str, indent: int, prefix: Optional[str] = None) -> List[str]:
+        if not text:
+            return []
+        writer = LineWriter(max_width=self.width)
+        for _ in range(indent // len(writer.indent_str)):
+            writer.indent()
+        if prefix is not None:
+            writer.append(prefix)
+        writer.append_wrapped(text)
+        return writer.getvalue().splitlines()
+
+    def get_arg_prefix(self, arg: Union[Tuple[str, str, str], Tuple[str, str]]) -> str:
+        if len(arg) == 3:
+            name, typ, _ = arg
+            return f"{name} ({typ})"
+        return f"{arg[0]}"
+
+    def render_short_prefix_arg(self, prefix: str, desc: str, indent: int, desc_col: int) -> List[str]:
+        writer = LineWriter(max_width=self.width)
+        for _ in range(indent // len(writer.indent_str)):
+            writer.indent()
+        writer.append(prefix)
+        writer.move_to_column(desc_col)
+        writer.append(": ")
+        writer.append_wrapped(desc)
+        return writer.getvalue().splitlines()
+
+    def render_long_prefix_arg(
+        self,
+        prefix: str,
+        desc: str,
+        indent: int,
+        min_col: int,
+    ) -> List[str]:
+        writer = LineWriter(max_width=self.width)
+        for _ in range(indent // len(writer.indent_str)):
+            writer.indent()
+        writer.append(prefix)
+        writer.newline()
+        writer.move_to_column(min_col)
+        writer.append(": ")
+        # writer.move_to_column(min_col + 2)
+        writer.append_wrapped(desc)
+        return writer.getvalue().splitlines()
+
+
+class DocstringSectionRenderer:
+    """
+    Renders Args, Returns, and Raises sections for Google-style docstrings using LineWriter.
+    """
+
+    def __init__(self, formatter: DocumentationFormatter) -> None:
+        self.formatter = formatter
+
+    def _render_short_prefix_arg(self, prefix: str, desc: str, indent: int, min_col: int) -> list[str]:
+        return self.formatter.render_short_prefix_arg(prefix, desc, indent, min_col)
+
+    def _render_exact_prefix_arg(self, prefix: str, desc: str, indent: int, min_col: int) -> list[str]:
+        return self.formatter.render_short_prefix_arg(prefix, desc, indent, min_col)
+
+    def _render_long_prefix_arg(self, prefix: str, desc: str, indent: int, min_col: int) -> list[str]:
+        return self.formatter.render_long_prefix_arg(prefix, desc, indent, min_col)
+
+    def render_args(self, args: List[Union[Tuple[str, str, str], Tuple[str, str]]], indent: int) -> List[str]:
+        lines: List[str] = []
+        min_col = self.formatter.min_desc_col
+        for arg in args:
+            prefix = self.formatter.get_arg_prefix(arg)
+            desc = arg[2] if len(arg) == 3 else arg[1]
+            prefix_len = indent + len(prefix)
+            if prefix_len < min_col:
+                lines.extend(self._render_short_prefix_arg(prefix, desc, indent, min_col))
+            elif prefix_len == min_col:
+                lines.extend(self._render_exact_prefix_arg(prefix, desc, indent, min_col))
+            else:
+                lines.extend(self._render_long_prefix_arg(prefix, desc, indent, min_col))
+        return lines
+
+    def render_returns(self, returns: Tuple[str, str], indent: int) -> List[str]:
+        typ, desc = returns
+        prefix = f"{typ}:"
+        writer = LineWriter(max_width=self.formatter.width)
+        for _ in range(indent // len(writer.indent_str)):
+            writer.indent()
+        writer.append(prefix)
+        writer.append(" ")
+        writer.append_wrapped(desc)
+        return writer.getvalue().splitlines()
+
+    def render_raises(self, raises: List[Tuple[str, str]], indent: int) -> List[str]:
+        writer = LineWriter(max_width=self.formatter.width)
+        for _ in range(indent // len(writer.indent_str)):
+            writer.indent()
+        if not raises:
+            return writer.lines
+        writer.append("HttpError:")
+        for code, desc in raises:
+            writer.newline()
+            writer.append(f"    {code}:")
+            if desc.strip():
+                writer.append(" ")
+                writer.append_wrapped(desc)
+        return writer.getvalue().splitlines()
+
+
+class DocumentationWriter:
+    """
+    Renders a DocumentationBlock into a Google-style Python docstring.
+    Delegates all formatting to DocumentationFormatter and section rendering to DocstringSectionRenderer.
+    """
+
+    def __init__(self, width: int = 88, min_desc_col: int = 30) -> None:
+        """
+        Initialize a DocumentationWriter.
+
+        Args:
+            width (int): The maximum line width for wrapping (default: 88).
+            min_desc_col (int): The minimum column for aligning descriptions (default: 30).
+        """
+        self.formatter = DocumentationFormatter(width=width, min_desc_col=min_desc_col)
+        self.section_renderer = DocstringSectionRenderer(self.formatter)
+        self.width = width
+        self.min_desc_col = min_desc_col
+
+    def render_docstring(self, doc: DocumentationBlock, indent: int = 0) -> str:
+        """
+        Render a Google-style docstring from a DocumentationBlock.
+
+        Args:
+            doc (DocumentationBlock): The docstring structure to render.
+            indent (int): The indentation level (in spaces) for the docstring block.
+
+        Returns:
+            str: The formatted docstring as a string.
+        """
+        lines: List[str] = []
+        lines.append(f'"""')
+        # Summary
+        if doc.summary:
+            lines.extend(self.formatter.wrap(doc.summary, indent))
+        # Description
+        if doc.description:
+            if doc.summary:
+                lines.append("")
+            lines.extend(self.formatter.wrap(doc.description, indent))
+        # Args
+        if doc.args:
+            lines.append("")
+            lines.append("Args:")
+            lines.extend(self.section_renderer.render_args(doc.args, indent + 4))
+        # Returns
+        if doc.returns:
+            lines.append("")
+            lines.append("Returns:")
+            lines.extend(self.section_renderer.render_returns(doc.returns, indent + 4))
+        # Raises
+        if doc.raises:
+            lines.append("")
+            lines.append("Raises:")
+            lines.extend(self.section_renderer.render_raises(doc.raises, indent + 4))
+        lines.append('"""')
+        return "\n".join(lines)

pyopenapi_gen/core/writers/line_writer.py

@@ -0,0 +1,217 @@
+"""
+LineWriter: Utility for building and formatting lines of text with precise control over indentation and width.
+
+This class is designed for use in both code and documentation generation, providing methods to append text, start
+new lines, and query the current line's width.
+"""
+
+from typing import List, Optional
+
+
+class LineWriter:
+    """
+    Utility for building lines of text with indentation and width tracking.
+
+    Attributes:
+        lines (List[str]): The accumulated lines of text.
+        indent_level (int): The current indentation level.
+        indent_str (str): The string used for one indentation level (default: 4 spaces).
+        max_width (int): The maximum line width for wrapping.
+    """
+
+    def __init__(self, indent_str: str = "    ", max_width: int = 80) -> None:
+        """
+        Initialize a new LineWriter with a single empty line, indentation state, and max line width.
+        Args:
+            indent_str (str): The string used for one indentation level (default: 4 spaces).
+            max_width (int): The maximum line width for wrapping (default: 80).
+        """
+        self.lines: List[str] = [""]
+        self.indent_level: int = 0
+        self.indent_str: str = indent_str
+        self._just_newlined: bool = True
+        self.max_width: int = max_width
+
+    def indent(self) -> None:
+        """
+        Increase the indentation level by one.
+        """
+        self.indent_level += 1
+
+    def dedent(self) -> None:
+        """
+        Decrease the indentation level by one (never below zero).
+        """
+        self.indent_level = max(0, self.indent_level - 1)
+
+    def append(self, text: str) -> None:
+        """
+        Append text to the current line, respecting current indentation if the line is empty and was just newlined.
+        Args:
+            text (str): The text to append.
+        """
+        if self.lines[-1] == "" and self._just_newlined:
+            self.lines[-1] = self.indent_str * self.indent_level + text
+        else:
+            self.lines[-1] += text
+        self._just_newlined = False
+
+    def newline(self) -> None:
+        """
+        Start a new line, with current indentation.
+        """
+        self.lines.append("")
+        self._just_newlined = True
+
+    def current_width(self) -> int:
+        """
+        Get the width (number of characters) of the current line.
+        Returns:
+            int: The width of the current line.
+        """
+        return len(self.lines[-1])
+
+    def current_line(self) -> str:
+        """
+        Get the current line.
+        """
+        return self.lines[-1]
+
+    def getvalue(self) -> str:
+        """
+        Get the full text as a single string, joined by newlines.
+        Returns:
+            str: The full text.
+        """
+        return "\n".join(self.lines)
+
+    def wrap_and_append(self, text: str, width: int, prefix: str = "") -> None:
+        """
+        Wrap the given text to the specified width and append it, using the given prefix for the first line.
+        Args:
+            text (str): The text to wrap and append.
+            width (int): The maximum line width.
+            prefix (str): The prefix for the first line (default: empty).
+        """
+        import textwrap
+
+        wrapped = textwrap.wrap(text, width=width, initial_indent=prefix, subsequent_indent=" " * len(prefix))
+        for i, line in enumerate(wrapped):
+            if i > 0:
+                self.newline()
+            self.append(line)
+
+    def _get_current_column(self) -> int:
+        """
+        Get the current column of the cursor.
+        """
+
+        line_width = self.current_width()
+        if line_width == 0:
+            return self.indent_level * len(self.indent_str)
+        return line_width
+
+    def append_wrapped(self, text: str) -> None:
+        """
+        Append text to the current line, wrapping as needed.
+
+        The first line wraps at (self.max_width - current cursor position), so wrapping always respects the available
+        space on the current line, including indentation and any already-appended text. Subsequent lines wrap
+        at (self.max_width - current column), and are aligned to the current column at the time of the call.
+
+        Args:
+            text (str): The text to append and wrap.
+        """
+        import textwrap
+
+        if not text:
+            return
+        wrap_col = self._get_current_column()
+        first_line_width = self.max_width - wrap_col
+        if first_line_width <= 0:
+            self.newline()
+            wrap_col = self._get_current_column()
+            first_line_width = self.max_width - wrap_col
+
+        prefix = self.current_line()
+        while len(prefix) < wrap_col:
+            prefix += " "
+        wrap_col = max(wrap_col, len(prefix))
+
+        wrapper = textwrap.TextWrapper(
+            width=self.max_width,
+            initial_indent="",
+            subsequent_indent=" " * wrap_col,
+            break_long_words=True,
+            break_on_hyphens=True,
+        )
+        wrapped_lines = wrapper.wrap(prefix + text)
+        if wrapped_lines:
+            self.replace_current_line(wrapped_lines[0])
+            for line in wrapped_lines[1:]:
+                self.newline()
+                self.replace_current_line(line)
+
+    def replace_current_line(self, line: str) -> None:
+        """
+        Replace the current line with the given line.
+        """
+        self.lines[-1] = line
+
+    def move_to_column(self, col: int) -> None:
+        """
+        Pad the current line with spaces until the cursor is at column col.
+        Args:
+            col (int): The target column to move the cursor to.
+        """
+        current = len(self.lines[-1])
+        if current < col:
+            self.lines[-1] += " " * (col - current - 1)
+        # If already at or past col, do nothing
+
+    def append_wrapped_at_column(self, text: str, width: int, col: Optional[int] = None) -> None:
+        """
+        Append text, wrapping as needed, so that the first line continues from the current position,
+        and all subsequent lines start at column `col`.
+
+        If `col` is None, the current line width at the time of the call is used as the wrap column.
+        This allows ergonomic alignment after any prefix or content.
+
+        Args:
+            text (str)          : The text to append and wrap.
+            width (int)         : The maximum line width.
+            col (Optional[int]) : The column at which to start wrapped lines. If None, uses current
+                                  line width.
+        """
+        import textwrap
+
+        if not text:
+            return  # Do nothing for empty text
+        # Determine wrap column
+        wrap_col = self.current_width() if col is None else col
+        # First line: fill up to current position, then append as much as fits
+        current = len(self.lines[-1])
+        available = max(0, width - current)
+        if available <= 0:
+            # No space left, start a new line at wrap_col
+            self.newline()
+            self.move_to_column(wrap_col)
+            current = len(self.lines[-1])
+            available = max(0, width - current)
+        words = text.split()
+        first_line = ""
+
+        while words and len(first_line) + len(words[0]) + (1 if first_line else 0) <= available:
+            if first_line:
+                first_line += " "
+            first_line += words.pop(0)
+        if first_line:
+            self.append(first_line)
+        # Remaining lines: wrap at width, start at wrap_col
+        if words:
+            rest = " ".join(words)
+            wrapped = textwrap.wrap(rest, width=width - wrap_col)
+            for line in wrapped:
+                self.newline()
+                self.move_to_column(wrap_col)
+                self.append(line)