Clipboard toolkit

Dragonfly’s clipboard toolkit offers easy access to and manipulation of the system clipboard. The Clipboard class forms the core of this toolkit. Each instance of this class is a container with a structure similar to the system clipboard, mapping content formats to content data.

Dragonfly chooses the clipboard class to alias as Clipboard based on the platform:

API differences

All platform clipboard classes have the same API, plus any platform-specific formats. The following two basic formats are always available:

  1. format_text – ANSI text format (format int: 1)

  2. format_unicode – Unicode text format (format int: 13)

The basic clipboard format constants used should match those used on Windows, e.g. format_unicode is represented by 13 (CF_UNICODETEXT). To be safe, use the format_* attributes defined by the clipboard class.

Usage examples

An instance of something contains clipboard data. The data stored within an instance can be transferred to and from the system clipboard as follows: (before running this example, the text “asdf” was copied into the system clipboard)

>>> from dragonfly.windows.clipboard import Clipboard
>>> instance = Clipboard()        # Create empty instance.
>>> print(instance)
Clipboard()

>>> instance.copy_from_system()   # Retrieve from system clipboard.
>>> print(instance)
Clipboard(unicode=u'asdf', text, oemtext, locale)
>>> # The line above shows that *instance* now contains content for
>>> #  4 different clipboard formats: unicode, text, oemtext, locale.
>>> #  The unicode format content is also displayed.

>>> instance.copy_to_system()     # Transfer back to system clipboard.

The situation frequently occurs that a developer would like to use the system clipboard to perform some task without the data currently stored in it being lost. This backing up and restoring can easily be achieved as follows:

>>> from dragonfly.windows.clipboard import Clipboard
>>> # Initialize instance with system clipboard content.
... original = Clipboard(from_system=True)
>>> print(original)
Clipboard(unicode=u'asdf', text, oemtext, locale)

>>> # Use the system clipboard to do something.
... temporary = Clipboard({Clipboard.format_unicode: u"custom content"})
>>> print(temporary)
Clipboard(unicode=u'custom content')
>>> temporary.copy_to_system()
>>> from dragonfly import Key
>>> Key("c-v").execute()

>>> # Restore original system clipboard content.
... print(Clipboard(from_system=True)) # Show system clipboard contents.
Clipboard(unicode=u'custom content', text, oemtext, locale)
>>> original.copy_to_system()
>>> print(Clipboard(from_system=True)) # Show system clipboard contents.
Clipboard(unicode=u'asdf', text, oemtext, locale)

Base Clipboard class

class BaseClipboard(contents=None, text=None, from_system=False)[source]

Base clipboard class.

classmethod clear_clipboard()[source]

Clear the system clipboard.

classmethod convert_format_content(format, content)[source]

Convert content for the given format, if necessary, and return it.

This method operates on the following formats:
  • text – encodes content to a binary string, if necessary and if possible.

  • unicode – decodes content to a text string, if necessary and if possible.

  • hdrop – converts content into a tuple of file paths, if necessary and if possible.

    String content must be a list of existing, absolute file paths separated by new lines and/or null characters. All specified file paths must be absolute paths referring to existing files on the system.

If the content cannot be converted for the given format, an error is raised.

Arguments:
  • format (int) – the clipboard format to convert.

  • content (string) – the clipboard contents to convert.

copy_from_system(formats=None, clear=False)[source]

Copy the system clipboard contents into this instance.

Arguments:
  • formats (iterable, default: None) – if not None, only the given content formats will be retrieved. If None, all available formats will be retrieved.

  • clear (boolean, default: False) – if true, the system clipboard will be cleared after its contents have been retrieved.

copy_to_system(clear=True)[source]

Copy the contents of this instance into the system clipboard.

Arguments:
  • clear (boolean, default: True) – if true, the system clipboard will be cleared before this instance’s contents are transferred.

get_available_formats()[source]

Retrieve a list of this instance’s available formats.

The preferred text format, if available, will always be the first on the list followed by any remaining formats in numerical order.

get_format(format)[source]

Retrieved this instance’s content for the given format.

Arguments:
  • format (int) – the clipboard format to retrieve.

If the given format is not available, a ValueError is raised.

classmethod get_system_text()[source]

