$ show tmux-python/tmuxp
tmuxp is a CLI tool and Python library for managing tmux sessions declaratively. It loads, freezes, converts, and imports workspace configurations in YAML or JSON formats, enabling reproducible tmux environments. The architecture follows a layered design: configuration files are parsed by a custom config reader, expanded with environment variables and shorthand forms, then processed through a `trickle` function that propagates defaults across session/window/pane hierarchy. A workspace builder (default is `ClassicWorkspaceBuilder`) translates the expanded config into tmux commands via the libtmux library, creating sessions, windows, panes, and executing shell commands. A plugin system allows custom workspace builders and lifecycle hooks (`before_workspace_builder`, `on_window_create`, `after_window_finished`, `before_script`, `reattach`). The CLI supports subcommands (load, freeze, convert, import, edit, ls, search, shell, debug-info) with structured output modes (human, JSON, NDJSON), semantic color support, and a thread-based progress spinner. External dependencies are minimal: Python ≥3.10, tmux ≥3.2, and libtmux ≈0.61.0. The codebase demonstrates strong engineering practices with extensive integration tests against multiple tmux versions, Sphinx documentation, and a well-defined plugin contract.
The LLM identified 4 files worth highlighting for reuse:
Provides a `Colors` class with semantic methods (`success`, `error`, `info`, `muted`, `highlight`) that output ANSI escape sequences. Automatically disables colors when `NO_COLOR` is set or terminal is non-TTY. Supports `FORCE_COLOR` override. Also includes a `style()` function for inline styling and a `build_description` helper. This module is self-contained (stdlib only) and could be extracted into a standalone library for consistent CLI color handling.
Exposes `PrivatePath` class that wraps `pathlib.Path` and masks the user's home directory with `~` when converted to a string. The module-level function `collapse_home_in_string` applies the same masking to arbitrary strings containing paths. This is a clean, reusable utility for any CLI tool that displays file paths to users and wants to avoid leaking absolute home directories. No external dependencies.
Implements `OutputFormatter` abstract base class and its concrete subclasses for human-readable, JSON, and NDJSON output modes. The `emit`/`emit_text`/`finalize` pattern provides a consistent interface for mixed output in CLI tools. The design allows switching output mode via a single parameter (`output_mode` enum). Reusable in any Python CLI that needs to support both human and machine-readable output; the code is small, well-typed, and does not depend on tmux or any heavy framework.
Provides two classes: `Spinner` (a thread-based animated spinner with configurable format strings) and `BuildTree` (an event-based renderer that tracks state of session/window/pane builds and displays a tree). The module uses only stdlib (`threading`, `collections`, `re`) and ANSI escape sequences for cursor control. It supports ~20 format tokens, presets, and a fallback map for missing tokens. This is a reusable progress visualization component for any CLI tool with multi-step processes; it handles TTY detection and synchronization gracefully.