pycodecommenter 2.0.3__py3-none-any.whl

PyCodeCommenter/docstring_parser.py

@@ -0,0 +1,121 @@
+"""
+Docstring parsing module for PyCodeCommenter.
+
+This module provides intelligent parsing of existing Python docstrings in multiple
+formats (Google, Sphinx, NumPy). It extracts structured information including
+summary, description, parameters, and return values for smart docstring merging.
+
+Classes:
+    DocstringParser: Main parser class for extracting docstring information
+"""
+import re
+import logging
+from typing import Dict, Any, List, Optional
+
+logger = logging.getLogger(__name__)
+
+class DocstringParser:
+    """
+    Parses existing docstrings in both Google and Sphinx styles.
+    Extracts summary, description, parameters, and return information.
+    """
+
+    def __init__(self, docstring: Optional[str] = None):
+        self.raw_docstring = docstring or ""
+        self.summary = ""
+        self.description = ""
+        self.params = {} # type: Dict[str, str]
+        self.returns = ""
+        
+        if self.raw_docstring:
+            self.parse()
+
+    def parse(self) -> None:
+        """Main entry point for parsing the docstring."""
+        if not self.raw_docstring.strip():
+            return
+
+        lines = self.raw_docstring.strip().splitlines()
+        self.summary = lines[0].strip()
+        
+        remaining_content = "\n".join(lines[1:]).strip()
+        
+        # Determine if it's likely Google or Sphinx
+        if ":param" in remaining_content or ":return" in remaining_content:
+            self._parse_sphinx(remaining_content)
+        else:
+            self._parse_google(remaining_content)
+
+    def _parse_sphinx(self, content: str) -> None:
+        """Parses Sphinx style documentation (:param name: desc)."""
+        desc_lines = []
+        current_param = None
+        
+        for line in content.splitlines():
+            line = line.strip()
+            if not line: continue
+            
+            if line.startswith(':param'):
+                match = re.match(r':param\s+(\w+):\s*(.*)', line)
+                if match:
+                    current_param = match.group(1)
+                    self.params[current_param] = match.group(2).strip()
+                continue
+            
+            if line.startswith(':return'):
+                match = re.match(r':returns?:\s*(.*)', line)
+                if match:
+                    self.returns = match.group(1).strip()
+                current_param = None
+                continue
+                
+            if current_param and not line.startswith(':'):
+                self.params[current_param] += " " + line
+            elif not line.startswith(':'):
+                desc_lines.append(line)
+        
+        self.description = " ".join(desc_lines).strip()
+
+    def _parse_google(self, content: str) -> None:
+        """Parses Google style documentation (Args:, Returns:)."""
+        # Split by sections, allowing headers to be at the start or after a newline
+        sections = re.split(r'(?m)^ *(Args|Returns|Attributes|Methods):$', content)
+        
+        # If the first part doesn't match a header, it's the description
+        self.description = sections[0].strip()
+        
+        for i in range(1, len(sections), 2):
+            header = sections[i]
+            body = sections[i+1] if i+1 < len(sections) else ""
+            
+            if header == "Args":
+                self._parse_google_args(body)
+            elif header == "Returns":
+                self.returns = body.strip()
+
+    def _parse_google_args(self, body: str) -> None:
+        """
+        Helper to parse the Args section of a Google docstring.
+        
+        Args:
+            body (str): The body of the Args section.
+        """
+        current_arg = None
+        for line in body.splitlines():
+            # Match "    name (type): desc" or "    name: desc"
+            # Improved regex to handle various spacing and optional types more robustly
+            match = re.match(r'^\s+(\w+)\s*(?:\(([^)]+)\))?\s*:\s*(.*)', line)
+            if match:
+                current_arg = match.group(1)
+                self.params[current_arg] = match.group(3).strip()
+            elif current_arg and line.startswith('        '): # Continuation line
+                self.params[current_arg] += " " + line.strip()
+
+    def get_info(self) -> Dict[str, Any]:
+        """Returns the parsed information as a dictionary."""
+        return {
+            "summary": self.summary,
+            "description": self.description,
+            "params": self.params,
+            "returns": self.returns
+        }

