jcloud-docsgen/docs/reference/jcloud_docsgen/utils.md

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

__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

__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

_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

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

_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

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

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

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]