Skip to main content

A python-native fx-alike terminal JSON viewer.

Project description

Pyfx

Build Status Documentation Status PyPI version Python Python Python Python GitHub codecov

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

  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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_fx-0.3.2.tar.gz (1.3 MB view details)

Uploaded Source

Built Distribution

python_fx-0.3.2-py3-none-any.whl (74.3 kB view details)

Uploaded Python 3

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

Hashes for python_fx-0.3.2.tar.gz
Algorithm Hash digest
SHA256 9646f58c716e2db6698bff3dfa55fa721b8b0cb741506287a87bc08055a96ceb
MD5 011c942481d1bf652feca74dcd175477
BLAKE2b-256 ff0bbb181b8c9dc640400dd8e3c82f41f77296f8eb167a8437d8ecf67a11ddff

See more details on using hashes here.

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

Hashes for python_fx-0.3.2-py3-none-any.whl
Algorithm Hash digest
SHA256 5498475b0f391b1649732328b58d188d9fc4b3f90f5bfb77d5c6e2ece2432c5f
MD5 672d13faeabd4eca7dd3b47a8cc5c47e
BLAKE2b-256 da5acb5b224d4934c3ca0c036ccba5925628b720fccee7e6dae28f4b7eca1397

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page