PyCodeCommenter/parameter_descriptions.py

@@ -0,0 +1,76 @@
+parameter_descriptions = {
+    "calculate_area": {
+        "length": "Length of the rectangle.",
+        "width": "Width of the rectangle."
+    },
+    "calculate_volume": {
+        "radius": "Radius of the sphere.",
+        "height": "Height of the cylinder."
+    },
+    "calculate_perimeter": {
+        "side": "Side length of the square.",
+        "length": "Length of the rectangle.",
+        "width": "Width of the rectangle."
+    },
+    "calculate_surface_area": {
+        "radius": "Radius of the sphere.",
+        "height": "Height of the cylinder.",
+        "length": "Length of the cuboid.",
+        "width": "Width of the cuboid.",
+        "depth": "Depth of the cuboid."
+    },
+    "calculate_density": {
+        "mass": "Mass of the object.",
+        "volume": "Volume of the object."
+    },
+    "sort_list": {
+        "lst": "List to be sorted.",
+        "reverse": "Sort in descending order if True."
+    },
+    "find_max": {
+        "numbers": "List of numbers to find the maximum from."
+    },
+    "find_min": {
+        "numbers": "List of numbers to find the minimum from."
+    },
+    "search_item": {
+        "lst": "List to search the item in.",
+        "item": "Item to search for in the list."
+    },
+    "concatenate_strings": {
+        "str1": "First string.",
+        "str2": "Second string."
+    },
+    "split_string": {
+        "string": "String to be split.",
+        "delimiter": "Delimiter to split the string by."
+    },
+    "read_file": {
+        "file_path": "Path to the file to be read."
+    },
+    "write_file": {
+        "file_path": "Path to the file to be written.",
+        "content": "Content to write to the file."
+    },
+    "connect_to_database": {
+        "host": "Database host address.",
+        "port": "Port number for the database connection.",
+        "username": "Username for the database connection.",
+        "password": "Password for the database connection."
+    },
+    "execute_query": {
+        "query": "SQL query to be executed.",
+        "connection": "Database connection object."
+    },
+    "send_request": {
+        "url": "URL to send the request to.",
+        "method": "HTTP method (GET, POST, etc.).",
+        "headers": "Headers to include in the request.",
+        "data": "Data to send in the request body."
+    },
+    "send_email": {
+        "to_address": "Recipient email address.",
+        "subject": "Subject of the email.",
+        "body": "Body content of the email."
+    },
+}

PyCodeCommenter/templates.py

