Metadata-Version: 2.4
Name: tklip
Version: 0.1.1
Summary: Clipboard read/write for Unix desktops using only tkinter - no xclip, wl-clipboard, or any external command required.
Keywords: clipboard,tkinter,x11,wayland,xclip,wl-clipboard,pyperclip
Author: Lilithbtw
Author-email: Lilithbtw <lili.macias@secunda.casa>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: pywayland>=0.4.18
Requires-Python: >=3.8
Project-URL: Homepage, https://git.gay/Lilithbtw/tk_clip
Description-Content-Type: text/markdown

# tklip

Clipboard read/write for Unix desktops that doesn't shell out to anything.

Most Python clipboard libraries (`pyperclip`, wrappers around `xclip`,
`xsel`, or `wl-copy`/`wl-paste`) work by spawning an external command and
depend on it being installed and on `PATH`. On a minimal container, a
locked-down system, or a machine where you simply don't control what
binaries are present, that dependency is a real point of failure.

`tklip` takes a different approach: it uses `tkinter`'s built-in bindings
to the X11/Wayland/native clipboard, which are already part of the Python
standard library on virtually every desktop installation. As long as a
desktop environment (and its `DISPLAY`/`WAYLAND_DISPLAY`) is running,
`tklip` works - no `xclip`, no `wl-clipboard`, no `pyperclip`, no
subprocess calls of any kind.

## Install

```bash
pip install tklip
```

`tkinter` must be available in your Python installation. It ships with
the standard CPython installer on most platforms; on some Linux
distributions it's a separate OS package (e.g. `python3-tk` on
Debian/Ubuntu/Fedora/Arch).

## Usage

```python
import tklip

# Read the clipboard
text = tklip.paste()

# Write the clipboard (persists only while this process is alive)
tklip.copy("hello")

# Write and block, keeping clipboard ownership so other apps can
# read it after your script would otherwise have exited
tklip.hold_copy("hello", seconds=5)
```

### The X11 ownership catch

On X11, whoever sets the clipboard *owns* the selection and must stay
alive to serve it to other applications. If your script sets the
clipboard and exits immediately, the value can vanish unless something
else (like a clipboard manager) takes over ownership.

- `paste()` is always safe - it reads instantly and returns.
- `copy()` sets the clipboard but only persists for as long as the
  calling process is alive. Fine for long-running GUI apps that keep a
  Tk mainloop running anyway.
- `hold_copy()` sets the clipboard and blocks (optionally for a fixed
  number of seconds), keeping ownership so the value survives for other
  apps to paste. Use this in short, fire-and-forget scripts.

## License

GPL-3.0-or-later. See [LICENSE](LICENSE).
