Skip to content

lmmx/cliptargets

Repository files navigation

cliptargets

uv pdm-managed PyPI Python Version License pre-commit.ci status

Enumerate multiple X11 clipboard targets (formats).

Python package for enumerating and accessing multiple clipboard targets (formats) in X11.

Background

In the X Window System, a clipboard can hold data in multiple different formats simultaneously—in superposition. Each format (such as plain text, UTF-8 text, or images) is identified by a target, with a label that is sometimes a MIMEtype.

  • The program that owns the clipboard, such as xclip, announces these available targets to other applications.
  • When another application wants to paste, it requests the clipboard data in a specific target format.
  • The clipboard owner then converts and provides the data in the requested format.
  • Although the clipboard owner stores only one original copy of the data, it can supply this data in various formats, depending on what the requesting application needs.

See How It Works for more details

cliptargets handles encoding (some clipboard targets may be non-UTF8) as either a CLI or Python API for inspecting the clipboard's contents across all available formats.

Features

  • Comprehensive Target Discovery: Enumerate all available clipboard targets/formats
  • Intelligent Encoding Detection: Automatically detects and properly handles various encodings (UTF-8, UTF-16LE, Latin-1)
  • Format-Specific Handling: Special handling for Mozilla-specific formats and other binary formats
  • Simple CLI: Command-line interface for quick clipboard inspection
  • Clean Python API: Programmatic access to clipboard targets
  • JSON Output: Option to export all targets and values as JSON
  • Zero Dependencies: Core functionality has no external dependencies (beyond xclip)

Installation

pip install cliptargets

Requirements

  • Python 3.10+
  • xclip

Note: The xclip command-line tool must be installed on your system separately.

  • On Debian/Ubuntu: sudo apt install xclip
  • On Fedora/RHEL: sudo dnf install xclip
  • On Arch Linux: sudo pacman -S xclip

Usage

Command Line

# Print all clipboard targets and their values
cliptargets

# Print as JSON
cliptargets --json

Python API

from cliptargets import get_all_targets, get_target_value, get_targets

# Get a list of all available targets
targets = get_targets()
print(f"Available targets: {targets}")

# Get the value of a specific target
value = get_target_value("STRING")
print(f"STRING value: {value}")

# Get a dictionary of all targets and their values
all_targets = get_all_targets()
for target, value in all_targets.items():
    print(f"{target}: {value}")

Use in Scripts

import cliptargets
import json

# Get HTML content from clipboard if available
html_content = cliptargets.get_target_value("text/html")
if html_content:
    print("HTML content found in clipboard!")
    # Process the HTML...

# Check if a URL is in the clipboard
url = cliptargets.get_target_value("text/x-moz-url-priv")
if url:
    print(f"URL found: {url}")

# Export all clipboard data to a JSON file
all_targets = cliptargets.get_all_targets()
with open("clipboard_data.json", "w") as f:
    json.dump(all_targets, f, indent=2)

Why Use This Library?

X11 clipboard can store data in multiple formats simultaneously, but most tools only access the default text format. This library lets you:

  1. Discover Hidden Data: Access formats like HTML, URLs, and application-specific data
  2. Debug Copy/Paste Issues: Diagnose why copy/paste operations work differently between applications
  3. Handle Encoding Correctly: Avoid encoding problems with UTF-16LE and other formats
  4. Access Raw Data: Get direct access to clipboard data without application interference
  5. Build Better Tools: Create clipboard managers and data transfer tools with access to all formats

Example Output

STDOUT

Found 9 clipboard targets:

COMPOUND_TEXT            : Hello World
MULTIPLE                 : <not available>
STRING                   : Hello World
TARGETS                  :
TIMESTAMP\nTARGETS\nMULTIPLE\nUTF8_STRING\nCOMPOUND_TEXT\nTEXT\nSTRING\ntext/plain;charset=utf-8\ntext/plain\n
TEXT                     : Hello World
TIMESTAMP                : 62401715\n
UTF8_STRING              : Hello World
text/plain               : Hello World
text/plain;charset=utf-8 : Hello World

JSON