@@ -0,0 +1,95 @@
+# function that maps common verbs to templates
+def get_function_description(func_name: str) -> str:
+    """
+    Returns a template-based description for a function based on its name.
+    
+    Args:
+        func_name (str): The name of the function to describe.
+        
+    Returns:
+        str: A descriptive sentence for the function.
+    """
+    verb_templates = {
+        "calculate": f"Calculates the {func_name.split('_', 1)[-1]}.",
+        "get": f"Retrieves the {func_name.split('_', 1)[-1]} from a given source.",
+        "create": f"Creates a new {func_name.split('_', 1)[-1]}.",
+        "fetch": f"Fetches the {func_name.split('_', 1)[-1]}.",
+        "process": f"Processes the input to produce a {func_name.split('_', 1)[-1]}.",
+        "update": f"Updates the {func_name.split('_', 1)[-1]}.",
+        "delete": f"Deletes the {func_name.split('_', 1)[-1]}.",
+        "remove": f"Removes the {func_name.split('_', 1)[-1]}.",
+        "add": f"Adds a new {func_name.split('_', 1)[-1]}.",
+        "set": f"Sets the {func_name.split('_', 1)[-1]}.",
+        "initialize": f"Initializes the {func_name.split('_', 1)[-1]}.",
+        "load": f"Loads the {func_name.split('_', 1)[-1]}.",
+        "save": f"Saves the {func_name.split('_', 1)[-1]}.",
+        "validate": f"Validates the {func_name.split('_', 1)[-1]}.",
+        "send": f"Sends the {func_name.split('_', 1)[-1]}.",
+        "receive": f"Receives the {func_name.split('_', 1)[-1]}.",
+        "compute": f"Computes the {func_name.split('_', 1)[-1]}.",
+        "generate": f"Generates the {func_name.split('_', 1)[-1]}.",
+        "convert": f"Converts the {func_name.split('_', 1)[-1]}.",
+        "transform": f"Transforms the {func_name.split('_', 1)[-1]}.",
+        "merge": f"Merges the {func_name.split('_', 1)[-1]}.",
+        "split": f"Splits the {func_name.split('_', 1)[-1]}.",
+        "extract": f"Extracts the {func_name.split('_', 1)[-1]}.",
+        "compare": f"Compares the {func_name.split('_', 1)[-1]}.",
+        "sort": f"Sorts the {func_name.split('_', 1)[-1]}.",
+        "filter": f"Filters the {func_name.split('_', 1)[-1]}.",
+        "aggregate": f"Aggregates the {func_name.split('_', 1)[-1]}.",
+        "map": f"Maps the {func_name.split('_', 1)[-1]}.",
+        "reduce": f"Reduces the {func_name.split('_', 1)[-1]}.",
+        "clean": f"Cleans the {func_name.split('_', 1)[-1]}.",
+        "normalize": f"Normalizes the {func_name.split('_', 1)[-1]}.",
+        "format": f"Formats the {func_name.split('_', 1)[-1]}.",
+        "parse": f"Parses the {func_name.split('_', 1)[-1]}.",
+        "serialize": f"Serializes the {func_name.split('_', 1)[-1]}.",
+        "deserialize": f"Deserializes the {func_name.split('_', 1)[-1]}.",
+        "encrypt": f"Encrypts the {func_name.split('_', 1)[-1]}.",
+        "decrypt": f"Decrypts the {func_name.split('_', 1)[-1]}.",
+        "compress": f"Compresses the {func_name.split('_', 1)[-1]}.",
+        "decompress": f"Decompresses the {func_name.split('_', 1)[-1]}.",
+        "archive": f"Archives the {func_name.split('_', 1)[-1]}.",
+        "unarchive": f"Unarchives the {func_name.split('_', 1)[-1]}.",
+        "backup": f"Backs up the {func_name.split('_', 1)[-1]}.",
+        "restore": f"Restores the {func_name.split('_', 1)[-1]}.",
+        "log": f"Logs the {func_name.split('_', 1)[-1]}.",
+        "monitor": f"Monitors the {func_name.split('_', 1)[-1]}.",
+        "track": f"Tracks the {func_name.split('_', 1)[-1]}.",
+        "report": f"Reports the {func_name.split('_', 1)[-1]}.",
+        "notify": f"Notifies about the {func_name.split('_', 1)[-1]}.",
+        "alert": f"Alerts about the {func_name.split('_', 1)[-1]}.",
+        "schedule": f"Schedules the {func_name.split('_', 1)[-1]}.",
+        "execute": f"Executes the {func_name.split('_', 1)[-1]}.",
+        "run": f"Runs the {func_name.split('_', 1)[-1]}.",
+        "test": f"Tests the {func_name.split('_', 1)[-1]}.",
+        "debug": f"Debugs the {func_name.split('_', 1)[-1]}.",
+        "build": f"Builds the {func_name.split('_', 1)[-1]}.",
+        "deploy": f"Deploys the {func_name.split('_', 1)[-1]}.",
+        "install": f"Installs the {func_name.split('_', 1)[-1]}.",
+        "uninstall": f"Uninstalls the {func_name.split('_', 1)[-1]}.",
+        "upgrade": f"Upgrades the {func_name.split('_', 1)[-1]}.",
+        "downgrade": f"Downgrades the {func_name.split('_', 1)[-1]}.",
+        "configure": f"Configures the {func_name.split('_', 1)[-1]}.",
+        "initialize": f"Initializes the {func_name.split('_', 1)[-1]}.",
+        "shutdown": f"Shuts down the {func_name.split('_', 1)[-1]}.",
+        "restart": f"Restarts the {func_name.split('_', 1)[-1]}.",
+        "start": f"Starts the {func_name.split('_', 1)[-1]}.",
+        "stop": f"Stops the {func_name.split('_', 1)[-1]}.",
+        "pause": f"Pauses the {func_name.split('_', 1)[-1]}.",
+        "resume": f"Resumes the {func_name.split('_', 1)[-1]}.",
+        "lock": f"Locks the {func_name.split('_', 1)[-1]}.",
+        "unlock": f"Unlocks the {func_name.split('_', 1)[-1]}.",
+        "authenticate": f"Authenticates the {func_name.split('_', 1)[-1]}.",
+        "authorize": f"Authorizes the {func_name.split('_', 1)[-1]}.",
+        "log_in": f"Logs in the {func_name.split('_', 1)[-1]}.",
+        "log_out": f"Logs out the {func_name.split('_', 1)[-1]}.",
+        "register": f"Registers the {func_name.split('_', 1)[-1]}.",
+        "deregister": f"Deregisters the {func_name.split('_', 1)[-1]}.",
+        "subscribe": f"Subscribes to the {func_name.split('_', 1)[-1]}.",
+        "unsubscribe": f"Unsubscribes from the {func_name.split('_', 1)[-1]}.",
+        "publish": f"Publishes the {func_name.split('_', 1)[-1]}.",
+    }
+
+    action = func_name.split('_')[0]  # First part is the action (verb)
+    return verb_templates.get(action, f"Executes the function {func_name}.")

