Merge pull request #242 from kellyjonbrazil/dev

Dev v1.19.0

CHANGELOG

@@ -1,5 +1,15 @@
 jc changelog
 
+20220513 v1.19.0
+- Add chage --list command parser tested on linux
+- Add git log command streaming parser
+- Fix git log standard parser for coner-cases where hash values are in messages
+- Fix df command parser for rare instances when a newline is found at the end
+- Allow jc to pip install on unsupported python version 3.6
+- Fix asciitable-m parser to skip some rows that contain column separator
+  characters in cell data. A warning message will be printed to STDOUT
+  unless `-q` or `quiet=True` is used.
+
 20220427 v1.18.8
 - Fix update-alternatives --query parser for cases where `slaves` are not present
 - Fix UnicodeEncodeError on some systems where LANG=C is set and unicode

EXAMPLES.md

@@ -265,6 +265,21 @@ blkid -o udev -ip /dev/sda2 | jc --blkid -p          # or:  jc -p blkid -o udev
   }
 ]
 ```
+### chage --list
+```bash
+chage --list joeuser | jc --chage -p          # or:  jc -p chage --list joeuser
+```
+```json
+{
+  "password_last_changed": "never",
+  "password_expires": "never",
+  "password_inactive": "never",
+  "account_expires": "never",
+  "min_days_between_password_change": 0,
+  "max_days_between_password_change": 99999,
+  "warning_days_before_password_expires": 7
+}
+```
 ### cksum
 ```bash
 cksum * | jc --cksum -p          # or:  jc -p cksum *

docs/parsers/asciitable_m.md

@@ -29,6 +29,11 @@ Headers (keys) are converted to snake-case and newlines between multi-line
 headers are joined with an underscore. All values are returned as strings,
 except empty strings, which are converted to None/null.
 
+> Note: table column separator characters (e.g. `|`) cannot be present
+  inside the cell data. If detected, a warning message will be printed to
+  STDERR and the line will be skipped. The warning message can be suppressed
+  by using the `-q` command option or by setting `quiet=True` in `parse()`.
+
 Usage (cli):
 
     $ cat table.txt | jc --asciitable-m
@@ -120,4 +125,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
 
-Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/chage.md

