clipvault 1.0.0__tar.gz

clipvault-1.0.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: clipvault
+Version: 1.0.0
+Summary: Windows-style clipboard manager for Ubuntu
+License: MIT
+Project-URL: Homepage, https://github.com/jinshah0322/ClipVault
+Project-URL: Issues, https://github.com/jinshah0322/ClipVault/issues
+Keywords: clipboard,ubuntu,linux,utility
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pynput>=1.7.0
+Requires-Dist: Pillow>=9.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-qt>=4.2.0; extra == "dev"
+
+# ClipVault — Windows-style Clipboard Manager for Ubuntu
+
+A pixel-perfect recreation of Windows **Win+V clipboard history** for Ubuntu Linux, built with PyQt5.
+
+---
+
+## Features
+
+| Feature | Windows Win+V | ClipVault |
+|---------|--------------|-----------|
+| Clipboard History | Yes | Yes |
+| Text support | Yes | Yes |
+| Image support | Yes | Yes |
+| Pin items | Yes | Yes |
+| Search history | Yes | Yes |
+| Global hotkey | Win+V | Super+V |
+| One-click paste | Yes | Yes |
+| Dark UI | Yes | Yes |
+| System tray | Yes | Yes |
+| Auto-start on login | Yes | Yes |
+| Tabs (All/Pinned/Text/Images) | Yes | Yes |
+| Cross-device sync | Yes (MS account) | No |
+
+---
+
+## Project structure
+
+```
+clipboard_manager/
+├── app/                        # Application package
+│   ├── main.py                 # Entry point
+│   ├── shared/
+│   │   └── constants.py        # Colors, file paths, limits
+│   ├── models/
+│   │   └── clip_item.py        # ClipItem data model
+│   ├── core/
+│   │   ├── history_manager.py  # Load/save/search clipboard history
+│   │   └── clipboard_watcher.py# QThread — polls system clipboard
+│   ├── workers/
+│   │   └── hotkey_listener.py  # Daemon thread — global Super+V hotkey
+│   └── ui/
+│       ├── main_window.py      # ClipVaultWindow (main UI)
+│       ├── tray_icon.py        # System tray icon + context menu
+│       └── widgets/
+│           └── clip_item_widget.py  # Per-item card widget
+├── installation/
+│   ├── install.sh              # One-shot installer for Ubuntu/Debian
+│   ├── uninstall.sh            # Removes all installed files
+│   └── README.md               # Installation guide
+├── pyproject.toml              # Project metadata, deps, pytest config
+└── README.md
+```
+
+---
+
+## Quick install
+
+```bash
+chmod +x installation/install.sh
+./installation/install.sh
+```
+
+Then launch:
+
+```bash
+clipvault
+```
+
+See [installation/README.md](installation/README.md) for the full installation guide and manual install instructions.
+
+To uninstall:
+
+```bash
+chmod +x installation/uninstall.sh
+./installation/uninstall.sh
+```
+
+---
+
+## Running without installing
+
+```bash
+# From the project root
+python3 app/main.py
+```
+
+---
+
+## Keyboard shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Super+V` | Toggle clipboard window |
+| `Escape` | Close window |
+| Click item | Paste immediately |
+| Pin button | Pin / Unpin item |
+| X button | Delete item |
+
+---
+
+## Configuration
+
+History is stored at `~/.clipvault_history.json`.
+
+To change the max history size, edit `app/shared/constants.py`:
+
+```python
+MAX_HISTORY = 50  # change this number
+```
+
+---
+
+## Compatibility
+
+- Ubuntu 20.04+
+- Debian 11+
+- Any GNOME / KDE / XFCE desktop on X11
+
+---
+
+## Wayland limitations
+
+ClipVault is built on PyQt5 + X11. On Wayland sessions some features are restricted:
+
+| Feature | X11 | Wayland |
+|---------|-----|---------|
+| Clipboard history | Yes | Yes |
+| `Super+V` global hotkey | Yes | No |
+| Auto-paste on item click | Yes | Partial |
+| System tray icon | Yes | Yes (via XWayland) |
+
+**Why the hotkey does not work on Wayland:**
+`pynput` uses X11 APIs (`python-xlib`) to intercept global key events. Wayland's security model blocks applications from listening to input outside their own window, so the `Super+V` hotkey cannot be registered.
+
+**Workarounds on Wayland:**
+- Click the system tray icon to toggle the window
+- Run the session in **X11 mode**: log out → on the login screen click the gear icon → select **Ubuntu on Xorg** → log back in
+- Set the environment variable before launching:
+  ```bash
+  QT_QPA_PLATFORM=xcb clipvault
+  ```
+
+**Check which session you are on:**
+```bash
+echo $XDG_SESSION_TYPE   # prints "x11" or "wayland"
+```

