Skip to main content

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.
  • Skip Directives: Use # docstring: skip comments to exclude a whole file, a block of code, or a single function/class from docstring generation.
  • Filtering options: ignore_magic, ignore_private, and ignore_uncommented flags let you exclude magic methods, private members, or undocumented functions from processing.
  • 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)

Filtering which functions get processed

Both parse_file and check_docstring accept a few boolean flags to control which functions/methods are taken into account:

  • ignore_magic (default False): skip dunder/magic methods (e.g. __init__, __repr__).
  • ignore_private (default False): skip functions/methods whose name starts with a single underscore (e.g. _helper), excluding dunder methods.
  • ignore_uncommented (default False): skip functions/methods that currently have no docstring at all, leaving them untouched instead of generating one.
import docstring_generator_ext

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

# Skip private helpers and leave functions without any docstring untouched
docstring_generator_ext.parse_file(
    file_path,
    style,
    ignore_private=True,
    ignore_uncommented=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

Skip Directives

You can tell the extension to leave parts of a file untouched using # docstring: skip comments. Three scopes are supported:

1. File-level skip

Place the directive within the first 10 lines of the file to skip the entire file:

# docstring: skip

def some_function():
    return None

2. Block/Range skip

Wrap a group of functions or classes between # docstring: off and # docstring: on to skip everything in between:

# docstring: off
def helper_one():
    ...


def helper_two():
    ...
# docstring: on

3. Single-target skip

Place the directive directly below a function or class to skip just that target:

def helper_three():
    # docstring: skip
    ...

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.

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.1.0.tar.gz (23.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.1.0-cp314-cp314-win_amd64.whl (304.5 kB view details)

Uploaded CPython 3.14Windows x86-64

docstring_generator_ext-2.1.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (945.6 kB view details)

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

docstring_generator_ext-2.1.0-cp314-cp314-macosx_13_0_x86_64.whl (549.2 kB view details)

Uploaded CPython 3.14macOS 13.0+ x86-64

docstring_generator_ext-2.1.0-cp314-cp314-macosx_13_0_arm64.whl (549.8 kB view details)

Uploaded CPython 3.14macOS 13.0+ ARM64

docstring_generator_ext-2.1.0-cp313-cp313-win_amd64.whl (296.9 kB view details)

Uploaded CPython 3.13Windows x86-64

docstring_generator_ext-2.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (945.7 kB view details)

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

docstring_generator_ext-2.1.0-cp313-cp313-macosx_13_0_x86_64.whl (549.3 kB view details)

Uploaded CPython 3.13macOS 13.0+ x86-64

docstring_generator_ext-2.1.0-cp313-cp313-macosx_13_0_arm64.whl (549.8 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

docstring_generator_ext-2.1.0-cp312-cp312-win_amd64.whl (297.0 kB view details)

Uploaded CPython 3.12Windows x86-64

docstring_generator_ext-2.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (944.4 kB view details)

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

docstring_generator_ext-2.1.0-cp312-cp312-macosx_13_0_x86_64.whl (548.6 kB view details)

Uploaded CPython 3.12macOS 13.0+ x86-64

docstring_generator_ext-2.1.0-cp312-cp312-macosx_13_0_arm64.whl (549.5 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

File details

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

File metadata

  • Download URL: docstring_generator_ext-2.1.0.tar.gz
  • Upload date:
  • Size: 23.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.1.0.tar.gz
Algorithm Hash digest
SHA256 d7ce411f6c82ffa57661af049d6f8e85ae2eaafc81f3e2e857a970ef28cf2315
MD5 4aed6dcd9be530989b5ecb0c1bae6007
BLAKE2b-256 a572aa5c98048ce244bfd4d13b6a8a19aed972fcad748f6ae006423497d2a637

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0.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.1.0-cp314-cp314-win_amd64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 b3b5d60bc3a857e4388f6270df0e6d8bb4c2dc7762dd05588fee0bc7ac601cec
MD5 a6768bd1d34b7da6209cd1130a793b47
BLAKE2b-256 da49e2cb11765af575f285a946fab02afaad2ebc5ba53f72ce0251db9100fef6

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-cp314-cp314-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.1.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 1533e02a128b7ab79fc49c3242551950935a117dad963685e5cc42a931f24984
MD5 b402a31e3a76371085058c3571a64660
BLAKE2b-256 3074a3df64881ae8646dcf02c177593cd43b80286dfee577ed776ec266103e60

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-cp314-cp314-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.1.0-cp314-cp314-macosx_13_0_x86_64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp314-cp314-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 133f82add01a1a0875a0027896bdc5e96aaff42eff3c47697f8528668f6db00c
MD5 0f8bf83dd3f6305e96d5bdb6ed491344
BLAKE2b-256 40d6baed621964183bbd4127e06fcd21926b88b6ceb5986afd740616b84114fd

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-cp314-cp314-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.1.0-cp314-cp314-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp314-cp314-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 acd8dccda9f2fa83fd505c02e3c79e2973c1c1edc416ddcd5f244457bc6a5fad
MD5 3a14ebd5e1752b11e8ab7b4ec8087022
BLAKE2b-256 19e4c1e2f8e2cc02efc127c35e4d83b961d80cc27f67bfd70a61c15d08476eb3

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-cp314-cp314-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.

File details

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 3eae137e04b48051ba2fb56a8c1315f66f5be66dedb3de5969c0dfa26ce9124b
MD5 f8239be746bc26162d5e40f9925da7f9
BLAKE2b-256 0bd0c10e2a072c813d6e88ab3380dcfc6d6b42477f1f1bdd5ffa814693e64a43

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-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.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 928ab348bb9497c41abc7bff6f509050e8bf74699f73de95463fe2b074810307
MD5 fe3a78265595a55cb5428d396c9052bf
BLAKE2b-256 cccbfc3010b058d34fca611b12ebe88b81eee7db0b5c45fcb3e4508eb6ce5aad

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-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.1.0-cp313-cp313-macosx_13_0_x86_64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp313-cp313-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 7e72d06186324a13f060044ac9bbb80feeb1d848f1ccd758ff3d246cb39434cd
MD5 fdf1a2a5fdab81e67aec00a49a8bbd4f
BLAKE2b-256 b9bd7f2d4389fcea80efc92058ea44861fbeee3f6da156e3d7d30a871d4a25aa

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-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.1.0-cp313-cp313-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 5dab646055aa0657d20ef4f412ad639a4657c3d399695761b0caedb2b976fcaa
MD5 335136bd69f6d1fbc7c317daf841b09a
BLAKE2b-256 eeb8588a2c08cd3aef74018f8fa2ceb5b23cc99175aa1f27da6bb1959de9b090

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-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.

File details

Details for the file docstring_generator_ext-2.1.0-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 b91240066f13fd51cab552f0281798585021d06bb4f227be9e81c4e1dc2e461a
MD5 5d481cd5cf43b389f77945074c3be261
BLAKE2b-256 21ebd91dc2db0c22b4152e9b57d985d876f19be4839eb9fc84ac4740426da763

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-cp312-cp312-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.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a30c36dcb8558573bc560341cff7e41d5a3a48db893cd9e16c8399bc4a3db0ae
MD5 c0e2a4cd98a72ae416065f94d4822ba6
BLAKE2b-256 021fb559079a716b521d2c757d07f0f1dc1d3e00e12b3494a67eca5321c4cd4b

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-cp312-cp312-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.1.0-cp312-cp312-macosx_13_0_x86_64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp312-cp312-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 7b83f6ec2f53f1ef31615e28d6206f9095961630df3f99b9fe332a2620ec6884
MD5 a073d70b205533e535eafd899cd7cece
BLAKE2b-256 a135cb6e8a22ce80ece8e4bff860935b6eb025c0506970f508df5615632cda31

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-cp312-cp312-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.1.0-cp312-cp312-macosx_13_0_arm64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.1.0-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 c1debda95092b51b236a58d19d2c76523edf9e055985f688c36561099af57e9e
MD5 a00aade73e42772a4c91bf6e7c0829b9
BLAKE2b-256 bf18e6fffd6ff2e3ffced404e5d95884ec8d757c26da050e1d6b54e1d2e0db88

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.1.0-cp312-cp312-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

This release

2.1.0 This release

13 files

2.0.14

13 files

2.0.12

13 files

2.0.11

13 files

2.0.10.post1

13 files

2.0.9

5 files

2.0.8

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

2.0.1

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