226 lines
9.9 KiB
Plaintext
226 lines
9.9 KiB
Plaintext
Metadata-Version: 2.1
|
|
Name: python-fx
|
|
Version: 0.3.1
|
|
Summary: A python-native fx-alike terminal JSON viewer.
|
|
Author-email: Yutian Wu <yutianwu@umich.edu>
|
|
License: MIT
|
|
Project-URL: repository, https://github.com/cielong/pyfx
|
|
Keywords: fx,pyfx,json viewer,tui
|
|
Classifier: Development Status :: 4 - Beta
|
|
Classifier: Programming Language :: Python :: 3 :: Only
|
|
Classifier: Environment :: Console
|
|
Classifier: Operating System :: POSIX
|
|
Classifier: Operating System :: MacOS :: MacOS X
|
|
Classifier: License :: OSI Approved :: MIT License
|
|
Classifier: Topic :: Utilities
|
|
Requires-Python: >=3.8
|
|
Description-Content-Type: text/markdown
|
|
License-File: LICENSE.txt
|
|
Requires-Dist: antlr4-python3-runtime ==4.8
|
|
Requires-Dist: asciimatics ==1.14.0
|
|
Requires-Dist: first ==2.0.2
|
|
Requires-Dist: jsonpath-ng ==1.6.0
|
|
Requires-Dist: ply ==3.11
|
|
Requires-Dist: pyperclip ==1.8.2
|
|
Requires-Dist: wcwidth ==0.2.6
|
|
Requires-Dist: urwid ==2.2.1 ; python_full_version >= "3.7.0"
|
|
Requires-Dist: future ==0.18.3 ; python_version >= "2.6" and python_version not in "3.0, 3.1, 3.2, 3.3"
|
|
Requires-Dist: loguru ==0.7.2 ; python_version >= "3.5"
|
|
Requires-Dist: dacite ==1.8.1 ; python_version >= "3.6"
|
|
Requires-Dist: overrides ==7.4.0 ; python_version >= "3.6"
|
|
Requires-Dist: pyyaml ==6.0.1 ; python_version >= "3.6"
|
|
Requires-Dist: yamale ==4.0.4 ; python_version >= "3.6"
|
|
Requires-Dist: click ==8.1.7 ; python_version >= "3.7"
|
|
Requires-Dist: pillow ==10.0.1 ; python_version >= "3.8"
|
|
Requires-Dist: pyfiglet ==0.8.post1 ; python_version >= "3.9"
|
|
|
|
# Pyfx
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A python-native JSON Viewer TUI, inspired by [fx](https://github.com/antonmedv/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](#prerequisites)
|
|
* [Installation](#installation)
|
|
* [PIP](#pip)
|
|
* [Build from Source](#build-from-source)
|
|
* [Quick Start](#quick-start)
|
|
* [CLI](#cli)
|
|
* [Python Module](#python-module)
|
|
* [Configuration](#configuration)
|
|
* [Default Configuration](#default-configuration)
|
|
* [License](#license)
|
|
* [Changelog](#changelog)
|
|
* [How to Contribute](#how-to-contribute)
|
|
|
|
## Prerequisites
|
|
* OS: MacOS / Linux
|
|
* python: >= 3.8
|
|
* pip
|
|
|
|
## Installation
|
|
### Pip
|
|
```bash
|
|
pip install python-fx
|
|
```
|
|
### Build from Source
|
|
Clone the this [repo](https://github.com/cielong/pyfx.git), change directory into the project and run
|
|
```bash
|
|
pip install -U autopep8 tox build
|
|
make install
|
|
```
|
|
### Local Development
|
|
Clone the this [repo](https://github.com/cielong/pyfx.git), change directory into the project and run
|
|
```bash
|
|
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](https://python-fx.readthedocs.io/en/latest/).
|
|
### CLI
|
|
Check [Key Bindings](#key-bindings) section for default key bindings.
|
|
*Pyfx* comes with a CLI, use it
|
|
* To open a JSON file
|
|
```bash
|
|
pyfx JSON_FILE
|
|
```
|
|
* To read JSON data from pipe
|
|
```bash
|
|
cat JSON_FILE | pyfx
|
|
```
|
|
* To read JSON data from clipboard
|
|
```bash
|
|
pyfx -x / --from-clipboard
|
|
```
|
|
|
|
### Python Module
|
|
Check [Key Bindings](#key-bindings) section for default key bindings.
|
|
|
|
#### Directly Attach *Pyfx* Simple TUI
|
|
Directly integrate *Pyfx*'s TUI into your own project.
|
|
```python
|
|
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.
|
|
```python
|
|
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](src/pyfx/config/yaml/config.yml)
|
|
|
|
For available configuration, see [configuration](https://python-fx.readthedocs.io/en/latest/configuration/index.html).
|
|
|
|
### Default Configuration
|
|
#### Theme
|
|
Alternative key bindings, see [Theme Configuration](https://python-fx.readthedocs.io/en/latest/configuration/theme.html).
|
|
|
|
| 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](https://python-fx.readthedocs.io/en/latest/configuration/keymap.html).
|
|
|
|
| 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](LICENSE.txt).
|
|
|
|
## Changelog
|
|
See the [changelog](CHANGELOG.md) for a history of notable changes to *Pyfx*.
|
|
|
|
## Contributors
|
|
[Avery (@nullableVoidPtr)](https://github.com/nullableVoidPtr)
|
|
[Zephyr Lykos (@mochaaP)](https://github.com/mochaaP)
|
|
|
|
## How to Contribute
|
|
If you run into any issues, please let me know by creating a GitHub issue.
|