python/jc
1
0
Fork 0
mirror of https://github.com/kellyjonbrazil/jc.git synced 2025-06-17 00:07:37 +02:00
Code Issues Releases Activity

update docstrings for new help functionality

Browse Source
This commit is contained in:
Kelly Brazil
2021-04-08 11:24:02 -07:00
parent 57c13cc0a3
commit 9b39917c79
17 changed files with 391 additions and 453 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -199,7 +199,7 @@ The JSON output can be compact (default) or pretty formatted with the `-p` optio
### Options
- `-a` about `jc`. Prints information about `jc` and the parsers (in JSON, of course!)
- `-d` debug mode. Prints trace messages if parsing issues are encountered (use `-dd` for verbose debugging)
- `-h` `jc` help
- `-h` `jc` help. Use `jc -h --parser_name` for parser documentation
- `-m` monochrome JSON output
- `-p` pretty format the JSON output
- `-q` quiet mode. Suppresses parser warning messages

94
docs/parsers/acpi.md
View File

@ -15,6 +15,45 @@ Usage (module):
import jc.parsers.acpi
result = jc.parsers.acpi.parse(acpi_command_output)
Schema:
[
{
"type": string,
"id": integer,
"state": string,
"charge_percent": integer,
"until_charged": string,
"until_charged_hours": integer,
"until_charged_minuts": integer,
"until_charged_seconds": integer,
"until_charged_total_seconds": integer,
"charge_remaining": string,
"charge_remaining_hours": integer,
"charge_remaining_minutes": integer,
"charge_remaining_seconds": integer,
"charge_remaining_total_seconds": integer,
"design_capacity_mah": integer,
"last_full_capacity": integer,
"last_full_capacity_percent": integer,
"on-line": boolean,
"mode": string,
"temperature": float,
"temperature_unit": string,
"trip_points": [
{
"id": integer,
"switches_to_mode": string,
"temperature": float,
"temperature_unit": string
}
],
"messages": [
string
]
}
]
Compatibility:
'linux'
@ -194,60 +233,7 @@ Examples:
```python
info()
```
## process
```python
process(proc_data)
```
Final processing to conform to the schema.
Parameters:
proc_data: (List of Dictionaries) raw structured data to process
Returns:
List of Dictionaries. Structured data with the following schema:
[
{
"type": string,
"id": integer,
"state": string,
"charge_percent": integer,
"until_charged": string,
"until_charged_hours": integer,
"until_charged_minuts": integer,
"until_charged_seconds": integer,
"until_charged_total_seconds": integer,
"charge_remaining": string,
"charge_remaining_hours": integer,
"charge_remaining_minutes": integer,
"charge_remaining_seconds": integer,
"charge_remaining_total_seconds": integer,
"design_capacity_mah": integer,
"last_full_capacity": integer,
"last_full_capacity_percent": integer,
"on-line": boolean,
"mode": string,
"temperature": float,
"temperature_unit": string,
"trip_points": [
{
"id": integer,
"switches_to_mode": string,
"temperature": float,
"temperature_unit": string
}
],
"messages": [
string
]
}
]
Provides parser metadata (version, author, etc.)
## parse
```python

56
docs/parsers/airport.md
View File

@ -17,6 +17,26 @@ Usage (module):
import jc.parsers.airport
result = jc.parsers.airport.parse(airport_command_output)
Schema:
{
"agrctlrssi": integer,
"agrextrssi": integer,
"agrctlnoise": integer,
"agrextnoise": integer,
"state": string,
"op_mode": string,
"lasttxrate": integer,
"maxrate": integer,
"lastassocstatus": integer,
"802_11_auth": string,
"link_auth": string,
"bssid": string,
"ssid": string,
"mcs": integer,
"channel": string
}
Compatibility:
'darwin'
@ -66,41 +86,7 @@ Examples:
```python
info()
```
## process
```python
process(proc_data)
```
Final processing to conform to the schema.
Parameters:
proc_data: (Dictionary) raw structured data to process
Returns:
Dictionary. Structured data with the following schema:
{
"agrctlrssi": integer,
"agrextrssi": integer,
"agrctlnoise": integer,
"agrextnoise": integer,
"state": string,
"op_mode": string,
"lasttxrate": integer,
"maxrate": integer,
"lastassocstatus": integer,
"802_11_auth": string,
"link_auth": string,
"bssid": string,
"ssid": string,
"mcs": integer,
"channel": string
}
Provides parser metadata (version, author, etc.)
## parse
```python

