A python-native JSON Viewer TUI, inspired by fx.
Pyfx supports:
- Read JSON files in terminal from several sources (file, pipe or clipboard).
- Query JSON files using JSONPath query.
- OS: MacOS / Linux
- python: >= 3.8
- pip
pip install python-fx
Clone the this repo, change directory into the project and run
pip install -U autopep8 tox build
make install
- Download and install the latest ANTLR v4
- It is required that ANTLR version installed matches the version of the Python ANTLR runtime version.
- Clone the this repo, change directory into the project and run
pip install -U pipenv
pipenv install --dev
You can use Pyfx in two ways:
- A standalone CLI tool
- A python module which can be integrated in any python CLI application
For details, please check the hosted documentation.
Check Key Bindings section for default key bindings.
Pyfx comes with a CLI, use it
- To open a JSON file
pyfx JSON_FILE
- To read JSON data from pipe
cat JSON_FILE | pyfx
- To read JSON data from clipboard
pyfx -x / --from-clipboard
Check Key Bindings section for default key bindings.
Directly integrate Pyfx's TUI into your own project.
from pyfx import PyfxApp
data = [1]
# data is the JSON data to be rendered in the TUI
PyfxApp(data=data).run()
Integrate Pyfx native JSON widgets into your own urwid-based TUI.
from pyfx.view.json_lib import JSONListBox, JSONListWalker
data = [1]
# 1. create JSONListBox from data
listbox = JSONListBox(JSONListWalker(data))
# 2. use listbox in your own TUI
Pyfx is configured using YAML. There are two ways to provide a configuration file:
- Pass directly through CLI option (
-c
|--config
). - Create a config file in predefined folders and Pyfx will load it with best effort.
The predefined folders are searched in following order, with the first exist one has high priority.~/.config/pyfx/config.yml
src/pyfx/config/yaml/config.yml
default config
For available configuration, see configuration.
Alternative key bindings, see Theme Configuration.
Name | Description | Foreground Color |
---|---|---|
body | Pyfx body (JSON Browser) | terminal default |
foot | Pyfx footer (Query Bar and Help Bar) | gray |
focused | focused display | gray |
Auto Complete PopUp | ||
autocomplete_popup | autocomplete popup | black |
autocomplete_popup_focused | focused display for autocomplete popup | white |
JSON Browser | ||
json_key | object key | blue |
json_string | string type value | green |
json_integer | integer type value | cyan |
json_numeric | numeric type value | cyan |
json_bool | boolean type value | yellow |
json_null | null type value | red |
json_focused | focused display for JSON | gray |
Alternative key bindings, see Key Bindings Configuration.
Key | Function |
---|---|
q | exit pyfx (except in Query Bar) |
? | open help page (except in Query Bar) |
JSON Browser | |
up | move cursor up one line |
down | move cursor down one line |
e | expand all |
c | collapse all |
enter | toggle expansion |
. | enter query window (used to input JSONPath query) |
Query Bar | |
enter | apply JSONPath query and switch to JSON Browser |
esc | cancel query and restore to state before query |
Autocomplete PopUp | |
up | move cursor up one line |
down | move cursor down one line |
enter | select option and complete the query |
esc | close pop up |
Help PopUp | |
up | move cursor up one line |
down | move cursor down one line |
esc | close the help popup |
When open with very large JSON files, Pyfx will freeze on JSONPath query.
The following statistics is tested at a MacBook Air (1.1GHz Quad-Core Intel Core i5 and 8GB RAM).
File Size | Functionality | Usability |
---|---|---|
57MB | Display JSON | Fairly good |
^^ | Query Autocomplete | Latency <= 200ms |
^^ | Query JSONPath | Roughly 1~2s latency |
570MB | Display JSON | Slow loading |
^^ | Query Autocomplete | Latency <= 200ms. Give up with large data |
^^ | Query JSONPath | UI may freeze depend on the search space |
The code is under The MIT License.
See the changelog for a history of notable changes to Pyfx.
Avery (@nullableVoidPtr)
Zephyr Lykos (@mochaaP)
@jcaesar
If you run into any issues, please let me know by creating a GitHub issue.