clipin 1.0.0

A zero-dependency cross-platform clipboard utility for Python.

🧠 clipin

clipin is a pure-Python clipboard utility that supports multiple clipboard formats — text, HTML, and images (where supported) — with minimal third-party dependencies.

✅ Features

• ✅ Cross-platform: Windows, macOS, Linux. However, headless systems (without a display), like bare bones containers, are not supported.
• 🧩 Supports MIME formats[^1] (where supported, see table below):
  • text/plain
  • text/html
  • image/png ; image/bmp ; image/tiff
• 🔄 Copy and paste multiple formats at once (where supported)
• 🐍 Pure Python with minimal dependencies (Python 3.9+)

🚀 Installation

pip install clipin

📦 Usage

Copy and paste simple text:

import clipin as cb
cb.copy("Hello, World!")
print(cb.paste())  # Outputs: Hello, World!

Copy an image file to the clipboard (open files in binary mode):

import clipin
filename = "image_file.tiff"
with open(filename, "rb") as f:
    clipin.copy(f.read(), "image/tiff")

Copy both a filename and image data (not supported on all platforms):

import clipin
filename = "image_file.png"
with open(filename, "rb") as f:
    clipin.copy({"image/png": f.read(), "text/plain": filename})

See the capabilities of the clipboard on the current platform:

import clipin
caps = clipin.capabilities()
print(caps)
# Example output on Windows:
# {'textplain': True, 'mime': True, 'multiple_formats_copy': True, 'multiple_formats_paste': True}

See table below.

📚 Interacting with MIME Types across Platforms

clipin uses MIME types (e.g., text/plain, image/png) to identify clipboard data formats. This approach enhances cross-platform compatibility, as different operating systems have their own clipboard format identifiers. However, note that Windows doesn't use MIME-style clipboard identifiers, so clipin maps between MIME types and Windows clipboard formats internally. To do this, clipin uses the Pillow library for image format conversions when necessary.

Here is a non-exhaustive list of the mappings performed:

Linux	Windows[^2]	macOS (Darwin)[^3]
text/plain	CF_TEXT = 1	NSPasteboardTypeString = public.utf8-plain-text
text/html	CF_UNICODETEXT = 13	NSPasteboardTypeHTML = public.html
image/bmp	CF_BITMAP = 2 [^4]	No equivalent[^5]
image/png	No equivalent[^6]	NSPasteboardTypePNG = public.png
image/tiff	CF_TIFF = 6	NSPasteboardTypeTIFF = public.tiff
image/jpeg	No equivalent[^6]	NSPasteboardTypeJPEG = public.jpeg
image/gif	No equivalent[^6]	NSPasteboardTypeGIF = com.compuserve.gif

Recommended Libraries

clipin is designed to be lightweight, with minimal dependencies. However, for enhanced functionality, especially regarding image format conversions on Windows, the following optional libraries are recommended:

• Windows: Pillow (for image format conversions)
• Linux: xclip (command line tool for clipboard access)
• macOS: pyobjc (for advanced clipboard interactions)

Without these libraries, clipin will still function for basic text copy and paste operations. The table below summarizes the capabilities based on the presence of these optional libraries.

Condition	textplain: text/plain	mime: text/html image/*	multiple_formats_copy	multiple_formats_paste
Windows	✅	✅	✅	✅
MacOS with pyobjc	✅	✅	✅	✅
MacOS, no pyobjc	✅	❌	❌	❌
Linux with xclip	✅	✅	❌	✅
Linux, with tkinter, no xclip	✅	❌	❌	❌
Linux, no tkinter nor xclip	❌	❌	❌	❌
Linux, headless	❌	❌	❌	❌

📄 License

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

🙏 Acknowledgements and Credits

This project was inspired on pyperclip, a library that almost everyone used and loved, but unfortunately was stalled. Firstly the pull-requests where not being attended and support for the new wheel package format was not being added. The initial goal of this project was to fork pyperclip and continue its development, but the scope quickly expanded.

The development of this library followed 4 basic principles:

1. Keep it simple to use. No object-oriented API, just simple functions to copy and paste.
2. Maintain cross-platform compatibility.
3. Support multiple clipboard formats.
4. Minimal dependencies. If third-party libraries are needed, they should be optional and only for enhanced functionality.

This project development was aided by ChatGPT-4 and GitHub Copilot. The long discussions on possibilities and implementation options were very helpful to clarify the design decisions. Also the implementation of DIB handling on Windows and NSPasteboard interactions on macOS were greatly simplified by the suggestions of these AI tools. Special thanks to the open-source community for creating and maintaining tools like pyperclip, Pillow, xclip, and pyobjc, which made this project possible.

Finally thanks to my wife and kids for their patience while I was working on this project.

I hope you find clipin useful! 😊 Stay well and happy coding! 🚀

⚙️ Notes

[^1]: Requires xclip on Linux and pyobjc on macOS. If these are not present, clipin will need python-tk installed to support only text copy and paste. If you run in a headless system, like bare bones linux container images, clipin will not work, unless you set up a virtual display (e.g., using Xvfb).

[^2]: Windows represents many clipboard formats as integer constants.

[^3]: macOS exposes common pasteboard types via AppKit (NSPasteboard / NSPasteboard.PasteboardType).

[^4]: On Windows, CF_BITMAP represents a device-dependent bitmap format. clipin is not exploiting this format directly; instead, it focuses on CF_DIB / CF_DIBV5 for image clipboard operations.

[^5]: macOS does not have a native Windows-style bitmap format; prefer PNG or TIFF.

[^6]: On Windows, images are typically stored on the clipboard as CF_DIB / CF_DIBV5 (Device Independent Bitmaps) rather than as PNG or JPEG files. clipin will:

- Detect native Windows bitmap formats
- Convert them to PNG if the Pillow library is available

If Pillow is not installed, clipin exposes the raw bitmap data and documents how to enable PNG conversion.

To enable PNG conversion, install Pillow:

```bash
pip install pillow
```

See: https://docs.microsoft.com/en-us/windows/win32/dataxchg/standard-clipboard-formats