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	--	--

Decorators

deprecated('Use pathlib.Path instead.')

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	--	--

Decorators

deprecated('Use pathlib.Path instead.')

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: type | types.UnionType | tuple[type, ...]) -> None

Returns

Return type: None

Parameters

Parameter	Type	Kind	Default value	Description
obj	object	normal	--	--
class_or_tuple	`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: str | None) -> str | None

Returns

The value or None.

Return type: str | None

Parameters

Parameter	Type	Kind	Default value	Description
value	`str	None`	normal	--

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: str | None

:return: The value or None. :rtype: 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]

Function fit_row_length

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).

Function signature

fit_row_length(expected: int, row: tuple) -> tuple

Returns

Return type: tuple

Parameters

Parameter	Type	Kind	Default value	Description
expected	int	normal	--	The expected length.
row	tuple	normal	--	The row.

Docstring

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

Function markdown_table

Generates a table.

If allow_markdown_table is False, an alternative representation is used.

Function signature

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

Returns

Return type: str

Parameters

Parameter	Type	Kind	Default value	Description
header	tuple	normal	--	--
body	list[tuple]	normal	--	The table body.
allow_markdown_table	bool	keyword-only	False	Controls whether a markdown table may be used.
force_row_lengths	bool	keyword-only	False	Controls whether an exception is raised if a row does not have the correct length.
one_line_values	bool	keyword-only	True	Controls whether all newlines in all values are replaced with spaces.
missing_value	str	keyword-only	'--'	The string that is used if a value is missing (only if force_row_lengths is False).

Docstring

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