generated from jCloud/repository-template
335 lines
6.3 KiB
Markdown
335 lines
6.3 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 | -- | -- |
|
|
|
|
|
|
|
|
|
|
|
|
### 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] |