6.8 KiB
Table of Contents
jc.utils
jc - JSON CLI output utility utils
warning_message
def warning_message(message_lines: List[str]) -> None
Prints warning message 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
error_message
def error_message(message_lines: List[str]) -> None
Prints an error message 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
compatibility
def compatibility(mod_name: str, compatible: List, quiet: bool = False) -> None
Checks for the parser's compatibility with the running OS platform.
Parameters:
mod_name: (string) __name__ of the calling module
compatible: (list) sys.platform name(s) compatible with
the parser. compatible options:
linux, darwin, cygwin, win32, aix, freebsd
quiet: (bool) supress compatibility message if True
Returns:
None - just prints output to STDERR
has_data
def has_data(data: str) -> bool
Checks if the input contains data. If there are any non-whitespace characters then return True, else return False.
Parameters:
data: (string) input to check whether it contains data
Returns:
Boolean True if input string (data) contains non-whitespace
characters, otherwise False
convert_to_int
def convert_to_int(value: Union[str, float]) -> 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
convert_to_float
def convert_to_float(value: Union[str, int]) -> 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
convert_to_bool
def convert_to_bool(value: Union[str, int, float]) -> 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.)
stream_success
def stream_success(output_line: Dict, ignore_exceptions: bool) -> Dict
Add _jc_meta object to output line if ignore_exceptions=True
stream_error
def stream_error(e: BaseException, ignore_exceptions: bool, line: str) -> Dict
Reraise the stream exception with annotation or print an error
_jc_meta field if ignore_exceptions=True.
add_jc_meta
def add_jc_meta(func)
Decorator for streaming parsers to add stream_success and stream_error objects. This simplifies the yield lines in the streaming parsers.
With the decorator on parse():
# successfully parsed line:
yield output_line if raw else _process(output_line)
# unsuccessfully parsed line:
except Exception as e:
yield e, line
Without the decorator on parse():
# successfully parsed line:
yield stream_success(output_line, ignore_exceptions) if raw else stream_success(_process(output_line), ignore_exceptions)
# unsuccessfully parsed line:
except Exception as e:
yield stream_error(e, ignore_exceptions, line)
In all cases above:
output_line: (Dict): successfully parsed line yielded as a dict
e: (BaseException): exception object as the first value
of the tuple if the line was not successfully parsed.
line: (str): string of the original line that did not
successfully parse.
input_type_check
def input_type_check(data: str) -> None
Ensure input data is a string. Raises TypeError if not.
streaming_input_type_check
def streaming_input_type_check(data: Iterable) -> None
Ensure input data is an iterable, but not a string or bytes. Raises
TypeError if not.
streaming_line_input_type_check
def streaming_line_input_type_check(line: str) -> None
Ensure each line is a string. Raises TypeError if not.
timestamp Objects
class timestamp()
__init__
def __init__(datetime_string: str) -> None
Input a date-time text string of several formats and convert to a naive or timezone-aware epoch timestamp in UTC.
Parameters:
datetime_string (str): a string representation of a
datetime in several supported formats
Returns a timestamp object with the following attributes:
string (str): the input datetime string
format (int | None): the format rule that was used to decode
the datetime string. None if conversion fails.
naive (int | None): timestamp based on locally configured
timezone. None if conversion fails.
utc (int | None): aware timestamp only if UTC timezone
detected in datetime string. None if conversion fails.