Docstring Generator Extension

C++ Tests Build Extension PyPI version Python versions License: MIT

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.
  • Async-function support: Handles both def and async def functions transparently.
  • Type-Hint Awareness: Extracts type information from annotations and default values.
  • Multiple Styles: Supports popular docstring formats:
    • reST (reStructuredText)
    • Google style
    • NumPy style
  • Format-style detection: Automatically detects the style of an existing docstring and refuses to silently mix styles unless allow_overwrite=True is passed.
  • Style conversion: With allow_overwrite=True, converts a docstring written in one style to another in a single call.
  • Exception detection: Analyses the function body with Python's ast module to identify raised exceptions and include them in the docstring.
  • Docstring coverage auditing: check_docstring() reports how many functions in a file have complete, partial, or missing docstrings without modifying the file.
  • High Performance: Core logic implemented in C++ for fast processing.
  • Preserves Existing Content: Keeps manually written descriptions across re-runs using special in-docstring markers:
    • $N binds the text on that line to the N-th function parameter.
    • >> provides the return-value description.

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)

Overwriting an existing docstring format

By default, parse_file refuses to overwrite a docstring that was already written in a different style than the one you requested, and will print a warning instead. Pass allow_overwrite=True to let the extension convert the existing docstring to the new style:

import docstring_generator_ext

file_path = "path/to/your_script.py"
style = docstring_generator_ext.DocstringFormatStyle.NUMPY

# Convert any existing docstring style to NUMPY — previous style will be removed
docstring_generator_ext.parse_file(file_path, style, allow_overwrite=True)

Auditing docstring coverage

You can 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

Preserving descriptions with special markers

When the extension processes a file that already contains docstrings, it tries to keep manually written descriptions in place. Two marker conventions are supported:

$N — argument description markers

Place a $ followed by the 1-based index of the parameter inside the docstring to bind a free-form description to that argument. The marker and the text on its line are extracted and attached to the corresponding parameter; the $N line is then removed from the generated docstring.

def add(a: int, b: int) -> int:
    """Add two numbers together.

    $1 The first operand.
    $2 The second operand.
    """
    return a + b

After the next parse_file run the descriptions will be wired to a and b automatically.

def add(a: int, b: int) -> int:
    """Add two numbers together.

    Args:
        a (int): The first operand.
        b (int): The second operand.
    Returns:
        int
    """
    return a + b

>> — return description marker

Place >> on its own line inside the docstring to provide the description for the return value. The text after >> on that line is extracted as the return description, and the marker line is removed.

def square(x: int) -> int:
    """Square a number.

    >> The squared value of x.
    """
    return x * x

After the next parse_file run the descriptions will be wired to Returns description automatically.

def square(x: int) -> int:
    """Square a number.

    Args:
        x (int):
    Returns:
        int: The squared value of x.
    """
    return x * x

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.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.1.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for FelixTheC from gravatar.com FelixTheC

Credits

Author: FelixTheC

Requires

Python >=3.13

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

docstring_generator_ext-2.0.8.tar.gz (16.6 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

docstring_generator_ext-2.0.8-cp313-cp313-win_amd64.whl (252.7 kB view details)

Uploaded CPython 3.13Windows x86-64

docstring_generator_ext-2.0.8-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (661.9 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

docstring_generator_ext-2.0.8-cp313-cp313-macosx_13_0_x86_64.whl (429.8 kB view details)

Uploaded CPython 3.13macOS 13.0+ x86-64

docstring_generator_ext-2.0.8-cp313-cp313-macosx_13_0_arm64.whl (433.0 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

File details

Details for the file docstring_generator_ext-2.0.8.tar.gz.

File metadata

  • Download URL: docstring_generator_ext-2.0.8.tar.gz
  • Upload date:
  • Size: 16.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for docstring_generator_ext-2.0.8.tar.gz
Algorithm Hash digest
SHA256 a63f7ff13beffbe561d8cc022fceda22eaef75d54613cb0a52d65b7dc842a1ec
MD5 f363e409d1fd54e4f4320cf2bdff3fd9
BLAKE2b-256 e42f0bfd0dfe34a416d6a121617f3c6bdaf43669c43292ec6d1030cc67cb3675

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.0.8.tar.gz:

Publisher: python-publish-ext.yml on FelixTheC/docstring_generator_ext

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docstring_generator_ext-2.0.8-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.8-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 04bfda2766176dc4fa48e21f519ba5c121ef203ebfca35f399eff0872d62d887
MD5 5dcd32d7ab1a53a558388547ed06a8f3
BLAKE2b-256 e6486bdc94ec3e2cd22c8d02bcc6398882a908811b96f54003ddb3c2b266c32d

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.0.8-cp313-cp313-win_amd64.whl:

Publisher: python-publish-ext.yml on FelixTheC/docstring_generator_ext

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docstring_generator_ext-2.0.8-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.8-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 effd5927aa7405bb1af747e46dc55d372c5a1e1ba81123eba82a00addf5f5e15
MD5 dd1af0d9e62972fcbbf7b16765b4be80
BLAKE2b-256 6fdcac4822f1e1a46b40e8b3b47d100226db462c680e1d12cf2c3a88907d75da

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.0.8-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: python-publish-ext.yml on FelixTheC/docstring_generator_ext

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docstring_generator_ext-2.0.8-cp313-cp313-macosx_13_0_x86_64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.8-cp313-cp313-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 846f0b92ba32118910772692e94b76a8fc6eb3f7f847dc851ab12e42a1374c08
MD5 babf6933c482e2a0b96fc3a3fb23223f
BLAKE2b-256 6419ee0e0568750e408bb1c447e9f47c7e9350f6119a7c00b4591174487e1fed

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.0.8-cp313-cp313-macosx_13_0_x86_64.whl:

Publisher: python-publish-ext.yml on FelixTheC/docstring_generator_ext

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docstring_generator_ext-2.0.8-cp313-cp313-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.8-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 41529f134499041de26a25e20f781fc95b7a2f42790305bd092f489f99ff5e21
MD5 18c713d853d61756de91316ba9d736a9
BLAKE2b-256 74496de6e2191377d44e034267333f7f396cf82e23ffea58c4062cdd5b10985b

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.0.8-cp313-cp313-macosx_13_0_arm64.whl:

Publisher: python-publish-ext.yml on FelixTheC/docstring_generator_ext

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

2.1.0

13 files

2.0.14

13 files

Pre-release

2.0.13a1

13 files

2.0.12

13 files

2.0.11

13 files

2.0.10.post1

13 files

2.0.9

5 files

This release

2.0.8 This release

5 files

2.0.7

5 files

2.0.6

5 files

2.0.5

5 files

2.0.4

5 files

2.0.3

5 files

2.0.2

5 files

Pre-release

2.0.2b0

5 files

2.0.1

5 files

Pre-release

1.0.3a5

5 files

1.0.2

9 files

1.0.1.post2

9 files

0.0.33

1 file

0.0.31

1 file

0.0.28

1 file

0.0.26

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page