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

### Decorators

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

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

### Decorators

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

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

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

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

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

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

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