clipvault-1.0.0/README.md

@@ -0,0 +1,146 @@
+# ClipVault — Windows-style Clipboard Manager for Ubuntu
+
+A pixel-perfect recreation of Windows **Win+V clipboard history** for Ubuntu Linux, built with PyQt5.
+
+---
+
+## Features
+
+| Feature | Windows Win+V | ClipVault |
+|---------|--------------|-----------|
+| Clipboard History | Yes | Yes |
+| Text support | Yes | Yes |
+| Image support | Yes | Yes |
+| Pin items | Yes | Yes |
+| Search history | Yes | Yes |
+| Global hotkey | Win+V | Super+V |
+| One-click paste | Yes | Yes |
+| Dark UI | Yes | Yes |
+| System tray | Yes | Yes |
+| Auto-start on login | Yes | Yes |
+| Tabs (All/Pinned/Text/Images) | Yes | Yes |
+| Cross-device sync | Yes (MS account) | No |
+
+---
+
+## Project structure
+
+```
+clipboard_manager/
+├── app/                        # Application package
+│   ├── main.py                 # Entry point
+│   ├── shared/
+│   │   └── constants.py        # Colors, file paths, limits
+│   ├── models/
+│   │   └── clip_item.py        # ClipItem data model
+│   ├── core/
+│   │   ├── history_manager.py  # Load/save/search clipboard history
+│   │   └── clipboard_watcher.py# QThread — polls system clipboard
+│   ├── workers/
+│   │   └── hotkey_listener.py  # Daemon thread — global Super+V hotkey
+│   └── ui/
+│       ├── main_window.py      # ClipVaultWindow (main UI)
+│       ├── tray_icon.py        # System tray icon + context menu
+│       └── widgets/
+│           └── clip_item_widget.py  # Per-item card widget
+├── installation/
+│   ├── install.sh              # One-shot installer for Ubuntu/Debian
+│   ├── uninstall.sh            # Removes all installed files
+│   └── README.md               # Installation guide
+├── pyproject.toml              # Project metadata, deps, pytest config
+└── README.md
+```
+
+---
+
+## Quick install
+
+```bash
+chmod +x installation/install.sh
+./installation/install.sh
+```
+
+Then launch:
+
+```bash
+clipvault
+```
+
+See [installation/README.md](installation/README.md) for the full installation guide and manual install instructions.
+
+To uninstall:
+
+```bash
+chmod +x installation/uninstall.sh
+./installation/uninstall.sh
+```
+
+---
+
+## Running without installing
+
+```bash
+# From the project root
+python3 app/main.py
+```
+
+---
+
+## Keyboard shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Super+V` | Toggle clipboard window |
+| `Escape` | Close window |
+| Click item | Paste immediately |
+| Pin button | Pin / Unpin item |
+| X button | Delete item |
+
+---
+
+## Configuration
+
+History is stored at `~/.clipvault_history.json`.
+
+To change the max history size, edit `app/shared/constants.py`:
+
+```python
+MAX_HISTORY = 50  # change this number
+```
+
+---
+
+## Compatibility
+
+- Ubuntu 20.04+
+- Debian 11+
+- Any GNOME / KDE / XFCE desktop on X11
+
+---
+
+## Wayland limitations
+
+ClipVault is built on PyQt5 + X11. On Wayland sessions some features are restricted:
+
+| Feature | X11 | Wayland |
+|---------|-----|---------|
+| Clipboard history | Yes | Yes |
+| `Super+V` global hotkey | Yes | No |
+| Auto-paste on item click | Yes | Partial |
+| System tray icon | Yes | Yes (via XWayland) |
+
+**Why the hotkey does not work on Wayland:**
+`pynput` uses X11 APIs (`python-xlib`) to intercept global key events. Wayland's security model blocks applications from listening to input outside their own window, so the `Super+V` hotkey cannot be registered.
+
+**Workarounds on Wayland:**
+- Click the system tray icon to toggle the window
+- Run the session in **X11 mode**: log out → on the login screen click the gear icon → select **Ubuntu on Xorg** → log back in
+- Set the environment variable before launching:
+  ```bash
+  QT_QPA_PLATFORM=xcb clipvault
+  ```
+
+**Check which session you are on:**
+```bash
+echo $XDG_SESSION_TYPE   # prints "x11" or "wayland"
+```

