deprecated parser support in lib

CHANGELOG

@@ -7,6 +7,7 @@ jc changelog
   display until `iso-datetime` is removed in a future version.
 - refactor cli module
 - optimize timestamps
+- add support for deprecating parsers
 
 20220926 v1.22.0
 - Add /proc file parsers for linux. Support for the following files:

completions/jc_bash_completion.sh

@@ -4,7 +4,7 @@ _jc()
           jc_about_options jc_about_mod_options jc_help_options jc_special_options
 
     jc_commands=(acpi airport arp blkid chage cksum crontab date df dig dmidecode dpkg du env file finger free git gpg hciconfig id ifconfig iostat iptables iw jobs last lastb ls lsblk lsmod lsof lspci lsusb md5 md5sum mdadm mount mpstat netstat nmcli ntpq pidstat ping ping6 pip pip3 postconf printenv ps route rpm rsync sfdisk sha1sum sha224sum sha256sum sha384sum sha512sum shasum ss stat sum sysctl systemctl systeminfo timedatectl top tracepath tracepath6 traceroute traceroute6 udevadm ufw uname update-alternatives upower uptime vdir vmstat w wc who xrandr zipinfo)
-    jc_parsers=(--acpi --airport --airport-s --arp --asciitable --asciitable-m --blkid --cef --cef-s --chage --cksum --crontab --crontab-u --csv --csv-s --date --datetime-iso --df --dig --dir --dmidecode --dpkg-l --du --email-address --env --file --finger --free --fstab --git-log --git-log-s --gpg --group --gshadow --hash --hashsum --hciconfig --history --hosts --id --ifconfig --ini --iostat --iostat-s --ip-address --iptables --iso-datetime --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lspci --lsusb --m3u --mdadm --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pci-ids --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --plist --postconf --proc --proc-buddyinfo --proc-consoles --proc-cpuinfo --proc-crypto --proc-devices --proc-diskstats --proc-filesystems --proc-interrupts --proc-iomem --proc-ioports --proc-loadavg --proc-locks --proc-meminfo --proc-modules --proc-mtrr --proc-pagetypeinfo --proc-partitions --proc-slabinfo --proc-softirqs --proc-stat --proc-swaps --proc-uptime --proc-version --proc-vmallocinfo --proc-vmstat --proc-zoneinfo --proc-driver-rtc --proc-net-arp --proc-net-dev --proc-net-dev-mcast --proc-net-if-inet6 --proc-net-igmp --proc-net-igmp6 --proc-net-ipv6-route --proc-net-netlink --proc-net-netstat --proc-net-packet --proc-net-protocols --proc-net-route --proc-net-unix --proc-pid-fdinfo --proc-pid-io --proc-pid-maps --proc-pid-mountinfo --proc-pid-numa-maps --proc-pid-smaps --proc-pid-stat --proc-pid-statm --proc-pid-status --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --syslog --syslog-s --syslog-bsd --syslog-bsd-s --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --timestamp --top --top-s --tracepath --traceroute --udevadm --ufw --ufw-appinfo --uname --update-alt-gs --update-alt-q --upower --uptime --url --vmstat --vmstat-s --w --wc --who --x509-cert --xml --xrandr --yaml --zipinfo)
+    jc_parsers=(--acpi --airport --airport-s --arp --asciitable --asciitable-m --blkid --cef --cef-s --chage --cksum --crontab --crontab-u --csv --csv-s --date --datetime-iso --df --dig --dir --dmidecode --dpkg-l --du --email-address --env --file --finger --free --fstab --git-log --git-log-s --gpg --group --gshadow --hash --hashsum --hciconfig --history --hosts --id --ifconfig --ini --iostat --iostat-s --ip-address --iptables --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lspci --lsusb --m3u --mdadm --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pci-ids --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --plist --postconf --proc --proc-buddyinfo --proc-consoles --proc-cpuinfo --proc-crypto --proc-devices --proc-diskstats --proc-filesystems --proc-interrupts --proc-iomem --proc-ioports --proc-loadavg --proc-locks --proc-meminfo --proc-modules --proc-mtrr --proc-pagetypeinfo --proc-partitions --proc-slabinfo --proc-softirqs --proc-stat --proc-swaps --proc-uptime --proc-version --proc-vmallocinfo --proc-vmstat --proc-zoneinfo --proc-driver-rtc --proc-net-arp --proc-net-dev --proc-net-dev-mcast --proc-net-if-inet6 --proc-net-igmp --proc-net-igmp6 --proc-net-ipv6-route --proc-net-netlink --proc-net-netstat --proc-net-packet --proc-net-protocols --proc-net-route --proc-net-unix --proc-pid-fdinfo --proc-pid-io --proc-pid-maps --proc-pid-mountinfo --proc-pid-numa-maps --proc-pid-smaps --proc-pid-stat --proc-pid-statm --proc-pid-status --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --syslog --syslog-s --syslog-bsd --syslog-bsd-s --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --timestamp --top --top-s --tracepath --traceroute --udevadm --ufw --ufw-appinfo --uname --update-alt-gs --update-alt-q --upower --uptime --url --vmstat --vmstat-s --w --wc --who --x509-cert --xml --xrandr --yaml --zipinfo)
     jc_options=(--force-color -C --debug -d --monochrome -m --meta-out -M --pretty -p --quiet -q --raw -r --unbuffer -u --yaml-out -y)
     jc_about_options=(--about -a)
     jc_about_mod_options=(--pretty -p --yaml-out -y --monochrome -m --force-color -C)

