From 63e43a7cabb51c624c962cdcc92a1199f18c77e5 Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Tue, 1 Feb 2022 17:57:12 -0800 Subject: [PATCH] doc updates --- README.md | 3 +- docs/lib.md | 4 +- docs/parsers/rsync.md | 163 ++++++++++++++++++++++++++++++++++++++ docs/parsers/universal.md | 2 +- docs/parsers/zipinfo.md | 2 +- docs/utils.md | 28 +++---- man/jc.1 | 7 +- 7 files changed, 188 insertions(+), 21 deletions(-) create mode 100644 docs/parsers/rsync.md diff --git a/README.md b/README.md index 7f48230d..692eaaa3 100644 --- a/README.md +++ b/README.md @@ -128,7 +128,7 @@ pip3 install jc > For more OS Packages, see https://repology.org/project/jc/versions. -### Binaries and Packages +### Binaries For precompiled binaries, see [Releases](https://github.com/kellyjonbrazil/jc/releases) on Github. @@ -208,6 +208,7 @@ option. - `--ps` enables the `ps` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ps)) - `--route` enables the `route` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/route)) - `--rpm-qi` enables the `rpm -qi` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/rpm_qi)) +- `--rsync` enables the `rsync` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/rsync)) - `--sfdisk` enables the `sfdisk` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/sfdisk)) - `--shadow` enables the `/etc/shadow` file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/shadow)) - `--ss` enables the `ss` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ss)) diff --git a/docs/lib.md b/docs/lib.md index 8d2b7c2b..970eef52 100644 --- a/docs/lib.md +++ b/docs/lib.md @@ -105,7 +105,7 @@ subset of `parser_mod_list()`. ### parser\_info ```python -def parser_info(parser_mod_name: str) -> Union[Dict, None] +def parser_info(parser_mod_name: str) -> Optional[Dict] ``` Returns a dictionary that includes the module metadata. @@ -121,7 +121,7 @@ This function will accept **module_name**, **cli-name**, and def all_parser_info() -> List[Optional[Dict]] ``` -Returns a list of dictionaris that includes metadata for all modules. +Returns a list of dictionaries that includes metadata for all modules. diff --git a/docs/parsers/rsync.md b/docs/parsers/rsync.md new file mode 100644 index 00000000..5acb555c --- /dev/null +++ b/docs/parsers/rsync.md @@ -0,0 +1,163 @@ +[Home](https://kellyjonbrazil.github.io/jc/) + + +# jc.parsers.rsync + +jc - JSON CLI output utility `rsync` command output parser + +Supports the `-i` or `--itemize-changes` options with all levels of +verbosity. + +Will also process the rsync log file generated with the `--log-file` +option. + +Usage (cli): + + $ rsync -i -a source/ dest | jc --rsync + + or + + $ jc rsync -i -a source/ dest + +Usage (module): + + import jc + result = jc.parse('rsync', rsync_command_output) + + or + + import jc.parsers.rsync + result = jc.parsers.rsync.parse(rsync_command_output) + +Schema: + + [ + { + "summary": { + "date": string, + "time": string, + "process": integer, + "sent": integer, + "received": integer, + "total_size": integer, + "matches": integer, + "hash_hits": integer, + "false_alarms": integer, + "data": integer, + "bytes_sec": float, + "speedup": float + }, + "files": [ + { + "filename": string, + "date": string, + "time": string, + "process": integer, + "metadata": string, + "update_type": string/null, [0] + "file_type": string/null, [1] + "checksum_or_value_different": bool/null, + "size_different": bool/null, + "modification_time_different": bool/null, + "permissions_different": bool/null, + "owner_different": bool/null, + "group_different": bool/null, + "acl_different": bool/null, + "extended_attribute_different": bool/null, + "epoch": int, [2] + } + ] + } + ] + + [0] 'file sent', 'file received', 'local change or creation', + 'hard link', 'not updated', 'message' + [1] 'file', 'directory', 'symlink', 'device', 'special file' + [2] naive timestamp if time and date fields exist and can be converted. + +Examples: + + $ rsync -i -a source/ dest | jc --rsync -p + [ + { + "summary": { + "sent": 1708, + "received": 8209, + "bytes_sec": 19834.0, + "total_size": 235, + "speedup": 0.02 + }, + "files": [ + { + "filename": "./", + "metadata": ".d..t......", + "update_type": "not updated", + "file_type": "directory", + "checksum_or_value_different": false, + "size_different": false, + "modification_time_different": true, + "permissions_different": false, + "owner_different": false, + "group_different": false, + "acl_different": false, + "extended_attribute_different": false + }, + ... + ] + } + ] + + $ rsync | jc --rsync -p -r + [ + { + "summary": { + "sent": "1,708", + "received": "8,209", + "bytes_sec": "19,834.00", + "total_size": "235", + "speedup": "0.02" + }, + "files": [ + { + "filename": "./", + "metadata": ".d..t......", + "update_type": "not updated", + "file_type": "directory", + "checksum_or_value_different": false, + "size_different": false, + "modification_time_different": true, + "permissions_different": false, + "owner_different": false, + "group_different": false, + "acl_different": false, + "extended_attribute_different": false + }, + ... + ] + } + ] + + + +### parse + +```python +def parse(data: str, raw: bool = False, quiet: bool = False) -> List[Dict] +``` + +Main text parsing function + +Parameters: + + data: (string) text data to parse + raw: (boolean) unprocessed output if True + quiet: (boolean) suppress warning messages if True + +Returns: + + List of Dictionaries. Raw or processed structured data. + +### Parser Information +Compatibility: linux, darwin, freebsd + +Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com) diff --git a/docs/parsers/universal.md b/docs/parsers/universal.md index f360f875..00dca1d3 100644 --- a/docs/parsers/universal.md +++ b/docs/parsers/universal.md @@ -40,7 +40,7 @@ Returns: ### sparse\_table\_parse ```python -def sparse_table_parse(data: List[str], delim: Optional[str] = '\u2063') -> List[Dict] +def sparse_table_parse(data: List[str], delim: str = '\u2063') -> List[Dict] ``` Parse tables with missing column data or with spaces in column data. diff --git a/docs/parsers/zipinfo.md b/docs/parsers/zipinfo.md index 49a4712a..665a1a31 100644 --- a/docs/parsers/zipinfo.md +++ b/docs/parsers/zipinfo.md @@ -44,7 +44,7 @@ Schema: { "flags": string, "zipversion": string, - "zipunder": string + "zipunder": string, "filesize": integer, "type": string, "method": string, diff --git a/docs/utils.md b/docs/utils.md index 2b914cac..6bdce8fc 100644 --- a/docs/utils.md +++ b/docs/utils.md @@ -67,7 +67,7 @@ Returns: ### compatibility ```python -def compatibility(mod_name: str, compatible: List, quiet: Optional[bool] = False) -> None +def compatibility(mod_name: str, compatible: List, quiet: bool = False) -> None ``` Checks for the parser's compatibility with the running OS @@ -112,7 +112,7 @@ Returns: ### convert\_to\_int ```python -def convert_to_int(value: Union[str, float]) -> Union[int, None] +def convert_to_int(value: Union[str, float]) -> Optional[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: Union[str, int]) -> Union[float, None] +def convert_to_float(value: Union[str, int]) -> Optional[float] ``` Converts string and int input to float. Strips all non-numeric @@ -238,21 +238,19 @@ naive or timezone-aware epoch timestamp in UTC. Parameters: - datetime_string: (str) a string representation of a - date-time in several supported formats + datetime_string (str): a string representation of a + datetime in several supported formats -Attributes: +Returns a timestamp object with the following 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 + format (int | None): 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 + naive (int | None): 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 + utc (int | None) aware timestamp only if UTC timezone + detected in datetime string. None if conversion fails. diff --git a/man/jc.1 b/man/jc.1 index f7bf3bf4..102676c2 100644 --- a/man/jc.1 +++ b/man/jc.1 @@ -1,4 +1,4 @@ -.TH jc 1 2022-01-27 1.18.2 "JSON CLI output utility" +.TH jc 1 2022-02-01 1.18.3 "JSON CLI output utility" .SH NAME jc \- JSONifies the output of many CLI tools and file-types .SH SYNOPSIS @@ -302,6 +302,11 @@ Key/Value file parser \fB--rpm-qi\fP `rpm -qi` command parser +.TP +.B +\fB--rsync\fP +`rsync` command parser + .TP .B \fB--sfdisk\fP