docstring-generator-ext 2.0.13a1__tar.gz → 2.0.14__tar.gz

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/PKG-INFO

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

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/docstring_generator_ext.egg-info/PKG-INFO

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

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring_generator_ext"
-version = "2.0.13a1"
+version = "2.0.14"
 description = "Generate Docstrings with type-hint information."
 authors = [
     { name = "FelixTheC", email = "fberndt87@gmail.com" },

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/src/FunctionFormat.cpp

@@ -131,6 +131,16 @@ void FunctionParameter::erase() {
 void FunctionInfo::update_descriptions(const DocstringFormatStyle &formatStyle) noexcept {
 
   const auto extractor = ExistingDocstringExtractor::parse_text(docstring.docstring, formatStyle);
+  if (!extractor.get_return_info().empty())
+    returns.description = extractor.get_return_info()[0].description;
+
+  if (!extractor.get_exception_info().empty()) {
+    for (const auto &exception: extractor.get_exception_info()) {
+      exceptions.emplace(exception.type, exception.description);
+    }
+  }
+
+  docstring.docstring = extractor.get_reduced_docstring();
   size_t param_idx = 0;
   // we expect that the params are in the same order, cause otherwise we had somewhere a violation agains a PEP
   for (const auto &param: extractor.get_extracted_parameters()) {

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/src/GoogleDocstring.cpp

@@ -38,8 +38,10 @@ std::string GoogleDocstring::docstringSummary() noexcept {
   if (res.empty())
     return res;
   if (!functionInfo.summary_only()) {
-    if (!res.ends_with('\n'))
+    if (!res.ends_with('\n')) {
       res += '\n';
+      res += '\n';
+    }
   }
   return res;
 }
@@ -85,8 +87,8 @@ std::string GoogleDocstring::docstringArgs() noexcept {
     }
 
     if (!val.default_value.empty()) {
-      auto tmp = std::format("Defaults to {}.", val.default_value);
-      if (val.description.empty() || val.description.find(tmp) == std::string::npos)
+      if (auto tmp = std::format("Defaults to {}.", val.default_value);
+        val.description.empty() || val.description.find(tmp) == std::string::npos)
         result += tmp;
     }
 

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/src/IDocstringFormat.cpp

@@ -20,21 +20,18 @@ bool onlyQuotesAndWhitespace(const std::string &s) {
     tmp += argTxt;
   }
   if (const auto returnTxt = docstringReturn(); !returnTxt.empty()) {
-    if (tmp.empty())
-      tmp += '\n';
     tmp += returnTxt;
   }
   if (const auto exceptionTxt = docstringExceptions(); !exceptionTxt.empty() && exceptionTxt != "\n") {
-    if (tmp.empty())
-      tmp += '\n';
     tmp += exceptionTxt;
   }
 
   result += current_pytab;
   result += R"(""")";
   if (const auto summaryTxt = docstringSummary(); !summaryTxt.empty()) {
-    if (trim(tmp) != trim(summaryTxt))
-      result += summaryTxt;
+    result += summaryTxt;
+    if (!result.empty() && !result.ends_with('\n') && !tmp.empty())
+      result += '\n';
   } else {
     result += '\n';
   }

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/src/NumpyDocstring.cpp

@@ -23,6 +23,7 @@ std::string NumpyDocstring::docstringSummary() noexcept {
     return res;
   if (!functionInfo.summary_only()) {
     res += '\n';
+    res += '\n';
   }
   return res;
 }
@@ -105,7 +106,6 @@ std::string NumpyDocstring::docstringReturn() noexcept {
     result += std::format("{}{}{}", current_py_tab, PY_TAB, functionInfo.returns.description);
   }
 
-  result += '\n';
   result += '\n';
   return result;
 }
@@ -116,6 +116,10 @@ std::string NumpyDocstring::docstringExceptions() noexcept {
 
   std::string result;
   result.reserve(256);
+
+  if (!functionInfo.returns.type.empty())
+    result += '\n';
+
   const auto current_py_tab = get_tabs();
 
   result += std::format("{}Raises\n", current_py_tab);

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/src/docstringFormat.cpp

@@ -207,7 +207,7 @@ std::map<std::string, int> check_docstrings(std::string &file_path, const bool &
     int start_pos = val.get_file_write_position() - 1;
     int end_pos = start_pos + 0;
 
-    if (!val.docstring.docstring.empty()) {
+    if (val.docstring.end_line != 0) {
       end_pos = val.docstring.end_line;
     }
 

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/src/existingDocstringExtractor.cpp

@@ -46,8 +46,11 @@ void DocstringParameter::extract_default_from_description() {
 }
 
 void DocstringParameter::extract_parameter_kind() {
-  const auto kind_candidates = {ParameterKind::ARG, ParameterKind::POS_ONLY, ParameterKind::KW_ONLY, ParameterKind::VARIADIC_ARG, ParameterKind::KEYWORD_ARG};
-  for (const auto &param_kind : kind_candidates) {
+  const auto kind_candidates = {
+        ParameterKind::ARG, ParameterKind::POS_ONLY, ParameterKind::KW_ONLY, ParameterKind::VARIADIC_ARG,
+        ParameterKind::KEYWORD_ARG
+      };
+  for (const auto &param_kind: kind_candidates) {
     const auto kind_str = parameter_kind::to_str(param_kind);
     if (description.find(kind_str) != std::string::npos) {
       this->kind = param_kind;
@@ -84,19 +87,39 @@ ExistingDocstringExtractor::get_extracted_parameters() const noexcept {
   return extracted_parameters;
 }
 
+std::string ExistingDocstringExtractor::get_reduced_docstring() const noexcept {
+  return std::string(trim_right(reduced_docstring));
+}
+
+std::vector<DocstringReturnInfo> ExistingDocstringExtractor::get_return_info() const noexcept {
+  return docstring_return_info;
+}
+
+std::vector<DocstringExceptionInfo> ExistingDocstringExtractor::get_exception_info() const noexcept {
+  return docstring_exception_info;
+}
+
 void ExistingDocstringExtractor::extract_numpy_parameters(
   std::string_view text
 ) {
+
+  reduced_docstring = text;
+
+  extract_numpy_exception_info();
+  extract_numpy_return_info();
+
   // this should be the line after parameters, cause the amount of `-` must
   // require the length of the word `Parameters` the same applies to `Raises`
   // and `Returns`
-  const auto start_pos = text.find("Parameters");
+  const auto start_pos = reduced_docstring.find("Parameters");
   std::string indentation{};
   std::string level2_indentation{};
 
   if (start_pos != std::string::npos) {
     DocstringParameter existing_parameter{};
+    reduced_docstring = std::string(text.substr(0, start_pos));
     std::string_view param_section = text.substr(start_pos + 10);
+
     for (auto &&raw_line: param_section | std::views::split('\n')) {
       std::string_view line(raw_line.begin(), raw_line.end());
 
@@ -181,19 +204,65 @@ void ExistingDocstringExtractor::extract_numpy_parameters(
       }
     }
   }
+
+  const auto return_pos = reduced_docstring.find("Returns");
+  if (return_pos != std::string::npos) {
+    const auto yield_pos = reduced_docstring.find("Yields");
+    const auto see_pos = reduced_docstring.find("See Also");
+    const auto raises_pos = reduced_docstring.find("Raises");
+    const auto return_pos_end = std::min(std::min(yield_pos, see_pos), raises_pos);
+
+    std::string return_section;
+    if (return_pos_end != std::string::npos) {
+      return_section = reduced_docstring.substr(return_pos, return_pos_end);
+    } else {
+      return_section = reduced_docstring.substr(return_pos);
+    }
+
+    // for (auto &&raw_line: return_section | std::views::split('\n')) {
+    //
+    // }
+    reduced_docstring = reduced_docstring.substr(0, return_pos);
+  }
+
+  const auto yield_pos = reduced_docstring.find("Yields");
+  if (yield_pos != std::string::npos) {
+    removed_returns = true;
+    reduced_docstring = reduced_docstring.substr(0, yield_pos);
+  }
+
+  const auto see_pos = reduced_docstring.find("See Also");
+  if (see_pos != std::string::npos) {
+    removed_returns = true;
+    reduced_docstring = reduced_docstring.substr(0, see_pos);
+  }
+
+  const auto raises_pos = reduced_docstring.find("Raises");
+  if (raises_pos != std::string::npos) {
+    removed_raises = true;
+    reduced_docstring = reduced_docstring.substr(0, raises_pos);
+  }
 }
 
 void ExistingDocstringExtractor::extract_google_parameters(
   std::string_view text
 ) {
-  const auto start_pos = text.find("Args:");
+
+  reduced_docstring = text;
+
+  extract_google_exception_info();
+  extract_google_return_info();
+
+  const auto start_pos = reduced_docstring.find("Args:");
   std::string indentation{};
   std::string level2_indentation{};
 
   if (start_pos != std::string::npos) {
     DocstringParameter existing_parameter{};
     // the length of the word "Args:" plus one linebreak
-    std::string_view param_section = text.substr(start_pos + 6);
+    std::string param_section = reduced_docstring.substr(start_pos + 6);
+    reduced_docstring = std::string(text.substr(0, start_pos));
+
     for (auto &&raw_line: param_section | std::views::split('\n')) {
       std::string_view line(raw_line.begin(), raw_line.end());
 
@@ -283,11 +352,12 @@ void ExistingDocstringExtractor::extract_rest_parameters(
   std::string indentation{};
   std::string level2_indentation{};
 
-  std::string_view body = text.substr(start_pos);
-
   if (start_pos != std::string::npos) {
     DocstringParameter existing_parameter{};
 
+    std::string_view body = text.substr(start_pos);
+    reduced_docstring = std::string(body.substr(0, start_pos));
+
     for (auto &&raw_line: body | std::views::split('\n')) {
       std::string_view line(raw_line.begin(), raw_line.end());
       std::string_view trimmed_line = trim(line);
@@ -319,7 +389,7 @@ void ExistingDocstringExtractor::extract_rest_parameters(
         existing_parameter.name = trim(param_name);
 
         auto trimmed_description = trim(description);
-        const auto default_pos =  trimmed_description.find("default");
+        const auto default_pos = trimmed_description.find("default");
 
         if (default_pos != std::string::npos) {
           existing_parameter.description = trimmed_description.substr(0, default_pos);
@@ -338,7 +408,6 @@ void ExistingDocstringExtractor::extract_rest_parameters(
         } else {
           existing_parameter.description = trim(description);
         }
-
       } else if (trimmed_line.starts_with(":type")) {
         std::string_view after_type = trimmed_line.substr(6);
         const auto [param_name, type_info] = split_once(after_type, ':');
@@ -375,3 +444,157 @@ void ExistingDocstringExtractor::extract_rest_parameters(
     }
   }
 }
+
+void ExistingDocstringExtractor::extract_google_exception_info() {
+  const auto raises_pos = reduced_docstring.find("Raises:");
+
+  if (raises_pos != std::string::npos) {
+    auto raises_section = reduced_docstring.substr(raises_pos + 7);
+    reduced_docstring = reduced_docstring.substr(0, raises_pos);
+    DocstringExceptionInfo exception_info {};
+
+    for (auto &&raw_line: raises_section | std::views::split('\n')) {
+      std::string_view line(raw_line.begin(), raw_line.end());
+      if (trim(line).empty()) {
+        if (!exception_info.type.empty()) {
+          docstring_exception_info.emplace_back(exception_info);
+          exception_info = {};
+        }
+        continue;
+      }
+      if (line.find(':') != std::string_view::npos) {
+        if (!exception_info.type.empty()) {
+          docstring_exception_info.emplace_back(exception_info);
+          exception_info = {};
+        }
+        const auto [type_info, description] = split_once(line, ':');
+        exception_info.type = std::string(trim(type_info));
+        exception_info.description = std::string(trim(description));
+      } else {
+        exception_info.description += '\n';
+        exception_info.description += std::string(trim(line));
+      }
+    }
+  }
+}
+
+void ExistingDocstringExtractor::extract_google_return_info() {
+  auto return_pos = reduced_docstring.find("Returns:");
+
+  if (return_pos != std::string::npos) {
+    // we have an return section
+    const auto yield_pos_ = reduced_docstring.find("Yields:");
+    const auto see_pos_ = reduced_docstring.find("See Also:");
+    const auto raises_pos_ = reduced_docstring.find("Raises:");
+    const auto return_pos_end = std::min(std::min(yield_pos_, see_pos_), raises_pos_);
+
+    std::string return_section{};
+    if (return_pos_end != std::string::npos) {
+      return_section = reduced_docstring.substr(return_pos + 8, return_pos_end - return_pos - 8);
+    } else {
+      return_section = reduced_docstring.substr(return_pos + 8);
+    }
+
+    DocstringReturnInfo return_info{};
+    for (auto &&raw_line: return_section | std::views::split('\n')) {
+      std::string_view line(raw_line.begin(), raw_line.end());
+      if (trim(line).empty()) {
+        if (!return_info.type.empty()) {
+          docstring_return_info.emplace_back(return_info);
+          return_info = {};
+        }
+        continue;
+      }
+      if (line.find(':') != std::string_view::npos) {
+        if (!return_info.type.empty()) {
+          docstring_return_info.emplace_back(return_info);
+          return_info = {};
+        }
+        const auto [type_info, description] = split_once(line, ':');
+        return_info.type = std::string(trim(type_info));
+        return_info.description = std::string(trim(description));
+      } else {
+        return_info.description += '\n';
+        return_info.description += std::string(trim(line));
+      }
+    }
+    reduced_docstring = reduced_docstring.substr(0, return_pos);
+  }
+}
+
+void ExistingDocstringExtractor::extract_numpy_exception_info() {
+  const auto raises_pos = reduced_docstring.find("Raises");
+
+  if (raises_pos != std::string::npos) {
+    auto raises_section = reduced_docstring.substr(raises_pos + 7);
+    reduced_docstring = reduced_docstring.substr(0, raises_pos);
+    DocstringExceptionInfo exception_info {};
+
+    for (auto &&raw_line: raises_section | std::views::split('\n')) {
+      std::string_view line(raw_line.begin(), raw_line.end());
+      if (trim(line).empty()) {
+        if (!exception_info.type.empty()) {
+          docstring_exception_info.emplace_back(exception_info);
+          exception_info = {};
+        }
+        continue;
+      }
+      if (line.find(':') != std::string_view::npos) {
+        if (!exception_info.type.empty()) {
+          docstring_exception_info.emplace_back(exception_info);
+          exception_info = {};
+        }
+        const auto [type_info, description] = split_once(line, ':');
+        exception_info.type = std::string(trim(type_info));
+        exception_info.description = std::string(trim(description));
+      } else {
+        exception_info.description += '\n';
+        exception_info.description += std::string(trim(line));
+      }
+    }
+  }
+}
+
+void ExistingDocstringExtractor::extract_numpy_return_info() {
+  auto return_pos = reduced_docstring.find("Returns");
+
+  if (return_pos != std::string::npos) {
+    // we have an return section
+    const auto yield_pos_ = reduced_docstring.find("Yields");
+    const auto see_pos_ = reduced_docstring.find("See Also");
+    const auto raises_pos_ = reduced_docstring.find("Raises");
+    const auto return_pos_end = std::min(std::min(yield_pos_, see_pos_), raises_pos_);
+
+    std::string return_section{};
+    if (return_pos_end != std::string::npos) {
+      return_section = reduced_docstring.substr(return_pos + 8, return_pos_end - return_pos - 8);
+    } else {
+      return_section = reduced_docstring.substr(return_pos + 8);
+    }
+
+    DocstringReturnInfo return_info{};
+    for (auto &&raw_line: return_section | std::views::split('\n')) {
+      std::string_view line(raw_line.begin(), raw_line.end());
+      if (trim(line).empty()) {
+        if (!return_info.type.empty()) {
+          docstring_return_info.emplace_back(return_info);
+          return_info = {};
+        }
+        continue;
+      }
+      if (line.find(':') != std::string_view::npos) {
+        if (!return_info.type.empty()) {
+          docstring_return_info.emplace_back(return_info);
+          return_info = {};
+        }
+        const auto [type_info, description] = split_once(line, ':');
+        return_info.type = std::string(trim(type_info));
+        return_info.description = std::string(trim(description));
+      } else {
+        return_info.description += '\n';
+        return_info.description += std::string(trim(line));
+      }
+    }
+    reduced_docstring = reduced_docstring.substr(0, return_pos);
+  }
+}

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/src/existingDocstringExtractor.hpp

@@ -20,16 +20,41 @@ struct DocstringParameter {
   void extract_parameter_kind();
 };
 
+struct DocstringReturnInfo {
+  std::string type {};
+  std::string description {};
+};
+
+struct DocstringExceptionInfo {
+  std::string type {};
+  std::string description {};
+};
+
 class ExistingDocstringExtractor {
 public:
   static ExistingDocstringExtractor parse_text(const std::string &text, DocstringFormatStyle formatStyle);
-  std::vector<DocstringParameter> get_extracted_parameters() const noexcept;
+  [[nodiscard]] std::vector<DocstringParameter> get_extracted_parameters() const noexcept;
+  [[ nodiscard ]] std::string get_reduced_docstring() const noexcept;
+  [[ nodiscard ]] std::vector<DocstringReturnInfo>get_return_info() const noexcept;
+  [[ nodiscard ]] std::vector<DocstringExceptionInfo> get_exception_info() const noexcept;
 
 private:
   std::vector<DocstringParameter> extracted_parameters{};
+  std::vector<DocstringReturnInfo> docstring_return_info{};
+  std::vector<DocstringExceptionInfo> docstring_exception_info{};
+  std::string reduced_docstring {};
+  bool removed_returns {false};
+  bool removed_raises {false};
+
   void extract_numpy_parameters(std::string_view text);
   void extract_google_parameters(std::string_view text);
   void extract_rest_parameters(std::string_view text);
+
+  void extract_google_exception_info();
+  void extract_google_return_info();
+
+  void extract_numpy_exception_info();
+  void extract_numpy_return_info();
 };
 
 #endif // DOCSTRING_GENERATOR_EXT_EXISTINGDOCSTRINGEXTRACTOR_HPP

{docstring_generator_ext-2.0.13a1 → docstring_generator_ext-2.0.14}/src/parser.hpp

@@ -53,7 +53,7 @@ void get_exception(
     bool ignore_magic
 ) noexcept;
 
-constexpr std::pair<std::string_view, std::string_view> split_once(std::string_view str, char delim) {
+constexpr std::pair<std::string_view, std::string_view> split_once(std::string_view str, const char delim) {
     auto pos = str.find(delim);
     if (pos == std::string_view::npos) {
         return {str, {}};
@@ -61,11 +61,17 @@ constexpr std::pair<std::string_view, std::string_view> split_once(std::string_v
     return {str.substr(0, pos), str.substr(pos + 1)};
 }
 
-constexpr std::string_view trim(std::string_view v) {
+constexpr std::string_view trim(const std::string_view v) {
     auto start = v.find_first_not_of(" \t\r\n");
     if (start == std::string_view::npos) return {};
     auto end = v.find_last_not_of(" \t\r\n");
     return v.substr(start, end - start + 1);
 }
 
+constexpr std::string_view trim_right(const std::string_view v) {
+    auto end = v.find_last_not_of(" \t\r\n");
+    if (end == std::string_view::npos) return {};
+    return v.substr(0, end + 1);
+}
+
 #endif //DOCSTRING_GENERATOR_EXT_PARSER_HPP