How can I access UbuntuOne contacts and notes with Python?

I want to use UbuntuOne in my own Python application. I want to access contacts and maybe store other data. But I could not find any documentation or (Python) examples. How can I use this?

There are a number of different ways of working with your Ubuntu One data, you'll be pleased to hear.

If your Python application is running on Ubuntu

Your contacts data is stored in Ubuntu One, and is also synced to your desktop. Contacts data is available in the desktopcouch storage system. You can find out more about desktopcouch in the documentation. There will be more information available over the next few months as part of the Ubuntu One app developer programme.

A short summary: desktopcouch is your own personal CouchDB, running on your Ubuntu desktop, and your contacts are stored in it. So you can use the desktopcouch.records library to get access to your contacts:

from desktopcouch.records.server import CouchDatabase
CONTACT_RECORD_TYPE = 'http://www.freedesktop.org/wiki/Specifications/desktopcouch/contact'
db=CouchDatabase('contacts')
contact_names = []
for row in db.get_records(record_type=CONTACT_RECORD_TYPE):
    first_name = row.value.get('first_name', '')
    last_name = row.value.get('last_name', '')
    contact_names.append('%s %s' % (first_name, last_name))
print contact_names

There are more examples of how to work with desktopcouch data in the desktopcouch documentation page. The data format for contacts is defined here.

You can create any other databases that you like in desktopcouch; simply do

db = CouchDatabase("my_new_db", create=True)

and then work with that database; your new database will be synchronised to your personal cloud and to all your machines, and you can store whatever data in it you want.

If your Python application is not running on Ubuntu, or you want to access the data at Ubuntu One directly

Your data is stored in your own personal CouchDB in the cloud at Ubuntu One as well as in desktopcouch on your Ubuntu desktop. You can access it directly in your personal cloud if you choose. You'll need to be familiar with OAuth for this. First, obtain an OAuth token for Ubuntu One; you can do this from an Ubuntu desktop by looking in the keyring. Next, OAuth sign a request to https://one.ubuntu.com/api/account/ which will return some JSON, including your "couchdb_root", which will look like https://couchdb.one.ubuntu.com/u/abc/efg/12345.

Your personal cloud contacts database is then available at https://couchdb.one.ubuntu.com/u%2Fabc%2Fefg%2F12345%2Fcontacts (it's your couchdb_root with "contacts" on the end, and the / escaped to %2F). You can then work with this as with any CouchDB by OAuth-signing your curl requests to it. The CouchDB guide explains how to work with CouchDB over HTTP.

Working with notes is a little more complicated: the primary store for notes is the Tomboy application. Tomboy will sync your notes to Ubuntu One, and they are available in your personal cloud CouchDB (a database called "notes"), and that "notes" DB is also synced into desktopcouch. However, if your application is running on the Ubuntu desktop, I'd recommend that you use Tomboy's comprehensive D-Bus API to work with your notes directly at the source, rather than editing the desktopcouch copies and waiting for those changes to be synced up to Ubuntu One and then down to Tomboy again! This Ars Technica article explains some of how to do that, and the Tomboy team are lovely people who will be eager to help.

We (Ubuntu One) are building up an application developer programme to make it even easier to answer this sort of question and provide guidance and documentation; I'd love to hear what you're planning to do and how I can make it easier for you, so do please drop me a line (stuart.langridge @ canonical.com, or http://kryogenix.org/contact) if I can help, or post more questions to askubuntu!