path: root/lib/pydelicious.py

"""Library to access del.icio.us data via Python.

An introduction to the project is given in the README.
pydelicious is released under the BSD license. See license.txt for details
and the copyright holders.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

TODO:
 - distribute license, readme docs via setup.py?
 - automatic release build?
"""
import sys
import os
import time
import datetime
import locale
import httplib
import urllib2
from urllib import urlencode, quote_plus
from StringIO import StringIO
from pprint import pformat

v = sys.version_info
if v[0] >= 2 and v[1] >= 5:
    from hashlib import md5
else:
    from md5 import md5

try:
    from elementtree.ElementTree import parse as parse_xml
except ImportError:
    # Python 2.5 and higher
    from xml.etree.ElementTree import parse as parse_xml

try:
    import feedparser
except ImportError:
    print >>sys.stderr, \
        "Feedparser not available, no RSS parsing."
    feedparser = None


### Static config

__version__ = '0.5.3'
__author__ = 'Frank Timmermann <regenkind_at_gmx_dot_de>'
    # GP: does not respond to emails
__contributors__ = [
    'Greg Pinero',
    'Berend van Berkum <berend+pydelicious@dotmpe.com>']
__url__ = 'http://code.google.com/p/pydelicious/'
# Old URL: 'http://deliciouspython.python-hosting.com/'
__author_email__ = ""
__docformat__ = "restructuredtext en"
__description__ = "pydelicious.py allows you to access the web service of " \
    "del.icio.us via it's API through Python."
__long_description__ = "The goal is to design an easy to use and fully " \
    "functional Python interface to del.icio.us."

DLCS_OK_MESSAGES = ('done', 'ok')
"Known text values of positive del.icio.us <result/> answers"
DLCS_WAIT_TIME = 4
"Time to wait between API requests"
DLCS_REQUEST_TIMEOUT = 444
"Seconds before socket triggers timeout"
#DLCS_API_REALM = 'del.icio.us API'
DLCS_API_HOST = 'api.del.icio.us'
DLCS_API_PATH = 'v1'
DLCS_API = "https://%s/%s" % (DLCS_API_HOST, DLCS_API_PATH)
DLCS_RSS = 'http://del.icio.us/rss/'
DLCS_FEEDS = 'http://feeds.delicious.com/v2/'

PREFERRED_ENCODING = locale.getpreferredencoding()
# XXX: might need to check sys.platform/encoding combinations here, ie
#if sys.platform == 'darwin' || PREFERRED_ENCODING == 'macroman:
#   PREFERRED_ENCODING = 'utf-8'
if not PREFERRED_ENCODING:
    PREFERRED_ENCODING = 'iso-8859-1'

ISO_8601_DATETIME = '%Y-%m-%dT%H:%M:%SZ'

USER_AGENT = 'pydelicious/%s %s' % (__version__, __url__)

DEBUG = 0
if 'DLCS_DEBUG' in os.environ:
    DEBUG = int(os.environ['DLCS_DEBUG'])
    if DEBUG:
        print >>sys.stderr, \
            "Set DEBUG to %i from DLCS_DEBUG env." % DEBUG

HTTP_PROXY = None
if 'HTTP_PROXY' in os.environ:
    HTTP_PROXY = os.environ['HTTP_PROXY']
    if DEBUG:
        print >>sys.stderr, \
            "Set HTTP_PROXY to %i from env." % HTTP_PROXY

### Timeoutsocket hack taken from FeedParser.py

# timeoutsocket allows feedparser to time out rather than hang forever on ultra-
# slow servers. Python 2.3 now has this functionality available in the standard
# socket library, so under 2.3 you don't need to install anything.  But you
# probably should anyway, because the socket module is buggy and timeoutsocket
# is better.
try:
    import timeoutsocket # http://www.timo-tasi.org/python/timeoutsocket.py
    timeoutsocket.setDefaultSocketTimeout(DLCS_REQUEST_TIMEOUT)
except ImportError:
    import socket
    if hasattr(socket, 'setdefaulttimeout'):
        socket.setdefaulttimeout(DLCS_REQUEST_TIMEOUT)