88
docs/parsers/blkid.md
View File

@ -15,6 +15,42 @@ Usage (module):
import jc.parsers.blkid
result = jc.parsers.blkid.parse(blkid_command_output)
Schema:
[
{
"device": string,
"uuid": string,
"type": string,
"usage": string,
"part_entry_scheme": string,
"part_entry_type": string,
"part_entry_flags": string,
"part_entry_number": integer,
"part_entry_offset": integer,
"part_entry_size": integer,
"part_entry_disk": string,
"id_fs_uuid": string,
"id_fs_uuid_enc": string,
"id_fs_version": string,
"id_fs_type": string,
"id_fs_usage": string,
"id_part_entry_scheme": string,
"id_part_entry_type": string,
"id_part_entry_flags": string,
"id_part_entry_number": integer,
"id_part_entry_offset": integer,
"id_part_entry_size": integer,
"id_iolimit_minimum_io_size": integer,
"id_iolimit_physical_sector_size": integer,
"id_iolimit_logical_sector_size": integer,
"id_part_entry_disk": string,
"minimum_io_size": integer,
"physical_sector_size": integer,
"logical_sector_size": integer
}
]
Compatibility:
'linux'
@ -90,57 +126,7 @@ Examples:
```python
info()
```
## process
```python
process(proc_data)
```
Final processing to conform to the schema.
Parameters:
proc_data: (List of Dictionaries) raw structured data to process
Returns:
List of Dictionaries. Structured data with the following schema:
[
{
"device": string,
"uuid": string,
"type": string,
"usage": string,
"part_entry_scheme": string,
"part_entry_type": string,
"part_entry_flags": string,
"part_entry_number": integer,
"part_entry_offset": integer,
"part_entry_size": integer,
"part_entry_disk": string,
"id_fs_uuid": string,
"id_fs_uuid_enc": string,
"id_fs_version": string,
"id_fs_type": string,
"id_fs_usage": string,
"id_part_entry_scheme": string,
"id_part_entry_type": string,
"id_part_entry_flags": string,
"id_part_entry_number": integer,
"id_part_entry_offset": integer,
"id_part_entry_size": integer,
"id_iolimit_minimum_io_size": integer,
"id_iolimit_physical_sector_size": integer,
"id_iolimit_logical_sector_size": integer,
"id_part_entry_disk": string,
"minimum_io_size": integer,
"physical_sector_size": integer,
"logical_sector_size": integer
}
]
Provides parser metadata (version, author, etc.)
## parse
```python

36
docs/parsers/cksum.md
View File

@ -19,6 +19,16 @@ Usage (module):
import jc.parsers.cksum
result = jc.parsers.cksum.parse(cksum_command_output)
Schema:
[
{
"filename": string,
"checksum": integer,
"blocks": integer
}
]
Compatibility:
'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
@ -50,31 +60,7 @@ Examples:
```python
info()
```
## process
```python
process(proc_data)
```
Final processing to conform to the schema.
Parameters:
proc_data: (List of Dictionaries) raw structured data to process
Returns:
List of Dictionaries. Structured data with the following schema:
[
{
"filename": string,
"checksum": integer,
"blocks": integer
}
]
Provides parser metadata (version, author, etc.)
## parse
```python

79
docs/parsers/crontab.md
View File

