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.15, >=3.12

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.12.tar.gz (17.3 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.12-cp314-cp314-win_amd64.whl (260.1 kB view details)

Uploaded CPython 3.14Windows x86-64

docstring_generator_ext-2.0.12-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (705.2 kB view details)

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

docstring_generator_ext-2.0.12-cp314-cp314-macosx_13_0_x86_64.whl (444.1 kB view details)

Uploaded CPython 3.14macOS 13.0+ x86-64

docstring_generator_ext-2.0.12-cp314-cp314-macosx_13_0_arm64.whl (447.1 kB view details)

Uploaded CPython 3.14macOS 13.0+ ARM64

docstring_generator_ext-2.0.12-cp313-cp313-win_amd64.whl (254.6 kB view details)

Uploaded CPython 3.13Windows x86-64

docstring_generator_ext-2.0.12-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (705.2 kB view details)

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

docstring_generator_ext-2.0.12-cp313-cp313-macosx_13_0_x86_64.whl (444.1 kB view details)

Uploaded CPython 3.13macOS 13.0+ x86-64

docstring_generator_ext-2.0.12-cp313-cp313-macosx_13_0_arm64.whl (447.1 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

docstring_generator_ext-2.0.12-cp312-cp312-win_amd64.whl (254.5 kB view details)

Uploaded CPython 3.12Windows x86-64

docstring_generator_ext-2.0.12-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (704.6 kB view details)

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

docstring_generator_ext-2.0.12-cp312-cp312-macosx_13_0_x86_64.whl (443.3 kB view details)

Uploaded CPython 3.12macOS 13.0+ x86-64

docstring_generator_ext-2.0.12-cp312-cp312-macosx_13_0_arm64.whl (446.8 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

File details

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

File metadata

  • Download URL: docstring_generator_ext-2.0.12.tar.gz
  • Upload date:
  • Size: 17.3 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.12.tar.gz
Algorithm Hash digest
SHA256 c2d4d8d766d321f893c539918f3c98c15515a0df3dacbec1411f31ba89564896
MD5 37380d9a3e1ff597385b44036a8f0e11
BLAKE2b-256 33939c628f63a1063f09735ff86cb3ae6a6d0f34ca070d1160ce1b6355b3d6e1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 c40019791c1748af32d439046d89838c67b6eab840d6510a4d41857143cf2a5a
MD5 06077051ec2f45336e0baa53f6c2f8ae
BLAKE2b-256 d111fa2e7db5d5a4aed3eac4d62d0518422cbe57729250705d6a52165f5c4182

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9d5156a1902e140ab49e7fa99f2729012ffc255332e9bd0989f4d4099c1ae68b
MD5 a77cc775c91909206fb0817825033064
BLAKE2b-256 75a455d1f00560fa0b6363d23e589f5886e27b772c12a71d7d8cea2338947cd6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp314-cp314-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 6a1e1d8d4ad168be1e5f2fe1193b36a7722e16a5a28f74b0084541a94f700f7a
MD5 035ca8cada30216661553ec4683661a9
BLAKE2b-256 38140a3d6a6a1b595be236b084e44b18141114cf6968713a28712476e82583ef

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp314-cp314-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 bf857f24e0c1e16310a2479192b4e66ee4e34e58e98daa374b9c643971cae02a
MD5 11dda12b945a8f7d38e59c359b09f709
BLAKE2b-256 341ab47db47425daa8ebacb433c1a53c3562881b4b70b68e0f306b50574f01c3

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.0.12-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.0.12-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 4671cca1d09e85ba32f01d6deca634bfe68f4be1bfe505e0c9566d440ef1c1f2
MD5 a48171b54a93cd481ae6bfcc694db165
BLAKE2b-256 2bb16f122828db02408c4a9eacd5cc16e689c1f1720050bea63859b1caf60b60

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 cbb2f3ba8b44d954486284d9df20e8f52b6be867b089a65206d8fdfe41d55f32
MD5 a6fc85582ab1db82e7e8231d586dba85
BLAKE2b-256 30d3182a175e2fb6e0e2a7f6ce389ebc27c54df43be660a0b1cfcb16d3ae5734

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp313-cp313-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 4ca64254f62ca5cc52694481128af772ab2973dd76370891990fafab90f8fe1a
MD5 9a90112a3a74cd20526fe5af350234f3
BLAKE2b-256 653261149650eba1741399ee670814719495ef7754eb5449331455ca06ea730f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 a809c643a47353b17dc271c6d3f12c9df223411590b4609d7b69e8378586b3ea
MD5 968a103f13e71afaf74f574d14d97aaa
BLAKE2b-256 fca40bd94e0b78af6bb75a2267755a064ed1038945f47a06118488bef299ffb8

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstring_generator_ext-2.0.12-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.0.12-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 7633773123ee3532bc60432957b9673bff6d0fe94ed50596c4c41b42e86ba95a
MD5 b18efeddc36e3d18701435d194c13a75
BLAKE2b-256 8cced8e0e3ff9072a64ed3b91d15cfad91b560b6f3af163cce7760e803faa074

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2bd8802b6b3ddcd93ba6510d8b494709b4cb9beaba46af880c8f9ebdbdbc1cfb
MD5 ccc2989c7a9357777451943744b0dab4
BLAKE2b-256 3fd450338266115bfb4d0d0db9814e37b874b71ab22a175d30b1444b43919979

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp312-cp312-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 4d4be5baf1f6750fff7eb514403740e62a124dd73ca17af0f6828325b7001725
MD5 f27581f3e0542d3c2a694a00153e1928
BLAKE2b-256 548e0cc120754c78586e47e1d16b84f19f67ed9f58ba6a2bf38cf686ecc1b98e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.12-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 d47f6da7b6cfa60041d27ee048560237674f501518bfcf5aabd1425b273d3603
MD5 c9f3b09c45786282178eb329bde4ce08
BLAKE2b-256 7508463497c4c8c3146450fde426a754bcd686e54809dcd29ead4733ed59f056

See more details on using hashes here.

Provenance

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

2.1.0

13 files

2.0.14

13 files

Pre-release

2.0.13a1

13 files

This release

2.0.12 This release

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

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