completions/jc_zsh_completion.sh

@@ -97,7 +97,7 @@ _jc() {
         'xrandr:run "xrandr" command with magic syntax.'
         'zipinfo:run "zipinfo" command with magic syntax.'
     )
-    jc_parsers=(--acpi --airport --airport-s --arp --asciitable --asciitable-m --blkid --cef --cef-s --chage --cksum --crontab --crontab-u --csv --csv-s --date --datetime-iso --df --dig --dir --dmidecode --dpkg-l --du --email-address --env --file --finger --free --fstab --git-log --git-log-s --gpg --group --gshadow --hash --hashsum --hciconfig --history --hosts --id --ifconfig --ini --iostat --iostat-s --ip-address --iptables --iso-datetime --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lspci --lsusb --m3u --mdadm --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pci-ids --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --plist --postconf --proc --proc-buddyinfo --proc-consoles --proc-cpuinfo --proc-crypto --proc-devices --proc-diskstats --proc-filesystems --proc-interrupts --proc-iomem --proc-ioports --proc-loadavg --proc-locks --proc-meminfo --proc-modules --proc-mtrr --proc-pagetypeinfo --proc-partitions --proc-slabinfo --proc-softirqs --proc-stat --proc-swaps --proc-uptime --proc-version --proc-vmallocinfo --proc-vmstat --proc-zoneinfo --proc-driver-rtc --proc-net-arp --proc-net-dev --proc-net-dev-mcast --proc-net-if-inet6 --proc-net-igmp --proc-net-igmp6 --proc-net-ipv6-route --proc-net-netlink --proc-net-netstat --proc-net-packet --proc-net-protocols --proc-net-route --proc-net-unix --proc-pid-fdinfo --proc-pid-io --proc-pid-maps --proc-pid-mountinfo --proc-pid-numa-maps --proc-pid-smaps --proc-pid-stat --proc-pid-statm --proc-pid-status --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --syslog --syslog-s --syslog-bsd --syslog-bsd-s --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --timestamp --top --top-s --tracepath --traceroute --udevadm --ufw --ufw-appinfo --uname --update-alt-gs --update-alt-q --upower --uptime --url --vmstat --vmstat-s --w --wc --who --x509-cert --xml --xrandr --yaml --zipinfo)
+    jc_parsers=(--acpi --airport --airport-s --arp --asciitable --asciitable-m --blkid --cef --cef-s --chage --cksum --crontab --crontab-u --csv --csv-s --date --datetime-iso --df --dig --dir --dmidecode --dpkg-l --du --email-address --env --file --finger --free --fstab --git-log --git-log-s --gpg --group --gshadow --hash --hashsum --hciconfig --history --hosts --id --ifconfig --ini --iostat --iostat-s --ip-address --iptables --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lspci --lsusb --m3u --mdadm --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pci-ids --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --plist --postconf --proc --proc-buddyinfo --proc-consoles --proc-cpuinfo --proc-crypto --proc-devices --proc-diskstats --proc-filesystems --proc-interrupts --proc-iomem --proc-ioports --proc-loadavg --proc-locks --proc-meminfo --proc-modules --proc-mtrr --proc-pagetypeinfo --proc-partitions --proc-slabinfo --proc-softirqs --proc-stat --proc-swaps --proc-uptime --proc-version --proc-vmallocinfo --proc-vmstat --proc-zoneinfo --proc-driver-rtc --proc-net-arp --proc-net-dev --proc-net-dev-mcast --proc-net-if-inet6 --proc-net-igmp --proc-net-igmp6 --proc-net-ipv6-route --proc-net-netlink --proc-net-netstat --proc-net-packet --proc-net-protocols --proc-net-route --proc-net-unix --proc-pid-fdinfo --proc-pid-io --proc-pid-maps --proc-pid-mountinfo --proc-pid-numa-maps --proc-pid-smaps --proc-pid-stat --proc-pid-statm --proc-pid-status --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --syslog --syslog-s --syslog-bsd --syslog-bsd-s --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --timestamp --top --top-s --tracepath --traceroute --udevadm --ufw --ufw-appinfo --uname --update-alt-gs --update-alt-q --upower --uptime --url --vmstat --vmstat-s --w --wc --who --x509-cert --xml --xrandr --yaml --zipinfo)
     jc_parsers_describe=(
         '--acpi:`acpi` command parser'
         '--airport:`airport -I` command parser'
@@ -145,7 +145,6 @@ _jc() {
         '--iostat-s:`iostat` command streaming parser'
         '--ip-address:IPv4 and IPv6 Address string parser'
         '--iptables:`iptables` command parser'
-        '--iso-datetime:Deprecated - please use datetime-iso'
         '--iw-scan:`iw dev [device] scan` command parser'
         '--jar-manifest:Java MANIFEST.MF file parser'
         '--jobs:`jobs` command parser'

docs/lib.md

@@ -99,7 +99,8 @@ Returns:
 ### parser\_mod\_list
 
 ```python
-def parser_mod_list() -> List[str]
+def parser_mod_list(show_hidden: bool = True,
+                    show_deprecated: bool = True) -> List[str]
 ```
 
 Returns a list of all available parser module names.
@@ -109,7 +110,8 @@ Returns a list of all available parser module names.
 ### plugin\_parser\_mod\_list
 
 ```python
-def plugin_parser_mod_list() -> List[str]
+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
@@ -120,7 +122,8 @@ subset of `parser_mod_list()`.
 ### standard\_parser\_mod\_list
 
 ```python
-def standard_parser_mod_list() -> List[str]
+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
@@ -132,7 +135,8 @@ parsers.
 ### streaming\_parser\_mod\_list
 
 ```python
-def streaming_parser_mod_list() -> List[str]
+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
@@ -163,17 +167,21 @@ Parameters:
 
 ```python
 def all_parser_info(documentation: bool = False,
-                    show_hidden: bool = False) -> List[Dict]
+                    show_hidden: bool = False,
+                    show_deprecated: bool = False) -> List[Dict]
 ```
 
 Returns a list of dictionaries that includes metadata for all parser
-modules.
+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.
 
 <a id="jc.lib.get_help"></a>
 

docs/parsers/iso_datetime.md

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

jc/cli.py

@@ -187,7 +187,7 @@ class JcCli():
         """Return the argument and description information from each parser"""
         ptext = ''
         padding_char = ' '
-        for p in all_parser_info(show_hidden=self.show_hidden):
+        for p in all_parser_info(show_hidden=self.show_hidden, show_deprecated=False):
             parser_arg = p.get('argument', 'UNKNOWN')
             padding = self.pad - len(parser_arg)
             parser_desc = p.get('description', 'No description available.')
@@ -230,7 +230,7 @@ class JcCli():
             'standard_parser_count': len(standard_parser_mod_list()),
             'streaming_parser_count': len(streaming_parser_mod_list()),
             'plugin_parser_count': len(plugin_parser_mod_list()),
-            'parsers': all_parser_info(show_hidden=True)
+            'parsers': all_parser_info(show_hidden=True, show_deprecated=True)
         }
 
     def helptext(self):

jc/lib.py

@@ -237,6 +237,28 @@ def _parser_is_streaming(parser):
 
     return False
 
+def _parser_is_hidden(parser):
+    """
+    Returns True if this is a hidden parser, else False
+
+    parser is a parser module object.
+    """
+    if getattr(parser.info, 'hidden', None):
+        return True
+
+    return False
+
+def _parser_is_deprecated(parser):
+    """
+    Returns True if this is a deprecated parser, else False
+
+    parser is a parser module object.
+    """
+    if getattr(parser.info, 'deprecated', None):
+        return True
+
+    return False
+
 def parse(
     parser_mod_name: str,
     data: Union[str, bytes, Iterable[str]],
@@ -319,18 +341,51 @@ def parse(
 
     return jc_parser.parse(data, quiet=quiet, raw=raw, **kwargs)
 
-def parser_mod_list() -> List[str]:
+def parser_mod_list(
+    show_hidden: bool = True,
+    show_deprecated: bool = True
+) -> List[str]:
     """Returns a list of all available parser module names."""
-    return [_cliname_to_modname(p) for p in parsers]
+    plist = []
+    for p in parsers:
+        parser = _get_parser(p)
 
-def plugin_parser_mod_list() -> List[str]:
+        if not show_hidden and _parser_is_hidden(parser):
+            continue
+
+        if not show_deprecated and _parser_is_deprecated(parser):
+            continue
+
+        plist.append(_cliname_to_modname(p))
+
+    return plist
+
+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()`.
     """
-    return [_cliname_to_modname(p) for p in local_parsers]
+    plist = []
+    for p in local_parsers:
+        parser = _get_parser(p)
 
-def standard_parser_mod_list() -> List[str]:
+        if not show_hidden and _parser_is_hidden(parser):
+            continue
+
+        if not show_deprecated and _parser_is_deprecated(parser):
+            continue
+
+        plist.append(_cliname_to_modname(p))
+
+    return plist
+
+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
@@ -339,11 +394,23 @@ def standard_parser_mod_list() -> List[str]:
     plist = []
     for p in parsers:
         parser = _get_parser(p)
+
         if not _parser_is_streaming(parser):
+
+            if not show_hidden and _parser_is_hidden(parser):
+                continue
+
+            if not show_deprecated and _parser_is_deprecated(parser):
+                continue
+
             plist.append(_cliname_to_modname(p))
+
     return plist
 
-def streaming_parser_mod_list() -> List[str]:
+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()`.
@@ -351,8 +418,17 @@ def streaming_parser_mod_list() -> List[str]:
     plist = []
     for p in parsers:
         parser = _get_parser(p)
+
         if _parser_is_streaming(parser):
+
+            if not show_hidden and _parser_is_hidden(parser):
+                continue
+
+            if not show_deprecated and _parser_is_deprecated(parser):
+                continue
+
             plist.append(_cliname_to_modname(p))
+
     return plist
 
 def parser_info(parser_mod_name: str, documentation: bool = False) -> Dict:
@@ -393,32 +469,39 @@ def parser_info(parser_mod_name: str, documentation: bool = False) -> Dict:
 
     return info_dict
 
-def all_parser_info(documentation: bool = False,
+def all_parser_info(
-                    show_hidden: bool = False
+    documentation: bool = False,
+    show_hidden: bool = False,
+    show_deprecated: bool = False
 ) -> List[Dict]:
     """
     Returns a list of dictionaries that includes metadata for all parser
-    modules.
+    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.
     """
-    temp_list = [parser_info(p, documentation=documentation) for p in parsers]
+    plist = []
+    for p in parsers:
+        parser = _get_parser(p)
 
-    p_list = []
+        if not show_hidden and _parser_is_hidden(parser):
-    if show_hidden:
+            continue
-        p_list = temp_list
 
-    else:
+        if not show_deprecated and _parser_is_deprecated(parser):
-        for item in temp_list:
+            continue
-            if not item.get('hidden', None):
-                p_list.append(item)
 
-    return p_list
+        plist.append(_cliname_to_modname(p))
 
+    p_info_list = [parser_info(p, documentation=documentation) for p in plist]
+
+    return p_info_list
 
 def get_help(parser_mod_name: str) -> None:
     """

jc/parsers/iso_datetime.py

@@ -11,13 +11,14 @@ import jc.utils
 
 class info():
     """Provides parser metadata (version, author, etc.)"""
-    version = '1.0'
+    version = '1.1'
     description = 'Deprecated - please use datetime-iso'
     author = 'Kelly Brazil'
     author_email = 'kellyjonbrazil@gmail.com'
     details = 'Deprecated - please use datetime-iso'
     compatible = ['linux', 'aix', 'freebsd', 'darwin', 'win32', 'cygwin']
     hidden = True
+    deprecated = True
 
 
 __version__ = info.version