Merge pull request 'Refactor(utils): move general utility functions to utility module' (#73) from refactor/restructure-general-utility-functions into main

Reviewed-on: #73

src/jcloud_docsgen/core/python/_core.py

@@ -28,7 +28,7 @@ from ...exceptions import (
     InvalidNamespaceError,
     PythonArgumentStructureError,
 )
-from ...utils import get_relative_path_segments, non_empty_str
+from ...utils import get_relative_path_segments, markdown_table, non_empty_str
 from .arguments import PythonArgumentKind, PythonFunctionArgument
 from .definitions import (
     PythonAsyncFunctionDefinition,
@@ -184,130 +184,6 @@ def _signature_argument_list(
     return args
 
 
-def _fit_row_length(expected: int, row: tuple) -> tuple:
-    """
-    Fits the row length to the expected length.
-
-    If the row is too long, the tail, that makes it too long, is omitted.
-    If it is too short, it is filled with ``None`` (at the end).
-
-    :param expected: The expected length.
-    :type expected: int
-    :param row: The row.
-    :type row: tuple
-    """
-
-    if expected < 0:
-        raise ValueError('expected must be larger than or equal 0.')
-
-    if len(row) > expected:
-        return row[:expected]
-    else:
-        return row + (None,) * (expected - len(row))
-
-
-def _markdown_table(
-    header: tuple,
-    body: list[tuple],
-    *,
-    allow_markdown_table: bool = False,
-    force_row_lengths: bool = False,
-    one_line_values: bool = True,
-    missing_value: str = '--',
-) -> str:
-    """
-    Generates a table.
-
-    If ``allow_markdown_table`` is ``False``, an alternative
-    representation is used.
-
-    :param headers: The table headers.
-    :type headers: tuple
-    :param body: The table body.
-    :type body: list[tuple]
-    :param allow_markdown_table: Controls whether a markdown table may be
-                                 used.
-    :type allow_markdown_table: bool
-    :param force_row_lengths: Controls whether an exception is raised if
-                              a row does not have the correct length.
-    :type force_row_lengths: bool
-    :param one_line_values: Controls whether all newlines in all values
-                            are replaced with spaces.
-    :type one_line_values: bool
-    :param missing_value: The string that is used if a value is missing
-                          (only if ``force_row_lengths`` is ``False``).
-    :type missing_value: str
-    """
-
-    if not header or not body:
-        return ''
-
-    header_len = len(header)
-
-    if allow_markdown_table:
-        table = (
-            '| ' + ' | '.join(header) + ' |\n|' + ' --- |' * len(header) + '\n'
-        )
-
-        for row in body:
-            if len(row) != header_len:
-                if force_row_lengths:
-                    raise ValueError(
-                        f'expected {header_len} value'
-                        f'{"s" if header_len > 1 else ""}, got {len(row)}'
-                    )
-                else:
-                    row = _fit_row_length(header_len, row)
-
-            table += (
-                '| '
-                + ' | '.join(
-                    [
-                        str(col if col is not None else missing_value)
-                        .replace('\n', ' ')
-                        .replace('|', '\\|')
-                        if one_line_values
-                        else str(
-                            col if col is not None else missing_value
-                        ).replace('|', '\\|')
-                        for col in row
-                    ]
-                )
-                + ' |\n'
-            )
-    else:
-        table = ''
-
-        for row in body:
-            if len(row) != header_len:
-                if force_row_lengths:
-                    raise ValueError(
-                        f'expected {header_len} value'
-                        f'{"s" if header_len > 1 else ""}, got {len(row)}'
-                    )
-                else:
-                    row = _fit_row_length(header_len, row)
-
-            sep = '- '
-            for i, col in enumerate(row):
-                table += (
-                    sep
-                    + header[i]
-                    + ': '
-                    + (
-                        str(col if col is not None else missing_value).replace(
-                            '\n', ' '
-                        )
-                        if one_line_values
-                        else str(col if col is not None else missing_value)
-                    )
-                    + '\n\n'
-                )
-                sep = '  '
-
-    return table.strip()
-
-
 def _is_docstring(docstring: str | PythonDocstring | None) -> bool:
     """
     Checks whether the docstring is a docstring or an empty docstring.
@@ -643,7 +519,7 @@ class PythonDefinitionDocumentationGenerator:
         )
 
         if params_types:
-            md += _markdown_table(
+            md += markdown_table(
                 ['Parameter', 'Type', 'Kind', 'Default value', 'Description'],
                 [
                     (
@@ -722,7 +598,7 @@ class PythonDefinitionDocumentationGenerator:
             md += self.level * '#' + '# Exceptions\n\n'
 
         if self._docstring.raises:
-            md += _markdown_table(
+            md += markdown_table(
                 ('Exception', 'Description'),
                 [
                     (

src/jcloud_docsgen/utils.py

@@ -34,6 +34,8 @@ __all__ = [
     'assert_that_is_instance',
     'non_empty_str',
     'get_relative_path_segments',
+    'fit_row_length',
+    'markdown_table',
 ]
 
 
@@ -237,3 +239,127 @@ def get_relative_path_segments(
         )
         .parts,
     )
+
+
+def fit_row_length(expected: int, row: tuple) -> tuple:
+    """
+    Fits the row length to the expected length.
+
+    If the row is too long, the tail, that makes it too long, is omitted.
+    If it is too short, it is filled with ``None`` (at the end).
+
+    :param expected: The expected length.
+    :type expected: int
+    :param row: The row.
+    :type row: tuple
+    """
+
+    if expected < 0:
+        raise ValueError('expected must be larger than or equal 0.')
+
+    if len(row) > expected:
+        return row[:expected]
+    else:
+        return row + (None,) * (expected - len(row))
+
+
+def markdown_table(
+    header: tuple,
+    body: list[tuple],
+    *,
+    allow_markdown_table: bool = False,
+    force_row_lengths: bool = False,
+    one_line_values: bool = True,
+    missing_value: str = '--',
+) -> str:
+    """
+    Generates a table.
+
+    If ``allow_markdown_table`` is ``False``, an alternative
+    representation is used.
+
+    :param headers: The table headers.
+    :type headers: tuple
+    :param body: The table body.
+    :type body: list[tuple]
+    :param allow_markdown_table: Controls whether a markdown table may be
+                                 used.
+    :type allow_markdown_table: bool
+    :param force_row_lengths: Controls whether an exception is raised if
+                              a row does not have the correct length.
+    :type force_row_lengths: bool
+    :param one_line_values: Controls whether all newlines in all values
+                            are replaced with spaces.
+    :type one_line_values: bool
+    :param missing_value: The string that is used if a value is missing
+                          (only if ``force_row_lengths`` is ``False``).
+    :type missing_value: str
+    """
+
+    if not header or not body:
+        return ''
+
+    header_len = len(header)
+
+    if allow_markdown_table:
+        table = (
+            '| ' + ' | '.join(header) + ' |\n|' + ' --- |' * len(header) + '\n'
+        )
+
+        for row in body:
+            if len(row) != header_len:
+                if force_row_lengths:
+                    raise ValueError(
+                        f'expected {header_len} value'
+                        f'{"s" if header_len > 1 else ""}, got {len(row)}'
+                    )
+                else:
+                    row = fit_row_length(header_len, row)
+
+            table += (
+                '| '
+                + ' | '.join(
+                    [
+                        str(col if col is not None else missing_value)
+                        .replace('\n', ' ')
+                        .replace('|', '\\|')
+                        if one_line_values
+                        else str(
+                            col if col is not None else missing_value
+                        ).replace('|', '\\|')
+                        for col in row
+                    ]
+                )
+                + ' |\n'
+            )
+    else:
+        table = ''
+
+        for row in body:
+            if len(row) != header_len:
+                if force_row_lengths:
+                    raise ValueError(
+                        f'expected {header_len} value'
+                        f'{"s" if header_len > 1 else ""}, got {len(row)}'
+                    )
+                else:
+                    row = fit_row_length(header_len, row)
+
+            sep = '- '
+            for i, col in enumerate(row):
+                table += (
+                    sep
+                    + header[i]
+                    + ': '
+                    + (
+                        str(col if col is not None else missing_value).replace(
+                            '\n', ' '
+                        )
+                        if one_line_values
+                        else str(col if col is not None else missing_value)
+                    )
+                    + '\n\n'
+                )
+                sep = '  '
+
+    return table.strip()

tests/unit/utils/test_fit_row_length.py

@@ -14,7 +14,7 @@
 
 import pytest
 
-from src.jcloud_docsgen.core.python._core import _fit_row_length
+from src.jcloud_docsgen.utils import fit_row_length
 
 
 @pytest.mark.parametrize(
@@ -37,8 +37,8 @@ from src.jcloud_docsgen.core.python._core import _fit_row_length
         (3, (1, 2, 3), (1, 2, 3)),
     ],
 )
-def test__fit_row_length(expected_length, row, expected):
-    assert _fit_row_length(expected_length, row) == expected
+def test_fit_row_length(expected_length, row, expected):
+    assert fit_row_length(expected_length, row) == expected
 
 
 @pytest.mark.parametrize(
@@ -60,7 +60,7 @@ def test__fit_row_length(expected_length, row, expected):
         (-42, ValueError),
     ],
 )
-def test__fit_row_length_exceptions(expected_length, row, expected_exception):
+def test_fit_row_length_exceptions(expected_length, row, expected_exception):
     with pytest.raises(expected_exception) as exc_info:
-        _fit_row_length(expected_length, row)
+        fit_row_length(expected_length, row)
     assert str(exc_info.value) == 'expected must be larger than or equal 0.'

tests/unit/utils/test_markdown_table.py

@@ -14,7 +14,7 @@
 
 import pytest
 
-from src.jcloud_docsgen.core.python._core import _markdown_table
+from src.jcloud_docsgen.utils import markdown_table
 
 
 @pytest.mark.parametrize(
@@ -318,7 +318,7 @@ from src.jcloud_docsgen.core.python._core import _markdown_table
         ),
     ],
 )
-def test__markdown_table(
+def test_markdown_table(
     header,
     body,
     allow_markdown_table,
@@ -328,7 +328,7 @@ def test__markdown_table(
     expected,
 ):
     assert (
-        _markdown_table(
+        markdown_table(
             header,
             body,
             allow_markdown_table=allow_markdown_table,
@@ -468,7 +468,7 @@ def test__markdown_table(
         ),
     ],
 )
-def test__markdown_table_exceptions(
+def test_markdown_table_exceptions(
     header,
     body,
     allow_markdown_table,
@@ -479,7 +479,7 @@ def test__markdown_table_exceptions(
     expected_exception_msg,
 ):
     with pytest.raises(expected_exception) as exc_info:
-        _markdown_table(
+        markdown_table(
             header,
             body,
             allow_markdown_table=allow_markdown_table,