""" Python wrapper for DecentURL.com API, by Ben Hoyt
    See http://decenturl.com/tools#api

Examples:

>>> import decenturl
>>> d = decenturl.get('http://youtube.com/watch?v=pQHX-SjgQvQ')
>>> d
'youtube/medieval-helpdesk-with-english'

>>> decenturl.resolve(d)
'http://youtube.com/watch?v=pQHX-SjgQvQ'

>>> decenturl.title('http://decenturl.com/')
('DecentURL - Making ugly URLs decent', 'making-ugly-urls-decent')

>>> decenturl.domain('http://brush.co.nz/')
'brush'

"""

BASE_URL = 'http://decenturl.com/api-'

import urllib, urllib2

class DecentError(Exception):
    pass

def call(name, **params):
    """ Call generic DecentURL API function, raise DecentError if not ok. """
    query = urllib.urlencode(params)
    f = urllib2.urlopen(BASE_URL + name + '?' + query)
    json = f.read()
    array = eval(json)  # this is fine if you trust me :-)
    if array[0] != 'ok':
        raise DecentError(array[0])
    return tuple(array[1:])

def get(url, title=''):
    """ Create or get decent URL from given ugly one and return it. """
    return call('get', u=url, t=title)[0]

def resolve(decent):
    """ Resolve decent URL and return ugly original. """
    return call('resolve', d=decent)[0]

def title(url, maxlen=1000):
    """ Return tuple of full <title> and decent title for given URL. """
    return call('title', u=url, l=maxlen)

def domain(url, maxlen=1000):
    """ Return URL's base domain. """
    return call('domain', u=url, l=maxlen)[0]