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.14.tar.gz (21.4 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.14-cp314-cp314-win_amd64.whl (299.5 kB view details)

Uploaded CPython 3.14Windows x86-64

docstring_generator_ext-2.0.14-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (929.4 kB view details)

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

docstring_generator_ext-2.0.14-cp314-cp314-macosx_13_0_x86_64.whl (531.7 kB view details)

Uploaded CPython 3.14macOS 13.0+ x86-64

docstring_generator_ext-2.0.14-cp314-cp314-macosx_13_0_arm64.whl (535.7 kB view details)

Uploaded CPython 3.14macOS 13.0+ ARM64

docstring_generator_ext-2.0.14-cp313-cp313-win_amd64.whl (292.1 kB view details)

Uploaded CPython 3.13Windows x86-64

docstring_generator_ext-2.0.14-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (929.4 kB view details)

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

docstring_generator_ext-2.0.14-cp313-cp313-macosx_13_0_x86_64.whl (531.6 kB view details)

Uploaded CPython 3.13macOS 13.0+ x86-64

docstring_generator_ext-2.0.14-cp313-cp313-macosx_13_0_arm64.whl (535.6 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

docstring_generator_ext-2.0.14-cp312-cp312-win_amd64.whl (292.1 kB view details)

Uploaded CPython 3.12Windows x86-64

docstring_generator_ext-2.0.14-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (928.8 kB view details)

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

docstring_generator_ext-2.0.14-cp312-cp312-macosx_13_0_x86_64.whl (531.0 kB view details)

Uploaded CPython 3.12macOS 13.0+ x86-64

docstring_generator_ext-2.0.14-cp312-cp312-macosx_13_0_arm64.whl (535.1 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

File details

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

File metadata

  • Download URL: docstring_generator_ext-2.0.14.tar.gz
  • Upload date:
  • Size: 21.4 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.14.tar.gz
Algorithm Hash digest
SHA256 6031ff7da7aa298f391178f8977a07a5f344c6629003ea8e60645ee7c29d1f8a
MD5 ae7ac995f1e3bb3e7fb35186ec4f9dd0
BLAKE2b-256 b6ff7d1a76e4af9f4c8b940ffb5ac3abaee6fe348700ed91268f1b76dc3ee9a6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 3e2bda8b59aa7faf214b8195c1bf1bf72dd822f87ac52499e6644c1b40a3844d
MD5 15180eb80b70ab375fbab7716690c7f3
BLAKE2b-256 fc0b8548c16b1d36e8a814a4ec5087304848d42742f483d7b7ca9118189f2f1a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f05a1936836216aaca449c0042a8c312271f8c35aadba583f5d698eac7a5b2e4
MD5 327403e3b292b421211c50c8ac837033
BLAKE2b-256 3ab08bbb10b6d3b577e5397d01e18f3c3af6cc7ffaf6c87df8154a033512b3b3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp314-cp314-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 1b4e58b3a13fc21a78fe36f83cced25053e7a425e514e6f5654e5c6e35bcaf4b
MD5 5b08bf4bf26dba7187ab7363a3c37d2a
BLAKE2b-256 e3ab83697480dc62c8933c08f11c0958f2ad58505a0cb23e87626cd36934a827

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp314-cp314-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 862ab447a66397ad9e1e7e4afbc883414234791d950c9ddbe85ae77e720844be
MD5 ff2dd8cafe356e7b406e3d900d4d3937
BLAKE2b-256 ad7a35ff74104563a9aa61956ea5f782f1ac786365eb4539ff37267e46a55661

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 9a56f95a31ce5d10953b171c0368e5c6aee1bc34ba597c7432122d8988f52ff6
MD5 ca0df17c487e61b6315311e108138e49
BLAKE2b-256 410ebc60dd6ef3f2a35ca47981d16634711ba4c5ef41f7d97eac38498abd1007

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 aede063647208e2a5197c90426653b833f51fa8883c3fc8e6f6c0b68d5085666
MD5 2420460bc6f6198a1186efa4d7e4e29c
BLAKE2b-256 edc40d3f35c51f1b8995d02824f6eaf8179706ac9d06db3be3b811908cda1129

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp313-cp313-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 b8edc652a212fb53bf166f7809ef6e341ed8c5672bf43ceb93da9bc8b841e08c
MD5 8dc51aa020e257dcc425786a5bed90e1
BLAKE2b-256 f1b6705249a05c9cd85ac725a35f7a0fedf732f494b115ce88ca498d11949b76

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 d46e8415f0944438f57dc0fec2d412a84bd4ad36a6ac587b12bea154e00cf213
MD5 3c1b248c225ce674959e452f07bc93ae
BLAKE2b-256 5d349d48f2f95c088ea63ccf92738edded8ca21be5482a62492d6b6a2fca0a52

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 bebf90356bd45a9c7f418425a90d4753a630482f844de6f282507270b7e0a30d
MD5 a67d9fac998e6459c928fc988a8bf795
BLAKE2b-256 f42aa2ffb251c1482659b48cbccb53f194de04d1875f1d7cd78b5638fa962965

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c37aae38fdef5892f4758a3012115003c51f112dadf9a2f45462bea80823b9fa
MD5 da80f3ffc569c1646ea8ae7b772bdfce
BLAKE2b-256 7a2fd2a7aeacc871375247d1f7d97ae24b12d9f58767ab780cfb06571f6e1100

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp312-cp312-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 76c2d1f1c9414ef91601afeb842b7711a3460748e375a5d7cfb09981318a13d2
MD5 36f6d69cfd28ee918da921413b67578b
BLAKE2b-256 880d799cca9e77cff958b21d2a4f35ff689686a3c7c2118cd10d67fb79731667

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.14-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 ef9b58d9ab5f1a39b27b76255db60f8c0dedc7f8fbdfa2af5a09fc2dba0b8278
MD5 3fa6dfa629352e9447f837a3e2bd5138
BLAKE2b-256 8537ee059f89b6101e08b473488dff8857202e42a0e734b3c34a1e2c8717710f

See more details on using hashes here.

Provenance

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

This release

2.0.14 This release

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

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