generated from jCloud/repository-template
443 lines
9.1 KiB
Markdown
443 lines
9.1 KiB
Markdown
# 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 |