Metadata-Version: 2.4
Name: linux-im-diagnose
Version: 0.1.0
Summary: Diagnose input method (Fcitx/IBus) framework status for Linux applications
Project-URL: Homepage, https://github.com/cliecy/linux-im-diagnose
Project-URL: Issues, https://github.com/cliecy/linux-im-diagnose/issues
Author-email: cliecy <guanjiezou@gmail.com>
License: MIT
License-File: LICENSE
Keywords: diagnose,electron,fcitx,gtk,ibus,input-method,linux,qt
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Provides-Extra: all
Requires-Dist: psutil>=5.9; extra == 'all'
Description-Content-Type: text/markdown

# im-diagnose

Diagnose input method (Fcitx/IBus) framework status for Linux applications.

Inspects running processes via `/proc` to detect their UI framework (GTK3, GTK4, Qt5, Qt6, Electron), window system (X11, XWayland, Wayland), and whether the correct input method module is actually loaded.

## Why?

Chinese/Japanese/Korean input on Linux is fragile. A common problem: you set `GTK_IM_MODULE=fcitx`, but an application silently loads IBus instead (or loads nothing). This tool tells you exactly what each application is doing at runtime.

## Quick Start

```bash
# Inspect a specific process
python3 im_diagnose.py --pid $(pgrep -f firefox)

# Click a window to inspect (X11/XWayland)
python3 im_diagnose.py --click

# Scan all GUI processes (requires psutil)
python3 im_diagnose.py --all-gui

# Search by name (requires psutil)
python3 im_diagnose.py --search telegram
```

## Installation

**From PyPI (recommended):**

```bash
# Basic install (--click and --pid work without extra dependencies)
pip install linux-im-diagnose

# With psutil for --search and --all-gui modes
pip install linux-im-diagnose[all]

# Or use pipx for isolated install
pipx install linux-im-diagnose[all]

# Or use uv
uv tool install linux-im-diagnose[all]
```

Then run: `linux-im-diagnose --help`

**Standalone (single file, no install):**

```bash
curl -O https://raw.githubusercontent.com/cliecy/linux-im-diagnose/main/im_diagnose.py
chmod +x im_diagnose.py
python3 im_diagnose.py --pid 12345
```

## Usage

```
usage: im_diagnose.py [--click | --pid PID | --search NAME | --all-gui]
                      [--json] [-v] [--no-color] [--version]

Options:
  --click          Click a window to inspect (X11/XWayland)
  --pid PID        Inspect a specific PID
  --search NAME    Fuzzy search by process name (requires psutil)
  --all-gui        Scan all GUI processes (requires psutil)
  --json           Output as JSON
  -v, --verbose    Show loaded .so paths
  --no-color       Disable colored output
```

Default behavior: `--click` if `DISPLAY` is set, otherwise `--all-gui`.

## Sample Output

```
IM Framework Diagnostic Report
========================================================================
D-Bus IM Services:  Fcitx5: inactive  |  Fcitx: active  |  IBus: active  (Current: sogoupinyin)

Process                  PID    WinSys  Framework      IM Config  IM Loaded  Health
-------------------------------------------------------------------------------------
cinnamon                 4514   X11     GTK3           fcitx      ibus       [WARN]
nemo-desktop             4601   X11     GTK3           fcitx      fcitx      [OK]
qq                       6368   X11     GTK3/Electron  fcitx      fcitx      [OK]
sogoupinyin-service      12020  X11     Qt5            fcitx      fcitx      [OK]
x-terminal-emulator      13785  X11     GTK4           fcitx      ibus       [WARN]

Warnings:
  cinnamon (4514):
    -> GTK_IM_MODULE=fcitx but ibus module loaded instead.
  x-terminal-emulator (13785):
    -> GTK_IM_MODULE=fcitx but ibus module loaded instead. GTK4 dropped GTK_IM_MODULE support; it uses ibus by default.
```

## What It Detects

| Category | Details |
|----------|---------|
| **UI Framework** | GTK3, GTK4, Qt5, Qt6, Electron, Chromium |
| **Container** | Flatpak, Snap |
| **Window System** | X11, XWayland, Wayland Native |
| **IM Environment** | `GTK_IM_MODULE`, `QT_IM_MODULE`, `QT_IM_MODULES`, `XMODIFIERS`, etc. |
| **IM Loaded** | Actual `.so` modules loaded in process memory (fcitx/ibus) |
| **D-Bus Services** | Fcitx5, Fcitx, IBus daemon status |

## Health Status

| Status | Meaning |
|--------|---------|
| `[OK]` | IM configuration matches loaded modules |
| `[WARN]` | Mismatch or missing module (may be expected for daemons) |
| `[??]` | No IM configuration detected |

### Known Cases

- **GTK4 apps showing ibus when fcitx is configured**: GTK4 removed `GTK_IM_MODULE` support. It uses IBus by default via the Wayland IM protocol. This is expected behavior.
- **Electron apps with no IM loaded**: Electron may need `--enable-wayland-ime` or `--gtk-version=4` flags.
- **Flatpak/Snap apps with no IM module**: The IM module may not be installed inside the sandbox runtime.

## Requirements

- **Python 3.8+**
- **Linux** with `/proc` filesystem
- **Optional**: `psutil` (for `--search` and `--all-gui` modes)
- **Optional**: `xprop` (for `--click` mode on X11)

### D-Bus Tools

The tool tries `busctl` (systemd) first, then falls back to `dbus-send` for non-systemd systems. If neither is available, D-Bus service detection is skipped.

## License

MIT
