python/jc
1
0
Fork 0
mirror of https://github.com/kellyjonbrazil/jc.git synced 2025-06-19 00:17:51 +02:00
Code Issues Releases Activity

formatting

Browse Source
This commit is contained in:
Kelly Brazil
2022-01-19 11:08:59 -08:00
parent 1d0e07c77b
commit b3c531193b
3 changed files with 125 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGELOG
View File

@ -1,7 +1,8 @@
jc changelog jc changelog
20220118 v1.18.0 20220119 v1.18.0
- Add high-level parse API for built-in and plugin parsers - Add high-level parse API for built-in and plugin parsers
- Documentation formatting enhancements
20220106 v1.17.7 20220106 v1.17.7
- Add stat command streaming parser tested on linux and macOS - Add stat command streaming parser tested on linux and macOS

79
docs/utils.md
View File

@ -7,9 +7,9 @@ jc - JSON CLI output utility utils
warning_message(message_lines) warning_message(message_lines)
``` ```
Prints warning message for non-fatal issues. The first line is prepended with Prints warning message for non-fatal issues. The first line is
'jc: Warning - ' and subsequent lines are indented. Wraps text as needed based prepended with 'jc: Warning - ' and subsequent lines are indented.
on the terminal width. Wraps text as needed based on the terminal width.
Parameters: Parameters:
@ -25,9 +25,9 @@ Returns:
error_message(message_lines) error_message(message_lines)
``` ```
Prints an error message for fatal issues. The first line is prepended with Prints an error message for fatal issues. The first line is
'jc: Error - ' and subsequent lines are indented. Wraps text as needed based prepended with 'jc: Error - ' and subsequent lines are indented.
on the terminal width. Wraps text as needed based on the terminal width.
Parameters: Parameters:
@ -42,17 +42,19 @@ Returns:
```python ```python
compatibility(mod_name, compatible, quiet=False) compatibility(mod_name, compatible, quiet=False)
``` ```
Checks for the parser's compatibility with the running OS platform.
Checks for the parser's compatibility with the running OS
platform.
Parameters: Parameters:
mod_name: (string) __name__ of the calling module mod_name: (string) __name__ of the calling module
compatible: (list) sys.platform name(s) compatible with the parser compatible: (list) sys.platform name(s) compatible with
compatible options: the parser. compatible options:
linux, darwin, cygwin, win32, aix, freebsd linux, darwin, cygwin, win32, aix, freebsd
quiet: (bool) supress compatibility message if True quiet: (bool) supress compatibility message if True
Returns: Returns:
@ -64,7 +66,8 @@ Returns:
has_data(data) has_data(data)
``` ```
Checks if the input contains data. If there are any non-whitespace characters then return True, else return False Checks if the input contains data. If there are any non-whitespace
characters then return True, else return False.
Parameters: Parameters:
@ -72,7 +75,8 @@ Parameters:
Returns: Returns:
Boolean True if input string (data) contains non-whitespace characters, otherwise False Boolean True if input string (data) contains non-whitespace
characters, otherwise False
## convert_to_int ## convert_to_int
@ -80,15 +84,16 @@ Returns:
convert_to_int(value) convert_to_int(value)
``` ```
Converts string and float input to int. Strips all non-numeric characters from strings. Converts string and float input to int. Strips all non-numeric
characters from strings.
Parameters: Parameters:
value: (string/integer/float) Input value value: (string/integer/float) Input value
Returns: Returns:
integer/None Integer if successful conversion, otherwise None integer/None Integer if successful conversion, otherwise None
## convert_to_float ## convert_to_float
@ -96,15 +101,16 @@ Returns:
convert_to_float(value) convert_to_float(value)
``` ```
Converts string and int input to float. Strips all non-numeric characters from strings. Converts string and int input to float. Strips all non-numeric
characters from strings.
Parameters: Parameters:
value: (string) Input value value: (string) Input value
Returns: Returns:
float/None Float if successful conversion, otherwise None float/None Float if successful conversion, otherwise None
## convert_to_bool ## convert_to_bool
@ -112,7 +118,8 @@ Returns:
convert_to_bool(value) convert_to_bool(value)
``` ```
Converts string, integer, or float input to boolean by checking for 'truthy' values Converts string, integer, or float input to boolean by checking
for 'truthy' values.
Parameters: Parameters:
@ -120,7 +127,8 @@ Parameters:
Returns: Returns:
True/False False unless a 'truthy' number or string is found ('y', 'yes', 'true', '1', 1, -1, etc.) True/False False unless a 'truthy' number or string is found
('y', 'yes', 'true', '1', 1, -1, etc.)
## stream_success ## stream_success
@ -133,8 +141,9 @@ Add `_jc_meta` object to output line if `ignore_exceptions=True`
```python ```python
stream_error(e, ignore_exceptions, line) stream_error(e, ignore_exceptions, line)
``` ```
Reraise the stream exception with annotation or print an error `_jc_meta`
field if `ignore_exceptions=True` Reraise the stream exception with annotation or print an error
`_jc_meta` field if `ignore_exceptions=True`.
## input_type_check ## input_type_check
@ -160,16 +169,26 @@ Ensure each line is a string
timestamp(datetime_string) timestamp(datetime_string)
``` ```
Input a date-time text string of several formats and convert to a naive or timezone-aware epoch timestamp in UTC Input a date-time text string of several formats and convert to a
naive or timezone-aware epoch timestamp in UTC.
Parameters: Parameters:
datetime_string: (str) a string representation of a date-time in several supported formats datetime_string: (str) a string representation of a
date-time in several supported formats
Attributes: Attributes:
string (str) the input datetime string string (str) the input datetime string
format (int) the format rule that was used to decode the datetime string. None if conversion fails
naive (int) timestamp based on locally configured timezone. None if conversion fails format (int) the format rule that was used to
utc (int) aware timestamp only if UTC timezone detected in datetime string. None if conversion fails decode the datetime string. None if
conversion fails
naive (int) timestamp based on locally configured
timezone. None if conversion fails
utc (int) aware timestamp only if UTC timezone
detected in datetime string. None if
conversion fails