if DEBUG: print >>sys.stderr, \
    "Set socket timeout to %s seconds" % DLCS_REQUEST_TIMEOUT


### Utility classes

class _Waiter:
    """Waiter makes sure a certain amount of time passes between
    successive calls of `Waiter()`.

    Some attributes:
    :last: time of last call
    :wait: the minimum time needed between calls
    :waited: the number of calls throttled

    pydelicious.Waiter is an instance created when the module is loaded.
    """
    def __init__(self, wait):
        self.wait = wait
        self.waited = 0
        self.lastcall = 0;

    def __call__(self):
        tt = time.time()
        wait = self.wait

        timeago = tt - self.lastcall

        if timeago < wait:
            wait = wait - timeago
            if DEBUG>0: print >>sys.stderr, "Waiting %s seconds." % wait
            time.sleep(wait)
            self.waited += 1
            self.lastcall = tt + wait
        else:
            self.lastcall = tt

Waiter = _Waiter(DLCS_WAIT_TIME)


class PyDeliciousException(Exception):
    """Standard pydelicious error"""
class PyDeliciousThrottled(Exception): pass
class PyDeliciousUnauthorized(Exception): pass

class DeliciousError(Exception):
    """Raised when the server responds with a negative answer"""

    @staticmethod
    def raiseFor(error_string, path, **params):
        if error_string == 'item already exists':
            raise DeliciousItemExistsError, params['url']
        else:
            raise DeliciousError, "%s, while calling <%s?%s>" % (error_string,
                    path, urlencode(params))

class DeliciousItemExistsError(DeliciousError):
    """Raised then adding an already existing post."""


class HTTPErrorHandler(urllib2.HTTPDefaultErrorHandler):

    def http_error_401(self, req, fp, code, msg, headers):
        raise PyDeliciousUnauthorized, "Check credentials."

    def http_error_503(self, req, fp, code, msg, headers):
        # Retry-After?
        errmsg = "Try again later."
        if 'Retry-After' in headers:
            errmsg = "You may try again after %s" % headers['Retry-After']
        raise PyDeliciousThrottled, errmsg


### Utility functions

def dict0(d):
    "Removes empty string values from dictionary"
    return dict([(k,v) for k,v in d.items()
            if v=='' and isinstance(v, basestring)])


def delicious_datetime(str):
    """Parse a ISO 8601 formatted string to a Python datetime ...
    """
    return datetime.datetime(*time.strptime(str, ISO_8601_DATETIME)[0:6])


def http_request(url, user_agent=USER_AGENT, retry=4, opener=None):
    """Retrieve the contents referenced by the URL using urllib2.

    Retries up to four times (default) on exceptions.
    """
    request = urllib2.Request(url, headers={'User-Agent':user_agent})

    if not opener:
        opener = urllib2.build_opener()

    # Remember last error
    e = None

    # Repeat request on time-out errors
    tries = retry;
    while tries:
        try:
            return opener.open(request)

        except urllib2.HTTPError, e:
            # reraise unexpected protocol errors as PyDeliciousException
            raise PyDeliciousException, "%s" % e

        except urllib2.URLError, e:
            # xxx: Ugly check for time-out errors
            #if len(e)>0 and 'timed out' in arg[0]:
            print >> sys.stderr, "%s, %s tries left." % (e, tries)
            Waiter()
            tries = tries - 1
            #else:
            #	tries = None

    # Give up
    raise PyDeliciousException, \
            "Unable to retrieve data at '%s', %s" % (url, e)


def build_api_opener(host, user, passwd, extra_handlers=() ):
    """
    Build a urllib2 style opener with HTTP Basic authorization for one host
    and additional error handling. If HTTP_PROXY is set a proxyhandler is also
    added.
    """

    global DEBUG

    if DEBUG: httplib.HTTPConnection.debuglevel = 1

    password_manager = urllib2.HTTPPasswordMgrWithDefaultRealm()
    password_manager.add_password(None, host, user, passwd)
    auth_handler = urllib2.HTTPBasicAuthHandler(password_manager)

    extra_handlers += ( HTTPErrorHandler(), )
    if HTTP_PROXY:
        extra_handlers += ( urllib2.ProxyHandler( {'http': HTTP_PROXY} ), )

    return urllib2.build_opener(auth_handler, *extra_handlers)


