dlcs - Manage a del.icio.us bookmark collection from the command-line.
 
 
Overview
--------
`dlcs` is a simple wrapper around pydelicious.DeliciousAPI. If offers
some facilities to get data from your online bookmark collection and
to perfom operations. See::
 
    % dlcs --help
 
This tool enables quick access but the server communication may be slow and
when doing multiple expensive requests del.icio.us may throttle you and
return 503's. This all depends on your collection size (posts/tags/bundles)
ofcourse. In any case, the post and tag lists are stored locally and some
changes to your collection may not be noticed until you clear this cache
since posts/update does not notice any edits.
 
Quickstart
----------
Just start `dlcs` using::
 
    % dlcs -u <username>
 
Post any URL using::
 
    % dlcs postit <URL>
 
Configuration
-------------
Your username and password can be stored in an INI formatted configuration
file under the section name 'dlcs'. The default location is ~/.dlcs-rc
but this can be changed using command line options. If no username or
password are provided `dlcs` will guess the username and prompt for the
password.
 
Limitation
----------
- Bundle sizes are restricted by the maximum URL size [xxx:length?], the
  del.icio.us interface allows bigger bundles.
 
Integration
-----------
When using curses based browsers you may have to miss the javascript
bookmarklets since most TUI browsers don't support these. That is why dlcs 
has a command `postit` that takes the URL and fires up your favorite editor 
to offer the same functionality.
 
To bookmark HTTP URLs with lynx, put the following line in your lynx.cfg::
 
    EXTERNAL:http:dlcs postit %s
 
For the elinks browser, create a uri_passing rule in the configuration file.
Something like the following::
 
    set document.uri_passing.dlcs = "bash -c "dlcs postit %c""
 
License
-------
Same as `pydelicious`, FreeBSD or Simplified BSD license.
See license.txt for details and the copyright holders.
 
TODO
----
- adapt to new meta attr's
- catch DeliciousErrors
- Output formatting (--outf)
- Pretty JSON printer
- Append recent posts (and tags) to cache
- Some intelligent statistics on the tag collection (tag size, usage)
- Other users, is it possible to: list all posters for a URL, all tags for a URL? Popular tags?
- There are no commands to work on date lists (but 'req' could)
- Tag relations,
- Tag value, could a simple algorithm weigh the value of a specific tag (combination)?

Modules
		codecs getpass locale math optparse os pydelicious sys time

Classes
		DebugWrapper MethodWrapper   class DebugWrapper       Methods defined here: __getattr__(self, name) __init__(self, base, log) __setattr__(self, name, value)   class MethodWrapper       Methods defined here: __call__(self, *args) __init__(self, name, method, base, log)