@ -17,6 +17,37 @@ Usage (module):
import jc.parsers.crontab
result = jc.parsers.crontab.parse(crontab_output)
Schema:
{
"variables": [
"name": string,
"value": string
],
"schedule": [
{
"occurrence" string,
"minute": [
string
],
"hour": [
string
],
"day_of_month": [
string
],
"month": [
string
],
"day_of_week": [
string
],
"occurrence": string,
"command": string
}
]
}
Compatibility:
'linux', 'darwin', 'aix', 'freebsd'
@ -145,53 +176,7 @@ Examples:
```python
info()
```
## process
```python
process(proc_data)
```
Final processing to conform to the schema.
Parameters:
proc_data: (Dictionary) raw structured data to process
Returns:
Dictionary. Structured data with the following schema:
{
"variables": [
"name": string,
"value": string
],
"schedule": [
{
"occurrence" string,
"minute": [
string
],
"hour": [
string
],
"day_of_month": [
string
],
"month": [
string
],
"day_of_week": [
string
],
"occurrence": string,
"command": string
}
]
}
Provides parser metadata (version, author, etc.)
## parse
```python

83
docs/parsers/crontab_u.md
View File

@ -13,6 +13,38 @@ Usage (module):
import jc.parsers.crontab_u
result = jc.parsers.crontab_u.parse(crontab_u_output)
Schema:
{
"variables": [
"name": string,
"value": string
],
"schedule": [
{
"occurrence" string,
"minute": [
string
],
"hour": [
string
],
"day_of_month": [
string
],
"month": [
string
],
"day_of_week": [
string
],
"occurrence": string,
"user": string,
"command": string
}
]
}
Compatibility:
'linux', 'darwin', 'aix', 'freebsd'
@ -136,60 +168,11 @@ Examples:
}
## info
```python
info()
```
## process
```python
process(proc_data)
```
Final processing to conform to the schema.
Parameters:
proc_data: (Dictionary) raw structured data to process
Returns:
Dictionary. Structured data with the following schema:
{
"variables": [
"name": string,
"value": string
],
"schedule": [
{
"occurrence" string,
"minute": [
string
],
"hour": [
string
],
"day_of_month": [
string
],
"month": [
string
],
"day_of_week": [
string
],
"occurrence": string,
"user": string,
"command": string
}
]
}
Provides parser metadata (version, author, etc.)
## parse
```python

6
jc/cli.py
View File

