jc/docs/lib.md

Table of Contents

• jc.lib
  • parse
  • parser_mod_list
  • plugin_parser_mod_list
  • standard_parser_mod_list
  • streaming_parser_mod_list
  • parser_info
  • all_parser_info
  • get_help

jc.lib

jc - JSON Convert lib module

parse

def parse(
    parser_mod_name: Union[str, ModuleType],
    data: Union[str, bytes, Iterable[str]],
    quiet: bool = False,
    raw: bool = False,
    ignore_exceptions: bool = None,
    **kwargs
) -> Union[JSONDictType, List[JSONDictType], Iterator[JSONDictType]]

Parse the string or bytes data using the supplied parser module.

This function provides a high-level API to simplify parser use. This function will call built-in parsers and custom plugin parsers.

Example (standard parsers):

>>> import jc
>>> date_obj = jc.parse('date', 'Tue Jan 18 10:23:07 PST 2022')
>>> print(f'The year is: {date_obj["year"]}')
The year is: 2022

Example (streaming parsers):

>>> import jc
>>> ping_gen = jc.parse('ping_s', ping_output.splitlines())
>>> for item in ping_gen:
>>>     print(f'Response time: {item["time_ms"]} ms')
Response time: 102 ms
Response time: 109 ms
...

To get a list of available parser module names, use parser_mod_list().

Alternatively, a parser module object can be supplied:

>>> import jc
>>> import jc.parsers.date as jc_date
>>> date_obj = jc.parse(jc_date, 'Tue Jan 18 10:23:07 PST 2022')
>>> print(f'The year is: {date_obj["year"]}')
The year is: 2022

You can also use the lower-level parser modules directly:

>>> import jc.parsers.date
>>> jc.parsers.date.parse('Tue Jan 18 10:23:07 PST 2022')

Though, accessing plugin parsers directly is a bit more cumbersome, so this higher-level API is recommended. Here is how you can access plugin parsers without this API:

>>> import os
>>> import sys
>>> import jc.appdirs
>>> data_dir = jc.appdirs.user_data_dir('jc', 'jc')
>>> local_parsers_dir = os.path.join(data_dir, 'jcparsers')
>>> sys.path.append(local_parsers_dir)
>>> import my_custom_parser
>>> my_custom_parser.parse('command_data')

Parameters:

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.

                                 A Module object can also be passed
                                 directly or via _get_parser()

data:               (string or   data to parse (string or bytes for
                    bytes or     standard parsers, iterable of
                    iterable)    strings for streaming parsers)

raw:                (boolean)    output preprocessed JSON if True

quiet:              (boolean)    suppress warning messages if True

ignore_exceptions:  (boolean)    ignore parsing exceptions if True
                                 (streaming parsers only)

Returns:

Standard Parsers:   Dictionary or List of Dictionaries
Streaming Parsers:  Generator Object containing Dictionaries

parser_mod_list

def parser_mod_list(show_hidden: bool = True,
                    show_deprecated: bool = True) -> List[str]

Returns a list of all available parser module names.

plugin_parser_mod_list

def plugin_parser_mod_list(show_hidden: bool = True,
                           show_deprecated: bool = True) -> List[str]

Returns a list of plugin parser module names. This function is a subset of parser_mod_list().

standard_parser_mod_list

def standard_parser_mod_list(show_hidden: bool = True,
                             show_deprecated: bool = True) -> List[str]

Returns a list of standard parser module names. This function is a subset of parser_mod_list() and does not contain any streaming parsers.

streaming_parser_mod_list

def streaming_parser_mod_list(show_hidden: bool = True,
                              show_deprecated: bool = True) -> List[str]

Returns a list of streaming parser module names. This function is a subset of parser_mod_list().

parser_info

def parser_info(parser_mod_name: str,
                documentation: bool = False) -> JSONDictType

Returns a dictionary that includes the parser module metadata.

Parameters:

parser_mod_name:    (string)     name of the parser module. This
                                 function will accept module_name,
                                 cli-name, and --argument-name
                                 variants of the module name.

documentation:      (boolean)    include parser docstring if True

all_parser_info

def all_parser_info(documentation: bool = False,
                    show_hidden: bool = False,
                    show_deprecated: bool = False) -> List[JSONDictType]

Returns a list of dictionaries that includes metadata for all parser modules. By default only non-hidden, non-deprecated parsers are returned.

Parameters:

documentation:      (boolean)    include parser docstrings if True
show_hidden:        (boolean)    also show parsers marked as hidden
                                 in their info metadata.
show_deprecated:    (boolean)    also show parsers marked as
                                 deprecated in their info metadata.

get_help

def get_help(parser_mod_name: str) -> None

Show help screen for the selected parser.

This function will accept module_name, cli-name, and --argument-name variants of the module name string.