clipvault-1.0.0/app/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

clipvault-1.0.0/app/core/clipboard_watcher.py

@@ -0,0 +1,57 @@
+import base64
+import time
+from io import BytesIO
+
+from PyQt5.QtCore import QThread, pyqtSignal
+from PyQt5.QtWidgets import QApplication
+
+try:
+    from PIL import Image
+    PIL_AVAILABLE = True
+except ImportError:
+    PIL_AVAILABLE = False
+
+
+class ClipboardWatcher(QThread):
+    new_text  = pyqtSignal(str)
+    new_image = pyqtSignal(str)   # base64-encoded PNG
+
+    def __init__(self):
+        super().__init__()
+        self._last_text = ""
+        self._last_img  = ""
+        self._running   = True
+
+    def run(self):
+        app = QApplication.instance()
+        while self._running:
+            try:
+                cb   = app.clipboard()
+                mime = cb.mimeData()
+
+                if mime.hasImage() and PIL_AVAILABLE:
+                    img = cb.image()
+                    if not img.isNull():
+                        buf = BytesIO()
+                        ba  = img.bits()
+                        ba.setsize(img.byteCount())
+                        pil = Image.frombytes("RGBA", (img.width(), img.height()), bytes(ba))
+                        pil.save(buf, format="PNG")
+                        b64 = base64.b64encode(buf.getvalue()).decode()
+                        if b64 != self._last_img:
+                            self._last_img = b64
+                            self.new_image.emit(b64)
+
+                elif mime.hasText():
+                    text = mime.text()
+                    if text and text != self._last_text:
+                        self._last_text = text
+                        self.new_text.emit(text)
+
+            except Exception:
+                pass
+
+            time.sleep(0.5)
+
+    def stop(self):
+        self._running = False

clipvault-1.0.0/app/core/history_manager.py

@@ -0,0 +1,61 @@
+import json
+import os
+
+from app.models.clip_item import ClipItem
+from app.shared.constants import HISTORY_FILE, MAX_HISTORY
+
+
+class HistoryManager:
+    def __init__(self):
+        self.items: list[ClipItem] = []
+        self.load()
+
+    def load(self):
+        try:
+            if os.path.exists(HISTORY_FILE):
+                with open(HISTORY_FILE, "r") as f:
+                    data = json.load(f)
+                self.items = [ClipItem.from_dict(d) for d in data]
+        except Exception:
+            self.items = []
+
+    def save(self):
+        try:
+            with open(HISTORY_FILE, "w") as f:
+                json.dump([i.to_dict() for i in self.items], f, indent=2)
+        except Exception:
+            pass
+
+    def add(self, content, kind="text"):
+        for item in self.items:
+            if item.kind == kind and item.content == content:
+                if not item.pinned:
+                    self.items.remove(item)
+                    self.items.insert(0, item)
+                    self.save()
+                return False
+
+        item     = ClipItem(content, kind)
+        pinned   = [i for i in self.items if i.pinned]
+        unpinned = [i for i in self.items if not i.pinned]
+        unpinned = unpinned[: MAX_HISTORY - 1]
+        self.items = [item] + unpinned + pinned
+        self.save()
+        return True
+
+    def toggle_pin(self, item):
+        item.pinned = not item.pinned
+        self.save()
+
+    def remove(self, item):
+        if item in self.items:
+            self.items.remove(item)
+            self.save()
+
+    def clear_unpinned(self):
+        self.items = [i for i in self.items if i.pinned]
+        self.save()
+
+    def search(self, query):
+        q = query.lower()
+        return [i for i in self.items if q in i.preview_text().lower()]

