Metadata-Version: 2.4
Name: pastebox
Version: 0.1.0
Summary: Background clipboard history tool: watches text and images, lets you browse and restore past items from a simple terminal menu
Author: BRSX-Labs
License: MIT
Project-URL: Homepage, https://github.com/BRSX-Labs/pastebox
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pyperclip>=1.8
Requires-Dist: pyperclipimg>=0.2
Requires-Dist: pillow>=10.0
Requires-Dist: pywin32>=306; sys_platform == "win32"
Requires-Dist: pyobjc-framework-quartz>=10.0; sys_platform == "darwin"

# pastebox

A background clipboard history tool. Watches the system clipboard
for text **and** images, saves everything automatically, and lets
you browse, restore, or delete past items from a simple terminal
menu — no GUI, no tray icon, just a clean CLI.

## Installation

```bash
pip install pastebox
```

or clone this repo and:

```bash
pip install -e .
```

### Linux note

On Linux, clipboard access needs one small native helper installed
(this is a limitation of the underlying clipboard libraries, not
`pastebox` itself):

```bash
sudo apt install xclip
# or, on Wayland:
sudo apt install wl-clipboard
```

Windows and macOS need no extra setup — the required platform
libraries (`pywin32` on Windows, `pyobjc-framework-quartz` on macOS)
are installed automatically as part of `pip install pastebox`.

## Usage

```bash
pastebox
```

or, without installing:

```bash
python run.py
```

or from your own Python code:

```python
from pastebox import box
box.run()
```

All three launch the same interactive menu.

### First run: setup wizard

The first time you run it, you're asked three quick questions:

- Where should clipboard history be stored (default: `pastebox_data`)
- Max history items to keep — type a number, or leave it as
  `unlimited` (the default) to never delete old items automatically
- How often to check the clipboard, in seconds (default: `1.0`)

These are saved to `pastebox.config.json` so you're not asked again.
Delete that file (or edit it directly) to change settings later.

### Main menu

```
1) Start watching the clipboard
2) View / restore / delete history
3) Clear all history
4) Exit
```

**1) Start watching** — runs in the foreground, checking the
clipboard on your chosen interval. Every time you copy something new
(text or an image), it's saved automatically and a short log line is
printed. Press `Ctrl+C` to stop watching and return to the menu.

**2) View / restore / delete history** — shows your most recent
items (newest first), with a short preview and timestamp for each.
From there you can:
- restore an item back onto the clipboard (so you can paste it
  somewhere), or
- delete a single item

**3) Clear all history** — deletes everything (asks for confirmation
first).

## How images are stored

Images aren't stuffed into the history file directly — each image is
saved as its own `.png` file inside `<data_dir>/images/`, and the
history file just keeps a small reference (filename, dimensions,
timestamp) pointing to it. This keeps the history file itself small
and fast to read, no matter how many images you've copied.

## Duplicate protection

If the clipboard still holds the same text you already saved (e.g.
you copied the same thing twice, or the polling loop just checked
again before anything changed), `pastebox` won't create a duplicate
entry — it only saves something new when the content actually
changes.

## Programmatic usage (advanced)

```python
from pastebox import config, storage, watcher

cfg = config.get_or_create_config()
hist = storage.HistoryStorage(cfg["data_dir"], max_items=cfg["max_items"])

# start watching (blocks until Ctrl+C)
watcher.watch_loop(hist, cfg["poll_interval_seconds"])

# or work with history directly
items = hist.list_items(limit=10)
hist.add_text("some text")
hist.delete_item(items[0]["id"])
hist.clear()
```

## Notes

- This is a local, offline tool — nothing is sent anywhere. Your
  clipboard history stays on your machine, in the folder you chose.
- `pastebox` polls the clipboard on an interval rather than hooking
  into OS-level clipboard change events, which keeps it simple and
  fully cross-platform, at the cost of a small delay (your configured
  poll interval, 1 second by default) before a new copy is captured.
- If you copy something pastebox can't read (e.g. a clipboard format
  it doesn't recognize), it's skipped silently rather than crashing
  the watcher.
