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.11.tar.gz (16.9 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.11-cp314-cp314-win_amd64.whl (259.1 kB view details)

Uploaded CPython 3.14Windows x86-64

docstring_generator_ext-2.0.11-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (696.5 kB view details)

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

docstring_generator_ext-2.0.11-cp314-cp314-macosx_13_0_x86_64.whl (430.8 kB view details)

Uploaded CPython 3.14macOS 13.0+ x86-64

docstring_generator_ext-2.0.11-cp314-cp314-macosx_13_0_arm64.whl (434.9 kB view details)

Uploaded CPython 3.14macOS 13.0+ ARM64

docstring_generator_ext-2.0.11-cp313-cp313-win_amd64.whl (253.2 kB view details)

Uploaded CPython 3.13Windows x86-64

docstring_generator_ext-2.0.11-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (696.6 kB view details)

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

docstring_generator_ext-2.0.11-cp313-cp313-macosx_13_0_x86_64.whl (430.9 kB view details)

Uploaded CPython 3.13macOS 13.0+ x86-64

docstring_generator_ext-2.0.11-cp313-cp313-macosx_13_0_arm64.whl (434.9 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

docstring_generator_ext-2.0.11-cp312-cp312-win_amd64.whl (253.2 kB view details)

Uploaded CPython 3.12Windows x86-64

docstring_generator_ext-2.0.11-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (696.1 kB view details)

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

docstring_generator_ext-2.0.11-cp312-cp312-macosx_13_0_x86_64.whl (430.5 kB view details)

Uploaded CPython 3.12macOS 13.0+ x86-64

docstring_generator_ext-2.0.11-cp312-cp312-macosx_13_0_arm64.whl (434.7 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

File details

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

File metadata

  • Download URL: docstring_generator_ext-2.0.11.tar.gz
  • Upload date:
  • Size: 16.9 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.11.tar.gz
Algorithm Hash digest
SHA256 3a322ee9597a05105d27fd4b396c5ca7d06dbd6e78096619483b9b115712cdde
MD5 06bd4e7c066f06dccbf93772db41a73d
BLAKE2b-256 0afa11df4752ecbb80f978cb543282dade00218a1e89754b378b279d9b1e1381

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 a93a7d2c92099f96483a3032427f17303b472c65c1862aaa7349b77c0c3ede6f
MD5 2ace45cb89a4c9031919b820c392a738
BLAKE2b-256 0b7efa304c6483bc01c183bed877e20c847c399accdffa1a663a30e97f0ee2f1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0f4884c4c9c24cd210e25b0e4766fecdd7080cb06f64e0272fd12c46ab6a5d63
MD5 8be4af0eaa0564545f445f55d8e005f7
BLAKE2b-256 50bedb7b63f18a1bd130774d544efb614b224c0e000d725da7965ef7066fcaba

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp314-cp314-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 da2a44ec1fbd4795685008f537f454aed5570f720f7713792e7fdef6a7ee7a7b
MD5 ca98df52c23fecac6a765219599f2f54
BLAKE2b-256 c6d97db644448aab4e185c70371260b543b2e7de9722c44cf6d8c3fad9148243

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp314-cp314-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 638d14b701398d813add22b4d3554e6949374b85a0adb517d0cd90c499d69b38
MD5 ce0cf41ba4e5b54914588cb89e529191
BLAKE2b-256 7c2113d335ffa236815323f9f0a29da9cba32d7a8090119a2b740bf938365133

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 06929370d3082c8eb727cdc4f1772b20468db3e1ee2dfea991b9704049092b38
MD5 994dfa8e6e518f806e7b12b088cb4aaf
BLAKE2b-256 c032e171d118cc33b72774d4d0533b3670f826c8d144ca4c836322891f51f2a8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 70620dced6ae3effb30ec81d0e34f149d5c3fcf1c045631d0be178f59437750f
MD5 1d1fa403ab20bbd96484b4264a56cfd9
BLAKE2b-256 7f980b61e568951aca07de8399ae9173c020ad8a27782e6f3898b8f77318faf7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp313-cp313-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 a8a5c5cd1a33ca25866bc495b4e0eb146a1c79cf730fc7910d33a9c13abe383e
MD5 3dec2c0dc30167db4ccb822a2498841b
BLAKE2b-256 156d21557506205b89c794e399431f2c42a2121935e7fb7e4e4e6121fc3d1dd1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 008d873cfea0d44d14e2c6444a229fd0b5951e3c6c188790a79f5dcce783f6c4
MD5 b4ef00a528ba279f07aca2aab18d5256
BLAKE2b-256 69abb2050937b440ea29d649f018305319ea25ff019b05de272e57ea0f612999

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 ea8cd9bedcd700565e95ec19019a9f15072e57f5f632908c46a64283573dbf5c
MD5 24563a852d9cf960892dd4be6294053e
BLAKE2b-256 df453a1ff2c4a262aeca135d13db837fce2a7e8b7c49fa1f2516b6a7760af484

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b36d87e691029f8487917470ccf74e9c6c79fd03304d3c770df26c53032934f3
MD5 91af97564a1f9c3ae7db559adb1a1d5d
BLAKE2b-256 a87a7c087adfed3d8eb23230496ae4a60af437b640350052267e83fecf4a10b6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp312-cp312-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 a60a55d64da00e4ee62c40b5ef2479e5e305559d4f9d1a6f696761aa6fce4755
MD5 a1916c2a95b655911e5821ca80e99ca4
BLAKE2b-256 faf0b6c6bfe811413231c16134c542e073e8b0da1225a06d704b1e771b5a7946

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.11-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 af87b9d4a6fe3b8f6727737098c6fd789dca58a644ffccab3bd59752af39a6d3
MD5 502fa42d55d5c8409aa62a031e66f37b
BLAKE2b-256 4e9ab5f15d02c7a9394cc08165ee0c9a24e5df8d7215d420928f9c19ddf90d50

See more details on using hashes here.

Provenance

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

This release

2.0.11 This release

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