Metadata-Version: 2.5
Name: PBKittyConfigStudio
Version: 0.1.0
Summary: A desktop GUI for configuring the kitty terminal
Project-URL: Homepage, https://github.com/kovidgoyal/kitty
Author-email: Marcel Spock <mrspock@cardolan.net>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: config,gui,kitty,qt,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: pyside6>=6.6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-qt>=4; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# PBKittyConfigStudio

[![Release](https://img.shields.io/github/v/release/ppoilbarbe/PBKittyConfigStudio)](https://github.com/ppoilbarbe/PBKittyConfigStudio/releases/latest)
[![CI](https://github.com/ppoilbarbe/PBKittyConfigStudio/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ppoilbarbe/PBKittyConfigStudio/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/ppoilbarbe/PBKittyConfigStudio/branch/main/graph/badge.svg)](https://codecov.io/gh/ppoilbarbe/PBKittyConfigStudio)
[![PyPI](https://img.shields.io/pypi/v/pbkittyconfigstudio)](https://pypi.org/project/pbkittyconfigstudio/)

Although [kitty](https://github.com/kovidgoyal/kitty) is a keyboard-driven
terminal for power users that also fully supports the mouse, editing its
configuration file can be a chore: knowing the options, their possible
values, their defaults... you need the documentation open in front of you.

This program is a graphical interface for configuring the
[kitty](https://github.com/kovidgoyal/kitty) terminal. It covers a broad
set of kitty's configuration options, pulled directly from
[kitty](https://github.com/kovidgoyal/kitty)'s own source (see
[CODING.md](CODING.md) for how).

Built with Python and PySide6 (Qt6), the app needs nothing else.

## Features

- **~237 settings** across 12 categories, mirroring kitty's own grouping:
  fonts, cursor, scrollback, mouse, performance, terminal bell, window
  layout, tab bar, color scheme (including the 16 ANSI colors and mark
  colors), advanced, OS-specific tweaks, and the non-mapping keyboard
  shortcut settings.
- **Real widgets for real values** — color pickers, spin boxes, toggle
  switches, dropdowns, a font picker built on Qt's own font database (no
  shelling out to `fc-list`), and a list editor for repeatable settings
  such as `font_features`/`modify_font`.
- **Search** — a search box above the sidebar filters settings by name or
  label across every category.
- **Default vs. modified at a glance** — every row is badged "default" or
  "modified" against kitty's own default value.
- **Non-destructive** — every save writes a timestamped backup
  (`kitty.conf.bak_<date>`) first, and rewrites existing lines (including
  commented-out ones) in place with a targeted regex, leaving comments and
  everything else in the file untouched. A value equal to its default is
  written back as a commented-out line, documenting it without forcing it.
- **Hot reload** — best-effort `SIGUSR1` to running kitty instances after a
  save.
- **Restore default configuration** — regenerates kitty's own pristine,
  fully-commented example `kitty.conf` (via a throwaway `kitty` instance)
  and overwrites the current file, behind a confirmation dialog and the
  usual timestamped backup.
- **Translated UI** — English and French out of the box (see
  [Development](#development) to add a language).
- **Stays in sync with kitty** — the settings schema is generated straight
  from kitty's own option definitions rather than hand-maintained; see
  [CODING.md](CODING.md) for the full pipeline.

## Requirements

- Python 3.12+
- [kitty](https://github.com/kovidgoyal/kitty) terminal
- [pixi](https://pixi.sh) (recommended) to manage the development environment

## Quick Start

```bash
make venv   # create the pixi environment (installs pixi if missing)
make run    # launch PBKittyConfigStudio
```

Or, without pixi, in any Python 3.12+ environment:

```bash
pip install -e .
python -m pb_kitty_config_studio
```

## Development

This project uses [pixi](https://pixi.sh) for environment management and a
`Makefile` for all common tasks — see `make help` for the full list.

```bash
make venv      # create/update the pixi environment
make install   # editable install + pre-commit hooks
make test      # run the test suite
make lint      # ruff check + format --check
make format    # ruff format + check --fix
```

See [CODING.md](CODING.md) for the architecture, the schema generation/
curation pipeline, and the i18n extraction details — start there before
adding or changing a setting.

### Translations

Strings are managed with [pybabel](https://babel.pocoo.org/) (never
`xgettext`/`msgfmt` directly).

```bash
make translate                  # extract strings, update & compile .po/.mo
make new-lang LOCALE=de         # scaffold a new language
python tools/po_check.py        # translation stats / search untranslated entries
```

### Packaging

```bash
make dist      # standalone PyInstaller executable → dist/
make srcdist   # source archive (git archive) → dist/
```

The PyInstaller build embeds the OS-level app icon (`.ico` on Windows,
`.icns` in the macOS `.app` bundle). Icons are sourced from the `PBIcons`
project; sync them with:

```bash
make update-icons
```

## License

GNU General Public License v3.0 or later — see [LICENSE](LICENSE).

## Credits

- **Kovid Goyal and the kitty development team** — many thanks for building
  and maintaining the [kitty](https://github.com/kovidgoyal/kitty) terminal
  this app configures.

## Author

Marcel Spock <mrspock@cardolan.net>
PBMou

PBMou is a cross-language pun: "PB" stands for "Poilbarbe", and "Mou" is the
French translation of "Soft" — so PBMou reads like "PBSoft" half-translated
into French.