114
jc/utils.py
View File

@ -9,9 +9,9 @@ from textwrap import TextWrapper
def warning_message(message_lines): def warning_message(message_lines):
""" """
Prints warning message for non-fatal issues. The first line is prepended with Prints warning message for non-fatal issues. The first line is
'jc: Warning - ' and subsequent lines are indented. Wraps text as needed based prepended with 'jc: Warning - ' and subsequent lines are indented.
on the terminal width. Wraps text as needed based on the terminal width.
Parameters: Parameters:
@ -45,9 +45,9 @@ def warning_message(message_lines):
def error_message(message_lines): def error_message(message_lines):
""" """
Prints an error message for fatal issues. The first line is prepended with Prints an error message for fatal issues. The first line is
'jc: Error - ' and subsequent lines are indented. Wraps text as needed based prepended with 'jc: Error - ' and subsequent lines are indented.
on the terminal width. Wraps text as needed based on the terminal width.
Parameters: Parameters:
@ -76,17 +76,19 @@ def error_message(message_lines):
def compatibility(mod_name, compatible, quiet=False): def compatibility(mod_name, compatible, quiet=False):
"""Checks for the parser's compatibility with the running OS platform. """
Checks for the parser's compatibility with the running OS
platform.
Parameters: Parameters:
mod_name: (string) __name__ of the calling module mod_name: (string) __name__ of the calling module
compatible: (list) sys.platform name(s) compatible with the parser compatible: (list) sys.platform name(s) compatible with
compatible options: the parser. compatible options:
linux, darwin, cygwin, win32, aix, freebsd linux, darwin, cygwin, win32, aix, freebsd
quiet: (bool) supress compatibility message if True quiet: (bool) supress compatibility message if True
Returns: Returns:
@ -109,7 +111,8 @@ def compatibility(mod_name, compatible, quiet=False):
def has_data(data): def has_data(data):
""" """
Checks if the input contains data. If there are any non-whitespace characters then return True, else return False Checks if the input contains data. If there are any non-whitespace
characters then return True, else return False.
Parameters: Parameters:
@ -117,22 +120,24 @@ def has_data(data):
Returns: Returns:
Boolean True if input string (data) contains non-whitespace characters, otherwise False Boolean True if input string (data) contains non-whitespace
characters, otherwise False
""" """
return bool(data and not data.isspace()) return bool(data and not data.isspace())
def convert_to_int(value): def convert_to_int(value):
""" """
Converts string and float input to int. Strips all non-numeric characters from strings. Converts string and float input to int. Strips all non-numeric
characters from strings.
Parameters: Parameters:
value: (string/integer/float) Input value value: (string/integer/float) Input value
Returns: Returns:
integer/None Integer if successful conversion, otherwise None integer/None Integer if successful conversion, otherwise None
""" """
if isinstance(value, str): if isinstance(value, str):
str_val = re.sub(r'[^0-9\-\.]', '', value) str_val = re.sub(r'[^0-9\-\.]', '', value)
@ -153,15 +158,16 @@ def convert_to_int(value):
def convert_to_float(value): def convert_to_float(value):
""" """
Converts string and int input to float. Strips all non-numeric characters from strings. Converts string and int input to float. Strips all non-numeric
characters from strings.
Parameters: Parameters:
value: (string) Input value value: (string) Input value
Returns: Returns:
float/None Float if successful conversion, otherwise None float/None Float if successful conversion, otherwise None
""" """
if isinstance(value, str): if isinstance(value, str):
try: try:
@ -178,7 +184,8 @@ def convert_to_float(value):
def convert_to_bool(value): def convert_to_bool(value):
""" """
Converts string, integer, or float input to boolean by checking for 'truthy' values Converts string, integer, or float input to boolean by checking
for 'truthy' values.
Parameters: Parameters:
@ -186,7 +193,8 @@ def convert_to_bool(value):
Returns: Returns:
True/False False unless a 'truthy' number or string is found ('y', 'yes', 'true', '1', 1, -1, etc.) True/False False unless a 'truthy' number or string is found
('y', 'yes', 'true', '1', 1, -1, etc.)
""" """
# if number, then bool it # if number, then bool it
# if string, try to convert to float # if string, try to convert to float
@ -221,8 +229,9 @@ def stream_success(output_line, ignore_exceptions):
def stream_error(e, ignore_exceptions, line): def stream_error(e, ignore_exceptions, line):
"""Reraise the stream exception with annotation or print an error `_jc_meta` """
field if `ignore_exceptions=True` Reraise the stream exception with annotation or print an error
`_jc_meta` field if `ignore_exceptions=True`.
""" """
if not ignore_exceptions: if not ignore_exceptions:
e.args = (str(e) + '... Use the ignore_exceptions option (-qq) to ignore streaming parser errors.',) e.args = (str(e) + '... Use the ignore_exceptions option (-qq) to ignore streaming parser errors.',)
@ -258,18 +267,28 @@ def streaming_line_input_type_check(line):
class timestamp: class timestamp:
""" """
Input a date-time text string of several formats and convert to a naive or timezone-aware epoch timestamp in UTC Input a date-time text string of several formats and convert to a
naive or timezone-aware epoch timestamp in UTC.
Parameters: Parameters:
datetime_string: (str) a string representation of a date-time in several supported formats datetime_string: (str) a string representation of a
date-time in several supported formats
Attributes: Attributes:
string (str) the input datetime string string (str) the input datetime string
format (int) the format rule that was used to decode the datetime string. None if conversion fails
naive (int) timestamp based on locally configured timezone. None if conversion fails format (int) the format rule that was used to
utc (int) aware timestamp only if UTC timezone detected in datetime string. None if conversion fails decode the datetime string. None if
conversion fails
naive (int) timestamp based on locally configured
timezone. None if conversion fails
utc (int) aware timestamp only if UTC timezone
detected in datetime string. None if
conversion fails
""" """
def __init__(self, datetime_string): def __init__(self, datetime_string):
@ -284,27 +303,42 @@ class timestamp:
def _parse(self): def _parse(self):
""" """
Input a date-time text string of several formats and convert to a naive or timezone-aware epoch timestamp in UTC Input a date-time text string of several formats and convert to
a naive or timezone-aware epoch timestamp in UTC.
Parameters: Parameters:
data: (string) a string representation of a date-time in several supported formats data: (string) a string representation of a date-time
in several supported formats
Returns: Returns:
Dictionary A Dictionary of the following format: Dictionary A Dictionary of the following format:
{ {
"format": integer, # for debugging purposes. None if conversion fails # for debugging purposes. None if conversion fails
"timestamp_naive": integer, # timestamp based on locally configured timezone. None if conversion fails "format": integer,
"timestamp_utc": integer # aware timestamp only if UTC timezone detected. None if conversion fails
# timestamp based on locally configured timezone.
# None if conversion fails.
"timestamp_naive": integer,
# aware timestamp only if UTC timezone detected.
# None if conversion fails.
"timestamp_utc": integer
} }
The format integer denotes which date_time format conversion succeeded. The `format` integer denotes which date_time format
The timestamp_naive integer is the converted date-time string to a naive epoch timestamp. conversion succeeded.
The timestamp_utc integer is the converted date-time string to an aware epoch timestamp
in the UTC timezone. If an aware conversion cannot be performed (e.g. the UTC timezone The `timestamp_naive` integer is the converted date-time
is not found in the date-time string), then this field will be None. string to a naive epoch timestamp.
The `timestamp_utc` integer is the converted date-time
string to an aware epoch timestamp in the UTC timezone. If
an aware conversion cannot be performed (e.g. the UTC
timezone is not found in the date-time string), then this
field will be None.
If the conversion completely fails, all fields will be None. If the conversion completely fails, all fields will be None.
""" """