def dlcs_api_opener(user, passwd):
    "Build an opener for DLCS_API_HOST, see build_api_opener()"

    return build_api_opener(DLCS_API_HOST, user, passwd)


def dlcs_api_request(path, params='', user='', passwd='', throttle=True,
        opener=None):
    """Retrieve/query a path within the del.icio.us API.

    This implements a minimum interval between calls to avoid
    throttling. [#]_ Use param 'throttle' to turn this behaviour off.

    .. [#] http://del.icio.us/help/api/
    """
    if throttle:
        Waiter()

    if params:
        url = "%s/%s?%s" % (DLCS_API, path, urlencode(params))
    else:
        url = "%s/%s" % (DLCS_API, path)

    if DEBUG: print >>sys.stderr, \
            "dlcs_api_request: %s" % url

    if not opener:
        opener = dlcs_api_opener(user, passwd)

    fl = http_request(url, opener=opener)

    if DEBUG>2: print >>sys.stderr, \
            pformat(fl.info().headers)

    return fl


def dlcs_encode_params(params, usercodec=PREFERRED_ENCODING):
    """Turn all param values (int, list, bool) into utf8 encoded strings.
    """

    if params:
        for key in params.keys():
            if isinstance(params[key], bool):
                if params[key]:
                    params[key] = 'yes'
                else:
                    params[key] = 'no'

            elif isinstance(params[key], int):
                params[key] = str(params[key])

            elif not params[key]:
                # strip/ignore empties other than False or 0
                del params[key]
                continue

            elif isinstance(params[key], list):
                params[key] = " ".join(params[key])

            elif not isinstance(params[key], unicode):
                params[key] = params[key].decode(usercodec)

            assert isinstance(params[key], basestring)

        params = dict([ (k, v.encode('utf8'))
                for k, v in params.items() if v])

    return params


def dlcs_parse_xml(data, split_tags=False):
    """Parse any del.icio.us XML document and return Python data structure.

    Recognizes all XML document formats as returned by the version 1 API and
    translates to a JSON-like data structure (dicts 'n lists).

    Returned instance is always a dictionary. Examples::

     {'posts': [{'url':'...','hash':'...',},],}
     {'tags':['tag1', 'tag2',]}
     {'dates': [{'count':'...','date':'...'},], 'tag':'', 'user':'...'}
     {'result':(True, "done")}
     # etcetera.
    """
    # TODO: split_tags is not implemented

    if DEBUG>3: print >>sys.stderr, "dlcs_parse_xml: parsing from ", data

    if not hasattr(data, 'read'):
        data = StringIO(data)

    doc = parse_xml(data)
    root = doc.getroot()
    fmt = root.tag

    # Split up into three cases: Data, Result or Update
    if fmt in ('tags', 'posts', 'dates', 'bundles'):

        # Data: expect a list of data elements, 'resources'.
        # Use `fmt` (without last 's') to find data elements, elements
        # don't have contents, attributes contain all the data we need:
        # append to list
        elist = [el.attrib for el in doc.findall(fmt[:-1])]

        # Return list in dict, use tagname of rootnode as keyname.
        data = {fmt: elist}

        # Root element might have attributes too, append dict.
        data.update(root.attrib)

        return data

    elif fmt == 'result':

        # Result: answer to operations
        if root.attrib.has_key('code'):
            msg = root.attrib['code']
        else:
            msg = root.text

        # XXX: Return {'result':(True, msg)} for /known/ O.K. messages,
        # use (False, msg) otherwise. Move this to DeliciousAPI?
        v = msg in DLCS_OK_MESSAGES
        return {fmt: (v, msg)}

    elif fmt == 'update':

        # Update: "time"
        return {fmt: {
            'time':time.strptime(root.attrib['time'], ISO_8601_DATETIME) }}

    else:
        raise PyDeliciousException, "Unknown XML document format '%s'" % fmt


