docstring-generator-ext 1.0.2__tar.gz → 1.0.3a5__tar.gz

{docstring_generator_ext-1.0.2 → docstring_generator_ext-1.0.3a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring_generator_ext
-Version: 1.0.2
+Version: 1.0.3a5
 Summary: Generate Docstrings with type-hint information.
 Author-email: FelixTheC <fberndt87@gmail.com>
 Classifier: Environment :: Console

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring_generator_ext
-Version: 1.0.2
+Version: 1.0.3a5
 Summary: Generate Docstrings with type-hint information.
 Author-email: FelixTheC <fberndt87@gmail.com>
 Classifier: Environment :: Console

{docstring_generator_ext-1.0.2 → docstring_generator_ext-1.0.3a5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring_generator_ext"
-version = "1.0.2"
+version = "1.0.3a5"
 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-1.0.2 → docstring_generator_ext-1.0.3a5}/src/docstringFormat.cpp

@@ -1,9 +1,10 @@
 #include "docstringFormat.hpp"
 #include <algorithm>
-#include <sstream>
-#include <map>
+#include <format>
 #include <fstream>
 #include <iostream>
+#include <map>
+#include <sstream>
 
 #include <pybind11/pybind11.h>
 namespace py = pybind11;
@@ -107,7 +108,7 @@ void FunctionParameter::update_description(const std::string &descr) noexcept {
     std::stringstream sstream;
     sstream << kind;
 
-    auto kind_name = sstream.str();
+    const auto kind_name = sstream.str();
     auto start_pos = descr.find(kind_name) + kind_name.size() + 2;
 
     if (descr.find(kind_name) == std::string::npos)
@@ -119,7 +120,7 @@ void FunctionParameter::update_description(const std::string &descr) noexcept {
         end_pos = descr.find("default") - 2;
     }
 
-    auto new_description = descr.substr(start_pos, end_pos - start_pos);
+    const auto new_description = descr.substr(start_pos, end_pos - start_pos);
     description = remove_whitespace(remove_trailing_whitespace(new_description));
 }
 
@@ -143,13 +144,13 @@ void FunctionParameter::update_rest_description(const std::string &descr) noexce
         end_pos = descr.find(kind_param);
     }
 