PyCodeCommenter/type_analyzer.py

@@ -0,0 +1,203 @@
+"""
+Type inference module for PyCodeCommenter.
+
+This module provides sophisticated type inference for Python code by analyzing
+AST nodes. It supports modern Python features including PEP 604 union types (|),
+PEP 585 generics (list[int]), and complex type annotations.
+
+Classes:
+    TypeAnalyzer: Analyzes Python AST nodes to infer types for variables,
+                  arguments, and return values
+"""
+import ast
+import logging
+from typing import Any, Dict, Optional, Set, Union
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+class TypeAnalyzer:
+    """
+    Analyzes Python AST nodes to infer types for variables, arguments, and return values.
+    Supports modern Python features like PEP 604 (|) and PEP 585 (generics).
+    """
+
+    def __init__(self, local_types: Optional[Dict[str, str]] = None):
+        """
+        Initializes the analyzer with optional pre-known local types.
+        
+        Args:
+            local_types (Optional[Dict[str, str]]): Dictionary mapping variable names to their inferred types.
+        """
+        self.local_types = local_types or {}
+
+    def infer_type(self, node: Any) -> str:
+        """
+        Infers the type of an AST node (Argument, Name, Constant, etc.).
+        
+        Args:
+            node (Any): The AST node to analyze.
+            
+        Returns:
+            str: The inferred type as a string (e.g., 'int', 'List[str]', 'any').
+        """
+        try:
+            # Handle Argument nodes (with annotations)
+            if isinstance(node, ast.arg):
+                if node.annotation:
+                    return self.get_annotation_type(node.annotation)
+                return self.local_types.get(node.arg, "any")
+
+            # Handle Value nodes (Expressions)
+            return self.infer_expr_type(node)
+        except Exception as e:
+            logger.error(f"Error in infer_type: {e}")
+            return "any"
+
+    def infer_expr_type(self, expr: Any) -> str:
+        """
+        Infers type from an expression node.
+        
+        Args:
+            expr (Any): The expression node to analyze.
+            
+        Returns:
+            str: The inferred type.
+        """
+        if isinstance(expr, ast.Constant):
+            return type(expr.value).__name__
+        
+        if isinstance(expr, (ast.List, ast.ListComp)):
+            return "list"
+        
+        if isinstance(expr, (ast.Dict, ast.DictComp)):
+            return "dict"
+        
+        if isinstance(expr, (ast.Set, ast.SetComp)):
+            return "set"
+        
+        if isinstance(expr, (ast.Tuple)):
+            return "tuple"
+
+        if isinstance(expr, ast.Name):
+            if expr.id in {'True', 'False'}:
+                return "bool"
+            if expr.id == 'None':
+                return "NoneType"
+            return self.local_types.get(expr.id, "any")
+
+        if isinstance(expr, ast.BinOp):
+            return self._infer_binop_type(expr)
+
+        if isinstance(expr, ast.Call):
+            return self._infer_call_type(expr)
+
+        if isinstance(expr, ast.Attribute):
+            return self._infer_attribute_type(expr)
+
+        return "any"
+
+    def get_annotation_type(self, annotation: Any) -> str:
+        """
+        Translates an AST annotation node into a human-readable type string.
+        Supports PEP 604 (|) and PEP 585 (list[int]).
+        
+        Args:
+            annotation (Any): The annotation node (ast.Name, ast.Subscript, etc.).
+            
+        Returns:
+            str: The type string.
+        """
+        if isinstance(annotation, ast.Name):
+            return annotation.id
+        
+        if isinstance(annotation, ast.Constant) and annotation.value is None:
+            return "None"
+        
+        if isinstance(annotation, ast.Attribute):
+            value_id = self.get_annotation_type(annotation.value)
+            return f"{value_id}.{annotation.attr}"
+        
+        if isinstance(annotation, ast.Subscript):
+            base_type = self.get_annotation_type(annotation.value)
+            # Python 3.9+ uses Slice for index in some cases, but 3.10+ simplified it
+            index = annotation.slice
+            if isinstance(index, ast.Index): # Older Python
+                index = index.value
+            
+            # Handle Tuple/List of types inside subscript
+            if isinstance(index, ast.Tuple):
+                inner_types = ", ".join(self.get_annotation_type(elt) for elt in index.elts)
+                return f"{base_type}[{inner_types}]"
+            
+            inner_type = self.get_annotation_type(index)
+            return f"{base_type}[{inner_type}]"
+
+        if isinstance(annotation, ast.BinOp):
+            if isinstance(annotation.op, ast.BitOr): # PEP 604: int | str
+                left = self.get_annotation_type(annotation.left)
+                right = self.get_annotation_type(annotation.right)
+                return f"Union[{left}, {right}]"
+
+        return "any"
+
+    def _infer_binop_type(self, node: ast.BinOp) -> str:
+        """
+        Infers the result of a binary operation.
+        
+        Args:
+            node (ast.BinOp): The binary operation node.
+            
+        Returns:
+            str: The inferred type.
+        """
+        left = self.infer_expr_type(node.left)
+        right = self.infer_expr_type(node.right)
+        
+        if left == "float" or right == "float":
+            return "float"
+        
+        if isinstance(node.op, ast.Div):
+            return "float"
+            
+        if left != "any":
+            return left
+        return right
+
+    def _infer_call_type(self, node: ast.Call) -> str:
+        """
+        Infers return type from a function call (basic heuristic).
+        
+        Args:
+            node (ast.Call): The call node to analyze.
+            
+        Returns:
+            str: The inferred return type.
+        """
+        if isinstance(node.func, ast.Name):
+            name = node.func.id
+            if name in {'int', 'float', 'str', 'list', 'dict', 'set', 'bool'}:
+                return name
+            if name == 'len':
+                return "int"
+        
+        if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+            if node.func.value.id == 'math':
+                return "float"
+                
+        return "any"
+
+    def _infer_attribute_type(self, node: ast.Attribute) -> str:
+        """
+        Infers type of an attribute access.
+        
+        Args:
+            node (ast.Attribute): The attribute node.
+            
+        Returns:
+            str: The inferred type.
+        """
+        if isinstance(node.value, ast.Name):
+            if node.value.id == 'math' and node.attr in {'pi', 'e', 'tau'}:
+                return "float"
+        return "any"