# Module `jcloud_docsgen.utils` The utilities for jcloud_docsgen ## Class `ExistingDirectory` 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. ### Base classes - `pathlib.Path` ### Body #### Constructor (method `__init__`) ##### Method signature ```python __init__(self, path, *args, **kwargs) -> None ``` ##### Returns Return type: `None` ##### Parameters | Parameter | Type | Kind | Default value | Description | | --- | --- | --- | --- | --- | | `self` | -- | normal | -- | -- | | `path` | -- | normal | -- | -- | | `args` | -- | vararg | -- | -- | | `kwargs` | -- | kwargs | -- | -- | ### Docstring 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. ## Class `ExistingFile` 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. ### Base classes - `pathlib.Path` ### Body #### Constructor (method `__init__`) ##### Method signature ```python __init__(self, path, *args, **kwargs) -> None ``` ##### Returns Return type: `None` ##### Parameters | Parameter | Type | Kind | Default value | Description | | --- | --- | --- | --- | --- | | `self` | -- | normal | -- | -- | | `path` | -- | normal | -- | -- | | `args` | -- | vararg | -- | -- | | `kwargs` | -- | kwargs | -- | -- | ### Docstring 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. ## Function `_quote` Quotes a string. ### Function signature ```python _quote(string: str, quotation_mark: str) -> str ``` ### Returns The quoted string Return type: `str` ### Parameters | Parameter | Type | Kind | Default value | Description | | --- | --- | --- | --- | --- | | `string` | `str` | normal | -- | The string to quote | | `quotation_mark` | `str` | normal | -- | The quotation mark | ### Docstring Quotes a string. :param string: The string to quote :type string: str :param quotation_mark: The quotation mark :type quotation_mark: str :return: The quoted string :rtype: str ## Function `human_readable_list` Generates a human-readable list from a list. ### Function signature ```python human_readable_list(ls: list, final_separator: str = 'and', quotation_mark: str = '') -> str ``` ### Returns The human-readable list. Return type: `str` ### Parameters | Parameter | Type | Kind | Default value | Description | | --- | --- | --- | --- | --- | | `ls` | `list` | normal | -- | The list. | | `final_separator` | `str` | normal | `'and'` | The seperator between the last and the second-to-last element of the list. Default is 'and'. | | `quotation_mark` | `str` | normal | `''` | The characters that are inserted before and after an element. Default is ''. | ### Docstring Generates a human-readable list from a list. :param ls: The list. :type ls: list :param final_separator: The seperator between the last and the second-to-last element of the list. Default is 'and'. :type final_separator: str :param quotation_mark: The characters that are inserted before and after an element. Default is ''. :return: The human-readable list. :rtype: str ## Function `_list_type_names` Converts a list of types into a list of their names (``__name__`` attribute) ### Function signature ```python _list_type_names(types: list[type]) -> list[str] ``` ### Returns The list of the names of the types Return type: `list[str]` ### Parameters | Parameter | Type | Kind | Default value | Description | | --- | --- | --- | --- | --- | | `types` | `list[type]` | normal | -- | The list of types | ### Docstring Converts a list of types into a list of their names (``__name__`` attribute) :param types: The list of types :type types: list[type] :return: The list of the names of the types :rtype: list[str] ## Function `assert_that_is_instance` ### Function signature ```python assert_that_is_instance(obj: object, class_or_tuple: Union[type, types.UnionType, tuple[type, ...]]) -> None ``` ### Returns Return type: `None` ### Parameters | Parameter | Type | Kind | Default value | Description | | --- | --- | --- | --- | --- | | `obj` | `object` | normal | -- | -- | | `class_or_tuple` | `Union[type, types.UnionType, tuple[type, ...]]` | normal | -- | -- | ## Function `non_empty_str` Returns the value or ``None``. Returns the value if it is not empty and not `Ǹone``; otherwise, returns ``None``. Please note: values are stripped, i. e. if the value consists only of spaces, it is also considered empty. ### Function signature ```python non_empty_str(value: Union[str, None]) -> Union[str, None] ``` ### Returns The value or ``None``. Return type: `Union[str, None]` ### Parameters | Parameter | Type | Kind | Default value | Description | | --- | --- | --- | --- | --- | | `value` | `Union[str, None]` | normal | -- | The value. | ### Docstring Returns the value or ``None``. Returns the value if it is not empty and not `Ǹone``; otherwise, returns ``None``. Please note: values are stripped, i. e. if the value consists only of spaces, it is also considered empty. :param value: The value. :type value: Union[str, None] :return: The value or ``None``. :rtype: Union[str, None] ## Function `get_relative_path_segments` Returns the path segments relative to ``root``. ### Function signature ```python get_relative_path_segments(path: pathlib.Path, root: pathlib.Path) -> list[str] ``` ### Returns The path segments relative to ``root``. Return type: `list[str]` ### Parameters | Parameter | Type | Kind | Default value | Description | | --- | --- | --- | --- | --- | | `path` | `pathlib.Path` | normal | -- | The path. | | `root` | `pathlib.Path` | normal | -- | The root path. | ### Docstring Returns the path segments relative to ``root``. :param path: The path. :type path: pathlib.Path :param root: The root path. :type root: pathlib.Path :return: The path segments relative to ``root``. :rtype: list[str]