@ -320,7 +320,7 @@ def helptext():
Options:
-a about jc
-d debug - show traceback (-dd for verbose traceback)
-h help (use -h --parser_name for detailed parser info)
-h help (use -h --parser_name for parser documentation)
-m monochrome output
-p pretty print output
-q quiet - suppress parser warnings
@ -334,9 +334,9 @@ def helptext():
jc -p ls -al
For detailed parser information:
For parser documentation:
jc -h --arp
jc -h --ls
'''
return textwrap.dedent(helptext_string)

85
jc/parsers/acpi.py
View File

@ -13,6 +13,45 @@ Usage (module):
import jc.parsers.acpi
result = jc.parsers.acpi.parse(acpi_command_output)
Schema:
[
{
"type": string,
"id": integer,
"state": string,
"charge_percent": integer,
"until_charged": string,
"until_charged_hours": integer,
"until_charged_minuts": integer,
"until_charged_seconds": integer,
"until_charged_total_seconds": integer,
"charge_remaining": string,
"charge_remaining_hours": integer,
"charge_remaining_minutes": integer,
"charge_remaining_seconds": integer,
"charge_remaining_total_seconds": integer,
"design_capacity_mah": integer,
"last_full_capacity": integer,
"last_full_capacity_percent": integer,
"on-line": boolean,
"mode": string,
"temperature": float,
"temperature_unit": string,
"trip_points": [
{
"id": integer,
"switches_to_mode": string,
"temperature": float,
"temperature_unit": string
}
],
"messages": [
string
]
}
]
Compatibility:
'linux'
@ -191,7 +230,8 @@ import jc.utils
class info():
version = '1.0'
"""Provides parser metadata (version, author, etc.)"""
version = '1.1'
description = '`acpi` command parser'
author = 'Kelly Brazil'
author_email = 'kellyjonbrazil@gmail.com'
@ -204,7 +244,7 @@ class info():
__version__ = info.version
def process(proc_data):
def _process(proc_data):
"""
Final processing to conform to the schema.
@ -214,44 +254,7 @@ def process(proc_data):
Returns:
List of Dictionaries. Structured data with the following schema:
[
{
"type": string,
"id": integer,
"state": string,
"charge_percent": integer,
"until_charged": string,
"until_charged_hours": integer,
"until_charged_minuts": integer,
"until_charged_seconds": integer,
"until_charged_total_seconds": integer,
"charge_remaining": string,
"charge_remaining_hours": integer,
"charge_remaining_minutes": integer,
"charge_remaining_seconds": integer,
"charge_remaining_total_seconds": integer,
"design_capacity_mah": integer,
"last_full_capacity": integer,
"last_full_capacity_percent": integer,
"on-line": boolean,
"mode": string,
"temperature": float,
"temperature_unit": string,
"trip_points": [
{
"id": integer,
"switches_to_mode": string,
"temperature": float,
"temperature_unit": string
}
],
"messages": [
string
]
}
]
List of Dictionaries. Structured data to conform to the schema.
"""
int_list = ['id', 'charge_percent', 'design_capacity_mah', 'last_full_capacity', 'last_full_capacity_percent']
float_list = ['temperature']
@ -406,4 +409,4 @@ def parse(data, raw=False, quiet=False):
if raw:
return raw_output
else:
return process(raw_output)
return _process(raw_output)

47
jc/parsers/airport.py
View File

@ -15,6 +15,26 @@ Usage (module):
import jc.parsers.airport
result = jc.parsers.airport.parse(airport_command_output)
Schema:
{
"agrctlrssi": integer,
"agrextrssi": integer,
"agrctlnoise": integer,
"agrextnoise": integer,
"state": string,
"op_mode": string,
"lasttxrate": integer,
"maxrate": integer,
"lastassocstatus": integer,
"802_11_auth": string,
"link_auth": string,
"bssid": string,
"ssid": string,
"mcs": integer,
"channel": string
}
Compatibility:
'darwin'
@ -63,7 +83,8 @@ import jc.utils
class info():
version = '1.1'
"""Provides parser metadata (version, author, etc.)"""
version = '1.2'
description = '`airport -I` command parser'
author = 'Kelly Brazil'
author_email = 'kellyjonbrazil@gmail.com'
@ -77,7 +98,7 @@ class info():
__version__ = info.version
def process(proc_data):
def _process(proc_data):
"""
Final processing to conform to the schema.
@ -87,25 +108,7 @@ def process(proc_data):
Returns:
Dictionary. Structured data with the following schema:
{
"agrctlrssi": integer,
"agrextrssi": integer,
"agrctlnoise": integer,
"agrextnoise": integer,
"state": string,
"op_mode": string,
"lasttxrate": integer,
"maxrate": integer,
"lastassocstatus": integer,
"802_11_auth": string,
"link_auth": string,
"bssid": string,
"ssid": string,
"mcs": integer,
"channel": string
}
Dictionary. Structured data to conform to the schema.
"""
# integer changes
int_list = ['agrctlrssi', 'agrextrssi', 'agrctlnoise', 'agrextnoise',
@ -148,4 +151,4 @@ def parse(data, raw=False, quiet=False):
if raw:
return raw_output
else:
return process(raw_output)
return _process(raw_output)

79
jc/parsers/blkid.py
View File

@ -13,6 +13,42 @@ Usage (module):
import jc.parsers.blkid
result = jc.parsers.blkid.parse(blkid_command_output)
Schema:
[
{
"device": string,
"uuid": string,
"type": string,
"usage": string,
"part_entry_scheme": string,
"part_entry_type": string,
"part_entry_flags": string,
"part_entry_number": integer,
"part_entry_offset": integer,
"part_entry_size": integer,
"part_entry_disk": string,
"id_fs_uuid": string,
"id_fs_uuid_enc": string,
"id_fs_version": string,
"id_fs_type": string,
"id_fs_usage": string,
"id_part_entry_scheme": string,
"id_part_entry_type": string,
"id_part_entry_flags": string,
"id_part_entry_number": integer,
"id_part_entry_offset": integer,
"id_part_entry_size": integer,
"id_iolimit_minimum_io_size": integer,
"id_iolimit_physical_sector_size": integer,
"id_iolimit_logical_sector_size": integer,
"id_part_entry_disk": string,
"minimum_io_size": integer,
"physical_sector_size": integer,
"logical_sector_size": integer
}
]
Compatibility:
'linux'
@ -88,7 +124,8 @@ import jc.utils
class info():
version = '1.2'
"""Provides parser metadata (version, author, etc.)"""
version = '1.3'
description = '`blkid` command parser'
author = 'Kelly Brazil'
author_email = 'kellyjonbrazil@gmail.com'
@ -102,7 +139,7 @@ class info():
__version__ = info.version
def process(proc_data):
def _process(proc_data):
"""
Final processing to conform to the schema.
@ -112,41 +149,7 @@ def process(proc_data):
Returns:
List of Dictionaries. Structured data with the following schema:
[
{
"device": string,
"uuid": string,
"type": string,
"usage": string,
"part_entry_scheme": string,
"part_entry_type": string,
"part_entry_flags": string,
"part_entry_number": integer,
"part_entry_offset": integer,
"part_entry_size": integer,
"part_entry_disk": string,
"id_fs_uuid": string,
"id_fs_uuid_enc": string,
"id_fs_version": string,
"id_fs_type": string,
"id_fs_usage": string,
"id_part_entry_scheme": string,
"id_part_entry_type": string,
"id_part_entry_flags": string,
"id_part_entry_number": integer,
"id_part_entry_offset": integer,
"id_part_entry_size": integer,
"id_iolimit_minimum_io_size": integer,
"id_iolimit_physical_sector_size": integer,
"id_iolimit_logical_sector_size": integer,
"id_part_entry_disk": string,
"minimum_io_size": integer,
"physical_sector_size": integer,
"logical_sector_size": integer
}
]
List of Dictionaries. Structured data to conform to the schema.
"""
for entry in proc_data:
if 'devname' in entry:
@ -225,4 +228,4 @@ def parse(data, raw=False, quiet=False):
if raw:
return raw_output
else:
return process(raw_output)
return _process(raw_output)

27
jc/parsers/cksum.py
View File

@ -17,6 +17,16 @@ Usage (module):
import jc.parsers.cksum
result = jc.parsers.cksum.parse(cksum_command_output)
Schema:
[
{
"filename": string,
"checksum": integer,
"blocks": integer
}
]
Compatibility:
'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
@ -47,7 +57,8 @@ import jc.utils
class info():
version = '1.0'
"""Provides parser metadata (version, author, etc.)"""
version = '1.1'
description = '`cksum` and `sum` command parser'
author = 'Kelly Brazil'
author_email = 'kellyjonbrazil@gmail.com'
@ -60,7 +71,7 @@ class info():
__version__ = info.version
def process(proc_data):
def _process(proc_data):
"""
Final processing to conform to the schema.
@ -70,15 +81,7 @@ def process(proc_data):
Returns:
List of Dictionaries. Structured data with the following schema:
[
{
"filename": string,
"checksum": integer,
"blocks": integer
}
]
List of Dictionaries. Structured data to conform to the schema.
"""
for entry in proc_data:
@ -124,4 +127,4 @@ def parse(data, raw=False, quiet=False):
if raw:
return raw_output
else:
return process(raw_output)
return _process(raw_output)

70
jc/parsers/crontab.py
View File

@ -15,6 +15,37 @@ Usage (module):
import jc.parsers.crontab
result = jc.parsers.crontab.parse(crontab_output)
Schema:
{
"variables": [
"name": string,
"value": string
],
"schedule": [
{
"occurrence" string,
"minute": [
string
],
"hour": [
string
],
"day_of_month": [
string
],
"month": [
string
],
"day_of_week": [
string
],
"occurrence": string,
"command": string
}
]
}
Compatibility:
'linux', 'darwin', 'aix', 'freebsd'
@ -143,7 +174,8 @@ import jc.parsers.universal
class info():
version = '1.4'
"""Provides parser metadata (version, author, etc.)"""
version = '1.5'
description = '`crontab` command and file parser'
author = 'Kelly Brazil'
author_email = 'kellyjonbrazil@gmail.com'
@ -157,7 +189,7 @@ class info():
__version__ = info.version
def process(proc_data):
def _process(proc_data):
"""
Final processing to conform to the schema.
@ -167,37 +199,7 @@ def process(proc_data):
Returns:
Dictionary. Structured data with the following schema:
{
"variables": [
"name": string,
"value": string
],
"schedule": [
{
"occurrence" string,
"minute": [
string
],
"hour": [
string
],
"day_of_month": [
string
],
"month": [
string
],
"day_of_week": [
string
],
"occurrence": string,
"command": string
}
]
}
Dictionary. Structured data to conform to the schema.
"""
# put itmes in lists
try:
@ -280,4 +282,4 @@ def parse(data, raw=False, quiet=False):
if raw:
return raw_output
else:
return process(raw_output)
return _process(raw_output)

74
jc/parsers/crontab_u.py
View File

@ -11,6 +11,38 @@ Usage (module):
import jc.parsers.crontab_u
result = jc.parsers.crontab_u.parse(crontab_u_output)
Schema:
{
"variables": [
"name": string,
"value": string
],
"schedule": [
{
"occurrence" string,
"minute": [
string
],
"hour": [
string
],
"day_of_month": [
string
],
"month": [
string
],
"day_of_week": [
string
],
"occurrence": string,
"user": string,
"command": string
}
]
}
Compatibility:
'linux', 'darwin', 'aix', 'freebsd'
@ -132,15 +164,14 @@ Examples:
}
]
}
"""
import jc.utils
import jc.parsers.universal
class info():
version = '1.5'
"""Provides parser metadata (version, author, etc.)"""
version = '1.6'
description = '`crontab` file parser with user support'
author = 'Kelly Brazil'
author_email = 'kellyjonbrazil@gmail.com'
@ -153,7 +184,7 @@ class info():
__version__ = info.version
def process(proc_data):
def _process(proc_data):
"""
Final processing to conform to the schema.
@ -163,38 +194,7 @@ def process(proc_data):
Returns:
Dictionary. Structured data with the following schema:
{
"variables": [
"name": string,
"value": string
],
"schedule": [
{
"occurrence" string,
"minute": [
string
],
"hour": [
string
],
"day_of_month": [
string
],
"month": [
string
],
"day_of_week": [
string
],
"occurrence": string,
"user": string,
"command": string
}
]
}
Dictionary. Structured data to conform to the schema.
"""
# put itmes in lists
try:
@ -279,4 +279,4 @@ def parse(data, raw=False, quiet=False):
if raw:
return raw_output
else:
return process(raw_output)
return _process(raw_output)

8
man/jc.1
View File

@ -385,7 +385,7 @@ debug - show traceback (\fB-dd\fP for verbose traceback)
.TP
.B
\fB-h\fP
help
help - use `-h --parser_name` for parser documentation
.TP
.B
\fB-m\fP
@ -450,6 +450,12 @@ or using the magic syntax:
jc \fB-p\fP ls \fB-al\fP
For parser documentation:
jc \fB-h\fP \fB--ls\fP
.SH AUTHOR
Kelly Brazil (kellyjonbrazil@gmail.com)

8
templates/manpage_template
View File

@ -40,7 +40,7 @@ debug - show traceback (\fB-dd\fP for verbose traceback)
.TP
.B
\fB-h\fP
help
help - use `-h --parser_name` for parser documentation
.TP
.B
\fB-m\fP
@ -105,6 +105,12 @@ or using the magic syntax:
jc \fB-p\fP ls \fB-al\fP
For parser documentation:
jc \fB-h\fP \fB--ls\fP
.SH AUTHOR
{{ jc.author }} ({{ jc.author_email }})

2
templates/readme_template
View File

@ -130,7 +130,7 @@ The JSON output can be compact (default) or pretty formatted with the `-p` optio
### Options
- `-a` about `jc`. Prints information about `jc` and the parsers (in JSON, of course!)
- `-d` debug mode. Prints trace messages if parsing issues are encountered (use `-dd` for verbose debugging)
- `-h` `jc` help
- `-h` `jc` help. Use `jc -h --parser_name` for parser documentation
- `-m` monochrome JSON output
- `-p` pretty format the JSON output
- `-q` quiet mode. Suppresses parser warning messages