{
  "TIMESTAMP": "62401715\n",
  "TARGETS":
"TIMESTAMP\nTARGETS\nMULTIPLE\nUTF8_STRING\nCOMPOUND_TEXT\nTEXT\nSTRING\ntext/plain;charset=utf-8\ntext/plain\n",
  "MULTIPLE": null,
  "UTF8_STRING": "Hello World",
  "COMPOUND_TEXT": "Hello World",
  "TEXT": "Hello World",
  "STRING": "Hello World",
  "text/plain;charset=utf-8": "Hello World",
  "text/plain": "Hello World"
}

Project Structure

  • cliptargets/core.py: Core functionality for handling clipboard targets and encoding
  • cliptargets/cli.py: Command-line interface implementation
  • cliptargets/__init__.py: Package exports and version information

Standard X11 Selection Targets

The ICCCM (Inter-Client Communication Conventions Manual) defines a comprehensive set of standard selection targets. Below is a table of these targets as defined in the X Consortium standards:

Target Atom Type Data Received
ADOBE_PORTABLE_DOCUMENT_FORMAT STRING PDF content
APPLE_PICT APPLE_PICT Apple PICT format image data
BACKGROUND PIXEL A list of pixel values
BITMAP BITMAP A list of bitmap IDs
CHARACTER_POSITION SPAN The start and end of the selection in bytes
CLASS TEXT Window class information
CLIENT_WINDOW WINDOW Any top-level window owned by the selection owner
COLORMAP COLORMAP A list of colormap IDs
COLUMN_NUMBER SPAN The start and end column numbers
COMPOUND_TEXT COMPOUND_TEXT Compound Text
DELETE NULL Special target with side effect (selection deletion)
DRAWABLE DRAWABLE A list of drawable IDs
ENCAPSULATED_POSTSCRIPT STRING EPS data
ENCAPSULATED_POSTSCRIPT_INTERCHANGE STRING EPSI data
FILE_NAME TEXT The full path name of a file
FOREGROUND PIXEL A list of pixel values
HOST_NAME TEXT The hostname of the client machine
INSERT_PROPERTY NULL Special target with side effect
INSERT_SELECTION NULL Special target with side effect
LENGTH INTEGER The number of bytes in the selection
LINE_NUMBER SPAN The start and end line numbers
LIST_LENGTH INTEGER The number of disjoint parts of the selection
MODULE TEXT The name of the selected procedure
MULTIPLE ATOM_PAIR For requesting multiple targets in one operation
NAME TEXT Window name information
ODIF TEXT ISO Office Document Interchange Format
OWNER_OS TEXT The operating system of the owner client
PIXMAP PIXMAP A list of pixmap IDs
POSTSCRIPT STRING PostScript data
PROCEDURE TEXT The name of the selected procedure
PROCESS INTEGER, TEXT The process ID of the owner
STRING STRING ISO Latin-1 (+TAB+NEWLINE) text
TARGETS ATOM A list of valid target atoms (required)
TASK INTEGER, TEXT The task ID of the owner
TEXT TEXT The text in the owner's choice of encoding
TIMESTAMP INTEGER The timestamp used to acquire the selection (required)
USER TEXT The name of the user running the owner

These targets allow for rich data exchange between X11 applications. The most commonly used are STRING, UTF8_STRING, and text/plain, but applications should be prepared to handle any of these targets.

Selection owners are required to support at least TARGETS (which returns the list of supported targets) and TIMESTAMP (which returns the time the selection was acquired).

For more comprehensive details, see the X Consortium: Inter-Client Communication Conventions Manual.

Contributing

Contributions are welcome!

  1. Issues & Discussions: Please open a GitHub issue for bugs, feature requests, or questions.
  2. Pull Requests: PRs are welcome!
    • Install the dev dependencies with pip install -e ".[dev]"
    • Make sure tests pass with pytest
    • Format code with pre-commit run --all-files

License

This project is licensed under the MIT License. See LICENSE for details.

Credits

The original inspiration for this tool came from troubleshooting complex clipboard encoding issues with X11 applications. Special thanks to the X.org community and the ICCCM documentation.

About

Enumerate multiple clipboard targets on X11 systems

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •  

Languages