cliptargets

cliptargets

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:

• Discover Hidden Data: Access formats like HTML, URLs, and application-specific data
• Debug Copy/Paste Issues: Diagnose why copy/paste operations work differently between applications
• Handle Encoding Correctly: Avoid encoding problems with UTF-16LE and other formats
• Access Raw Data: Get direct access to clipboard data without application interference
• 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!

• Issues & Discussions: Please open a GitHub issue for bugs, feature requests, or questions.
• 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.