Functions
		bundle(conf, dlcs, name, *tags, **opts) Bundle some tags under a name, replaces previous bundle contents::   % dlcs bundle bundlename tag(s) bundleadd(conf, dlcs, name, *tags, **opts) Add one or more tags to a bundle. Retrieves current bundles, adds the tags to the indicated bundle and posts it back to del.icio.us::       % dlcs bundleadd bundlename tag(s) bundleremove(conf, dlcs, name, *tags, **opts) Remove one or more tags from a bundle. Retrieves current bundles, removes the tags from the indicated bundle and posts it back to del.icio.us::       % dlcs bundleremove bundlename tag(s) bundles(conf, dlcs, **opts) Retrieve all bundles and print their names. cache_append_posts(fl) cache_file(fn, data) cached_posts(conf, dlcs, noupdate=False) Same as cached_tags but for the post list. cached_tags(conf, dlcs, noupdate=False) Make sure the tag list is cached locally. Updates when the file is older than the last time the posts where updated (according to del.icio.us posts/update, which only notes new posts, not any updates). clearcache(conf, dlcs, *clear, **opts) Delete all locally cached data::   % dlcs clear [tags | posts] deletebundle(conf, dlcs, name, **opts) Delete an entire bundle. deleteposts(conf, dlcs, *urls, **opts) Delete one or more URLs. findposts(conf, dlcs, keyword, **opts) Search all text fields of all posts for the keyword and print machting URLs.   % dlcs findposts keyword findtags(conf, dlcs, *tags, **opts) Search all tags for (a part of) a tag. getbundle(conf, dlcs, name, **opts) Retrieve all tags within a bundle. getposts(conf, dlcs, *urls, **opts) Print the posts for the given URLs in JSON. gettags(conf, dlcs, *tags, **opts) Print info about tag. help(conf, dlcs, cmd='', **opts) Prints the docstring for a command or DeliciousAPI method. http_dump(fl) Format fileobject wrapped in urllib.addinfourl as HTTP message string and return. info(conf, dlcs, **opts) Default command. main(argv) This will prepare al input data and call a command function to perform the operations. Default command is `info()`.   Configuration file is loaded and used to store username/password. mates(conf, dlcs, *args, **opts) The following was adapted from delicious_mates. http://www.aiplayground.org/artikel/delicious-mates/       % dlcs mates [max_mates[, min_bookmarks[, min_common]]] md5 = openssl_md5(...) Returns a md5 hash object; optionally initialized with a string output(cmd, opts, data) output_json(data) output_prettyjson(data) output_rst(data) output_text(data) # TODO: write output formatting for text parse_argv_split(options, argv, usage='%prog [args] [options]') Parse argument vector to a tuple with an arguments list and an option dictionary. post(conf, dlcs, url, description, extended, *tags, **opts) Do a standard post to del.icio.us::   % dlcs post "URL" "DESCRIPTION" "EXTENDED" tag1 tag2... postit(conf, dlcs, url, shared='yes', replace='no', **opts) Create and edit posts. posts(conf, dlcs, *urls, **opts) Either prints the ALL URLs or posts of given urls. postsupdate(conf, dlcs, **opts) Print last update time. prettify_json(json, level=0) Formats a JSON string to separated, indented lines. recent(conf, dlcs, **opts) Fetch the 15 most recent posts. rename(conf, dlcs, oldtag, *newtags, **opts) rename a tag to one or more tags.   % dlcs rename oldtag newtag(s) req(conf, dlcs, path, **opts) Request data from a (URI-)path using pydelicious.DeliciousAPI. E.g.::       % dlcs req posts/get?tag=energy     % dlcs req --outf=raw tags/bundles/all     % dlcs req -d posts/update   The `raw` option causes the response XML to be printed as JSON, `dump` prints the entire HTTP XML response. Note that since the v1 API is not RESTful you can change data using this function too. E.g.::       % dlcs req tags/bundles/delete?bundle=foo     % dlcs req "tags/bundles/set?bundle=foo&tags=bar%20baz"   Remember to URL encode and use shell-escaping on the paths. shortrepr(object) # Debugwrappers stats(conf, dlcs, **opts) Statistics tag(conf, dlcs, tags, *urls, **opts) Tag all URLs with the given tag(s)::       % dlcs tag "tag1 tag2" http://... http://...   This will retrieve the post for each URL, add the given tags and then replace the post at del.icio.us. URLs not in the collection cause a message to stderr and are ignored. tagged(conf, dlcs, *tags, **opts) Request all posts for a tag or overlap of tags. Print URLs.   % dlcs tagged tag [tag2 ...] tagrel(conf, dlcs, *tags, **opts) Print related tags.   Finds all posts tagged `tags` and gather other tags for post. tags(conf, dlcs, *count, **opts) Print all tags, optionally filtered by their count.   % dlcs tags [[ '>' | '<' | '=' ] count] untag(conf, dlcs, tags, *urls, **opts) Reverse of tag, remove given tags from the given URLs. Tags and URLs not found are reported on stderr and ignored. Provide only tag names without URL to completely remove them from the collection. Setting --ignore-case will lowercase all tags for the given URLs. updateposts(conf, dlcs, **opts) TODO: Retrieve 15 most recent posts and add to local cache, (after which it will be considered up-to-date again). value_sorted(dic) Return dic.items(), sorted by the values stored in the dictionary.

Data
		DEBUG = 0 DLCS_CONFIG = '/home/berend/.dlcs-rc' ENCODING = 'UTF-8' NEW_CONFIG = False __cmds__ = ['bundle', 'bundleadd', 'bundleremove', 'bundles', 'clearcache', 'deletebundle', 'deleteposts', 'findposts', 'findtags', 'getbundle', 'getposts', 'gettags', 'help', 'info', 'mates', 'post', 'postit', 'posts', 'postsupdate', 'recent', ...] __options__ = [(('-c', '--config'), {'default': '/home/berend/.dlcs-rc', 'help': 'Use custom config file [%default]'}), (('-C', '--keep-cache'), {'action': 'store_true', 'default': False, 'dest': 'keep_cache', 'help': "Don't update locally cached file(s) if they're out of date."}), (('-e', '--encoding'), {'default': 'UTF-8', 'help': 'Use custom character encoding [locale: %default]'}), (('-u', '--username'), {'help': 'del.icio.us username (defaults to config or loginname)'}), (('-p', '--password'), {'help': 'Password for the del.icio.us user (usage not recommended, but this will override the config)'}), (('-I', '--ignore-case'), {'action': 'store_true', 'default': False, 'dest': 'ignore_case', 'help': 'Ignore case for string searches'}), (('-d', '--dump'), {'default': False, 'help': 'Dump entire response (`req` only)'}), (('-o', '--outf'), {'choices': ['text', 'json', 'prettyjson'], 'default': 'text', 'help': 'Output formatting'}), (('-s', '--shared'), {'default': True, 'help': "When posting a URL, set the 'shared' parameter."}), (('-r', '--replace'), {'default': False, 'help': "When posting a URL, set the 'replace' parameter."}), (('-v', '--verboseness'), {'default': 0, 'help': 'TODO: Increase or set DEBUG (defaults to 0 or the DLCS_DEBUG env. var.)'})] __usage__ = '%prog [options] [command] [args...] \ncommand can...ommand]` to get more information about a command.' debugindent = {} debugmidline = {}