Retrieve the system clipboard text.

get_text()[source]

Retrieve this instance’s text content. If no text content is available, this method returns None.

has_format(format)[source]

Determine whether this instance has content for the given format.

Arguments:
  • format (int) – the clipboard format to look for.

has_text()[source]

Determine whether this instance has text content.

set_format(format, content)[source]

Set this instance’s content for the given format.

Arguments:
  • format (int) – the clipboard format to set.

  • content (string) – the clipboard contents to set.

If the given format is not available, a ValueError is raised.

If None is given as the content, any content stored for the given format will be cleared.

classmethod set_system_text(content)[source]

Set the system clipboard text.

Arguments:
  • content (string) – the clipboard contents to set.

If None is given as the content, text on the system clipboard will be cleared.

set_text(content)[source]

Set the text content for this instance.

Arguments:
  • content (string) – the text content to set.

If None is given as the content, any text content stored in this instance will be cleared.

classmethod synchronized_changes(timeout, step=0.001, formats=None, initial_clipboard=None)[source]

Context manager for synchronizing local and system clipboard changes. This takes the same arguments as the wait_for_change() method.

Arguments:
  • timeout (float) – timeout in seconds.

  • step (float, default: 0.001) – number of seconds between each check.

  • formats (iterable, default: None) – if not None, only changes to the given content formats will register. If None, all formats will be observed.

  • initial_clipboard (Clipboard, default: None) – if a clipboard is given, the method will wait until the system clipboard differs from the instance’s contents.

Use with a Python ‘with’ block:

from dragonfly import Clipboard, Key

# Copy the selected text with Ctrl+C and wait until a system
#  clipboard change is detected.
timeout = 3
with Clipboard.synchronized_changes(timeout):
    Key("c-c", use_hardware=True).execute()

# Retrieve the system text.
text = Clipboard.get_system_text()
property text

Retrieve this instance’s text content. If no text content is available, this method returns None.

classmethod wait_for_change(timeout, step=0.001, formats=None, initial_clipboard=None)[source]

Wait (poll) for the system clipboard to change.

This is a blocking method which returns whether or not the system clipboard changed within a specified timeout period.

Arguments:
  • timeout (float) – timeout in seconds.

  • step (float, default: 0.001) – number of seconds between each check.

  • formats (iterable, default: None) – if not None, only changes to the given content formats will register. If None, all formats will be observed.

  • initial_clipboard (Clipboard, default: None) – if a clipboard is given, the method will wait until the system clipboard differs from the instance’s contents.

Windows Clipboard class

class Win32Clipboard(contents=None, text=None, from_system=False)[source]

Class for interacting with the Windows system clipboard.

This is Dragonfly’s default clipboard class on Windows.

classmethod clear_clipboard()[source]

Clear the system clipboard.

copy_from_system(formats=None, clear=False)[source]

Copy the system clipboard contents into this instance.

Arguments:
  • formats (iterable, default: None) – if not None, only the given content formats will be retrieved. If None, all available formats will be retrieved.

  • clear (boolean, default: False) – if true, the system clipboard will be cleared after its contents have been retrieved.

copy_to_system(clear=True)[source]

Copy the contents of this instance into the system clipboard.

Arguments:
  • clear (boolean, default: True) – if true, the system clipboard will be cleared before this instance’s contents are transferred.

classmethod get_system_text()[source]

Retrieve the system clipboard text.

classmethod set_system_text(content)[source]

Set the system clipboard text.

Arguments:
  • content (string) – the clipboard contents to set.

If None is given as the content, text on the system clipboard will be cleared.

classmethod synchronized_changes(timeout, step=0.001, formats=None, initial_clipboard=None)[source]

Context manager for synchronizing local and system clipboard changes. This takes the same arguments as the wait_for_change() method.

Arguments:
  • timeout (float) – timeout in seconds.

  • step (float, default: 0.001) – number of seconds between each check.

  • formats (iterable, default: None) – if not None, only changes to the given content formats will register. If None, all formats will be observed.

  • initial_clipboard (Clipboard, default: None) – if a clipboard is given, the method will wait until the system clipboard differs from the instance’s contents.

Use with a Python ‘with’ block:

