A python-native fx-alike terminal JSON viewer.
Project description
Pyfx
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.
Table of Content
Prerequisites
- OS: MacOS / Linux
- python: >= 3.8
- pip
Installation
Pip
pip install python-fx
Build from Source
Clone the this repo, change directory into the project and run
pip install -U autopep8 tox build
make install
Local Development
- 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
Quick Start
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.
CLI
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
Python Module
Check Key Bindings section for default key bindings.
Directly Attach Pyfx Simple TUI
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 with Your Own Urwid-based TUI
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
Configuration
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.
Default Configuration
Theme
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 |
Key Bindings
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 |
Known Limitation
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 |
License
The code is under The MIT License.
Changelog
See the changelog for a history of notable changes to Pyfx.
Contributors
Avery (@nullableVoidPtr)
Zephyr Lykos (@mochaaP)
@jcaesar
How to Contribute
If you run into any issues, please let me know by creating a GitHub issue.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file python_fx-0.3.2.tar.gz
.
File metadata
- Download URL: python_fx-0.3.2.tar.gz
- Upload date:
- Size: 1.3 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.11.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9646f58c716e2db6698bff3dfa55fa721b8b0cb741506287a87bc08055a96ceb |
|
MD5 | 011c942481d1bf652feca74dcd175477 |
|
BLAKE2b-256 | ff0bbb181b8c9dc640400dd8e3c82f41f77296f8eb167a8437d8ecf67a11ddff |
File details
Details for the file python_fx-0.3.2-py3-none-any.whl
.
File metadata
- Download URL: python_fx-0.3.2-py3-none-any.whl
- Upload date:
- Size: 74.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.11.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5498475b0f391b1649732328b58d188d9fc4b3f90f5bfb77d5c6e2ece2432c5f |
|
MD5 | 672d13faeabd4eca7dd3b47a8cc5c47e |
|
BLAKE2b-256 | da5acb5b224d4934c3ca0c036ccba5925628b720fccee7e6dae28f4b7eca1397 |