Pre-release

This release is a pre-release and may not be stable for production use.

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.13a1.tar.gz (20.5 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.13a1-cp314-cp314-win_amd64.whl (294.3 kB view details)

Uploaded CPython 3.14Windows x86-64

docstring_generator_ext-2.0.13a1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (917.5 kB view details)

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

docstring_generator_ext-2.0.13a1-cp314-cp314-macosx_13_0_x86_64.whl (523.1 kB view details)

Uploaded CPython 3.14macOS 13.0+ x86-64

docstring_generator_ext-2.0.13a1-cp314-cp314-macosx_13_0_arm64.whl (524.5 kB view details)

Uploaded CPython 3.14macOS 13.0+ ARM64

docstring_generator_ext-2.0.13a1-cp313-cp313-win_amd64.whl (287.1 kB view details)

Uploaded CPython 3.13Windows x86-64

docstring_generator_ext-2.0.13a1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (917.5 kB view details)

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

docstring_generator_ext-2.0.13a1-cp313-cp313-macosx_13_0_x86_64.whl (523.2 kB view details)

Uploaded CPython 3.13macOS 13.0+ x86-64

docstring_generator_ext-2.0.13a1-cp313-cp313-macosx_13_0_arm64.whl (524.6 kB view details)

Uploaded CPython 3.13macOS 13.0+ ARM64

docstring_generator_ext-2.0.13a1-cp312-cp312-win_amd64.whl (287.1 kB view details)

Uploaded CPython 3.12Windows x86-64

docstring_generator_ext-2.0.13a1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (917.0 kB view details)

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

docstring_generator_ext-2.0.13a1-cp312-cp312-macosx_13_0_x86_64.whl (522.6 kB view details)

Uploaded CPython 3.12macOS 13.0+ x86-64

docstring_generator_ext-2.0.13a1-cp312-cp312-macosx_13_0_arm64.whl (524.2 kB view details)

Uploaded CPython 3.12macOS 13.0+ ARM64

File details

Details for the file docstring_generator_ext-2.0.13a1.tar.gz.

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1.tar.gz
Algorithm Hash digest
SHA256 eae4da950ac186caa6f5c66278860150254b4d7b6c8cc45534cd5665eefc3939
MD5 9923bff5829502da9eb142e45b72fef2
BLAKE2b-256 73c021f63dda4205ff5a102b39c29f95840fbcee6d8ce4c1aef4d6746373af67

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 d2fb55c975d86edbadfedceb6800b03905a5c6788fcb9f492566a59886d3d33a
MD5 4add40bd4c1a0e634e4b7920f0bfab66
BLAKE2b-256 ee1b9c62938f985791da5dc3db21a20649249f32e8e8ca516556513f28e7a26a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 56dfbe6435df9fedf8c2fcc22712afc16c53b941b99a552f0a8c905dcc571b16
MD5 e1abb0df55e1ffd3cc9ae20e6c31d58b
BLAKE2b-256 909c77e0ba26c1ad13cd2941d3b17528d68820719649cd0270ccac6ec25fa116

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp314-cp314-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 51f3c5bd90d8b351df681d1c3b79aa5f56748e06bf44922befcfb9437df964ad
MD5 b0061a3a5ca982fa770fe615ce931b22
BLAKE2b-256 b821542db17477135401dc7f7152a158f584c013769d87acedf4013bf0018ee6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp314-cp314-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 adb2b8035f7702004702c5b0c3c1a8bdd554760d7105250c09000a302f8c51e2
MD5 361471b7c2f21b45d677dcea7273bdb9
BLAKE2b-256 dd39bd722fc6ec99cd2a4f45ad4d2a3a56e14b268a065cef084b4f00e8c35bdf

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 95475665b7fad720553048f593b7a31fbd310ec2c1bd56de10399ed81e677f19
MD5 10dba21adb66f77dc29f8ede5f101d0d
BLAKE2b-256 a0888814ff06086e1c29a457b60991ce9394d68726b5b6b441377dd0de157831

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 788d25e936fe461a9bf2603b2b51f74cc950c109813557f83173a5fe609452fc
MD5 8cd6458a8fb79e3a63f5fafd91f13520
BLAKE2b-256 7088daa45526a30d40b71901973fd6469962cb8551cc973401f2137d0a9dbe50

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp313-cp313-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 a5d221cb7963c6cb5ba2d6da9e6696d4814706a01ec4025fa9ffebab1716dd3d
MD5 f2fa1f071b6950e86006ca5436eeba1d
BLAKE2b-256 5c526ab1a090367c1804cb9466fad45f3beeb801fa085cd914827ce9d9ce3c1d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp313-cp313-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 788c2f2b1c2160267e5ca5218acf1d559e8a062b9217a764756554f469bef171
MD5 6dc3e93bcd9dd5568400c7a5f102636a
BLAKE2b-256 c4c66adcaea892e5f75c7c13d9bc19424b6716202db5e80e8b2b7eb848b5f679

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 cc5ced7f2c85850e2513e4299ed55b5cfba2954c1fe26faeace76cf51dc442b5
MD5 afbc25d2500e00337e2c249d3a3c7fae
BLAKE2b-256 c536aba3211e599907497f1ba204118ade7684aca1d2f6b9781f1f9dbf96e477

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 57d0fc4cc60ed02738c75274c47fc80d3217d3ddf504ce307f5eaf961107e1c9
MD5 75046ccfac35b632805577adb4442bf1
BLAKE2b-256 56330c888422da0b0d3b44862e2029d7fcf845b6c1a7e81fe264e2f4f9dd5ed1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp312-cp312-macosx_13_0_x86_64.whl
Algorithm Hash digest
SHA256 7a88c8d9055828ae290c191cdc26d6e51192c0855ace9c51d4c6f92537b16682
MD5 4a16a8e9cc188a89ff151bfbe190a9fe
BLAKE2b-256 c3fc35188806f24b2710928cbfa00e76d9c4634f0d193889dab11d67533c8a4a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for docstring_generator_ext-2.0.13a1-cp312-cp312-macosx_13_0_arm64.whl
Algorithm Hash digest
SHA256 58ff009a2d7ac50a8617e78c7a42a6012113c79b991baf0831c512bb2625724a
MD5 6dd907e91d87c8bc8f430f76f06338e1
BLAKE2b-256 9e00f9506206483e4cef003939fee345bdac2660ffa416e4895c4e243148097a

See more details on using hashes here.

Provenance

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

This release
Pre-release

2.0.13a1 This release

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