python-fx

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

• Prerequisite
• Installation
  • PIP
  • Build from Source
• Quick Start
  • CLI
  • Python Module
• Configuration
  • Default Configuration
• License
• Changelog
• How to Contribute

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

1. Download and install the latest ANTLR v4

• It is required that ANTLR version installed matches the version of the Python ANTLR runtime version.

1. 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.
  1. ~/.config/pyfx/config.yml
  2. 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.