+    auto new_description = descr.substr(start_pos);
+
     if (end_pos != std::string::npos) {
-        auto new_description = descr.substr(start_pos, end_pos - start_pos);
-        description = remove_whitespace(remove_trailing_whitespace(new_description));
-    } else {
-        auto new_description = descr.substr(start_pos);
-        description = remove_whitespace(remove_trailing_whitespace(new_description));
+        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 {
@@ -167,7 +168,7 @@ void FunctionParameter::update_rest_description(const std::string &descr) noexce
     return 0;
 }
 
-void FunctionInfo::update_descriptions(DocstringFormatStyle &formatStyle) noexcept {
+void FunctionInfo::update_descriptions(const DocstringFormatStyle &formatStyle) noexcept {
     for (size_t idx = 0; idx < args.size(); ++idx) {
         size_t start_pos;
 
@@ -194,7 +195,7 @@ void FunctionInfo::update_descriptions(DocstringFormatStyle &formatStyle) noexce
 
 [[ nodiscard ]] std::string DocstringFormat::docstring() noexcept {
     std::stringstream sstream;
-    auto current_pytab = get_tabs();
+    const auto current_pytab = get_tabs();
 
     sstream << current_pytab << R"(""")";
     if (functionInfo.docstring.docstring.empty()) {
@@ -202,6 +203,7 @@ void FunctionInfo::update_descriptions(DocstringFormatStyle &formatStyle) noexce
     }
     sstream << docstringArgs();
     sstream << docstringReturn();
+    sstream << docstringExceptions();
 
     sstream << current_pytab << R"(""")";
     if (functionInfo.docstring.docstring.empty()) {
@@ -251,9 +253,7 @@ std::string GoogleDocstring::docstringArgs() noexcept {
     }
 
     sstream << "Args:\n";
-    std::for_each(
-        functionInfo.args.begin(),
-        functionInfo.args.end(),
+    std::ranges::for_each(functionInfo.args,
         [&sstream, &current_py_tab](const FunctionParameter &val) {
             sstream << current_py_tab << val.name;
             if (!val.type.empty()) {
@@ -264,14 +264,12 @@ std::string GoogleDocstring::docstringArgs() noexcept {
                 sstream << ")";
             }
 
-            if (val.description.empty()) {
-                sstream << " : " << val.kind << "\n";
-            } else {
-                sstream << " : " << val.kind << ". " << val.description << "\n";
+            if (!val.description.empty()) {
+                sstream << ": " << val.description;
             }
 
             if (!val.default_value.empty()) {
-                sstream << current_py_tab << PY_TAB << "(default is " << val.default_value << ")\n";
+                sstream << " (default is " << val.default_value << ")\n";
             }
         }
     );
@@ -283,9 +281,9 @@ std::string GoogleDocstring::docstringReturn() noexcept {
     std::stringstream sstream;
     auto current_py_tab = get_tabs();
 
-    sstream << "\n";
-
     if (!functionInfo.returns.description.empty() || !functionInfo.returns.type.empty()) {
+        sstream << "\n";
+
         if (PY_TAB != current_py_tab) {
             sstream << PY_TAB;
         } else {
@@ -295,10 +293,46 @@ std::string GoogleDocstring::docstringReturn() noexcept {
 
         sstream << "Returns:\n";
         sstream << current_py_tab;
+
         if (!functionInfo.returns.type.empty()) {
-            sstream << "( " << functionInfo.returns.type << " ) : ";
+            sstream << functionInfo.returns.type << ": ";
+        }
+        if (!functionInfo.returns.description.empty()) {
+            sstream << functionInfo.returns.description;
+        }
+    } else {
+        sstream << "";
+    }
+
+    return sstream.str();
+}
+
+std::string GoogleDocstring::docstringExceptions() noexcept {
+    if (functionInfo.exceptions.empty())
+        return "\n";
+
+    std::stringstream sstream;
+    auto current_py_tab = get_tabs();
+
+    sstream << "\n";
+
+    if (PY_TAB != current_py_tab) {
+        sstream << PY_TAB;
+    } else {
+        sstream << PY_TAB;
+        current_py_tab = PY_TAB + PY_TAB;
+    }
+
+    sstream << "Raises:\n";
+    sstream << current_py_tab;
+
+    for (const auto &[name, description] : functionInfo.exceptions) {
+        if (!name.empty()) {
+            sstream << name << ": ";
+        }
+        if (!description.empty()) {
+            sstream << description;
         }
-        sstream << functionInfo.returns.description << "\n";
 
         sstream << "\n";
     }
@@ -367,10 +401,23 @@ std::string reStructuredDocstring::docstringReturn() noexcept {
     const auto current_py_tab = get_tabs();
 
     if (!functionInfo.returns.description.empty()) {
-        sstream << current_py_tab << ":returns:" << functionInfo.returns.description << "\n";
+        sstream << current_py_tab << ":returns: " << functionInfo.returns.description << "\n";
     }
     if (!functionInfo.returns.type.empty()) {
-        sstream << current_py_tab << ":rtype:" << functionInfo.returns.type << "\n";
+        sstream << current_py_tab << ":rtype: " << functionInfo.returns.type << "\n";
+    }
+    return sstream.str();
+}
+
+std::string reStructuredDocstring::docstringExceptions() noexcept {
+    if (functionInfo.exceptions.empty())
+        return "";
+
+    std::stringstream sstream;
+    const auto current_py_tab = get_tabs();
+
+    for (const auto &[name, description] : functionInfo.exceptions) {
+        sstream << current_py_tab << ":raises " << name << ": " << description << "\n";
     }
     return sstream.str();
 }
@@ -404,7 +451,11 @@ std::string NumpyDocstring::docstringArgs() noexcept {
         [&docstream, &current_py_tab](const FunctionParameter &val) {
             std::stringstream sstream;
 
-            sstream << current_py_tab << val.name;
+            if (val.name.empty())
+                sstream << current_py_tab << "PLACEHOLDER";
+            else
+                sstream << current_py_tab << val.name;
+
             sstream << " :";
 
             if (!val.type.empty()) {
@@ -456,7 +507,33 @@ std::string NumpyDocstring::docstringReturn() noexcept {
         sstream << current_py_tab << PY_TAB << functionInfo.returns.description;
     }
 
+    if (!functionInfo.returns.type.empty() || !functionInfo.returns.description.empty())
+        sstream << "\n";
+
+    return sstream.str();
+}
+
+std::string NumpyDocstring::docstringExceptions() noexcept {
+    if (functionInfo.exceptions.empty())
+        return "";
+
+    std::stringstream sstream;
+    const auto current_py_tab = get_tabs();
+
     sstream << "\n";
+    sstream << current_py_tab << "Raises\n";
+    sstream << current_py_tab << "-------\n";
+
+    for (const auto &[name, description]: functionInfo.exceptions) {
+        if (!name.empty()) {
+            sstream << current_py_tab << name;
+            sstream << "\n";
+        }
+        if (!description.empty()) {
+            sstream << current_py_tab << PY_TAB << description;
+        }
+        sstream << "\n";
+    }
 
     return sstream.str();
 }
@@ -464,7 +541,7 @@ std::string NumpyDocstring::docstringReturn() noexcept {
 void write_to_file_position(
     std::vector<FunctionInfo> &&infos,
     const std::string &file_path,
-    DocstringFormatStyle &formatStyle
+                            const DocstringFormatStyle &formatStyle
 ) noexcept;
 
 FunctionDocstring get_docstring(const py::object &obj, const py::module &ast_module) noexcept {
@@ -656,7 +733,7 @@ std::vector<FunctionParameter> generate_function_parameters(
             annotation_str = parse_ast_obj(annotation, ast_module);
         }
 
-        std::string parameter_name = py::cast<std::string>(py::getattr(vararg, "arg"));
+        auto parameter_name = py::cast<std::string>(py::getattr(vararg, "arg"));
         result.emplace_back(
             FunctionParameter{
                 parameter_name,
@@ -678,7 +755,7 @@ std::vector<FunctionParameter> generate_function_parameters(
                 annotation_str = parse_ast_obj(annotation, ast_module);
             }
 
-            std::string parameter_name = py::cast<std::string>(py::getattr(elem, "arg"));
+            auto parameter_name = py::cast<std::string>(py::getattr(elem, "arg"));
             result.emplace_back(
                 FunctionParameter{
                     parameter_name,
@@ -700,7 +777,7 @@ std::vector<FunctionParameter> generate_function_parameters(
             annotation_str = parse_ast_obj(annotation, ast_module);
         }
 
-        std::string parameter_name = py::cast<std::string>(py::getattr(kwarg, "arg"));
+        auto parameter_name = py::cast<std::string>(py::getattr(kwarg, "arg"));
         result.emplace_back(
             FunctionParameter{
                 parameter_name,
@@ -805,8 +882,77 @@ void get_docstring_arg_descr(FunctionInfo &functionInfo) noexcept {
     }
 }
 
+void get_exception(const pybind11::object &function_body, py::module &ast_module, std::vector<FunctionException> &exception_names, const py::object &parent = py::none()) {
+    py::iterator iter = py::iter(function_body);
+    for (auto &obj: iter) {
+        if (py::hasattr(obj, "body")) {
+            const auto inner = py::getattr(obj, "body");
+            if (py::isinstance(obj, ast_module.attr("If"))) {
+                auto parent_node = py::reinterpret_borrow<py::object>(obj);
+                get_exception(inner, ast_module, exception_names, parent_node);
+            }
+            else
+                get_exception(inner, ast_module, exception_names);
+        }
+
+        if (py::isinstance(obj, ast_module.attr("Try"))) {
+            auto handlers = py::getattr(obj, "handlers");
+            py::iterator handlers_iter = py::iter(handlers);
+            for (const auto &handler : handlers_iter) {
+                const auto parent_node = py::reinterpret_borrow<py::object>(handler);
+                const auto inner = py::getattr(handler, "body");
+                get_exception(inner, ast_module, exception_names, parent_node);
+            }
+        }
+
+        if (py::isinstance(obj, ast_module.attr("Raise"))) {
+            // when `exc` is None this means we're re-raising the exception
+            if (py::getattr(obj, "exc").is(py::none())) {
+                if (!parent.is(py::none())) {
+                    if (py::hasattr(parent, "type")) {
+                        const auto exception_type = py::getattr(parent, "type");
+                        if (py::hasattr(exception_type, "id")) {
+                            const auto exception_name = py::cast<std::string>(py::getattr(exception_type, "id"));
+                            exception_names.emplace_back(FunctionException{.name=exception_name, .description="Re-raising this handled exception"});
+                        }
+                    }
+                }
+            } else {
+                try {
+                    const auto exception_object = py::getattr(py::getattr(obj, "exc"), "func");
+                    if (py::hasattr(exception_object, "id")) {
+                        const auto exception_name = py::cast<std::string>(py::getattr(exception_object, "id"));
+                        std::string exception_description = "If a certain condition is met.";
+
+                        if (!parent.is(py::none())) {
+                            if (py::hasattr(parent, "test")) {
+                                const auto val = py::cast<std::string>(ast_module.attr("unparse")(py::getattr(parent, "test")));
+                                // Should theoretical not be empty, cause we parse an "If" expression
+                                if (!val.empty()) {
+                                    exception_description = std::format("If {}", val);
+                                }
+                            } else if (py::hasattr(parent, "type")) {
+                                const auto exception_type = py::getattr(parent, "type");
+                                if (py::hasattr(exception_type, "id")) {
+                                    const auto main_exception_name = py::cast<std::string>(py::getattr(exception_type, "id"));
+                                    if (!main_exception_name.empty())
+                                        exception_description = std::format("Re-Raised from {}", main_exception_name);
+                                }
+                            }
+                        }
+
+                        if (!exception_name.empty())
+                            exception_names.emplace_back(FunctionException{.name=exception_name, .description=exception_description});
+                    }
+                } catch (const std::exception &) {
+                    py::print("Could not extract exception.");
+                }
+            }
+        }
+    }
+}
+
 void parse_file(std::string &file_path, DocstringFormatStyle &formatStyle) {
-    std::string file_path_cache = file_path;
     py::module ast_module = py::module_::import("ast");
     py::object generator_result = ast_module.attr("walk")(ast_module.attr("parse")(read_file(file_path)));
     py::iterator iter = py::iter(generator_result);
@@ -814,7 +960,14 @@ void parse_file(std::string &file_path, DocstringFormatStyle &formatStyle) {
     std::vector<FunctionInfo> infos{};
 
     for (auto &obj: iter) {
-        if (py::isinstance(obj, ast_module.attr("FunctionDef"))) {
+        if (py::isinstance(obj, ast_module.attr("FunctionDef")) || py::isinstance(obj, ast_module.attr("AsyncFunctionDef"))) {
+            std::vector<FunctionException> function_exceptions{};
+
+            if (py::hasattr(obj, "body")) {
+                auto inner = py::getattr(obj, "body");
+                get_exception(inner, ast_module, function_exceptions);
+            }
+
             auto name = py::cast<std::string>(py::getattr(obj, "name"));
             auto offset = py::cast<uint32_t>(py::getattr(obj, "col_offset"));
 
@@ -840,13 +993,17 @@ void parse_file(std::string &file_path, DocstringFormatStyle &formatStyle) {
             auto f_args = generate_function_parameters(args, ast_module);
 
             FunctionInfo functionInfo{
-                        f_args,
-                        offset,
-                        doc_str,
-                        functionReturn,
-
+                        .args=f_args,
+                        .offset=offset,
+                        .docstring=doc_str,
+                        .returns=functionReturn,
+                        .exceptions={}
                     };
 
+            for (auto &exception: function_exceptions) {
+                functionInfo.exceptions.insert(exception);
+            }
+
             get_docstring_arg_descr(functionInfo);
             functionInfo.update_descriptions(formatStyle);
 
@@ -854,21 +1011,21 @@ void parse_file(std::string &file_path, DocstringFormatStyle &formatStyle) {
         }
     }
 
-    std::sort(
-        infos.begin(),
-        infos.end(),
-        [](FunctionInfo &left, FunctionInfo &right) {
+    std::ranges::sort(infos,
+        [](const FunctionInfo &left, const FunctionInfo &right) {
             return left.get_file_write_position() > right.get_file_write_position();
         }
     );
 
+#ifndef DRY_RUN
     write_to_file_position(std::move(infos), file_path, formatStyle);
+#endif
 }
 
 void write_to_file_position(
     std::vector<FunctionInfo> &&infos,
     const std::string &file_path,
-    DocstringFormatStyle &formatStyle
+    const DocstringFormatStyle &formatStyle
 ) noexcept {
     std::fstream file;
 
@@ -921,9 +1078,7 @@ void write_to_file_position(
 
     file.open(file_path, std::ios::out);
 
-    std::for_each(
-        lines.begin(),
-        lines.end(),
+    std::ranges::for_each(lines,
         [&file](const auto &line) {
             file << line;
             if (line[line.size() - 1] != '\n') {

{docstring_generator_ext-1.0.2 → docstring_generator_ext-1.0.3a5}/src/docstringFormat.hpp

@@ -2,6 +2,7 @@
 #define DOCSTRING_GENERATOR_EXT_DOCSTRINGFORMAT_HPP
 
 #include <memory>
+#include <set>
 #include <string>
 #include <vector>
 
@@ -54,14 +55,22 @@ struct FunctionDocstring {
     std::string docstring;
 };
 
+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(DocstringFormatStyle &formatStyle) noexcept;
+    void update_descriptions(const DocstringFormatStyle &formatStyle) noexcept;
 };
 
 struct DocstringFormat {
@@ -69,6 +78,7 @@ struct DocstringFormat {
 
     virtual std::string docstringArgs() noexcept = 0;
     virtual std::string docstringReturn() noexcept = 0;
+    virtual std::string docstringExceptions() noexcept = 0;
     virtual void check_current_docstring() noexcept = 0;
 
     virtual ~DocstringFormat() = default;
@@ -81,18 +91,21 @@ struct GoogleDocstring : DocstringFormat {
     void check_current_docstring() noexcept override;
     std::string docstringArgs() noexcept override;
     std::string docstringReturn() noexcept override;
+    std::string docstringExceptions() noexcept override;
 };
 
 struct reStructuredDocstring : DocstringFormat {
     void check_current_docstring() noexcept override;
     std::string docstringArgs() noexcept override;
     std::string docstringReturn() noexcept override;
+    std::string docstringExceptions() noexcept override;
 };
 
 struct NumpyDocstring : DocstringFormat {
     void check_current_docstring() noexcept override;
     std::string docstringArgs() noexcept override;
     std::string docstringReturn() noexcept override;
+    std::string docstringExceptions() noexcept override;
 };
 
 std::string read_file(const std::string &file_path);