def dlcs_rss_request(tag="", popular=0, user="", url=''):
    """Parse a RSS request.

    This requests old (now undocumented?) URL paths that still seem to work.
    """

    tag = quote_plus(tag)
    user = quote_plus(user)

    if url != '':
        # http://del.icio.us/rss/url/efbfb246d886393d48065551434dab54
        url = DLCS_RSS + 'url/%s' % md5(url).hexdigest()

    elif user != '' and tag != '':
        url = DLCS_RSS + '%(user)s/%(tag)s' % {'user':user, 'tag':tag}

    elif user != '' and tag == '':
        # http://del.icio.us/rss/delpy
        url = DLCS_RSS + '%s' % user

    elif popular == 0 and tag == '':
        url = DLCS_RSS

    elif popular == 0 and tag != '':
        # http://del.icio.us/rss/tag/apple
        # http://del.icio.us/rss/tag/web2.0
        url = DLCS_RSS + "tag/%s" % tag

    elif popular == 1 and tag == '':
        url = DLCS_RSS + 'popular/'

    elif popular == 1 and tag != '':
        url = DLCS_RSS + 'popular/%s' % tag

    if DEBUG:
        print 'dlcs_rss_request', url

    rss = http_request(url).read()

    # assert feedparser, "dlcs_rss_request requires feedparser to be installed."
    if not feedparser:
        return rss

    rss = feedparser.parse(rss)

    posts = []
    for e in rss.entries:
        if e.has_key("links") and e["links"]!=[] and e["links"][0].has_key("href"):
            url = e["links"][0]["href"]
        elif e.has_key("link"):
            url = e["link"]
        elif e.has_key("id"):
            url = e["id"]
        else:
            url = ""
        if e.has_key("title"):
            description = e['title']
        elif e.has_key("title_detail") and e["title_detail"].has_key("title"):
            description = e["title_detail"]['value']
        else:
            description = ''
        try: tags = e['categories'][0][1]
        except:
            try: tags = e["category"]
            except: tags = ""
        if e.has_key("modified"):
            dt = e['modified']
        else:
            dt = ""
        if e.has_key("summary"):
            extended = e['summary']
        elif e.has_key("summary_detail"):
            e['summary_detail']["value"]
        else:
            extended = ""
        if e.has_key("author"):
            user = e['author']
        else:
            user = ""
        #  time = dt ist weist auf ein problem hin
        # die benennung der variablen ist nicht einheitlich
        #  api senden und
        #  xml bekommen sind zwei verschiedene schuhe :(
        posts.append({'url':url, 'description':description, 'tags':tags,
                'dt':dt, 'extended':extended, 'user':user})
    return posts


delicious_v2_feeds = {
    #"Bookmarks from the hotlist"
    '': "%(format)s",
    #"Recent bookmarks"
    'recent': "%(format)s/recent",
    #"Recent bookmarks by tag"
    'tagged': "%(format)s/tag/%(tags)s",
    #"Popular bookmarks"
    'popular': "%(format)s/popular",
    #"Popular bookmarks by tag"
    'popular_tagged': "%(format)s/popular/%(tag)s",
    #"Recent site alerts (as seen in the top-of-page alert bar on the site)"
    'alerts': "%(format)s/alerts",
    #"Bookmarks for a specific user"
    'user': "%(format)s/%(username)s",
    #"Bookmarks for a specific user by tag(s)"
    'user_tagged': "%(format)s/%(username)s/%(tags)s",
    #"Public summary information about a user (as seen in the network badge)"
    'user_info': "%(format)s/userinfo/%(username)s",
    #"A list of all public tags for a user"
    'user_tags': "%(format)s/tags/%(username)s",
    #"Bookmarks from a user's subscriptions"
    'user_subscription': "%(format)s/subscriptions/%(username)s",
    #"Private feed for a user's inbox bookmarks from others"
    'user_inbox': "%(format)s/inbox/%(username)s?private=%(key)s",
    #"Bookmarks from members of a user's network"
    'user_network': "%(format)s/network/%(username)s",
    #"Bookmarks from members of a user's network by tag"
    'user_network_tagged': "%(format)s/network/%(username)s/%(tags)s",
    #"A list of a user's network members"
    'user_network_member': "%(format)s/networkmembers/%(username)s",
    #"A list of a user's network fans"
    'user_network_fan': "%(format)s/networkfans/%(username)s",
    #"Recent bookmarks for a URL"
    'url': "%(format)s/url/%(urlmd5)s",
    #"Summary information about a URL (as seen in the tagometer)"
    'urlinfo': "json/urlinfo/%(urlmd5)s",
}

