apd-tui
A vim-like terminal UI for viewing and editing APD (product design) exported JSON.
Built with Textual. It renders the APD JSON as a navigable tree of relationships (nested objects / arrays) on the left, the selected node's scalar fields and child relationships on the right, and a live system shell on the far right.
This document describes only the
apd-tui/Python program. It does not cover the rest of thegwpc-cloud-accrepository.
AI disclaimer
This program and its documentation were generated and iteratively refined with the assistance of an AI coding agent (Tencent HY3). The code, behavior, and text above should be reviewed and tested by a human before being relied upon in production. No warranty, express or implied, is made regarding correctness, security, or fitness for any particular purpose.
Features
- Relationship-only tree — only nested
dict/listnodes are shown as tree nodes; scalar properties (uuid/code/name/type/sequence…) stay in the detail panel. Array items are labeled with their semantic field (name/code/uuid) rather than a raw index. The root node is labeled with the root object'sdescription(falls back toname/code/uuid, then the file name). - Two-section detail panel — scalar properties, then a
RELATIONSHIPSsection listing each child relationship with its item count; clicking a relationship row focuses the matching tree node. - Schema-aware fields — uses the
schema/ProductV10.schema.jsonyou supply via--schemato show declared-but-missing fields as(not provided)so the full field set of a level is always visible. The bundledschema/ProductV10.schema.jsonis the current/latest schema and matches the bundledpersonal-umbrella.sample.json. - Inline editing —
Enteron a field opens an inline editor; values are type-coerced (bool/int/float/None/str). Acategoryfield whose value matches a product-defined category code gets a dropdown; otherwise it is free text.uuidandsubtypeare read-only and cannot be edited. - Sequence reordering — editing the
sequenceof an item physically moves it within its parent array (1-based, bounded by1..N) and renumbers the siblings to1..N. - Delete / paste —
dddeletes the selected node (saved to a clipboard),ppastes it as a sibling below the selection with type-compatibility checks. - Undo / redo —
u/Ctrl+R, whole-document snapshots (unbounded stack). - Full-text search —
/opens a bottom search bar; matches across keys and scalar values;n/Ncycle through matches. - Vim-style panes —
h/lmove focus left/right across the three panes. - Live terminal pane — a real PTY running your
$SHELL, rendered withpyte. Off by default; turn it on withCtrl+Shift+T(orterminal onfrom the command palette /--terminal-on), off withCtrl+Shift+Y, toggle withCtrl+T, leave focus withCtrl+B. - Themes — bundled themes (catppuccin, everforest, apd_dark, apd_light), switchable at runtime and persisted across launches.
- Safe persistence — edits are written to a vim-style swap file
(
temp/<basename>.lock);Ctrl+S/:watomically overwrites the source file.F5reloads the source from disk. - Command palette —
:opens it (quit/help + dynamic theme commands).
Requirements
- Python 3 (developed on 3.14).
- Third-party packages (run inside the project's
.venv):textual(TUI framework)pyte(terminal emulator for the shell pane)
The virtual environment (
.venv) is not committed to the repository (it is gitignored). You must create it yourself the first time — the launchers below do this for you automatically.
Set up the environment (one time):
# From the project root (apd-tui/):
python3 -m venv .venv
.venv/bin/pip install "textual>=8.2.8" "pyte>=0.8.2"
# or, to install this package so the `apd-tui` console script is available:
.venv/bin/pip install -e .
Usage
macOS / Linux
Run the bundled launcher (creates the .venv if missing, then uses its Python
and passes through arguments):
cd apd-tui
# Open the in-repo sample file (runTest passes --file for you)
./runTest
# Or specify a file / theme explicitly — --file is required
./run --file /path/to/apd.json
./run --file apd.json --theme everforest
You can also invoke the entry module directly with the same .venv:
.venv/bin/python apd_viewer.py --file PATH --schema PATH [--theme NAME]
--file and --schema are both mandatory: launching without either prints the
usage (listing every available argument) and exits.
Windows (PowerShell)
Run run.ps1. It creates the .venv on first use (reusing it afterwards — no
need to activate manually) and forwards all arguments:
# From the project root (apd-tui/):
.\run.ps1 --file .\personal-umbrella.sample.json
.\run.ps1 --file apd.json --theme everforest
Note: the interactive terminal (shell) pane requires a Unix PTY and is unavailable on Windows. The tree and detail panes work fully; the terminal pane shows a placeholder instead of a live shell.
For local testing without installing, use the standalone test.ps1 /
testSample.ps1 launchers instead. They mirror the Unix run / runTest
scripts: they reuse an already-created .venv (and error out if it is
missing) rather than creating it. testSample.ps1 opens the bundled sample
automatically. Because PowerShell blocks local scripts by default, run them
with -ExecutionPolicy Bypass (or relax the policy once with
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned):
# From the project root (apd-tui/):
powershell -ExecutionPolicy Bypass -File .\testSample.ps1 # opens the bundled sample + schema
powershell -ExecutionPolicy Bypass -File .\testSample.ps1 --theme everforest
powershell -ExecutionPolicy Bypass -File .\test.ps1 --file apd.json --schema schema/ProductV10.schema.json
If the .venv does not exist yet, create it once:
py -m venv .venv
.\.venv\Scripts\pip install "textual>=8.2.8" "pyte>=0.8.2"
| Argument | Description |
|---|---|
--file PATH |
APD JSON file to load. Required — omitting it prints the usage and exits. |
--schema PATH |
APD product JSON schema file. Required — omitting it prints the usage and exits. |
--theme NAME |
Initial theme. Defaults to the last-used theme (or catppuccin). |
--terminal-on |
Start with the terminal pane visible. |
--terminal-off |
Start with the terminal pane hidden (default). Mutually exclusive with --terminal-on. |
Keyboard shortcuts
| Key | Action |
|---|---|
j / k |
Move selection down / up in the tree |
h / l |
Move focus left / right across panes (tree → detail → terminal) |
t |
Focus the terminal pane |
Ctrl+Shift+T |
Show the terminal pane (TerminalOn; default off on startup) |
Ctrl+Shift+Y |
Hide the terminal pane (TerminalOff) |
Ctrl+T |
Toggle the terminal pane visibility |
Enter |
Edit the selected detail field (inline editor) |
dd |
Delete the selected node (double-tap d; a lone d does nothing) |
p |
Paste the last-deleted node as a sibling below the selection |
u |
Undo |
Ctrl+R |
Redo |
F5 |
Reload the source file from disk |
Ctrl+S |
Save (write swap file over the source) |
/ |
Open the full-text search bar |
n / N |
Jump to next / previous search match (cycles) |
Esc |
Close the search bar (keeps results); cancel an inline edit |
: |
Open the command palette (quit / help / theme switching) |
q |
Quit |
Inside the terminal pane all keystrokes are forwarded verbatim to the shell.
Press Ctrl+B to return focus to the viewer.
Editing model & persistence
- Edits mutate the in-memory document and are flushed to a vim-style swap file
temp/<basename>.lockimmediately. Ctrl+S(or:wvia the command palette) atomically overwrites the original source file.F5re-reads the source file from disk (useful after editing it externally in the terminal pane).- Every edit (
dd,p, inline edit, sequence change) pushes a whole-document snapshot before mutating, enablingu/Ctrl+R. New edits clear the redo stack.
Read-only fields (uuid, subtype) are blocked both at the editor entry point
and at the write-back stage.
Themes
Themes live in the themes/ package — one module per theme exposing a THEME
instance. ThemeManager auto-discovers them, so adding a theme is just dropping
a new file.
The selected theme is persisted to ~/.config/apd-viewer/config.json and
reused on the next launch. A --theme argument overrides it for that run.
Architecture & design
Layout
Header
Horizontal
├── Tree #tree (25%) relationship-only structure
├── ScrollableContainer #detail (25%) └── DataTable #detail_table
└── TerminalPane #terminal (50%) live PTY shell (toggleable)
Footer
Panes use percentage widths (not fr) so the ratio stays exact on resize. When
the terminal is hidden the detail pane reclaims its width (tree 25% / detail 75%).
Data flow
--file → load_apd (normalizes U+00A0 NBSP → space) → _root_label (root description)
→ build_tree (recurse dict/list relationships only; each node .data stores
the Python object + cached _schema_fields / _schema_path_key)
→ Tree.NodeSelected → render_detail (scalar props + RELATIONSHIPS)
→ detail row click → tree.select_node (focus matching node)
Each tree node stores the actual Python object in .data, giving O(1) access on
selection without re-walking the JSON. A id(obj) → TreeNode map (_node_by_id)
resolves full-text search hits back to tree nodes.
Module structure
apd-tui/
├── apd_viewer.py # Entry point: args, theme resolution, config,
│ # import wiring, launch MainScreen.
├── config.py # User config (~/.config/apd-viewer/config.json):
│ # atomic theme persistence.
├── personal-umbrella.sample.json # Sample APD product (dev fixture; not packaged).
├── schema/ProductV10.schema.json # JSON schema used for field completion (NOT packaged; pass via --schema).
├── run / runTest # Unix launcher scripts (use project .venv).
├── run.ps1 # Windows (PowerShell) launcher (creates .venv if missing).
├── test.ps1 / testSample.ps1 # Windows local-test launchers (reuse existing .venv; do not install).
├── temp/ # Vim-style swap files (<basename>.lock); gitignored.
├── screen/
│ ├── main_screen.py # MainScreen: compose, tree/detail, editing,
│ │ # undo/redo, search, save/reload, terminal visibility.
│ ├── main_bindings.py # MAIN_BINDINGS: the vim key map (single source).
│ ├── main_css.py # MAIN_CSS: three-pane layout styles.
│ ├── shortcut_command.py # Command pattern: ShortcutCommand interface,
│ │ # CommandRegistry, one class per shortcut,
│ │ # build_registry(). Keeps MainScreen thin.
│ ├── shared.py # Tree/JSON helpers (load_apd, build_tree, labels,
│ │ # move_and_renumber, READONLY_FIELDS) and reusable
│ │ # widgets (HelpScreen, APDCommandProvider,
│ │ # EditInput, EditSelect, SpaceFriendlyInput).
│ └── terminal_pane.py # TerminalPane: PTY + pyte shell, key-to-bytes
│ # forwarding, resize, pause/resume, cleanup.
└── themes/
├── manager.py # ThemeManager: auto-discovers THEME modules.
├── __init__.py # Exposes CUSTOM_THEMES.
└── catppuccin.py / everforest.py / apd_dark.py / apd_light.py
Design decisions
- Command pattern for shortcuts — every binding action maps to a
ShortcutCommandinstance in aCommandRegistry;MainScreen.action_*methods are thin forwards (self._commands.dispatch(...)). Adding a key means adding a command class, not editing the screen, and the import graph stays strictly one-directional. - Relationship-only tree — scalars stay in the detail panel so a large APD
document (≈136 KB sample) stays navigable; node
.dataholds object identity for O(1) selection. - Whole-document undo snapshots — chosen over inverse-command or per-node
diffs because APD files are small and
deepcopyis cheap. After a restore the document object is brand new, so the cursor is re-located by JSON path (key/index chain), not object identity. - Real PTY terminal — a genuine interactive shell via
pty.fork()+pyte, with a background reader thread feeding the emulator and forwarding keys as raw bytes. Single-letter App bindings are re-declared as no-ops on the pane so the shell receives them verbatim (e.g. typingqmust not quit the viewer). - iTerm2 input robustness —
SpaceFriendlyInputrecovers punctuation/space keys delivered as keysyms (emptyevent.character) so inline editors work under iTerm2.
Publishing & installation
The program is packaged with pyproject.toml (setuptools build backend) so it
can be built into a wheel/sdist and installed with pip.
For users (install from an index)
pip install apd-tui
apd-tui --file /path/to/apd.json --schema /path/to/schema/ProductV10.schema.json
Neither the schema nor the sample document is bundled inside the wheel. The
schema drives field completion and the (not provided) field list and must be
supplied via the required --schema argument (it is not packaged, issue
#16). The sample document is a development fixture and is also not packaged,
so --file must always point at your own APD export; running apd-tui without
--file or --schema exits with a usage error.
From source (development / local use)
cd apd-tui
../.venv/bin/pip install -e . # editable install into the project venv
apd-tui --file personal-umbrella.sample.json --schema schema/ProductV10.schema.json
Building the distribution
Requires the build tooling (install once in any venv):
pip install build twine
python -m build # creates dist/*.whl and dist/*.tar.gz
twine check dist/* # sanity-check the artifacts
One-shot publish script
A publish.sh at the repo root wraps the whole release flow (pre-flight
checks → python -m build → twine check → interactive confirmation →
twine upload -r pypi). Your PyPI credentials must already be present in
~/.pypirc (a [pypi] section), per the official guide:
./publish.sh
The script aborts early (with a clear message) if build/twine are missing,
and asks for a y/N confirmation before any upload. It never deletes or
modifies pyproject.toml.
On Windows (PowerShell), use the equivalent publish.ps1. It mirrors the
Unix flow (auto-installs build/twine if missing, then builds, runs
twine check, asks for confirmation, and uploads via twine -r <repo>) and
reads credentials from the ~/.pypirc [<repo>] section — no token is
hard-coded in the script. PowerShell blocks local scripts by default, so run it
with -ExecutionPolicy Bypass:
powershell -ExecutionPolicy Bypass -File .\publish.ps1 # upload to 'pypi'
powershell -ExecutionPolicy Bypass -File .\publish.ps1 -Repo testpypi
Publishing to an index
-
Internal / private index (recommended here) — this project pins a custom
textual>=8.2.8build that may not exist on public PyPI:twine upload --repository-url http://<your-index>/simple/ dist/*
Users then install from that index:
pip install --index-url http://<your-index>/simple/ apd-tui
-
Public PyPI (only if your
textualis the public release):twine upload -r pypi dist/* # needs a PyPI account + API token
Dependency notes
textualis pinned to>=8.2.8andpyteto>=0.8.2, matching the versions this was developed and tested against. If yourtextualis an internal build, publish and install through the internal index above.- Requires Python 3.10+.
- The
apd-tuiconsole script maps toapd_viewer:main.
Notes
- The program does not modify the sample JSON or the schema file you pass via
--schema. temp/is gitignored; swap files are scratch working copies of unsaved edits.- Parse errors (missing file / invalid JSON) surface as a
notifyerror rather than crashing.
Metadata
Release files for apd-viewer-tui 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| apd_viewer_tui-0.1.0.tar.gz | 42.9 kB | Without provenance | Details for apd_viewer_tui-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| apd_viewer_tui-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for apd_viewer_tui-0.1.0-py3-none-any.whl |
Total release size: 90.9 kB
Release files / apd_viewer_tui-0.1.0.tar.gz
| Download URL | apd_viewer_tui-0.1.0.tar.gz |
|---|---|
| Size | 42.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0f0fdd7c16fe11b321d1a6ea7d51bb13ffd3e90681a9a177c55468bb83e5a281
|
|
BLAKE2b-256 checksum How to use checksums |
3688fe3a46f1231926d94743a63431efbfbaf1fdf8716071922eaffd3f4692b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / apd_viewer_tui-0.1.0-py3-none-any.whl
| Download URL | apd_viewer_tui-0.1.0-py3-none-any.whl |
|---|---|
| Size | 48.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1421bd5fce967e38ce2423139d9c3ab758aee546f3e43c381fd46b7df5ae152b
|
|
BLAKE2b-256 checksum How to use checksums |
cad6608e39192d232fb9856c5796f645073603d21d14188c9f08d54317e9e3f9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for apd-viewer-tui 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.