docstring-generator-ext 2.0.1

Generate Docstrings with type-hint information.

Docstring Generator Extension

docstring_generator_ext is a high-performance Python extension written in C++ (using pybind11) designed to automatically generate and inject docstrings into Python source files. It leverages Python's ast module to extract type-hint information and function signatures to create well-formatted docstrings in various styles.

Features

• Automatic Docstring Injection: Parses Python files and inserts docstrings for functions and methods.
• Type-Hint Awareness: Extracts type information from annotations and default values.
• Multiple Styles: Supports popular docstring formats:
  • reST (reStructuredText)
  • Google style
  • NumPy style
• High Performance: Core logic implemented in C++ for fast processing.
• Preserves Existing Content: Can update existing docstrings while trying to preserve manually added descriptions (using a special $ marker convention).

Installation

Prerequisites

• Python 3.13 or higher
• A C++ compiler with C++20 support (e.g., GCC, Clang, or MSVC)
• pybind11

Building from Source

1. Clone the repository:

   git clone https://github.com/FelixTheC/docstring_generator_ext.git
   cd docstring_generator_ext
   

2. Install the build package:

   pip install build
   

3. Build the package:

   python -m build
   

4. Install the built wheel:

   pip install dist/docstring_generator_ext-*.whl
   

Usage

After installation, you can use the extension in your Python scripts:

import docstring_generator_ext

# Path to the Python file you want to process
file_path = "path/to/your_script.py"

# Choose a style: GOOGLE, NUMPY, or reST
style = docstring_generator_ext.DocstringFormatStyle.GOOGLE

# Generate and inject docstrings
docstring_generator_ext.parse_file(file_path, style)

You can also audit an existing file to see how well its functions are documented, without making any changes:

import docstring_generator_ext

# Path to the Python file you want to audit
file_path = "path/to/your_script.py"

# Returns a dict with docstring coverage statistics
result = docstring_generator_ext.check_docstring(file_path)

print(f"Functions checked  : {result['num_functions_checked']}")
print(f"Complete docstrings: {result['complete_docstrings']}")
print(f"Partial docstrings : {result['partial_docstrings']}")
print(f"No docstrings      : {result['no_docstrings']}")

The returned dictionary always contains four keys:

Key	Description
num_functions_checked	Total number of functions/methods found in the file
complete_docstrings	Functions whose docstring fully matches the signature
partial_docstrings	Functions with an incomplete or outdated docstring
no_docstrings	Functions with no docstring at all

Docstring Styles

The extension provides an enum DocstringFormatStyle to choose the desired output:

• docstring_generator_ext.DocstringFormatStyle.reST
• docstring_generator_ext.DocstringFormatStyle.GOOGLE
• docstring_generator_ext.DocstringFormatStyle.NUMPY

C++20

The core of this extension is written in C++20 to take full advantage of the modern standard's best algorithms and features:

• std::format: Used for clean, type-safe string formatting throughout the docstring generation logic.
• Ranges & views: C++20 ranges enable expressive, composable data transformations without raw loops.
• Concepts: Improve template code clarity and provide better compiler error messages.
• std::span: Provides safe, bounds-checked views over contiguous data without ownership overhead.

Compiler Requirements

Building from source requires a C++ compiler with full C++20 support:

Platform	Minimum version
Linux	GCC 11+ / Clang 14+
macOS	Apple Clang 15+ / GCC 13+ (via Homebrew)
Windows	MSVC 2022 (19.30+)

Pre-built wheels on PyPI are compiled with C++20 enabled and require no special toolchain on the user's side.

Authors

• FelixTheC

License

This project is licensed under the MIT License - see the LICENSE.md file for details.