From bf05de1d635f40da9fa0edc2cd0aef9dcb4d5455 Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Sat, 6 Jan 2024 19:37:20 -0800 Subject: [PATCH] doc update --- docs/lib.md | 15 +++++++++++++-- docs/readme.md | 20 ++++++++++++++++++++ jc/__init__.py | 20 ++++++++++++++++++++ jc/lib.py | 15 +++++++++++++-- 4 files changed, 66 insertions(+), 4 deletions(-) diff --git a/docs/lib.md b/docs/lib.md index 537ca2ee..060a5c8b 100644 --- a/docs/lib.md +++ b/docs/lib.md @@ -31,13 +31,24 @@ parser module. Parameters: - parser_mod_name: (string or name of the parser module. This + parser_mod_name: (string or Name of the parser module. This Module) function will accept module_name, cli-name, and --argument-name variants of the module name. + + If a Module is given and the Module + is a valid parser Module, then the + same Module is returned. + Returns: - Parser: the parser module object + Module: the parser Module object + +Raises: + + ModuleNotFoundError: If the Module is not found or is not a valid + parser Module, then a ModuleNotFoundError + exception is raised. diff --git a/docs/readme.md b/docs/readme.md index 2c0d7e6d..488c3d00 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -52,6 +52,18 @@ menu. Alternatively, you can bypass the high-level API and call the parser modules directly: + >>> import subprocess + >>> import jc + >>> + >>> jc_dig = jc.get_parser('dig') + >>> cmd_output = subprocess.check_output(['dig', 'example.com'], + text=True) + >>> data = jc_dig.parse(cmd_output) + >>> data + [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', ...}] + +or + >>> import subprocess >>> import jc.parsers.dig >>> @@ -75,6 +87,14 @@ Use `help(jc.lib)` for details. High-level API to easily access the parser. This API will find both built-in parsers and local plugin parsers. +### get_parser + + get_parser( + parser_module_name: str + ) -> ModuleType + +Get a parser Module object so you can use it directly. + ### parser_info parser_info( diff --git a/jc/__init__.py b/jc/__init__.py index e59824cb..6d8882b6 100644 --- a/jc/__init__.py +++ b/jc/__init__.py @@ -48,6 +48,18 @@ menu. Alternatively, you can bypass the high-level API and call the parser modules directly: + >>> import subprocess + >>> import jc + >>> + >>> jc_dig = jc.get_parser('dig') + >>> cmd_output = subprocess.check_output(['dig', 'example.com'], + text=True) + >>> data = jc_dig.parse(cmd_output) + >>> data + [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', ...}] + +or + >>> import subprocess >>> import jc.parsers.dig >>> @@ -71,6 +83,14 @@ Use `help(jc.lib)` for details. High-level API to easily access the parser. This API will find both built-in parsers and local plugin parsers. +### get_parser + + get_parser( + parser_module_name: str + ) -> ModuleType + +Get a parser Module object so you can use it directly. + ### parser_info parser_info( diff --git a/jc/lib.py b/jc/lib.py index 15e4e23a..83d81c09 100644 --- a/jc/lib.py +++ b/jc/lib.py @@ -281,13 +281,24 @@ def get_parser(parser_mod_name: Union[str, ModuleType]) -> ModuleType: Parameters: - parser_mod_name: (string or name of the parser module. This + parser_mod_name: (string or Name of the parser module. This Module) function will accept module_name, cli-name, and --argument-name variants of the module name. + + If a Module is given and the Module + is a valid parser Module, then the + same Module is returned. + Returns: - Parser: the parser module object + Module: the parser Module object + + Raises: + + ModuleNotFoundError: If the Module is not found or is not a valid + parser Module, then a ModuleNotFoundError + exception is raised. """ if isinstance(parser_mod_name, ModuleType): jc_parser = parser_mod_name