def dlcs_feed(name_or_url, url_map=delicious_v2_feeds, count=15, **params):

    """
    Request and parse a feed. See delicious_v2_feeds for available names and
    required parameters. Format defaults to json.
    """

# http://delicious.com/help/feeds
# TODO: plain or fancy

    format = params.setdefault('format', 'json')
    if count == 'all':
# TODO: fetch all
        print >>sys.stderr, "! Maxcount 100 "
        count = 100

    if name_or_url in url_map:
        params['count'] = count
        url = DLCS_FEEDS + url_map[name_or_url] % params

    else:
        url = name_or_url

    if DEBUG:
        print 'dlcs_feed', url

    feed = http_request(url).read()

    if format == 'rss':
        if feedparser:
            rss = feedparser.parse(feed)
            return rss

        else:
            return feed

    elif format == 'json':
        return feed


### Main module class

class DeliciousAPI:

    """A single-user Python facade to the del.icio.us HTTP API.

    See http://delicious.com/help/api.

    Methods ``request`` and ``request_raw`` represent the core. For all API
    paths there are furthermore methods (e.g. posts_add for 'posts/all') with
    an explicit declaration of parameters and documentation. 
    """

    def __init__(self, user, passwd, codec=PREFERRED_ENCODING,
            api_request=dlcs_api_request, xml_parser=dlcs_parse_xml,
            build_opener=dlcs_api_opener, encode_params=dlcs_encode_params):

        """Initialize access to the API for ``user`` with ``passwd``.

        ``codec`` sets the encoding of the arguments, which defaults to the
        users preferred locale.

        The ``api_request`` and ``xml_parser`` parameters by default point to
        functions within this package with standard implementations which
        request and parse a resource. See ``dlcs_api_request()`` and
        ``dlcs_parse_xml()``.

        Parameter ``build_opener`` is a callable that, provided with the 
        credentials, should build a urllib2 opener for the delicious API server
        with HTTP authentication. See ``dlcs_api_opener()`` for the default
        implementation.

        ``encode_params`` finally preprocesses API parameters before
        they are passed to ``api_request``.
        """

        assert user != ""
        self.user = user
        self.passwd = passwd
        self.codec = codec

        # Implement communication to server and parsing of respons messages:
        assert callable(encode_params)
        self._encode_params = encode_params
        assert callable(build_opener)
        self._opener = build_opener(user, passwd)
        assert callable(api_request)
        self._api_request = api_request
        assert callable(xml_parser)
        self._parse_response = xml_parser

    ### Core functionality

    def request(self, path, _raw=False, **params):
        """Sends a request message to `path` in the API, and parses the results
        from XML. Use with ``_raw=True`` or ``call request_raw()`` directly
        to get the filehandler and process the response message manually.

        Calls to some paths will return a `result` message, i.e.::

            <result code="..." />

        or::

            <result>...</result>

        These should all be parsed to ``{'result':(Boolean, MessageString)}``,
        this method raises a ``DeliciousError`` on negative `result` answers.
        Positive answers are silently accepted and nothing is returned.

        Using ``_raw=True`` bypasses all parsing and never raises
        ``DeliciousError``.

        See ``dlcs_parse_xml()`` and ``self.request_raw()``."""

        if _raw:
            # return answer
            return self.request_raw(path, **params)

        else:
            params = self._encode_params(params, self.codec)

            # get answer and parse
            fl = self._api_request(path, params=params, opener=self._opener)
            rs = self._parse_response(fl)

            if type(rs) == dict and 'result' in rs:
                if not rs['result'][0]:
                    # Raise an error for negative 'result' answers
                    errmsg = ""
                    if len(rs['result'])>0:
                        errmsg = rs['result'][1]
                    DeliciousError.raiseFor(errmsg, path, **params)

                else:
                    # not out-of-the-oridinary result, OK
                    return

            return rs

    def request_raw(self, path, **params):
        """Calls the path in the API, returns the filehandle. Returned file-
        like instances have an ``HTTPMessage`` instance with HTTP header
        information available. Use ``filehandle.info()`` or refer to the
        ``urllib2.openurl`` documentation.
        """
        # see `request()` on how the response can be handled
        params = self._encode_params(params, self.codec)
        return self._api_request(path, params=params, opener=self._opener)

    ### Explicit declarations of API paths, their parameters and docs

    # Tags
    def tags_get(self, **kwds):
        """Returns a list of tags and the number of times it is used by the
        user.
        ::

            <tags>
                <tag tag="TagName" count="888">
        """
        return self.request("tags/get", **kwds)

    def tags_delete(self, tag, **kwds):
        """Delete an existing tag.

        &tag={TAG}
            (required) Tag to delete
        """
        return self.request('tags/delete', tag=tag, **kwds)

    def tags_rename(self, old, new, **kwds):
        """Rename an existing tag with a new tag name. Returns a `result`
        message or raises an ``DeliciousError``. See ``self.request()``.

        &old={TAG}
            (required) Tag to rename.
        &new={TAG}
            (required) New tag name.
        """
        return self.request("tags/rename", old=old, new=new, **kwds)

    # Posts
    def posts_update(self, **kwds):
        """Returns the last update time for the user. Use this before calling
        `posts_all` to see if the data has changed since the last fetch.
        ::

            <update time="CCYY-MM-DDThh:mm:ssZ">
        """
        return self.request("posts/update", **kwds)

    def posts_dates(self, tag="", **kwds):
        """Returns a list of dates with the number of posts at each date.
        ::

            <dates>
                <date date="CCYY-MM-DD" count="888">

        &tag={TAG}
            (optional) Filter by this tag
        """
        return self.request("posts/dates", tag=tag, **kwds)

    def posts_get(self, tag="", dt="", url="", hashes=[], meta=True, **kwds):
        """Returns posts matching the arguments. If no date or url is given,
        most recent date will be used.
        ::

            <posts dt="CCYY-MM-DD" tag="..." user="...">
                <post ...>

        &tag={TAG} {TAG} ... {TAG}
            (optional) Filter by this/these tag(s).
        &dt={CCYY-MM-DDThh:mm:ssZ}
            (optional) Filter by this date, defaults to the most recent date on
            which bookmarks were saved.
        &url={URL}
            (optional) Fetch a bookmark for this URL, regardless of date.
        &hashes={MD5} {MD5} ... {MD5}
            (optional) Fetch multiple bookmarks by one or more URL MD5s
            regardless of date.
        &meta=yes
            (optional) Include change detection signatures on each item in a
            'meta' attribute. Clients wishing to maintain a synchronized local
            store of bookmarks should retain the value of this attribute - its
            value will change when any significant field of the bookmark
            changes.
        """
        return self.request("posts/get", tag=tag, dt=dt, url=url,
                hashes=hashes, meta=meta, **kwds)

    def posts_recent(self, tag="", count="", **kwds):
        """Returns a list of the most recent posts, filtered by argument.
        ::

            <posts tag="..." user="...">
                <post ...>

        &tag={TAG}
            (optional) Filter by this tag.
        &count={1..100}
            (optional) Number of items to retrieve (Default:15, Maximum:100).
        """
        return self.request("posts/recent", tag=tag, count=count, **kwds)

    def posts_all(self, tag="", start=None, results=None, fromdt=None,
            todt=None, meta=True, hashes=False, **kwds):
        """Returns all posts. Please use sparingly. Call the `posts_update`
        method to see if you need to fetch this at all.
        ::

            <posts tag="..." user="..." update="CCYY-MM-DDThh:mm:ssZ">
                <post ...>

        &tag
            (optional) Filter by this tag.
        &start={#}
            (optional) Start returning posts this many results into the set.
        &results={#}
            (optional) Return this many results.
        &fromdt={CCYY-MM-DDThh:mm:ssZ}
            (optional) Filter for posts on this date or later
        &todt={CCYY-MM-DDThh:mm:ssZ}
            (optional) Filter for posts on this date or earlier
        &meta=yes
            (optional) Include change detection signatures on each item in a
            'meta' attribute. Clients wishing to maintain a synchronized local
            store of bookmarks should retain the value of this attribute - its
            value will change when any significant field of the bookmark
            changes.
        &hashes
            (optional, exclusive) Do not fetch post details but a posts
            manifest with url- and meta-hashes. Other options do not apply.
        """
        if hashes:
            return self.request("posts/all", hashes=hashes, **kwds)
        else:
            return self.request("posts/all", tag=tag, fromdt=fromdt, todt=todt,
                    start=start, results=results, meta=meta, **kwds)

    def posts_add(self, url, description, extended="", tags="", dt="",
            replace=False, shared=True, **kwds):
        """Add a post to del.icio.us. Returns a `result` message or raises an
        ``DeliciousError``. See ``self.request()``.

        &url (required)
            the url of the item.
        &description (required)
            the description of the item.
        &extended (optional)
            notes for the item.
        &tags (optional)
            tags for the item (space delimited).
        &dt (optional)
            datestamp of the item (format "CCYY-MM-DDThh:mm:ssZ").
            Requires a LITERAL "T" and "Z" like in ISO8601 at
            http://www.cl.cam.ac.uk/~mgk25/iso-time.html for example:
            "1984-09-01T14:21:31Z"
        &replace=no (optional) - don't replace post if given url has already
            been posted.
        &shared=yes (optional) - wether the item is public.
        """
        return self.request("posts/add", url=url, description=description,
                extended=extended, tags=tags, dt=dt,
                replace=replace, shared=shared, **kwds)

    def posts_delete(self, url, **kwds):
        """Delete a post from del.icio.us. Returns a `result` message or
        raises an ``DeliciousError``. See ``self.request()``.

        &url (required)
            the url of the item.
        """
        return self.request("posts/delete", url=url, **kwds)

    # Bundles
    def bundles_all(self, **kwds):
        """Retrieve user bundles from del.icio.us.
        ::

            <bundles>
                <bundel name="..." tags=...">
        """
        return self.request("tags/bundles/all", **kwds)

    def bundles_set(self, bundle, tags, **kwds):
        """Assign a set of tags to a single bundle, wipes away previous
        settings for bundle. Returns a `result` messages or raises an
        ``DeliciousError``. See ``self.request()``.

        &bundle (required)
            the bundle name.
        &tags (required)
            list of tags.
        """
        if type(tags)==list:
            tags = " ".join(tags)
        return self.request("tags/bundles/set", bundle=bundle, tags=tags,
                **kwds)

    def bundles_delete(self, bundle, **kwds):
        """Delete a bundle from del.icio.us. Returns a `result` message or
        raises an ``DeliciousError``. See ``self.request()``.

        &bundle (required)
            the bundle name.
        """
        return self.request("tags/bundles/delete", bundle=bundle, **kwds)

    ### Utils

    # Lookup table for del.icio.us url-path to DeliciousAPI method.
    paths = {
        'tags/get': 'tags_get',
        'tags/delete': 'tags_delete',
        'tags/rename': 'tags_rename',
        'posts/update': 'posts_update',
        'posts/dates': 'posts_dates',
        'posts/get': 'posts_get',
        'posts/recent': 'posts_recent',
        'posts/all': 'posts_all',
        'posts/add': 'posts_add',
        'posts/delete': 'posts_delete',
        'tags/bundles/all': 'bundles_all',
        'tags/bundles/set': 'bundles_set',
        'tags/bundles/delete': 'bundles_delete',
    }
    def get_method(self, path):
        return getattr(self, self.paths[path])

    def get_url(self, url):
        """Return the del.icio.us url at which the HTML page with posts for
        ``url`` can be found.
        """
        return "http://del.icio.us/url/?url=%s" % (url,)

    def __repr__(self):
        return "DeliciousAPI(%s)" % self.user