@@ -0,0 +1,82 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.chage"></a>
+
+# jc.parsers.chage
+
+jc - JSON Convert `chage --list` command output parser
+
+Supports `chage -l <username>` or `chage --list <username>`
+
+Usage (cli):
+
+    $ chage -l johndoe | jc --chage
+
+    or
+
+    $ jc chage -l johndoe
+
+Usage (module):
+
+    import jc
+    result = jc.parse('chage', chage_command_output)
+
+Schema:
+
+    {
+      "password_last_changed":                      string,
+      "password_expires":                           string,
+      "password_inactive":                          string,
+      "account_expires":                            string,
+      "min_days_between_password_change":           integer,
+      "max_days_between_password_change":           integer,
+      "warning_days_before_password_expires":       integer
+    }
+
+Examples:
+
+    $ chage --list joeuser | jc --chage -p
+    {
+      "password_last_changed": "never",
+      "password_expires": "never",
+      "password_inactive": "never",
+      "account_expires": "never",
+      "min_days_between_password_change": 0,
+      "max_days_between_password_change": 99999,
+      "warning_days_before_password_expires": 7
+    }
+
+    $ chage --list joeuser | jc --chage -p -r
+    {
+      "password_last_changed": "never",
+      "password_expires": "never",
+      "password_inactive": "never",
+      "account_expires": "never",
+      "min_days_between_password_change": "0",
+      "max_days_between_password_change": "99999",
+      "warning_days_before_password_expires": "7"
+    }
+
+<a id="jc.parsers.chage.parse"></a>
+
+### parse
+
+```python
+def parse(data: str, raw: bool = False, quiet: bool = False) -> 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:
+
+    Dictionary. Raw or processed structured data.
+
+### Parser Information
+Compatibility:  linux
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/csv_s.md

@@ -5,8 +5,8 @@
 
 jc - JSON Convert `csv` file streaming parser
 
-> This streaming parser outputs JSON Lines (cli) or returns a Generator
-  iterator of Dictionaries (module)
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+  Dictionaries (module)
 
 The `csv` streaming parser will attempt to automatically detect the
 delimiter character. If the delimiter cannot be detected it will default
@@ -68,7 +68,7 @@ Examples:
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
-Main text parsing generator function. Returns an iterator object.
+Main text parsing generator function. Returns an iterable object.
 
 Parameters:
 
@@ -79,13 +79,9 @@ Parameters:
     quiet:             (boolean)   suppress warning messages if True
     ignore_exceptions: (boolean)   ignore parsing exceptions if True
 
-Yields:
-
-    Dictionary. Raw or processed structured data.
-
 Returns:
 
-    Iterator object (generator)
+    Iterable of Dictionaries
 
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, win32, aix, freebsd

docs/parsers/df.md

@@ -120,4 +120,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, freebsd
 
-Version 1.9 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.10 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/git_log.md

@@ -172,4 +172,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
 
-Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/git_log_s.md

@@ -0,0 +1,111 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.git_log_s"></a>
+
+# jc.parsers.git\_log\_s
+
+jc - JSON Convert `git log` command output streaming parser
+
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+  Dictionaries (module)
+
+Can be used with the following format options:
+- `oneline`
+- `short`
+- `medium`
+- `full`
+- `fuller`
+
+Additional options supported:
+- `--stat`
+- `--shortstat`
+
+The `epoch` calculated timestamp field is naive. (i.e. based on the
+local time of the system the parser is run on)
+
+The `epoch_utc` calculated timestamp field is timezone-aware and is
+only available if the timezone field is UTC.
+
+Usage (cli):
+
+    $ git log | jc --git-log-s
+
+Usage (module):
+
+    import jc
+
+    result = jc.parse('git_log_s', git_log_command_output.splitlines())
+    for item in result:
+        # do something
+
+Schema:
+
+    {
+      "commit":               string,
+      "author":               string,
+      "author_email":         string,
+      "date":                 string,
+      "epoch":                integer, [0]
+      "epoch_utc":            integer, [1]
+      "commit_by":            string,
+      "commit_by_email":      string,
+      "commit_by_date":       string,
+      "message":              string,
+      "stats" : {
+        "files_changed":      integer,
+        "insertions":         integer,
+        "deletions":          integer,
+        "files": [
+                              string
+        ]
+      }
+
+      # below object only exists if using -qq or ignore_exceptions=True
+      "_jc_meta": {
+        "success":      boolean,     # false if error parsing
+        "error":        string,      # exists if "success" is false
+        "line":         string       # exists if "success" is false
+      }
+    }
+
+    [0] naive timestamp if "date" field is parsable, else null
+    [1] timezone aware timestamp availabe for UTC, else null
+
+Examples:
+
+    $ git log | jc --git-log-s
+    {"commit":"a730ae18c8e81c5261db132df73cd74f272a0a26","author":"Kelly...}
+    {"commit":"930bf439c06c48a952baec05a9896c8d92b7693e","author":"Kelly...}
+    ...
+
+<a id="jc.parsers.git_log_s.parse"></a>
+
+### parse
+
+```python
+@add_jc_meta
+def parse(data: Iterable[str],
+          raw: bool = False,
+          quiet: bool = False,
+          ignore_exceptions: bool = False) -> Union[Iterable[Dict], tuple]
+```
+
+Main text parsing generator function. Returns an iterable object.
+
+Parameters:
+
+    data:              (iterable)  line-based text data to parse
+                                   (e.g. sys.stdin or str.splitlines())
+
+    raw:               (boolean)   unprocessed output if True
+    quiet:             (boolean)   suppress warning messages if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+
+
+Returns:
+
+    Iterable of Dictionaries
+
+### Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/iostat_s.md

@@ -5,8 +5,8 @@
 
 jc - JSON Convert `iostat` command output streaming parser
 
-> This streaming parser outputs JSON Lines (cli) or returns a Generator
-  iterator of Dictionaries (module)
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+  Dictionaries (module)
 
 Note: `iostat` version 11 and higher include a JSON output option
 
@@ -112,7 +112,7 @@ Examples:
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
-Main text parsing generator function. Returns an iterator object.
+Main text parsing generator function. Returns an iterable object.
 
 Parameters:
 
@@ -123,13 +123,9 @@ Parameters:
     quiet:             (boolean)   suppress warning messages if True
     ignore_exceptions: (boolean)   ignore parsing exceptions if True
 
-Yields:
-
-    Dictionary. Raw or processed structured data.
-
 Returns:
 
-    Iterator object (generator)
+    Iterable of Dictionaries
 
 ### Parser Information
 Compatibility:  linux

docs/parsers/ls_s.md

@@ -5,8 +5,8 @@
 
 jc - JSON Convert `ls` and `vdir` command output streaming parser
 
-> This streaming parser outputs JSON Lines (cli) or returns a Generator
-  iterator of Dictionaries (module)
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+  Dictionaries (module)
 
 Requires the `-l` option to be used on `ls`. If there are newline characters
 in the filename, then make sure to use the `-b` option on `ls`.
@@ -81,7 +81,7 @@ Examples:
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
-Main text parsing generator function. Returns an iterator object.
+Main text parsing generator function. Returns an iterable object.
 
 Parameters:
 
@@ -92,13 +92,9 @@ Parameters:
     quiet:             (boolean)   suppress warning messages if True
     ignore_exceptions: (boolean)   ignore parsing exceptions if True
 
-Yields:
-
-    Dictionary. Raw or processed structured data.
-
 Returns:
 
-    Iterator object (generator)
+    Iterable of Dictionaries
 
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, aix, freebsd