docgenpranay 0.1.0__tar.gz

docgenpranay-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: docgenpranay
+Version: 0.1.0
+Summary: Automated Python Docstring Generator
+Author: Muddam Pranay
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pydocstyle

docgenpranay-0.1.0/docgenpranay.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: docgenpranay
+Version: 0.1.0
+Summary: Automated Python Docstring Generator
+Author: Muddam Pranay
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pydocstyle

docgenpranay-0.1.0/docgenpranay.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+pyproject.toml
+docgenpranay.egg-info/PKG-INFO
+docgenpranay.egg-info/SOURCES.txt
+docgenpranay.egg-info/dependency_links.txt
+docgenpranay.egg-info/entry_points.txt
+docgenpranay.egg-info/requires.txt
+docgenpranay.egg-info/top_level.txt
+docugenius/__init__.py
+docugenius/cli.py
+docugenius/core.py
+tests/test_edge_cases.py

docgenpranay-0.1.0/docgenpranay.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

docgenpranay-0.1.0/docgenpranay.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docgenpranay = docugenius.cli:main

docgenpranay-0.1.0/docgenpranay.egg-info/requires.txt

@@ -0,0 +1 @@
+pydocstyle

docgenpranay-0.1.0/docgenpranay.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+dist
+docugenius
+tests

docgenpranay-0.1.0/docugenius/cli.py

@@ -0,0 +1,117 @@
+import argparse
+import sys
+import ast
+from pathlib import Path
+
+from docugenius.core import (
+    extract_definitions,
+    get_function_metadata,
+    generate_coverage_report,
+    instrument_tree,
+    generate_instrumented_code,
+    validate_file,
+)
+
+
+def process_file(file_path: Path, style: str):
+    """
+    Process a single Python file.
+    Returns (instrumented_code, coverage_percent, compliance_percent)
+    """
+    source = file_path.read_text(encoding="utf-8")
+
+    tree = ast.parse(source)
+    functions, _ = extract_definitions(tree)
+
+    metadata = [get_function_metadata(func) for func in functions]
+
+    coverage = generate_coverage_report(metadata)
+    violations = validate_file(source)
+
+    total = coverage["total_functions"]
+    compliance = (
+        round(((total - len(violations)) / total) * 100, 2)
+        if total > 0 else 100.0
+    )
+
+    # Instrument
+    instrumented_tree = instrument_tree(tree, style=style)
+    instrumented_code = generate_instrumented_code(instrumented_tree)
+
+    return instrumented_code, coverage["coverage_percent"], compliance
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Automated Python Docstring Generator"
+    )
+
+    parser.add_argument(
+        "files",
+        nargs="+",
+        help="Path(s) to Python file(s)"
+    )
+
+    parser.add_argument(
+        "--style",
+        choices=["google", "numpy", "reST"],
+        default="google",
+        help="Docstring style"
+    )
+
+    parser.add_argument(
+        "--min-coverage",
+        type=float,
+        default=0,
+        help="Minimum required documentation coverage percentage"
+    )
+
+    parser.add_argument(
+        "--min-compliance",
+        type=float,
+        default=0,
+        help="Minimum required PEP-257 compliance percentage"
+    )
+
+    args = parser.parse_args()
+
+    overall_success = True
+
+    for file_str in args.files:
+        file_path = Path(file_str)
+
+        if not file_path.exists():
+            print(f"❌ File not found: {file_str}")
+            overall_success = False
+            continue
+
+        try:
+            instrumented_code, coverage, compliance = process_file(
+                file_path, args.style
+            )
+
+            print(f"\n📄 File: {file_path}")
+            print(f"Coverage: {coverage}%")
+            print(f"Compliance: {compliance}%")
+
+            if coverage < args.min_coverage:
+                print(f"❌ Coverage below minimum ({args.min_coverage}%)")
+                overall_success = False
+
+            if compliance < args.min_compliance:
+                print(f"❌ Compliance below minimum ({args.min_compliance}%)")
+                overall_success = False
+
+            # Print generated code
+            print("\n--- Generated Code ---\n")
+            print(instrumented_code)
+
+        except Exception as e:
+            print(f"❌ Error processing {file_str}: {e}")
+            overall_success = False
+
+    sys.exit(0 if overall_success else 1)
+
+
+if __name__ == "__main__":
+    main()

docgenpranay-0.1.0/docugenius/core.py