### Convenience functions on this package

def apiNew(user, passwd):
    "Creates a new DeliciousAPI object, requires user(name) and passwd."
    return DeliciousAPI(user=user, passwd=passwd)

def add(user, passwd, url, description, tags="", extended="", dt=None,
        replace=False):
    apiNew(user, passwd).posts_add(url=url, description=description,
            extended=extended, tags=tags, dt=dt, replace=replace)

def get(user, passwd, tag="", dt=None, count=0, hashes=[]):
    "Returns a list of posts for the user"
    posts = apiNew(user, passwd).posts_get(
            tag=tag, dt=dt, hashes=hashes)['posts']
    if count: posts = posts[:count]
    return posts

def get_update(user, passwd):
    "Returns the last update time for the user."
    return apiNew(user, passwd).posts_update()['update']['time']

def get_all(user, passwd, tag="", start=0, results=100, fromdt=None,
        todt=None):
    "Returns a list with all posts. Please use sparingly. See `get_updated`"
    return apiNew(user, passwd).posts_all(tag=tag, start=start,
            results=results, fromdt=fromdt, todt=todt, meta=True)['posts']

def get_tags(user, passwd):
    "Returns a list with all tags for user."
    return apiNew(user=user, passwd=passwd).tags_get()['tags']

def delete(user, passwd, url):
    "Delete the URL from the del.icio.us account."
    apiNew(user, passwd).posts_delete(url=url)

