From d4d5e206cae14acd25445952f820810818b3fdce Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Wed, 26 Jan 2022 15:54:36 -0800 Subject: [PATCH] type hints update --- docs/lib.md | 15 +++++++++++++-- docs/utils.md | 26 +++++++++++++------------- jc/utils.py | 27 ++++++++++++++------------- 3 files changed, 40 insertions(+), 28 deletions(-) diff --git a/docs/lib.md b/docs/lib.md index e38072cf..189c1de7 100644 --- a/docs/lib.md +++ b/docs/lib.md @@ -5,6 +5,7 @@ * [parser\_mod\_list](#jc.lib.parser_mod_list) * [plugin\_parser\_mod\_list](#jc.lib.plugin_parser_mod_list) * [parser\_info](#jc.lib.parser_info) + * [all\_parser\_info](#jc.lib.all_parser_info) * [get\_help](#jc.lib.get_help) @@ -19,7 +20,7 @@ JC lib module ### parse ```python -def parse(parser_mod_name: str, data: Union[str, Iterable[str]], quiet: Optional[bool] = False, raw: Optional[bool] = False, ignore_exceptions: Optional[Union[None, bool]] = None, **kwargs: Any) -> Union[Dict[str, Any], List[Dict[str, Any]], Iterator[Dict[str, Any]]] +def parse(parser_mod_name: str, data: Union[str, Iterable[str]], quiet: Optional[bool] = False, raw: Optional[bool] = False, ignore_exceptions: Optional[bool] = None, **kwargs: Any) -> Union[Dict, List[Dict], Iterator[Dict]] ``` Parse the string data using the supplied parser module. @@ -104,7 +105,7 @@ subset of `parser_mod_list()`. ### parser\_info ```python -def parser_info(parser_mod_name: str) -> Dict[str, Any] +def parser_info(parser_mod_name: str) -> Dict ``` Returns a dictionary that includes the module metadata. @@ -112,6 +113,16 @@ Returns a dictionary that includes the module metadata. This function will accept module_name, cli-name, and --argument-name variants of the module name string. + + +### all\_parser\_info + +```python +def all_parser_info() -> List[Dict] +``` + +Returns a list of dictionaris that includes metadata for all modules. + ### get\_help diff --git a/docs/utils.md b/docs/utils.md index 67e847b9..65ea2703 100644 --- a/docs/utils.md +++ b/docs/utils.md @@ -27,7 +27,7 @@ jc - JSON CLI output utility utils ### warning\_message ```python -def warning_message(message_lines) +def warning_message(message_lines: List[str]) -> None ``` Prints warning message for non-fatal issues. The first line is @@ -47,7 +47,7 @@ Returns: ### error\_message ```python -def error_message(message_lines) +def error_message(message_lines: List[str]) -> None ``` Prints an error message for fatal issues. The first line is @@ -67,7 +67,7 @@ Returns: ### compatibility ```python -def compatibility(mod_name, compatible, quiet=False) +def compatibility(mod_name: str, compatible: List, quiet: Optional[bool] = False) -> None ``` Checks for the parser's compatibility with the running OS @@ -92,7 +92,7 @@ Returns: ### has\_data ```python -def has_data(data) +def has_data(data: str) -> bool ``` Checks if the input contains data. If there are any non-whitespace @@ -112,7 +112,7 @@ Returns: ### convert\_to\_int ```python -def convert_to_int(value) +def convert_to_int(value: Union[str, float]) -> int ``` Converts string and float input to int. Strips all non-numeric @@ -131,7 +131,7 @@ Returns: ### convert\_to\_float ```python -def convert_to_float(value) +def convert_to_float(value: Union[str, int]) -> float ``` Converts string and int input to float. Strips all non-numeric @@ -150,7 +150,7 @@ Returns: ### convert\_to\_bool ```python -def convert_to_bool(value) +def convert_to_bool(value: Union[str, int, float]) -> bool ``` Converts string, integer, or float input to boolean by checking @@ -170,7 +170,7 @@ Returns: ### stream\_success ```python -def stream_success(output_line, ignore_exceptions) +def stream_success(output_line: Dict, ignore_exceptions: bool) -> Dict ``` Add `_jc_meta` object to output line if `ignore_exceptions=True` @@ -180,7 +180,7 @@ Add `_jc_meta` object to output line if `ignore_exceptions=True` ### stream\_error ```python -def stream_error(e, ignore_exceptions, line) +def stream_error(e: BaseException, ignore_exceptions: bool, line: str) -> Dict ``` Reraise the stream exception with annotation or print an error @@ -191,7 +191,7 @@ Reraise the stream exception with annotation or print an error ### input\_type\_check ```python -def input_type_check(data) +def input_type_check(data: str) -> None ``` Ensure input data is a string @@ -201,7 +201,7 @@ Ensure input data is a string ### streaming\_input\_type\_check ```python -def streaming_input_type_check(data) +def streaming_input_type_check(data: Iterable) -> None ``` Ensure input data is an iterable, but not a string or bytes @@ -211,7 +211,7 @@ Ensure input data is an iterable, but not a string or bytes ### streaming\_line\_input\_type\_check ```python -def streaming_line_input_type_check(line) +def streaming_line_input_type_check(line: str) -> None ``` Ensure each line is a string @@ -229,7 +229,7 @@ class timestamp() ### \_\_init\_\_ ```python -def __init__(datetime_string) +def __init__(datetime_string: str) -> None ``` Input a date-time text string of several formats and convert to a diff --git a/jc/utils.py b/jc/utils.py index 82f32753..babc8ffa 100644 --- a/jc/utils.py +++ b/jc/utils.py @@ -5,9 +5,10 @@ import locale import shutil from datetime import datetime, timezone from textwrap import TextWrapper +from typing import Dict, Iterable, List, Any, Union, Iterator, Optional -def warning_message(message_lines): +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. @@ -43,7 +44,7 @@ def warning_message(message_lines): print(message, file=sys.stderr) -def error_message(message_lines): +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. @@ -75,7 +76,7 @@ def error_message(message_lines): print(message, file=sys.stderr) -def compatibility(mod_name, compatible, quiet=False): +def compatibility(mod_name: str, compatible: List, quiet: Optional[bool] = False) -> None: """ Checks for the parser's compatibility with the running OS platform. @@ -109,7 +110,7 @@ def compatibility(mod_name, compatible, quiet=False): f'Compatible platforms: {compat_list}']) -def has_data(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. @@ -126,7 +127,7 @@ def has_data(data): return bool(data and not data.isspace()) -def convert_to_int(value): +def convert_to_int(value: Union[str, float]) -> int: """ Converts string and float input to int. Strips all non-numeric characters from strings. @@ -156,7 +157,7 @@ def convert_to_int(value): return None -def convert_to_float(value): +def convert_to_float(value: Union[str, int]) -> float: """ Converts string and int input to float. Strips all non-numeric characters from strings. @@ -182,7 +183,7 @@ def convert_to_float(value): return None -def convert_to_bool(value): +def convert_to_bool(value: Union[str, int, float]) -> bool: """ Converts string, integer, or float input to boolean by checking for 'truthy' values. @@ -220,7 +221,7 @@ def convert_to_bool(value): return False -def stream_success(output_line, ignore_exceptions): +def stream_success(output_line: Dict, ignore_exceptions: bool) -> Dict: """Add `_jc_meta` object to output line if `ignore_exceptions=True`""" if ignore_exceptions: output_line.update({'_jc_meta': {'success': True}}) @@ -228,7 +229,7 @@ def stream_success(output_line, ignore_exceptions): return output_line -def stream_error(e, ignore_exceptions, line): +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`. @@ -247,26 +248,26 @@ def stream_error(e, ignore_exceptions, line): } -def input_type_check(data): +def input_type_check(data: str) -> None: """Ensure input data is a string""" if not isinstance(data, str): raise TypeError("Input data must be a 'str' object.") -def streaming_input_type_check(data): +def streaming_input_type_check(data: Iterable) -> None: """Ensure input data is an iterable, but not a string or bytes""" if not hasattr(data, '__iter__') or isinstance(data, (str, bytes)): raise TypeError("Input data must be a non-string iterable object.") -def streaming_line_input_type_check(line): +def streaming_line_input_type_check(line: str) -> None: """Ensure each line is a string""" if not isinstance(line, str): raise TypeError("Input line must be a 'str' object.") class timestamp: - def __init__(self, datetime_string): + def __init__(self, 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.