from dragonfly import Clipboard, Key

# Copy the selected text with Ctrl+C and wait until a system
#  clipboard change is detected.
timeout = 3
with Clipboard.synchronized_changes(timeout):
    Key("c-c", use_hardware=True).execute()

# Retrieve the system text.
text = Clipboard.get_system_text()
classmethod wait_for_change(timeout, step=0.001, formats=None, initial_clipboard=None)[source]

Wait (poll) for the system clipboard to change.

This is a blocking method which returns whether or not the system clipboard changed within a specified timeout period.

Arguments:
  • timeout (float) – timeout in seconds.

  • step (float, default: 0.001) – number of seconds between each check.

  • formats (iterable, default: None) – if not None, only changes to the given content formats will register. If None, all formats will be observed.

  • initial_clipboard (Clipboard, default: None) – if a clipboard is given, the method will wait until the system clipboard differs from the instance’s contents.

Windows Clipboard context manager

class win32_clipboard_ctx(timeout=0.5, step=0.001)[source]

Python context manager for safely opening the Windows clipboard by polling for access, timing out after the specified number of seconds.

Arguments:
  • timeout (float, default: 0.5) – timeout in seconds.

  • step (float, default: 0.001) – number of seconds between each attempt to open the clipboard.

Notes:
  • The polling is necessary because the clipboard is a shared resource which may be in use by another process.

  • Nested usage will not close the clipboard early.

Use with a Python ‘with’ block:

with win32_clipboard_ctx():
    # Do clipboard operation(s).
    win32clipboard.EmptyClipboard()

X11 Clipboard classes

class BaseX11Clipboard(contents=None, text=None, from_system=False)[source]

Base X11 clipboard class.

classmethod clear_clipboard()[source]

Clear the system clipboard.

copy_from_system(formats=None, clear=False)[source]

Copy the system clipboard contents into this instance.

Arguments:
  • formats (iterable, default: None) – if not None, only the given content formats will be retrieved. If None, all available formats will be retrieved.

  • clear (boolean, default: False) – if true, the system clipboard will be cleared after its contents have been retrieved.

copy_to_system(clear=True)[source]

Copy the contents of this instance into the system clipboard.

Arguments:
  • clear (boolean, default: True) – if true, the system clipboard will be cleared before this instance’s contents are transferred.

format_x_clipboard = 13

Format for the clipboard X selection (alias of format_unicode).

format_x_primary = 65536

Format for the primary X selection.

format_x_secondary = 65537

Format for the secondary X selection.

classmethod get_system_text()[source]

Retrieve the system clipboard text.

classmethod set_system_text(content)[source]

Set the system clipboard text.

Arguments:
  • content (string) – the clipboard contents to set.

If None is given as the content, text on the system clipboard will be cleared.

class XselClipboard(contents=None, text=None, from_system=False)[source]

Class for interacting with X selections (clipboards) using xsel.

This is Dragonfly’s default clipboard class on X11/Linux.

Pyperclip Clipboard class

class PyperclipClipboard(contents=None, text=None, from_system=False)[source]

Class for interacting with the system clipboard via the pyperclip Python package.

This is Dragonfly’s default clipboard class on platforms other than Windows.

Note

This class does work on Windows, however the Windows dragonfly.windows.win32_clipboard.Win32Clipboard class should be used instead because this class doesn’t support as many clipboard formats.

classmethod clear_clipboard()[source]

Clear the system clipboard.

copy_from_system(formats=None, clear=False)[source]

Copy the system clipboard contents into this instance.

Arguments:
  • formats (iterable, default: None) – if not None, only the given content formats will be retrieved. If None, all available formats will be retrieved.

  • clear (boolean, default: False) – if true, the system clipboard will be cleared after its contents have been retrieved.

copy_to_system(clear=True)[source]

Copy the contents of this instance into the system clipboard.

Arguments:
  • clear (boolean, default: True) – if true, the system clipboard will be cleared before this instance’s contents are transferred.

classmethod get_system_text()[source]

Retrieve the system clipboard text.

classmethod set_system_text(content)[source]

Set the system clipboard text.

Arguments:
  • content (string) – the clipboard contents to set.

If None is given as the content, text on the system clipboard will be cleared.