def rename_tag(user, passwd, oldtag, newtag):
    "Rename the tag for the del.icio.us account."
    apiNew(user=user, passwd=passwd).tags_rename(old=oldtag, new=newtag)


### RSS functions

def getrss(tag="", popular=0, url='', user=""):
    """Get posts from del.icio.us via parsing RSS.

    tag (opt) sort by tag
    popular (opt) look for the popular stuff
    user (opt) get the posts by a user, this striks popular
    url (opt) get the posts by url
    """
    return dlcs_rss_request(tag=tag, popular=popular, user=user, url=url)

def get_userposts(user):
    "parse RSS for user"
    return getrss(user=user)

def get_tagposts(tag):
    "parse RSS for tag"
    return getrss(tag=tag)

def get_urlposts(url):
    "parse RSS for URL"
    return getrss(url=url)

def get_popular(tag=""):
    "parse RSS for popular URLS for tag"
    return getrss(tag=tag, popular=1)


### JSON feeds
# TODO: untested

def json_posts(user, count=15, tag=None, raw=True):
    """
    user
    count=###   the number of posts you want to get (default is 15, maximum 
                is 100)
    raw         a raw JSON object is returned, instead of an object named 
                Delicious.posts
    """
    url = "http://del.icio.us/feeds/json/" + \
            dlcs_encode_params({0:user})[0]
    if tag: url += '/'+dlcs_encode_params({0:tag})[0]

    return dlcs_feed(url, count=count, raw=raw)