clipvault-1.0.0/app/main.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""
+ClipVault - Windows-style Clipboard Manager for Ubuntu
+Keyboard shortcut: Super+V (Win+V equivalent)
+"""
+
+import sys
+import os
+import argparse
+import signal
+import atexit
+
+# Allow running from the project root: python app/main.py
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from app import __version__
+from PyQt5.QtCore import Qt
+from PyQt5.QtWidgets import QApplication
+
+from app.core.history_manager import HistoryManager
+from app.ui.main_window import ClipVaultWindow
+from app.ui.tray_icon import TrayIcon
+from app.shared.constants import PID_FILE
+
+
+def _parse_args():
+    parser = argparse.ArgumentParser(
+        prog="clipvault",
+        description="Windows-style clipboard manager for Ubuntu",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"ClipVault {__version__}"
+    )
+    return parser.parse_args()
+
+
+def _write_pid():
+    os.makedirs(os.path.dirname(PID_FILE), exist_ok=True)
+    with open(PID_FILE, "w") as f:
+        f.write(str(os.getpid()))
+    atexit.register(lambda: os.path.exists(PID_FILE) and os.remove(PID_FILE))
+
+
+def main():
+    _parse_args()
+    _write_pid()
+
+    QApplication.setAttribute(Qt.AA_EnableHighDpiScaling, True)
+    QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps, True)
+    app = QApplication(sys.argv)
+    app.setApplicationName("ClipVault")
+    app.setQuitOnLastWindowClosed(False)
+
+    history = HistoryManager()
+    window  = ClipVaultWindow(history)
+    tray    = TrayIcon(window, app)   # noqa: F841 — kept alive by reference
+
+    # SIGUSR1 → toggle window (sent by the GNOME custom keybinding toggle script)
+    signal.signal(signal.SIGUSR1, lambda *_: window._hotkey_activated.emit())
+
+    window.show()
+    sys.exit(app.exec_())
+
+
+if __name__ == "__main__":
+    main()

clipvault-1.0.0/app/models/clip_item.py

@@ -0,0 +1,40 @@
+from datetime import datetime
+from app.shared.constants import MAX_TEXT_PREVIEW
+
+
+class ClipItem:
+    def __init__(self, content, kind="text", timestamp=None, pinned=False):
+        self.content   = content          # str for text, base64 str for image
+        self.kind      = kind             # "text" | "image"
+        self.timestamp = timestamp or datetime.now().isoformat()
+        self.pinned    = pinned
+
+    def to_dict(self):
+        return {
+            "content":   self.content,
+            "kind":      self.kind,
+            "timestamp": self.timestamp,
+            "pinned":    self.pinned,
+        }
+
+    @staticmethod
+    def from_dict(d):
+        return ClipItem(d["content"], d["kind"], d["timestamp"], d.get("pinned", False))
+
+    def preview_text(self):
+        if self.kind == "image":
+            return "📷 Image"
+        t = self.content.strip().replace("\n", " ")
+        return t[:MAX_TEXT_PREVIEW] + ("…" if len(t) > MAX_TEXT_PREVIEW else "")
+
+    def time_label(self):
+        try:
+            dt = datetime.fromisoformat(self.timestamp)
+            delta = datetime.now() - dt
+            s = int(delta.total_seconds())
+            if s < 60:    return "Just now"
+            if s < 3600:  return f"{s // 60}m ago"
+            if s < 86400: return f"{s // 3600}h ago"
+            return dt.strftime("%b %d")
+        except Exception:
+            return ""

clipvault-1.0.0/app/shared/constants.py

@@ -0,0 +1,24 @@
+import os
+
+# ── File paths ────────────────────────────────────────────────────────────────
+HISTORY_FILE = os.path.expanduser("~/.clipvault_history.json")
+PID_FILE     = os.path.expanduser("~/.local/share/clipvault/clipvault.pid")
+
+# ── Limits ────────────────────────────────────────────────────────────────────
+MAX_HISTORY = 50
+MAX_TEXT_PREVIEW = 120
+
+# ── Colors (Windows 11 dark palette) ─────────────────────────────────────────
+C_BG        = "#1c1c1c"
+C_SURFACE   = "#2d2d2d"
+C_ITEM      = "#383838"
+C_ITEM_HOV  = "#424242"
+C_ITEM_SEL  = "#0078d4"
+C_ACCENT    = "#0078d4"
+C_ACCENT2   = "#005a9e"
+C_TEXT      = "#ffffff"
+C_TEXT_DIM  = "#9d9d9d"
+C_BORDER    = "#404040"
+C_PIN       = "#f0c040"
+C_CLOSE     = "#c42b1c"
+C_SEARCH_BG = "#404040"

clipvault-1.0.0/app/tests/conftest.py

@@ -0,0 +1,7 @@
+import os
+import sys
+
+# Ensure the project root is on sys.path so `app.*` imports resolve
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+if ROOT not in sys.path:
+    sys.path.insert(0, ROOT)

clipvault-1.0.0/app/tests/test_clip_item.py

@@ -0,0 +1,114 @@
+from datetime import datetime, timedelta
+
+import pytest
+
+from app.models.clip_item import ClipItem
+from app.shared.constants import MAX_TEXT_PREVIEW
+
+
+class TestClipItemInit:
+    def test_defaults(self):
+        item = ClipItem("hello")
+        assert item.content == "hello"
+        assert item.kind == "text"
+        assert item.pinned is False
+        assert item.timestamp is not None
+
+    def test_custom_fields(self):
+        ts = "2024-01-01T12:00:00"
+        item = ClipItem("data", kind="image", timestamp=ts, pinned=True)
+        assert item.kind == "image"
+        assert item.timestamp == ts
+        assert item.pinned is True
+
+    def test_timestamp_auto_set(self):
+        before = datetime.now().isoformat()
+        item = ClipItem("x")
+        after = datetime.now().isoformat()
+        assert before <= item.timestamp <= after
+
+
+class TestClipItemSerialization:
+    def test_to_dict(self):
+        item = ClipItem("hello", kind="text", timestamp="2024-06-01T10:00:00", pinned=True)
+        d = item.to_dict()
+        assert d == {
+            "content": "hello",
+            "kind": "text",
+            "timestamp": "2024-06-01T10:00:00",
+            "pinned": True,
+        }
+
+    def test_from_dict_roundtrip(self):
+        original = ClipItem("world", kind="text", timestamp="2024-06-01T10:00:00", pinned=False)
+        restored = ClipItem.from_dict(original.to_dict())
+        assert restored.content == original.content
+        assert restored.kind == original.kind
+        assert restored.timestamp == original.timestamp
+        assert restored.pinned == original.pinned
+
+    def test_from_dict_missing_pinned_defaults_false(self):
+        d = {"content": "hi", "kind": "text", "timestamp": "2024-01-01T00:00:00"}
+        item = ClipItem.from_dict(d)
+        assert item.pinned is False
+
+
+class TestClipItemPreviewText:
+    def test_text_short(self):
+        item = ClipItem("Hello world")
+        assert item.preview_text() == "Hello world"
+
+    def test_text_strips_newlines(self):
+        item = ClipItem("line1\nline2\nline3")
+        assert "\n" not in item.preview_text()
+        assert "line1 line2 line3" == item.preview_text()
+
+    def test_text_strips_leading_trailing_whitespace(self):
+        item = ClipItem("  trimmed  ")
+        assert item.preview_text() == "trimmed"
+
+    def test_text_truncated_at_max(self):
+        long_text = "a" * (MAX_TEXT_PREVIEW + 10)
+        item = ClipItem(long_text)
+        preview = item.preview_text()
+        assert preview.endswith("…")
+        assert len(preview) == MAX_TEXT_PREVIEW + 1  # content + ellipsis char
+
+    def test_text_exactly_at_limit_no_ellipsis(self):
+        text = "b" * MAX_TEXT_PREVIEW
+        item = ClipItem(text)
+        assert item.preview_text() == text
+        assert not item.preview_text().endswith("…")
+
+    def test_image_preview(self):
+        item = ClipItem("base64data", kind="image")
+        assert item.preview_text() == "📷 Image"
+
+
+class TestClipItemTimeLabel:
+    def _item_with_delta(self, seconds):
+        ts = (datetime.now() - timedelta(seconds=seconds)).isoformat()
+        return ClipItem("x", timestamp=ts)
+
+    def test_just_now(self):
+        assert self._item_with_delta(30).time_label() == "Just now"
+
+    def test_minutes_ago(self):
+        label = self._item_with_delta(150).time_label()   # 2m 30s
+        assert label == "2m ago"
+
+    def test_hours_ago(self):
+        label = self._item_with_delta(7200).time_label()  # 2h
+        assert label == "2h ago"
+
+    def test_days_ago_shows_date(self):
+        ts = (datetime.now() - timedelta(days=3)).isoformat()
+        item = ClipItem("x", timestamp=ts)
+        label = item.time_label()
+        # Should be a month-day string like "Mar 24"
+        assert len(label) > 0
+        assert "ago" not in label
+
+    def test_invalid_timestamp_returns_empty(self):
+        item = ClipItem("x", timestamp="not-a-date")
+        assert item.time_label() == ""