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.10.post1.tar.gz (16.7 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.10.post1-cp314-cp314-win_amd64.whl (258.6 kB view details)

Uploaded CPython 3.14Windows x86-64

docstring_generator_ext-2.0.10.post1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (693.8 kB view details)

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

docstring_generator_ext-2.0.10.post1-cp314-cp314-macosx_13_0_x86_64.whl (429.9 kB view details)

Uploaded CPython 3.14macOS 13.0+ x86-64

docstring_generator_ext-2.0.10.post1-cp314-cp314-macosx_13_0_arm64.whl (433.1 kB view details)

Uploaded CPython 3.14macOS 13.0+ ARM64

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

Uploaded CPython 3.13Windows x86-64

docstring_generator_ext-2.0.10.post1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (693.8 kB view details)

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

docstring_generator_ext-2.0.10.post1-cp313-cp313-macosx_13_0_x86_64.whl (429.9 kB view details)

Uploaded CPython 3.13macOS 13.0+ x86-64

docstring_generator_ext-2.0.10.post1-cp313-cp313-macosx_13_0_arm64.whl (433.2 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

docstring_generator_ext-2.0.10.post1-cp312-cp312-win_amd64.whl (252.7 kB view details)

Uploaded CPython 3.12Windows x86-64

docstring_generator_ext-2.0.10.post1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (693.5 kB view details)

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

docstring_generator_ext-2.0.10.post1-cp312-cp312-macosx_13_0_x86_64.whl (429.3 kB view details)

Uploaded CPython 3.12macOS 13.0+ x86-64

docstring_generator_ext-2.0.10.post1-cp312-cp312-macosx_13_0_arm64.whl (432.8 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

File details

Details for the file docstring_generator_ext-2.0.10.post1.tar.gz.

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1.tar.gz
Algorithm Hash digest
SHA256 2d6c7ca556466091a2dd33cd15ea798fef78d90f28a7c93db6d4d8ab3fca588c
MD5 f7a290626b29f02b78199353a54e2a87
BLAKE2b-256 f86ca23dbcd00091936b1736c43727a462da0d034e38809bfe9197085db92ea5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 f717ab39edab37c33680b98ced69f4913acf068c2f80f26ada9c15a64f247d0b
MD5 824e530fa17f4fee9ce13d304db39066
BLAKE2b-256 9936b6cc650adcc0a3176679c793857d4a38971ae9d1468bb7d7f8420fee00c3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9903c96efb89f025b85e994591212d02f0cbe6e822091b1bb407e193691ab87d
MD5 c93caf6359b307a446d7b1a0efcf7d54
BLAKE2b-256 c7d59486177b80289f8235205fd1f1892b53a0730c193b86cefc552a543c40d9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp314-cp314-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 89c9f64cc847c63aa8cd2f28d537d1a6b01aa3d96fd9c1520c00ad4e8cb50343
MD5 d77de5a740ec91e633fba029d8939120
BLAKE2b-256 828d95e06ad7a3456e37373870af0564c17c136f362088597c594996ff1c19bf

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp314-cp314-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 546df6e56ddb567e4468f2adaf2b3f8104cc7b5384f300145df0ad01c796eadc
MD5 db92a423a9e1b77db7832f5da7d5e5ba
BLAKE2b-256 99e615aba8c1096189da7cd79ae51edcefeaf593312535a6d37214a3034c939f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 8df39c8624a64b1d0b9055a5fdf5f7542bcbf0031422b65482b9c66b6ce85280
MD5 5f117f8d3de152a7013d8a4408ea17c8
BLAKE2b-256 556e235de994131c1b373300f4e617cbe85d47edbde71be4e484620f86f5ef1f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 274a3f2c6186b20c19cbf0d8a4ca30110716e39484ca42f2e4da94a940d2916e
MD5 f02be90f2a7b096046bd0592201d1e1f
BLAKE2b-256 31f40dec66e9322434870520527da6d7ac3fb14bcc46301a6bd83faa656fde5a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp313-cp313-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 7d3d754da6f3acf290aca61573c00f95058222b8c71d6f5839362375cbffff75
MD5 c310c7172131f5a8f98f832483b807c9
BLAKE2b-256 12b76e7cd03187c7b8e3fa575d2c75471064f081df35eab71633a045b3e3b058

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 7bb4e50358ce94f1fa610fbf6db26f2b16ed0d86da1a537129ea7e6e97075fc2
MD5 dd5316a55736a25f1df3c9551e628925
BLAKE2b-256 8d625be74a475189e77e9a6d3d7158def9d9475834516b8f70490d678164ded7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 78382f510c261e511ab7024ec6da239c2191d9716c3187547b9311666a639848
MD5 220a567c5fa088e1e07c79ade5cd0457
BLAKE2b-256 f3e323016e80172b4c32637dd0db3cbdfef79df86a40c80527c12b7490b3a940

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 861f59fdd028131623efe2836e6812481f7961d2c4af44d5396251b057222c4b
MD5 74adc034ce0179976b4cfa34eba9515b
BLAKE2b-256 7c416b9ba6642680485a94d8e6b0341fbf6e80b5737153a8b7631f8dbe4a9c2c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp312-cp312-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 b0b1da4c82e67295a19ecd4edd293bf7e809d27463b852643554cfaf4b4bd381
MD5 e5592693e4ee7814d63c410df39d9df9
BLAKE2b-256 b0a859eab340c65ddff45cd37623bc8a5eba868aebde025d8fe8fe91c22f4270

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.10.post1-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 3a07a25382c8685f39b45db272c5b08c4fbd5daa2dc64b964940243c07ce6ed9
MD5 c96013c952a792f571b5a3953ae8bfc3
BLAKE2b-256 517749e0a139a7116f1dd30e1e1e7f3bd2da3d1d17dfc3a7762ba0d077db8538

See more details on using hashes here.

Provenance

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

2.0.12

13 files

2.0.11

13 files

This release

2.0.10.post1 This release

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