@@ -0,0 +1,215 @@
+import ast
+import re
+import tempfile
+import os
+from typing import Dict, List
+import pydocstyle
+
+
+# =====================================================
+# PARSER
+# =====================================================
+
+def parse_file(file_path):
+    with open(file_path, "r") as f:
+        source_code = f.read()
+    return ast.parse(source_code)
+
+
+# =====================================================
+# EXTRACTION
+# =====================================================
+
+def extract_definitions(tree: ast.AST):
+    functions = []
+    classes = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef):
+            functions.append(node)
+        elif isinstance(node, ast.ClassDef):
+            classes.append(node)
+
+    return functions, classes
+
+
+def get_function_metadata(func: ast.FunctionDef) -> Dict:
+    params = [arg.arg for arg in func.args.args]
+    docstring = ast.get_docstring(func)
+    has_return = any(isinstance(n, ast.Return) for n in ast.walk(func))
+
+    raises = set()
+    for n in ast.walk(func):
+        if isinstance(n, ast.Raise) and n.exc:
+            try:
+                exc = ast.unparse(n.exc)
+                exc = re.sub(r"\(.*\)", "", exc)
+                raises.add(exc)
+            except Exception:
+                pass
+
+    is_generator = any(
+        isinstance(n, (ast.Yield, ast.YieldFrom))
+        for n in ast.walk(func)
+    )
+
+    return {
+        "name": func.name,
+        "params": params,
+        "has_docstring": docstring is not None,
+        "docstring": docstring,
+        "has_return": has_return,
+        "raises": list(raises),
+        "is_generator": is_generator,
+    }
+
+
+# =====================================================
+# COVERAGE
+# =====================================================
+
+def generate_coverage_report(metadata):
+    total_functions = len(metadata)
+
+    documented = [m for m in metadata if m.get("has_docstring")]
+    undocumented = [m for m in metadata if not m.get("has_docstring")]
+
+    coverage_percent = (
+        round((len(documented) / total_functions) * 100, 2)
+        if total_functions > 0 else 0
+    )
+
+    return {
+        "total_functions": total_functions,
+        "documented_functions": len(documented),
+        "undocumented_functions": len(undocumented),
+        "coverage_percent": coverage_percent
+    }
+
+
+# =====================================================
+# DOCSTRING GENERATION
+# =====================================================
+
+def generate_docstring(meta: dict, style: str = "google") -> str:
+    """
+    Generate clean PEP-257 compliant docstring.
+    """
+
+    name = meta["name"].replace("_", " ").capitalize()
+    params = meta["params"]
+    raises = meta["raises"]
+    is_generator = meta["is_generator"]
+    has_return = meta["has_return"]
+
+    lines = [f"{name}.", ""]
+
+    # ---------------- PARAMETERS ----------------
+    if params:
+        lines.append("Args:")
+        for p in params:
+            lines.append(f"    {p}: Description.")
+        lines.append("")
+
+    # ---------------- RETURNS / YIELDS ----------------
+    if is_generator:
+        lines.append("Yields:")
+        lines.append("    value: Description.")
+        lines.append("")
+    elif has_return:
+        lines.append("Returns:")
+        lines.append("    value: Description.")
+        lines.append("")
+
+    # ---------------- RAISES ----------------
+    if raises:
+        lines.append("Raises:")
+        for r in raises:
+            lines.append(f"    {r}: Description.")
+        lines.append("")
+
+    # Remove trailing blank lines
+    while lines and lines[-1] == "":
+        lines.pop()
+
+    return "\n".join(lines)
+
+
+# =====================================================
+# INSTRUMENTATION
+# =====================================================
+
+def instrument_ast(tree: ast.AST, style: str = "google") -> ast.AST:
+    """
+    Insert generated docstrings into module, classes, and functions.
+    """
+
+    # ---------------- MODULE DOCSTRING ----------------
+    if not ast.get_docstring(tree):
+        module_doc = ast.Expr(
+            value=ast.Constant("Module description.")
+        )
+        tree.body.insert(0, module_doc)
+
+    for node in ast.walk(tree):
+
+        # ---------------- CLASS DOCSTRING ----------------
+        if isinstance(node, ast.ClassDef):
+            if not ast.get_docstring(node):
+                class_doc = ast.Expr(
+                    value=ast.Constant(f"{node.name} class.")
+                )
+                node.body.insert(0, class_doc)
+
+        # ---------------- FUNCTION DOCSTRING ----------------
+        if isinstance(node, ast.FunctionDef):
+            if not ast.get_docstring(node):
+                meta = get_function_metadata(node)
+                docstring = generate_docstring(meta, style)
+
+                node.body.insert(
+                    0,
+                    ast.Expr(value=ast.Constant(docstring))
+                )
+
+    return tree
+
+
+def instrument_tree(tree, metadata=None, style="google"):
+    return instrument_ast(tree, style)
+
+
+def generate_instrumented_code(tree):
+    return ast.unparse(tree)
+
+
+# =====================================================
+# VALIDATOR
+# =====================================================
+
+IGNORED_RULES = [
+    "D100", "D101", "D102",
+    "D205", "D400", "D401", "D212", "D213",
+    "D406", "D407", "D413",
+]
+
+
+def validate_file(source_code: str) -> List[Dict]:
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as tmp:
+        tmp.write(source_code)
+        tmp_path = tmp.name
+
+    violations = []
+
+    try:
+        for error in pydocstyle.check([tmp_path], ignore=IGNORED_RULES):
+            violations.append({
+                "line": error.line,
+                "code": error.code,
+                "message": error.message,
+                "source": error.source,
+            })
+    finally:
+        os.unlink(tmp_path)
+
+    return violations

