Metadata-Version: 2.4
Name: kclipdrop
Version: 0.1.0
Summary: Automatically clear the KDE Plasma 6 clipboard history after a period of inactivity
Author-email: Michal Belica <code@beli.sk>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/coders-sk/kclipdrop
Project-URL: Repository, https://gitlab.com/coders-sk/kclipdrop
Project-URL: Issues, https://gitlab.com/coders-sk/kclipdrop/-/issues
Keywords: kde,plasma,klipper,clipboard,privacy,dbus
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Desktop Environment :: K Desktop Environment (KDE)
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dbus-fast>=2
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Dynamic: license-file

# kclipdrop

Automatically clear the KDE Plasma 6 clipboard history - including the
current clipboard contents - after a configurable period of inactivity.

kclipdrop is a small background daemon that watches the KDE Plasma clipboard
history (Klipper) over D-Bus. Every new copy re-arms a timer; when the
clipboard has been left untouched for the configured time, the whole history
is wiped. It is meant to be run as a user systemd service.

## How it works

In Plasma 6, Klipper is built into `plasmashell` and exposes the historical
D-Bus interface at `org.kde.klipper` / `/klipper` /
`org.kde.klipper.klipper`. kclipdrop uses two calls from it:

- `getClipboardHistoryMenu` - reads the current history (used to detect
  changes reliably, even when a change signal is missed);
- `clearClipboardHistory` - wipes the whole history. As a side effect of the
  Plasma implementation, this also clears the live clipboard contents.

The D-Bus `clipboardHistoryUpdated` signal is used only as a wake-up hint; the
daemon always re-reads the history to decide. After a wipe it goes idle until
the next copy, so it never clears an already-empty clipboard in a loop.

Time spent suspended (e.g. laptop lid closed) counts as inactivity: the
deadline is wall-clock based and is checked on resume.

See [docs/kde-clipboard-history-dbus-notes.md](docs/kde-clipboard-history-dbus-notes.md)
for the full research notes on the Klipper D-Bus interface.

## Requirements

- KDE Plasma 6 session with the clipboard (Klipper) feature enabled;
- Python 3.11 or newer;
- a session D-Bus (present in any graphical session).

## Installation

### Fedora (RPM)

Fedora 44+:

```bash
sudo dnf install kclipdrop
```

(once the package is published to the repository at rpm.coders.sk - see
`packaging/` for how it is built, signed and uploaded).

The RPM installs `/usr/bin/kclipdrop`, the AppStream metadata and the
`kclipdrop.service` user unit.

### Native (pip / pipx)

```bash
pipx install kclipdrop        # or: pip install --user kclipdrop
```

This installs the `kclipdrop` script into `~/.local/bin`.

## Configuration

Copy `config.example.toml` to `~/.config/kclipdrop/config.toml` (or
`$XDG_CONFIG_HOME/kclipdrop/config.toml`) and adjust it. All keys are
optional:

| Key        | Default | Description                                                          |
| ---------- | ------- | -------------------------------------------------------------------- |
| `timeout`  | `300`   | Seconds without clipboard activity after which everything is wiped.  |
| `log_level`| `"info"`| One of `debug`, `info`, `warning`, `error`, `critical`.              |

Command-line overrides win over the file: `kclipdrop daemon --timeout 600
--log-level debug` ignores the corresponding keys from `config.toml`.

## Running as a systemd user service

RPM install - the unit ships with the package:

```bash
systemctl --user enable --now kclipdrop
```

pipx / `pip install --user` install - copy the unit and override the
command with a drop-in (the shipped unit assumes `/usr/bin/kclipdrop`):

```bash
mkdir -p ~/.config/systemd/user
cp data/kclipdrop.service ~/.config/systemd/user/
systemctl --user edit kclipdrop
```

```ini
[Service]
ExecStart=
ExecStart=%h/.local/bin/kclipdrop daemon
```

```bash
systemctl --user daemon-reload
systemctl --user enable --now kclipdrop
```

Check status and logs:

```bash
systemctl --user status kclipdrop
journalctl --user -u kclipdrop -f
```

The daemon tolerates plasmashell restarts and bus hiccups: it reconnects with
exponential backoff and never exits on D-Bus errors.

## Manual use

```bash
kclipdrop clear          # wipe the clipboard history right now
kclipdrop daemon --dry-run   # watch, but only log what would be cleared
```

`kclipdrop daemon` accepts optional overrides for the config file options:

```bash
kclipdrop daemon --timeout 600 --log-level debug
```

Run `kclipdrop daemon --help` for the complete list.

## Development

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'
.venv/bin/pytest
```

The integration tests in `tests/test_klipper.py` run against a mock Klipper
service on the session bus; they are skipped automatically when no bus is
available or when a real Klipper already owns the name.

## Troubleshooting

- **`org.kde.klipper is not available on the session bus`** - the Plasma
  clipboard feature is not running. Enable it in the Clipboard applet settings
  ("Keep the selection and clipboard history"), or ensure plasmashell is
  running.
- **Cleared items reappear** - the "Prevent empty clipboard" option may keep
  an entry alive; with the history wiped there is nothing to restore, but if
  you copy something new it starts a fresh inactivity period.
- **Where is the state?** - kclipdrop itself stores no state; the history
  database (`~/.local/share/klipper/`) is managed entirely by plasmashell.

## License

MIT - see [LICENSE](LICENSE).
