style: format source code using Ruff

src/jcloud_docsgen/utils.py

@@ -12,9 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-'''
+"""
 The utilities for jcloud_docsgen
-'''
+"""
 
 import pathlib
 import os
@@ -27,15 +27,17 @@ try:
 except ImportError:
     from typing_extensions import deprecated
 
+
 @deprecated('Use pathlib.Path instead.')
 class ExistingDirectory(pathlib.Path):
-    '''
+    """
     pathlib.Path subclass that is a directory.
 
     ExistingDirectory represents a filesystem path but it also checks
     whether the path exists and is not a file but a directory. It
     inherits from pathlib.Path.
-    '''
+    """
+
     def __init__(self, path, *args, **kwargs) -> None:
         if not os.path.exists(path):
             raise FileNotFoundError(
@@ -47,15 +49,17 @@ class ExistingDirectory(pathlib.Path):
             raise NotADirectoryError(errno.ENOTDIR, 'not a directory', path)
         super().__init__(*(path, *args), **kwargs)
 
+
 @deprecated('Use pathlib.Path instead.')
 class ExistingFile(pathlib.Path):
-    '''
+    """
     pathlib.Path subclass that is a file.
 
     ExistingFile represents a filesystem path but it also checks whether
     the path exists and is not a directory but a file. It inherits from
     pathlib.Path.
-    '''
+    """
+
     def __init__(self, path, *args, **kwargs) -> None:
         if not os.path.exists(path):
             raise FileNotFoundError(
@@ -67,8 +71,9 @@ class ExistingFile(pathlib.Path):
             raise IsADirectoryError(errno.EISDIR, 'is a directory', path)
         super().__init__(*(path, *args), **kwargs)
 
+
 def _quote(string: str, quotation_mark: str) -> str:
-    '''
+    """
     Quotes a string.
 
     :param string: The string to quote
@@ -78,16 +83,17 @@ def _quote(string: str, quotation_mark: str) -> str:
 
     :return: The quoted string
     :rtype: str
-    '''
+    """
 
     return quotation_mark + string + quotation_mark
 
+
 def human_readable_list(
     ls: list,
     final_separator: str = 'and',
     quotation_mark: str = '',
 ) -> str:
-    '''
+    """
     Generates a human-readable list from a list.
 
     :param ls: The list.
@@ -101,7 +107,7 @@ def human_readable_list(
 
     :return: The human-readable list.
     :rtype: str
-    '''
+    """
 
     # empty list
     if not ls:
@@ -111,18 +117,26 @@ def human_readable_list(
     if len(ls) == 1:
         return _quote(str(ls[0]), quotation_mark)
 
-    return ', '.join(
-        [
-            _quote(
-                str(obj),
-                quotation_mark
-            ) # quote the string representation of the object
-            for obj in ls[:-1] # do not include the last element of the list
-        ],
-    ) + ' ' + final_separator + ' ' + _quote(str(ls[-1]), quotation_mark)
+    return (
+        ', '.join(
+            [
+                _quote(
+                    str(obj), quotation_mark
+                )  # quote the string representation of the object
+                for obj in ls[
+                    :-1
+                ]  # do not include the last element of the list
+            ],
+        )
+        + ' '
+        + final_separator
+        + ' '
+        + _quote(str(ls[-1]), quotation_mark)
+    )
+
 
 def _list_type_names(types: list[type]) -> list[str]:
-    '''
+    """
     Converts a list of types into a list of their names (``__name__``
     attribute)
 
@@ -131,10 +145,11 @@ def _list_type_names(types: list[type]) -> list[str]:
 
     :return: The list of the names of the types
     :rtype: list[str]
-    '''
+    """
 
     return [tp.__name__ for tp in types]
 
+
 def assert_that_is_instance(
     obj: object,
     class_or_tuple: Union[
@@ -145,8 +160,8 @@ def assert_that_is_instance(
 ) -> None:
     if not isinstance(class_or_tuple, Union[type, types.UnionType, tuple]):
         raise TypeError(
-            f'class_or_tuple: expected \'Union[type, types.UnionType, '
-            f'tuple[type, ...]]\', \'got {type(class_or_tuple).__name__}\'',
+            f"class_or_tuple: expected 'Union[type, types.UnionType, "
+            f"tuple[type, ...]]', 'got {type(class_or_tuple).__name__}'",
         )
     if not isinstance(obj, class_or_tuple):
         if isinstance(class_or_tuple, (tuple, types.UnionType)):
@@ -157,18 +172,21 @@ def assert_that_is_instance(
             else:
                 exception_message_expected = ''
             exception_message_expected += human_readable_list(
-                _list_type_names(class_or_tuple), 'or', '\'',
+                _list_type_names(class_or_tuple),
+                'or',
+                "'",
             )
         else:
-            exception_message_expected = '\'' + class_or_tuple.__name__ + '\''
+            exception_message_expected = "'" + class_or_tuple.__name__ + "'"
         raise TypeError(
-            f'expected {exception_message_expected}, got \'{type(
-                obj
-            ).__name__}\'',
+            f"expected {exception_message_expected}, got '{
+                type(obj).__name__
+            }'",
         )
 
+
 def non_empty_str(value: Union[str, None]) -> Union[str, None]:
-    '''
+    """
     Returns the value or ``None``.
 
     Returns the value if it is not empty and not `Ǹone``; otherwise,
@@ -181,7 +199,7 @@ def non_empty_str(value: Union[str, None]) -> Union[str, None]:
 
     :return: The value or ``None``.
     :rtype: Union[str, None]
-    '''
+    """
 
     if value is None:
         return None
@@ -191,11 +209,12 @@ def non_empty_str(value: Union[str, None]) -> Union[str, None]:
 
     return value
 
+
 def get_relative_path_segments(
     path: pathlib.Path,
     root: pathlib.Path,
 ) -> list[str]:
-    '''
+    """
     Returns the path segments relative to ``root``.
 
     :param path: The path.
@@ -205,7 +224,7 @@ def get_relative_path_segments(
 
     :return: The path segments relative to ``root``.
     :rtype: list[str]
-    '''
+    """
 
     return list(
         path.resolve()