docgenpranay-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "docgenpranay"
+version = "0.1.0"
+description = "Automated Python Docstring Generator"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+    { name = "Muddam Pranay" }
+]
+dependencies = [
+    "pydocstyle"
+]
+
+[project.scripts]
+docgenpranay = "docugenius.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]

docgenpranay-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

docgenpranay-0.1.0/tests/test_edge_cases.py

@@ -0,0 +1,123 @@
+import ast
+import pytest
+
+from docugenius.core import (
+    extract_definitions,
+    get_function_metadata,
+    instrument_tree,
+    generate_instrumented_code,
+    validate_file,
+)
+
+
+# ---------------------------------------------------
+# HELPER
+# ---------------------------------------------------
+
+def _parse_and_instrument(source: str):
+    tree = ast.parse(source)
+    instrumented_tree = instrument_tree(tree, style="google")
+    return generate_instrumented_code(instrumented_tree)
+
+
+# ---------------------------------------------------
+# TESTS
+# ---------------------------------------------------
+
+def test_empty_python_file():
+    """Empty file should be handled safely."""
+    source = ""
+    tree = ast.parse(source)
+    instrumented_tree = instrument_tree(tree, style="google")
+    code = generate_instrumented_code(instrumented_tree)
+
+    # Should at least be valid Python
+    ast.parse(code)
+
+
+def test_module_docstring_added_if_missing():
+    """Missing module docstring should be inserted."""
+    source = "x = 10"
+    instrumented = _parse_and_instrument(source)
+
+    assert 'Module description.' in instrumented
+
+
+def test_nested_function_only_outer_documented():
+    """Nested functions should not necessarily be documented separately."""
+    source = """
+def outer():
+    def inner():
+        return 5
+    return inner()
+"""
+    instrumented = _parse_and_instrument(source)
+    tree = ast.parse(instrumented)
+
+    functions, _ = extract_definitions(tree)
+
+    outer = next(f for f in functions if f.name == "outer")
+    inner = next(f for f in functions if f.name == "inner")
+
+    assert ast.get_docstring(outer) is not None
+    # Depending on your logic, inner may or may not be documented.
+    # If your instrumentor documents all, change this to assert is not None.
+    assert ast.get_docstring(inner) is not None
+
+
+def test_class_without_methods_gets_docstring():
+    """Classes without methods should receive docstrings."""
+    source = """
+class Empty:
+    pass
+"""
+    instrumented = _parse_and_instrument(source)
+    tree = ast.parse(instrumented)
+    _, classes = extract_definitions(tree)
+
+    empty_class = next(c for c in classes if c.name == "Empty")
+    assert ast.get_docstring(empty_class) is not None
+
+
+def test_existing_docstring_not_overwritten():
+    """Existing function docstrings should not be replaced."""
+    source = '''
+def multiply(x, y):
+    """Existing docstring."""
+    return x * y
+'''
+    instrumented = _parse_and_instrument(source)
+    tree = ast.parse(instrumented)
+    functions, _ = extract_definitions(tree)
+
+    multiply = next(f for f in functions if f.name == "multiply")
+    doc = ast.get_docstring(multiply)
+
+    assert "Existing docstring." in doc
+
+
+def test_syntax_error_raises():
+    """Invalid Python input should raise SyntaxError."""
+    bad_source = "def broken(:"
+    with pytest.raises(SyntaxError):
+        ast.parse(bad_source)
+
+
+def test_generated_code_removes_missing_docstring_violation():
+    """Instrumentation should remove missing-docstring violations."""
+    source = """
+def add(x, y):
+    return x + y
+"""
+
+    before_violations = validate_file(source)
+    instrumented = _parse_and_instrument(source)
+    after_violations = validate_file(instrumented)
+
+    before_codes = {v["code"] for v in before_violations}
+    after_codes = {v["code"] for v in after_violations}
+
+    # Ensure D103 (missing function docstring) is removed
+    assert "D103" in before_codes
+    assert "D103" not in after_codes
+