
Usage
=====

::

    from richxerox import copy, paste, available
    from richxerox import dict_print # demo only
    
    print available() # what kind of data is on the clipboard?
    
    print paste()     # get data in the default format ('text')
    print paste(format='rtf')   # get RTF
    print paste(format='html')  # get HTML
    
    dict_print(pasteall(), 'ALL CONTENTS')

    clear()
    dict_print(pasteall(), 'AFTER CLEAR')

    copy(text="this is good!", html="this is <strong>good</strong>!")
    dict_print(pasteall(), 'AFTER COPY')

The API is modeled on that of `xerox <http://pypi.python.org/pypi/xerox>`_,
with simple ``copy()`` and ``paste()`` operations.  Think of
``paste()`` as pasting *into* your program and ``copy()`` as copying
*from* your program.  

If the API were more object-oriented, ``paste()`` would be something like
``pasteboard.get_contents()`` and ``copy()`` would be something
like ``pasteboard.set_contents()``.

Background
==========

I searched long and hard but couldn't find a simple Python module that made
``copy`` and ``paste`` operations on Mac OS X easy and straightforward. `xerox
<http://pypi.python.org/pypi/xerox>`_ works well, but it only supports plain
text. What about browsers and word processors that export rich text with
hyperlinks, styles, and so on? How can you access *that* data?

After banging my head against this a few times, I eventually found code samples
I could adapt and make work without understanding the entirety of Apple's
``Foundation`` and ``AppKit``. This module is the result.

It's still in flux as I improve my understanding of the underlying
``NSPasteboard`` class and ``UTI`` descriptors, and of how my programs will use
the APIs.

Credits and References
======================

Code inspired by and/or based on:

 * Genba's `Reading URLs from OS X clipboard with PyObjC <http://genbastechthoughts.wordpress.com/2012/05/20/reading-urls-from-os-x-clipboard-with-pyobjc/>`_
 * Carl M. Johnson's `copy_paste.py <http://blog.carlsensei.com/post/88897796>`_

See also:

 * `NSPasteboard docs <http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/ApplicationKit/Classes/NSPasteboard_Class/Reference/Reference.html>`_
 * `discussion on UTIs <http://sigpipe.macromates.com/2009/03/09/uti-problems/>`_
 * John Siracusa's `discussion of the evolution of Mac OS types <http://www.scribd.com/doc/6915424/Mac-OS-X-104-Tiger#page=52>`_

Also Useful
===========

Even in this HTML-everywhere age,
Apple and Mac OS X apps are unfortunately
`RTF <http://en.wikipedia.org/wiki/Rich_Text_Format>`_-centric.
Mac apps occasionally put HTML contents on the pasteboard, but
RTF seems to be the *lingua franca*. There aren't AFAIK any 
particularly good Python tools for parsing and transforming RTF.
The handy `textutil <http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man1/textutil.1.html>`_
tool will, however, convert an RTF file into quite clean HTML, like so::

    textutil -convert html temp.rtf

yielding ``temp.html``. This can be parsed and manipulated
with `lxml <http://pypi.python.org/pypi/lxml>`_ or your favorite HTML/XML library.

Installation
============

::

    pip install richxerox
    
(You may need to prefix this with "sudo " to authorize installation.)
