docstring-generator-ext 1.0.2__tar.gz → 2.0.1__tar.gz

{docstring_generator_ext-1.0.2 → docstring_generator_ext-2.0.1}/MANIFEST.in

@@ -2,8 +2,7 @@
 include README.md
 include pyproject.toml
 include setup.py
-include src/docstringFormat.cpp
-include src/docstringFormat.hpp
+recursive-include src *.cpp *.hpp
 
 # What to exclude
 prune src/cmake-build-debug

{docstring_generator_ext-1.0.2 → docstring_generator_ext-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring_generator_ext
-Version: 1.0.2
+Version: 2.0.1
 Summary: Generate Docstrings with type-hint information.
 Author-email: FelixTheC <fberndt87@gmail.com>
 Classifier: Environment :: Console
@@ -81,6 +81,32 @@ style = docstring_generator_ext.DocstringFormatStyle.GOOGLE
 docstring_generator_ext.parse_file(file_path, style)
 ```
 
+You can also audit an existing file to see how well its functions are documented, without making any changes:
+
+```python
+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:
@@ -89,6 +115,28 @@ The extension provides an enum `DocstringFormatStyle` to choose the desired outp
 - `docstring_generator_ext.DocstringFormatStyle.GOOGLE`
 - `docstring_generator_ext.DocstringFormatStyle.NUMPY`
 
+## 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](https://pypi.org/project/docstring_generator_ext/) are compiled with C++20 enabled and require no special toolchain on the user's side.
+
+
 ## Authors
 
 - **FelixTheC**
@@ -97,3 +145,4 @@ The extension provides an enum `DocstringFormatStyle` to choose the desired outp
 
 This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
 
+

{docstring_generator_ext-1.0.2 → docstring_generator_ext-2.0.1}/README.md

@@ -67,6 +67,32 @@ style = docstring_generator_ext.DocstringFormatStyle.GOOGLE
 docstring_generator_ext.parse_file(file_path, style)
 ```
 
+You can also audit an existing file to see how well its functions are documented, without making any changes:
+
+```python
+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:
@@ -75,6 +101,28 @@ The extension provides an enum `DocstringFormatStyle` to choose the desired outp
 - `docstring_generator_ext.DocstringFormatStyle.GOOGLE`
 - `docstring_generator_ext.DocstringFormatStyle.NUMPY`
 
+## 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](https://pypi.org/project/docstring_generator_ext/) are compiled with C++20 enabled and require no special toolchain on the user's side.
+
+
 ## Authors
 
 - **FelixTheC**
@@ -83,3 +131,4 @@ The extension provides an enum `DocstringFormatStyle` to choose the desired outp
 
 This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
 
+

{docstring_generator_ext-1.0.2 → docstring_generator_ext-2.0.1}/docstring_generator_ext.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring_generator_ext
-Version: 1.0.2
+Version: 2.0.1
 Summary: Generate Docstrings with type-hint information.
 Author-email: FelixTheC <fberndt87@gmail.com>
 Classifier: Environment :: Console
@@ -81,6 +81,32 @@ style = docstring_generator_ext.DocstringFormatStyle.GOOGLE
 docstring_generator_ext.parse_file(file_path, style)
 ```
 
+You can also audit an existing file to see how well its functions are documented, without making any changes:
+
+```python
+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:
@@ -89,6 +115,28 @@ The extension provides an enum `DocstringFormatStyle` to choose the desired outp
 - `docstring_generator_ext.DocstringFormatStyle.GOOGLE`
 - `docstring_generator_ext.DocstringFormatStyle.NUMPY`
 
+## 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](https://pypi.org/project/docstring_generator_ext/) are compiled with C++20 enabled and require no special toolchain on the user's side.
+
+
 ## Authors
 
 - **FelixTheC**
@@ -97,3 +145,4 @@ The extension provides an enum `DocstringFormatStyle` to choose the desired outp
 
 This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
 
+

docstring_generator_ext-2.0.1/docstring_generator_ext.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+docstring_generator_ext.egg-info/PKG-INFO
+docstring_generator_ext.egg-info/SOURCES.txt
+docstring_generator_ext.egg-info/dependency_links.txt
+docstring_generator_ext.egg-info/requires.txt
+docstring_generator_ext.egg-info/top_level.txt
+src/FunctionFormat.cpp
+src/FunctionFormat.hpp
+src/GoogleDocstring.cpp
+src/GoogleDocstring.hpp
+src/IDocstringFormat.cpp
+src/IDocstringFormat.hpp
+src/NumpyDocstring.cpp
+src/NumpyDocstring.hpp
+src/ReStructuredDocstring.cpp
+src/ReStructuredDocstring.hpp
+src/docComparator.cpp
+src/docComparator.hpp
+src/docstringFormat.cpp
+src/docstringFormat.hpp
+src/parser.cpp
+src/parser.hpp

{docstring_generator_ext-1.0.2 → docstring_generator_ext-2.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring_generator_ext"
-version = "1.0.2"
+version = "2.0.1"
 description = "Generate Docstrings with type-hint information."
 authors = [
     { name = "FelixTheC", email = "fberndt87@gmail.com" },
@@ -41,5 +41,9 @@ archs = ["x86_64"]
 [tool.cibuildwheel.macos]
 archs = ["x86_64", "arm64"]
 
+[tool.cibuildwheel.macos.environment]
+MACOSX_DEPLOYMENT_TARGET = "13.3"
+CXXFLAGS = "-std=c++20"
+
 [tool.cibuildwheel.windows]
 archs = ["AMD64"]

docstring_generator_ext-2.0.1/setup.py

@@ -0,0 +1,59 @@
+# Available at setup time due to pyproject.toml
+import os
+import platform
+import shutil
+from setuptools import setup
+try:
+    from pybind11.setup_helpers import Pybind11Extension, build_ext
+except ImportError:
+    from setuptools import Extension as Pybind11Extension
+    build_ext = None
+
+# Ensure a modern system compiler is used instead of any toolchain compiler
+# (e.g. GNAT's old g++) that may appear earlier on PATH.
+def _find_compiler(names: list[str]) -> str | None:
+    for name in names:
+        path = shutil.which(name)
+        if path and "/GNAT" not in path and "/gnat" not in path:
+            return path
+    return None
+
+# On macOS, cibuildwheel uses Apple Clang and controls -arch flags for
+# cross-compilation (x86_64 / arm64).  Overriding CC/CXX with a
+# Homebrew GCC here would break that and produce a single-arch binary
+# that delocate-wheel rejects.  Only apply the GNAT-avoidance logic on
+# Linux (and Windows, where shutil.which won't find g++ anyway).
+if platform.system() != "Darwin":
+    if not os.environ.get("CC"):
+        cc = _find_compiler(["gcc-13", "gcc-14", "gcc-15", "gcc"])
+        if cc:
+            os.environ["CC"] = cc
+
+    if not os.environ.get("CXX"):
+        cxx = _find_compiler(["g++-13", "g++-14", "g++-15", "g++"])
+        if cxx:
+            os.environ["CXX"] = cxx
+
+
+ext_modules = [
+    Pybind11Extension(
+        "docstring_generator_ext",
+        [
+            "src/docstringFormat.cpp",
+            "src/parser.cpp",
+            "src/FunctionFormat.cpp",
+            "src/IDocstringFormat.cpp",
+            "src/GoogleDocstring.cpp",
+            "src/NumpyDocstring.cpp",
+            "src/ReStructuredDocstring.cpp",
+            "src/docComparator.cpp",
+        ],
+        include_dirs=["src"],
+        cxx_std=20,
+    ),
+]
+
+setup(
+    ext_modules=ext_modules,
+    cmdclass={"build_ext": build_ext} if build_ext else {},
+)

docstring_generator_ext-2.0.1/src/FunctionFormat.cpp

@@ -0,0 +1,177 @@
+#include "FunctionFormat.hpp"
+
+#include <map>
+#include "parser.hpp"
+
+const std::map<std::string, ParameterKind> ParameterKinds = {
+    {"argument", ParameterKind::ARG},
+    {"positional only argument", ParameterKind::POS_ONLY},
+    {"keyword only argument", ParameterKind::KW_ONLY},
+    {"variadic argument", ParameterKind::VARIADIC_ARG},
+    {"keyword arguments", ParameterKind::KEYWORD_ARG},
+};
+
+
+ParameterKind from_str(const std::string &kind) {
+    const auto kind_lower = to_lower(kind);
+    if (const auto it = ParameterKinds.find(kind_lower); it != ParameterKinds.end()) {
+        return it->second;
+    }
+    return ParameterKind::ARG;
+}
+
+std::ostream &operator<<(std::ostream &out, ParameterKind const &obj) noexcept {
+    switch (obj) {
+        case ParameterKind::ARG:
+            return out << "Argument";
+        case ParameterKind::POS_ONLY:
+            return out << "Positional only argument";
+        case ParameterKind::KW_ONLY:
+            return out << "Keyword only argument";
+        case ParameterKind::VARIADIC_ARG:
+            return out << "Variadic arguments";
+        case ParameterKind::KEYWORD_ARG:
+            return out << "Keyword arguments";
+    }
+
+    return out;
+}
+
+void FunctionParameter::update_description(const std::string &descr, const DocstringFormatStyle &formatStyle) noexcept {
+    switch (formatStyle) {
+        case DocstringFormatStyle::reST:
+            update_rest_description(descr);
+            break;
+        case DocstringFormatStyle::GOOGLE:
+        case DocstringFormatStyle::NUMPY:
+            update_description(descr);
+            break;
+    }
+}
+
+void FunctionParameter::update_description(const std::string &descr) noexcept {
+    if (descr.empty()) {
+        return;
+    }
+
+    std::stringstream sstream;
+    sstream << kind;
+
+    const auto kind_name = sstream.str();
+    auto start_pos = descr.find(kind_name);
+
+    if (start_pos == std::string::npos)
+       start_pos = 0;
+    else {
+        start_pos += kind_name.size() + 2;
+    }
+
+    auto end_pos = descr.size();
+
+    if (!default_value.empty()) {
+        if (const auto default_pos = descr.find("default"); default_pos != std::string::npos)
+            end_pos = default_pos - 2;
+    }
+
+    if (end_pos != std::string::npos) {
+        const auto new_description = descr.substr(start_pos, end_pos - start_pos);
+        description = remove_whitespace(remove_trailing_whitespace(new_description));
+    }
+}
+
+void FunctionParameter::update_rest_description(const std::string &descr) noexcept {
+    auto param_name = ":param " + name + ":";
+    auto type_param = ":type " + name + ":";
+    auto kind_param = ":kind " + name + ":";
+    auto start_pos = descr.find(param_name);
+    if (start_pos == std::string::npos) {
+        return;
+    }
+
+    start_pos += param_name.size();
+    size_t end_pos = std::string::npos;
+
+    if (!default_value.empty()) {
+        end_pos = descr.find("(default is");
+    } else if (!type.empty()) {
+        end_pos = descr.find(type_param);
+    } else {
+        end_pos = descr.find(kind_param);
+    }
+
+    auto new_description = descr.substr(start_pos);
+
+    if (end_pos != std::string::npos) {
+        new_description = descr.substr(start_pos, end_pos - start_pos);
+    }
+
+    description = remove_whitespace(remove_trailing_whitespace(new_description));
+}
+
+[[nodiscard]] int FunctionInfo::get_file_write_position() const noexcept {
+    if (!docstring.docstring.empty()) {
+        return docstring.start_line;
+    }
+
+    if (returns.line_no > 0) {
+        return static_cast<int>(returns.line_no + 1);
+    }
+    if (!args.empty()) {
+        return static_cast<int>(args[args.size() - 1].line_no + 1);
+    }
+
+    return 0;
+}
+
+void FunctionInfo::update_descriptions(const DocstringFormatStyle &formatStyle) noexcept {
+    for (size_t idx = 0; idx < args.size(); ++idx) {
+        size_t start_pos;
+
+        if (formatStyle == DocstringFormatStyle::reST) {
+            start_pos = docstring.docstring.find(":param " + args[idx].name + ":");
+        } else {
+            start_pos = docstring.docstring.find(args[idx].name);
+        }
+
+        if (start_pos < std::string::npos) {
+            size_t end_pos = docstring.docstring.size() - 1;
+
+            if (idx < args.size() - 1) {
+                end_pos = docstring.docstring.find(args[idx + 1].name);
+            } else if (idx == args.size() - 1 && docstring.docstring.find("Returns") < std::string::npos) {
+                if (const auto return_pos = docstring.docstring.find("Returns"); return_pos != std::string::npos) {
+                    end_pos = return_pos - 1;
+                }
+            }
+
+            if (end_pos != std::string::npos) {
+                std::string part_of_interest = docstring.docstring.substr(start_pos, end_pos - start_pos);
+                args[idx].update_description(part_of_interest, formatStyle);
+            }
+        }
+    }
+}
+
+FunctionDocstring get_docstring(const py::object &obj, const py::module &ast_module) noexcept {
+    FunctionDocstring functionDocstring{};
+
+    py::list body_list = py::getattr(obj, "body");
+    py::object body = body_list[0];
+
+    if (py::hasattr(body, "value")) {
+        py::object body_val = py::getattr(body, "value");
+
+        if (py::isinstance(body_val, ast_module.attr("Constant"))) {
+            try {
+                functionDocstring.docstring = py::cast<std::string>(py::getattr(body_val, "value"));
+            } catch (std::exception &) {
+                return functionDocstring;
+            }
+
+            functionDocstring.start_line = py::cast<uint32_t>(py::getattr(body_val, "lineno"));
+            functionDocstring.end_line = py::cast<uint32_t>(py::getattr(body_val, "end_lineno"));
+        }
+    }
+
+    return functionDocstring;
+}

docstring_generator_ext-2.0.1/src/FunctionFormat.hpp

@@ -0,0 +1,72 @@
+#ifndef DOCSTRING_GENERATOR_EXT_FUNCTIONFORMAT_HPP
+#define DOCSTRING_GENERATOR_EXT_FUNCTIONFORMAT_HPP
+#include <set>
+#include <string>
+#include <vector>
+
+#include <pybind11/pybind11.h>
+namespace py = pybind11;
+
+enum class ParameterKind {
+    ARG,
+    POS_ONLY,
+    KW_ONLY,
+    VARIADIC_ARG,
+    KEYWORD_ARG,
+};
+
+enum class DocstringFormatStyle {
+    reST,
+    GOOGLE,
+    NUMPY
+};
+
+ParameterKind from_str(const std::string &kind);
+std::ostream &operator<<(std::ostream &out, ParameterKind const &obj) noexcept;
+
+struct FunctionParameter {
+    std::string name;
+    std::string default_value;
+    std::string type;
+    ParameterKind kind;
+    uint32_t line_no;
+    std::string description{};
+
+    void update_description(const std::string &descr, const DocstringFormatStyle &formatStyle) noexcept;
+    void update_description(const std::string &descr) noexcept;
+    void update_rest_description(const std::string &descr) noexcept;
+};
+
+struct FunctionReturn {
+    uint32_t line_no{};
+    std::string type;
+    std::string description;
+};
+
+struct FunctionDocstring {
+    uint32_t start_line{};
+    size_t end_line{};
+    std::string docstring;
+};
+
+FunctionDocstring get_docstring(const py::object &obj, const py::module &ast_module) noexcept;
+
+struct FunctionException {
+    std::string name;
+    std::string description;
+
+    auto operator<=>(const FunctionException&) const = default;
+};
+
+struct FunctionInfo {
+    std::vector<FunctionParameter> args{};
+    uint32_t offset{};
+    FunctionDocstring docstring;
+    FunctionReturn returns;
+    std::set<FunctionException> exceptions {};
+
+    [[nodiscard]] int get_file_write_position() const noexcept;
+    void update_descriptions(const DocstringFormatStyle &formatStyle) noexcept;
+};
+
+#endif //DOCSTRING_GENERATOR_EXT_FUNCTIONFORMAT_HPP