# 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
1. Download and install the latest [ANTLR v4](https://www.antlr.org/)
* It is required that ANTLR version installed matches the version of the Python ANTLR runtime version.
2. 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)
[@jcaesar](https://github.com/jcaesar)
## How to Contribute
If you run into any issues, please let me know by creating a GitHub issue.
Raw data
{
"_id": null,
"home_page": null,
"name": "python-fx",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "fx, pyfx, json viewer, tui",
"author": null,
"author_email": "Yutian Wu <yutianwu@umich.edu>",
"download_url": "https://files.pythonhosted.org/packages/ff/0b/bb181b8c9dc640400dd8e3c82f41f77296f8eb167a8437d8ecf67a11ddff/python_fx-0.3.2.tar.gz",
"platform": null,
"description": "# Pyfx\n\n\n\n\n\n\n\n\n\n\nA python-native JSON Viewer TUI, inspired by [fx](https://github.com/antonmedv/fx). \n*Pyfx* supports:\n* Read JSON files in terminal from several sources (file, pipe or clipboard).\n* Query JSON files using JSONPath query.\n\n\n\n## Table of Content\n\n* [Prerequisite](#prerequisites)\n* [Installation](#installation)\n * [PIP](#pip)\n * [Build from Source](#build-from-source)\n* [Quick Start](#quick-start)\n * [CLI](#cli)\n * [Python Module](#python-module)\n* [Configuration](#configuration)\n * [Default Configuration](#default-configuration)\n* [License](#license)\n* [Changelog](#changelog)\n* [How to Contribute](#how-to-contribute)\n\n## Prerequisites\n* OS: MacOS / Linux\n* python: >= 3.8\n* pip\n\n## Installation\n### Pip\n```bash\npip install python-fx\n```\n### Build from Source\nClone the this [repo](https://github.com/cielong/pyfx.git), change directory into the project and run\n```bash\npip install -U autopep8 tox build\nmake install\n```\n### Local Development\n1. Download and install the latest [ANTLR v4](https://www.antlr.org/)\n\n* It is required that ANTLR version installed matches the version of the Python ANTLR runtime version. \n\n2. Clone the this [repo](https://github.com/cielong/pyfx.git), change directory into the project and run\n```bash\npip install -U pipenv\npipenv install --dev\n```\n\n## Quick Start\nYou can use *Pyfx* in two ways:\n* A standalone CLI tool\n* A python module which can be integrated in any python CLI application\n\nFor details, please check the hosted [documentation](https://python-fx.readthedocs.io/en/latest/).\n### CLI\nCheck [Key Bindings](#key-bindings) section for default key bindings. \n*Pyfx* comes with a CLI, use it\n* To open a JSON file\n ```bash\n pyfx JSON_FILE\n ```\n* To read JSON data from pipe\n ```bash\n cat JSON_FILE | pyfx\n ```\n* To read JSON data from clipboard\n ```bash\n pyfx -x / --from-clipboard\n ```\n\n### Python Module\nCheck [Key Bindings](#key-bindings) section for default key bindings.\n \n#### Directly Attach *Pyfx* Simple TUI\nDirectly integrate *Pyfx*'s TUI into your own project. \n```python\nfrom pyfx import PyfxApp\n\ndata = [1]\n# data is the JSON data to be rendered in the TUI\nPyfxApp(data=data).run()\n```\n\n#### Integrate with Your Own Urwid-based TUI\nIntegrate *Pyfx* native JSON widgets into your own urwid-based TUI.\n```python\nfrom pyfx.view.json_lib import JSONListBox, JSONListWalker\n\ndata = [1]\n\n# 1. create JSONListBox from data\nlistbox = JSONListBox(JSONListWalker(data))\n\n# 2. use listbox in your own TUI\n```\n\n## Configuration\n*Pyfx* is configured using YAML. There are two ways to provide a configuration file: \n* Pass directly through CLI option (`-c` | `--config`).\n* Create a config file in predefined folders and *Pyfx* will load it with best effort. \n The predefined folders are searched in following order, with the first exist one has high priority. \n 1. `~/.config/pyfx/config.yml`\n 2. `src/pyfx/config/yaml/config.yml` [default config](src/pyfx/config/yaml/config.yml)\n\nFor available configuration, see [configuration](https://python-fx.readthedocs.io/en/latest/configuration/index.html).\n\n### Default Configuration\n#### Theme\nAlternative key bindings, see [Theme Configuration](https://python-fx.readthedocs.io/en/latest/configuration/theme.html). \n\n| Name | Description | Foreground Color |\n|-------------------------------|--------------------------------------------------------|--------------------|\n| body | Pyfx body (JSON Browser) | terminal default |\n| foot | Pyfx footer (Query Bar and Help Bar) | gray |\n| focused | focused display | gray |\n| **Auto Complete PopUp** |\n| autocomplete_popup | autocomplete popup | black |\n| autocomplete_popup_focused | focused display for autocomplete popup | white |\n| **JSON Browser** |\n| json_key | object key | blue |\n| json_string | *string* type value | green |\n| json_integer | *integer* type value | cyan |\n| json_numeric | *numeric* type value | cyan |\n| json_bool | *boolean* type value | yellow |\n| json_null | *null* type value | red |\n| json_focused | focused display for JSON | gray |\n\n#### Key Bindings\nAlternative key bindings, see [Key Bindings Configuration](https://python-fx.readthedocs.io/en/latest/configuration/keymap.html). \n\n| Key | Function |\n|------------------|---------------------------------------------------|\n| q | exit pyfx (except in Query Bar) |\n| ? | open help page (except in Query Bar) |\n| **JSON Browser** |\n| up | move cursor up one line |\n| down | move cursor down one line |\n| e | expand all |\n| c | collapse all |\n| enter | toggle expansion |\n| . | enter query window (used to input JSONPath query) |\n| **Query Bar** |\n| enter | apply JSONPath query and switch to JSON Browser |\n| esc | cancel query and restore to state before query |\n| **Autocomplete PopUp** |\n| up | move cursor up one line |\n| down | move cursor down one line |\n| enter | select option and complete the query |\n| esc | close pop up |\n| **Help PopUp** |\n| up | move cursor up one line |\n| down | move cursor down one line |\n| esc | close the help popup |\n\n## Known Limitation\nWhen open with very large JSON files, Pyfx will freeze on JSONPath query. \n\nThe following statistics is tested at a MacBook Air (1.1GHz Quad-Core Intel Core i5\nand 8GB RAM).\n\n| File Size | Functionality | Usability |\n|------------------|---------------------|----------------------------------------------|\n| 57MB | Display JSON | Fairly good |\n| ^^ | Query Autocomplete | Latency <= 200ms |\n| ^^ | Query JSONPath | Roughly 1~2s latency |\n| 570MB | Display JSON | Slow loading |\n| ^^ | Query Autocomplete | Latency <= 200ms. Give up with large data |\n| ^^ | Query JSONPath | UI may freeze depend on the search space |\n\n## License\nThe code is under [The MIT License](LICENSE.txt).\n\n## Changelog\nSee the [changelog](CHANGELOG.md) for a history of notable changes to *Pyfx*.\n\n## Contributors\n[Avery (@nullableVoidPtr)](https://github.com/nullableVoidPtr) \n[Zephyr Lykos (@mochaaP)](https://github.com/mochaaP) \n[@jcaesar](https://github.com/jcaesar) \n\n## How to Contribute\nIf you run into any issues, please let me know by creating a GitHub issue.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A python-native fx-alike terminal JSON viewer.",
"version": "0.3.2",
"project_urls": {
"repository": "https://github.com/cielong/pyfx"
},
"split_keywords": [
"fx",
" pyfx",
" json viewer",
" tui"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "da5acb5b224d4934c3ca0c036ccba5925628b720fccee7e6dae28f4b7eca1397",
"md5": "672d13faeabd4eca7dd3b47a8cc5c47e",
"sha256": "5498475b0f391b1649732328b58d188d9fc4b3f90f5bfb77d5c6e2ece2432c5f"
},
"downloads": -1,
"filename": "python_fx-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "672d13faeabd4eca7dd3b47a8cc5c47e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 74300,
"upload_time": "2024-08-12T18:39:48",
"upload_time_iso_8601": "2024-08-12T18:39:48.423822Z",
"url": "https://files.pythonhosted.org/packages/da/5a/cb5b224d4934c3ca0c036ccba5925628b720fccee7e6dae28f4b7eca1397/python_fx-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ff0bbb181b8c9dc640400dd8e3c82f41f77296f8eb167a8437d8ecf67a11ddff",
"md5": "011c942481d1bf652feca74dcd175477",
"sha256": "9646f58c716e2db6698bff3dfa55fa721b8b0cb741506287a87bc08055a96ceb"
},
"downloads": -1,
"filename": "python_fx-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "011c942481d1bf652feca74dcd175477",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1342667,
"upload_time": "2024-08-12T18:39:50",
"upload_time_iso_8601": "2024-08-12T18:39:50.877921Z",
"url": "https://files.pythonhosted.org/packages/ff/0b/bb181b8c9dc640400dd8e3c82f41f77296f8eb167a8437d8ecf67a11ddff/python_fx-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-12 18:39:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cielong",
"github_project": "pyfx",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "antlr4-python3-runtime",
"specs": [
[
"==",
"4.13.2"
]
]
},
{
"name": "asciimatics",
"specs": [
[
"==",
"1.15.0"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "dacite",
"specs": [
[
"==",
"1.8.1"
]
]
},
{
"name": "first",
"specs": [
[
"==",
"2.0.2"
]
]
},
{
"name": "jsonpath-ng",
"specs": [
[
"==",
"1.6.1"
]
]
},
{
"name": "loguru",
"specs": [
[
"==",
"0.7.2"
]
]
},
{
"name": "overrides",
"specs": [
[
"==",
"7.7.0"
]
]
},
{
"name": "pillow",
"specs": [
[
"==",
"10.4.0"
]
]
},
{
"name": "ply",
"specs": [
[
"==",
"3.11"
]
]
},
{
"name": "pyfiglet",
"specs": [
[
"==",
"1.0.2"
]
]
},
{
"name": "pyperclip",
"specs": [
[
"==",
"1.9.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.12.2"
]
]
},
{
"name": "urwid",
"specs": [
[
"==",
"2.6.15"
]
]
},
{
"name": "wcwidth",
"specs": [
[
"==",
"0.2.13"
]
]
},
{
"name": "yamale",
"specs": [
[
"==",
"5.2.1"
]
]
}
],
"tox": true,
"lcname": "python-fx"
}
JSON
