mirror of
https://github.com/kellyjonbrazil/jc.git
synced 2025-06-17 00:07:37 +02:00
New doc generation script
This commit is contained in:
Kelly Brazil
410
docs/utils.md
410
docs/utils.md
@ -1,78 +1,27 @@
|
||||
# Table of Contents
|
||||
|
||||
* [jc.utils](#jc.utils)
|
||||
* [warning\_message](#jc.utils.warning_message)
|
||||
* [error\_message](#jc.utils.error_message)
|
||||
* [is\_compatible](#jc.utils.is_compatible)
|
||||
* [compatibility](#jc.utils.compatibility)
|
||||
* [has\_data](#jc.utils.has_data)
|
||||
* [remove\_quotes](#jc.utils.remove_quotes)
|
||||
* [normalize\_key](#jc.utils.normalize_key)
|
||||
* [convert\_to\_int](#jc.utils.convert_to_int)
|
||||
* [convert\_to\_float](#jc.utils.convert_to_float)
|
||||
* [convert\_to\_bool](#jc.utils.convert_to_bool)
|
||||
* [convert\_size\_to\_int](#jc.utils.convert_size_to_int)
|
||||
* [input\_type\_check](#jc.utils.input_type_check)
|
||||
* [line\_slice](#jc.utils.line_slice)
|
||||
* [timestamp](#jc.utils.timestamp)
|
||||
* [\_\_init\_\_](#jc.utils.timestamp.__init__)
|
||||
|
||||
[Home](https://kellyjonbrazil.github.io/jc/)
|
||||
<a id="jc.utils"></a>
|
||||
|
||||
# jc.utils
|
||||
|
||||
# Table of Contents
|
||||
|
||||
*[jc.utils](#jc.utils)
|
||||
*[compatibility](#jc.utils.compatibility)
|
||||
*[convert_size_to_int](#jc.utils.convert_size_to_int)
|
||||
*[convert_to_bool](#jc.utils.convert_to_bool)
|
||||
*[convert_to_float](#jc.utils.convert_to_float)
|
||||
*[convert_to_int](#jc.utils.convert_to_int)
|
||||
*[error_message](#jc.utils.error_message)
|
||||
*[has_data](#jc.utils.has_data)
|
||||
*[input_type_check](#jc.utils.input_type_check)
|
||||
*[is_compatible](#jc.utils.is_compatible)
|
||||
*[line_slice](#jc.utils.line_slice)
|
||||
*[normalize_key](#jc.utils.normalize_key)
|
||||
*[remove_quotes](#jc.utils.remove_quotes)
|
||||
*[warning_message](#jc.utils.warning_message)
|
||||
|
||||
jc - JSON Convert utils
|
||||
|
||||
<a id="jc.utils.warning_message"></a>
|
||||
|
||||
### warning\_message
|
||||
|
||||
```python
|
||||
def warning_message(message_lines: List[str]) -> None
|
||||
```
|
||||
|
||||
Prints warning message to `STDERR` for non-fatal issues. The first line
|
||||
is prepended with 'jc: Warning - ' and subsequent lines are indented.
|
||||
Wraps text as needed based on the terminal width.
|
||||
|
||||
Parameters:
|
||||
|
||||
message: (list) list of string lines
|
||||
|
||||
Returns:
|
||||
|
||||
None - just prints output to STDERR
|
||||
|
||||
<a id="jc.utils.error_message"></a>
|
||||
|
||||
### error\_message
|
||||
|
||||
```python
|
||||
def error_message(message_lines: List[str]) -> None
|
||||
```
|
||||
|
||||
Prints an error message to `STDERR` for fatal issues. The first line is
|
||||
prepended with 'jc: Error - ' and subsequent lines are indented.
|
||||
Wraps text as needed based on the terminal width.
|
||||
|
||||
Parameters:
|
||||
|
||||
message: (list) list of string lines
|
||||
|
||||
Returns:
|
||||
|
||||
None - just prints output to STDERR
|
||||
|
||||
<a id="jc.utils.is_compatible"></a>
|
||||
|
||||
### is\_compatible
|
||||
|
||||
```python
|
||||
def is_compatible(compatible: List[str]) -> bool
|
||||
```
|
||||
|
||||
Returns True if the parser is compatible with the running OS platform.
|
||||
|
||||
<a id="jc.utils.compatibility"></a>
|
||||
|
||||
### compatibility
|
||||
@ -101,135 +50,9 @@ Returns:
|
||||
|
||||
None - just prints output to STDERR
|
||||
|
||||
<a id="jc.utils.has_data"></a>
|
||||
|
||||
### has\_data
|
||||
|
||||
```python
|
||||
def has_data(data: Union[str, bytes]) -> bool
|
||||
```
|
||||
|
||||
Checks if the string input contains data. If there are any
|
||||
non-whitespace characters then return `True`, else return `False`.
|
||||
|
||||
For bytes, returns True if there is any data.
|
||||
|
||||
Parameters:
|
||||
|
||||
data: (string, bytes) input to check whether it contains data
|
||||
|
||||
Returns:
|
||||
|
||||
Boolean True if input string (data) contains non-whitespace
|
||||
characters, otherwise False. For bytes data, returns
|
||||
True if there is any data, otherwise False.
|
||||
|
||||
<a id="jc.utils.remove_quotes"></a>
|
||||
|
||||
### remove\_quotes
|
||||
|
||||
```python
|
||||
def remove_quotes(data: str) -> str
|
||||
```
|
||||
|
||||
Remove single or double quotes surrounding a string. If no quotes are
|
||||
found then the string is returned unmodified.
|
||||
|
||||
Parameters:
|
||||
|
||||
data: (string) Input value
|
||||
|
||||
Returns:
|
||||
|
||||
string
|
||||
|
||||
<a id="jc.utils.normalize_key"></a>
|
||||
|
||||
### normalize\_key
|
||||
|
||||
```python
|
||||
def normalize_key(data: str) -> str
|
||||
```
|
||||
|
||||
Normalize a key name by shifting to lower-case and converting special
|
||||
characters to underscores.
|
||||
|
||||
Special characters are defined as `space` and the following:
|
||||
|
||||
!"#$%&'()*+,-./:;<=>?@[\]^`{|}~
|
||||
|
||||
This is a lossy algorithm. Repeating and trailing underscores are
|
||||
removed.
|
||||
|
||||
Parameters:
|
||||
|
||||
data: (string) Input value
|
||||
|
||||
Returns:
|
||||
|
||||
string
|
||||
|
||||
<a id="jc.utils.convert_to_int"></a>
|
||||
|
||||
### convert\_to\_int
|
||||
|
||||
```python
|
||||
def convert_to_int(value: object) -> Optional[int]
|
||||
```
|
||||
|
||||
Converts string and float input to int. Strips all non-numeric
|
||||
characters from strings.
|
||||
|
||||
Parameters:
|
||||
|
||||
value: (string/float) Input value
|
||||
|
||||
Returns:
|
||||
|
||||
integer/None Integer if successful conversion, otherwise None
|
||||
|
||||
<a id="jc.utils.convert_to_float"></a>
|
||||
|
||||
### convert\_to\_float
|
||||
|
||||
```python
|
||||
def convert_to_float(value: object) -> Optional[float]
|
||||
```
|
||||
|
||||
Converts string and int input to float. Strips all non-numeric
|
||||
characters from strings.
|
||||
|
||||
Parameters:
|
||||
|
||||
value: (string/integer) Input value
|
||||
|
||||
Returns:
|
||||
|
||||
float/None Float if successful conversion, otherwise None
|
||||
|
||||
<a id="jc.utils.convert_to_bool"></a>
|
||||
|
||||
### convert\_to\_bool
|
||||
|
||||
```python
|
||||
def convert_to_bool(value: object) -> bool
|
||||
```
|
||||
|
||||
Converts string, integer, or float input to boolean by checking
|
||||
for 'truthy' values.
|
||||
|
||||
Parameters:
|
||||
|
||||
value: (string/integer/float) Input value
|
||||
|
||||
Returns:
|
||||
|
||||
True/False False unless a 'truthy' number or string is found
|
||||
('y', 'yes', 'true', '1', 1, -1, etc.)
|
||||
|
||||
<a id="jc.utils.convert_size_to_int"></a>
|
||||
|
||||
### convert\_size\_to\_int
|
||||
### convert_size_to_int
|
||||
|
||||
```python
|
||||
def convert_size_to_int(size: str, binary: bool = False) -> Optional[int]
|
||||
@ -269,9 +92,110 @@ gigabytes, terabytes and petabytes. Some examples:
|
||||
>>> convert_size_to_int('1.5 GB', binary=True)
|
||||
1610612736
|
||||
|
||||
<a id="jc.utils.convert_to_bool"></a>
|
||||
|
||||
### convert_to_bool
|
||||
|
||||
```python
|
||||
def convert_to_bool(value: object) -> bool
|
||||
```
|
||||
|
||||
Converts string, integer, or float input to boolean by checking
|
||||
for 'truthy' values.
|
||||
|
||||
Parameters:
|
||||
|
||||
value: (string/integer/float) Input value
|
||||
|
||||
Returns:
|
||||
|
||||
True/False False unless a 'truthy' number or string is found
|
||||
('y', 'yes', 'true', '1', 1, -1, etc.)
|
||||
|
||||
<a id="jc.utils.convert_to_float"></a>
|
||||
|
||||
### convert_to_float
|
||||
|
||||
```python
|
||||
def convert_to_float(value: object) -> Optional[float]
|
||||
```
|
||||
|
||||
Converts string and int input to float. Strips all non-numeric
|
||||
characters from strings.
|
||||
|
||||
Parameters:
|
||||
|
||||
value: (string/integer) Input value
|
||||
|
||||
Returns:
|
||||
|
||||
float/None Float if successful conversion, otherwise None
|
||||
|
||||
<a id="jc.utils.convert_to_int"></a>
|
||||
|
||||
### convert_to_int
|
||||
|
||||
```python
|
||||
def convert_to_int(value: object) -> Optional[int]
|
||||
```
|
||||
|
||||
Converts string and float input to int. Strips all non-numeric
|
||||
characters from strings.
|
||||
|
||||
Parameters:
|
||||
|
||||
value: (string/float) Input value
|
||||
|
||||
Returns:
|
||||
|
||||
integer/None Integer if successful conversion, otherwise None
|
||||
|
||||
<a id="jc.utils.error_message"></a>
|
||||
|
||||
### error_message
|
||||
|
||||
```python
|
||||
def error_message(message_lines: List[str]) -> None
|
||||
```
|
||||
|
||||
Prints an error message to `STDERR` for fatal issues. The first line is
|
||||
prepended with 'jc: Error - ' and subsequent lines are indented.
|
||||
Wraps text as needed based on the terminal width.
|
||||
|
||||
Parameters:
|
||||
|
||||
message: (list) list of string lines
|
||||
|
||||
Returns:
|
||||
|
||||
None - just prints output to STDERR
|
||||
|
||||
<a id="jc.utils.has_data"></a>
|
||||
|
||||
### has_data
|
||||
|
||||
```python
|
||||
def has_data(data: Union[str, bytes]) -> bool
|
||||
```
|
||||
|
||||
Checks if the string input contains data. If there are any
|
||||
non-whitespace characters then return `True`, else return `False`.
|
||||
|
||||
For bytes, returns True if there is any data.
|
||||
|
||||
Parameters:
|
||||
|
||||
data: (string, bytes) input to check whether it contains data
|
||||
|
||||
Returns:
|
||||
|
||||
Boolean True if input string (data) contains non-whitespace
|
||||
characters, otherwise False. For bytes data, returns
|
||||
True if there is any data, otherwise False.
|
||||
|
||||
<a id="jc.utils.input_type_check"></a>
|
||||
|
||||
### input\_type\_check
|
||||
### input_type_check
|
||||
|
||||
```python
|
||||
def input_type_check(data: object) -> None
|
||||
@ -279,16 +203,26 @@ def input_type_check(data: object) -> None
|
||||
|
||||
Ensure input data is a string. Raises `TypeError` if not.
|
||||
|
||||
<a id="jc.utils.is_compatible"></a>
|
||||
|
||||
### is_compatible
|
||||
|
||||
```python
|
||||
def is_compatible(compatible: List[str]) -> bool
|
||||
```
|
||||
|
||||
Returns True if the parser is compatible with the running OS platform.
|
||||
|
||||
<a id="jc.utils.line_slice"></a>
|
||||
|
||||
### line\_slice
|
||||
### line_slice
|
||||
|
||||
```python
|
||||
def line_slice(
|
||||
data: Union[str, Iterable[str], TextIO, bytes, None],
|
||||
data: Union[str, Iterable[str], TextIO, bytes, NoneType],
|
||||
slice_start: Optional[int] = None,
|
||||
slice_end: Optional[int] = None
|
||||
) -> Union[str, Iterable[str], TextIO, bytes, None]
|
||||
) -> Union[str, Iterable[str], TextIO, bytes, NoneType]
|
||||
```
|
||||
|
||||
Slice input data by lines - lazily, if possible.
|
||||
@ -310,51 +244,69 @@ Returns:
|
||||
string if input is a string.
|
||||
iterable of strings if input is an iterable (for streaming parsers)
|
||||
|
||||
<a id="jc.utils.timestamp"></a>
|
||||
<a id="jc.utils.normalize_key"></a>
|
||||
|
||||
### timestamp Objects
|
||||
### normalize_key
|
||||
|
||||
```python
|
||||
class timestamp()
|
||||
def normalize_key(data: str) -> str
|
||||
```
|
||||
|
||||
<a id="jc.utils.timestamp.__init__"></a>
|
||||
Normalize a key name by shifting to lower-case and converting special
|
||||
characters to underscores.
|
||||
|
||||
### \_\_init\_\_
|
||||
Special characters are defined as `space` and the following:
|
||||
|
||||
```python
|
||||
def __init__(datetime_string: Optional[str],
|
||||
format_hint: Optional[Iterable[int]] = None) -> None
|
||||
```
|
||||
!"#$%&'()*+,-./:;<=>?@[\]^`{|}~
|
||||
|
||||
Input a datetime text string of several formats and convert to a
|
||||
naive or timezone-aware epoch timestamp in UTC.
|
||||
This is a lossy algorithm. Repeating and trailing underscores are
|
||||
removed.
|
||||
|
||||
Parameters:
|
||||
|
||||
datetime_string (str): a string representation of a
|
||||
datetime in several supported formats
|
||||
data: (string) Input value
|
||||
|
||||
format_hint (iterable): an optional iterable of format ID
|
||||
integers to instruct the timestamp object to try those
|
||||
formats first in the order given. Other formats will be
|
||||
tried after the format hint list is exhausted. This can
|
||||
speed up timestamp conversion so several different formats
|
||||
don't have to be tried in brute-force fashion.
|
||||
Returns:
|
||||
|
||||
Returns a timestamp object with the following attributes:
|
||||
string
|
||||
|
||||
string (str): the input datetime string
|
||||
<a id="jc.utils.remove_quotes"></a>
|
||||
|
||||
format (int | None): the format rule that was used to decode
|
||||
the datetime string. None if conversion fails.
|
||||
### remove_quotes
|
||||
|
||||
naive (int | None): timestamp based on locally configured
|
||||
timezone. None if conversion fails.
|
||||
```python
|
||||
def remove_quotes(data: str) -> str
|
||||
```
|
||||
|
||||
utc (int | None): aware timestamp only if UTC timezone
|
||||
detected in datetime string. None if conversion fails.
|
||||
Remove single or double quotes surrounding a string. If no quotes are
|
||||
found then the string is returned unmodified.
|
||||
|
||||
Parameters:
|
||||
|
||||
data: (string) Input value
|
||||
|
||||
Returns:
|
||||
|
||||
string
|
||||
|
||||
<a id="jc.utils.warning_message"></a>
|
||||
|
||||
### warning_message
|
||||
|
||||
```python
|
||||
def warning_message(message_lines: List[str]) -> None
|
||||
```
|
||||
|
||||
Prints warning message to `STDERR` for non-fatal issues. The first line
|
||||
is prepended with 'jc: Warning - ' and subsequent lines are indented.
|
||||
Wraps text as needed based on the terminal width.
|
||||
|
||||
Parameters:
|
||||
|
||||
message: (list) list of string lines
|
||||
|
||||
Returns:
|
||||
|
||||
None - just prints output to STDERR
|
||||
|
||||
iso (str | None): ISO string - timezone information is output
|
||||
only if UTC timezone is detected in the datetime string.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user