def json_tags(user, atleast, count, sort='alpha', raw=True, callback=None):
    """
    user
    atleast=###         include only tags for which there are at least ### 
                        number of posts.
    count=###           include ### tags, counting down from the top.
    sort={alpha|count}  construct the object with tags in alphabetic order 
                        (alpha), or by count of posts (count).
    callback=NAME       wrap the object definition in a function call NAME(...),
                        thus invoking that function when the feed is executed.
    raw                 a pure JSON object is returned, instead of code that 
                        will construct an object named Delicious.tags.
    """
    url = 'http://del.icio.us/feeds/json/tags/' + \
            dlcs_encode_params({0:user})[0]
    return dlcs_feed(url, atleast=atleast, count=count, sort=sort, raw=raw, 
            callback=callback)


def json_network(user, raw=True, callback=None):
    """
    callback=NAME       wrap the object definition in a function call NAME(...)
    ?raw                a raw JSON object is returned, instead of an object named 
                        Delicious.posts
    """
    url = 'http://del.icio.us/feeds/json/network/' + \
            dlcs_encode_params({0:user})[0]
    return dlcs_feed(url, raw=raw, callback=callback)


def json_fans(user, raw=True, callback=None):
    """
    callback=NAME       wrap the object definition in a function call NAME(...)
    ?raw                a pure JSON object is returned, instead of an object named 
                        Delicious.
    """
    url = 'http://del.icio.us/feeds/json/fans/' + \
            dlcs_encode_params({0:user})[0]
    return dlcs_feed(url, raw=raw, callback=callback)


### delicious V2 feeds

def getfeed(name, **params):
    return dlcs_feed(name, **params)