projects thirtyboxes
$LastChangedDate$ # thirtyboxes -- a Python 30boxes.com API
Download
Home http://trentm.com/projects/thirtyboxes/
License MIT (more details at OSI)
Platforms Windows, Linux, Mac OS X, Unix
Current Version 0.5
Dev Status Complete. It binds to all of the API and the API is simple.
Requirements Python >= 2.4 (because decorators are used), ElementTree XML library for anything but the "raw" interface. Any of ElementTree, cElementTree, xml.etree (in Python 2.5) or lxml will suffice.
Documentation

Why thirtyboxes?

[30boxes.com](http://30boxes.com/) is a nice web calendaring app with a simple [web API](http://30boxes.com/api/). `thirtyboxes.py` provides a Python module binding to this web API and a command-line interface. Install notes and intro docs are below. Please send any feedback to [Trent Mick](mailto:trentm at gmail NO dot SPAM com).

Install Notes

Download the latest `thirtyboxes.py` source package, unzip it, and run `python setup.py install`: unzip thirtyboxes-0.8.1.zip cd thirtyboxes-0.8.1 python setup.py install If your install fails then please visit [the Troubleshooting FAQ](http://trentm.com/faq.html#troubleshooting-python-package-installation). This will install `thirtyboxes.py` (and its one dependency `cmdln.py`) into your Python's site-packages area. Alternatively, you may use `thirtyboxes.py` in-place without installing it into your Python installation, if you wish.

Introduction

### The module inteface. Start the python interactive shell in your terminal and import thirtyboxes. $ python >>> import thirtyboxes First you need an API key to use any of the API. >>> tb = thirtyboxes.ThirtyBoxes() This will open your browser to a page on 30boxes.com that will give you your API key (once you login to your account on 30boxes) -- a long string that looks something like `1234-1234567890abcdefghijklmnopqrstuv`. Set the APIKEY and then ping 30boxes to see if everything is working fine. >>> import sys, pprint; sys.displayhook = pprint.pprint >>> tb.api_key = "1234-1234567890abcdefghijklmnopqrstuv" >>> tb.ping() {'msg': 'API key for user 1234 was verified.', 'ping': 'pong'} This API parses the XML responses into more useful Python data structures. >>> tb.find_user(1) {'avatar': 'http://static.flickr.com/25/97988637_27ec96a24f_o.jpg', 'createDate': datetime.date(2005, 9, 10), 'firstName': 'Nick', 'id': 1, ...} >>> tb.find_user("hamish@example.com") Traceback (most recent call last): ... thirtyboxes.ThirtyBoxesAPIError: [Error 3] No users found for 'hamish@example.com' Errors are translated into Python exceptions. Before you can access a user's private data you need to get another key: the authorized user token ("auth_token" for short here). A web app using this API will want to [look into](http://30boxes.com/api/#user.Authorize) using the optional `return_url` argument. >>> tb.authorize_user(app_name="My 30boxes Mashup") Again, this will open a browser window asking the user to give confirmation that the app (here "My 30boxes Mashup") may access private information on 30boxes. Without a `return_url` you'll get the authtoken in the browser. >>> tb.auth_token = "1234-vutsrqponmlkjihgfedcba0987654321" Now you can use the API methods that return private data. >>> tb.all_user_info() {'IM': {'AIM': None, 'MSN': 'hamish@passport.com', 'Yahoo': None}, 'avatar': '...', 'buddies': [{'lastName': 'McDougal', 'id': 4321, 'firstName': 'Dougal'}], 'createDate': datetime.date(2006, 2, 5), 'emails': [{'primary': True, 'address': 'hamish@example.com'}], 'feeds': [{'name': "hamish's Photos", 'url': 'http://www.flickr.com/services/feeds/pho...'}], 'firstName': 'Hamish', 'id': 1234, 'lastName': 'McDonald', 'personalSite': 'http://hamish.example.com/', 'startDay': 0, 'use24HourClock': False} >>> from datetime import date, timedelta >>> today = date.today() >>> tomorrow = today + timedelta(1) >>> tb.events(start=today, end=tomorrow) {'events': [{'allDayEvent': False, 'end': datetime.datetime(2006, 3, 25, 22, 0), 'id': 156569, 'invitation': {'isInvitation': False}, 'notes': '' 'privacy': 'shared', 'repeatEndDate': None, 'repeatType': 'no', 'start': datetime.datetime(2006, 3, 25, 19, 0), 'summary': 'Bagpipe practice', 'tags': 'pipes'}], 'listEnd': datetime.date(2006, 3, 26), 'listStart': datetime.date(2006, 3, 25), 'userId': 1234} >>> tb.search('caber toss') ...returns events for caber tossing >>> tb.tagsearch('pipes') ...returns events tagged with 'pipes' ### Storing the API key and authorized user token For convenience of using this module it will automatically pick up an API key stored in either the `THIRTYBOXES_APIKEY` environment variable or in the `~/.30boxes/apikey` file. As well, you can store your authtoken in either the `THIRTYBOXES_AUTHTOKEN` environment variable or the `~/.30boxes/authtoken` file. $ cat ~/.30boxes/apikey 1234-1234567890abcdefghijklmnopqrstuv $ cat ~/.30boxes/authtoken 1234-vutsrqponmlkjihgfedcba0987654321" ### The command-line interface If you installed thirtyboxes.py to your Python site-packages directory, then you can invoke it with Python's `-m` switch: $ python -m thirtyboxes ...usage output... Otherwise you can just run the script directly: $ python thirtyboxes.py ...usage output... (Bash users might want to setup an alias something like `alias 30b='python -m thirtyboxes'`.) $ 30b ping pong: API key for user 1234 was verified. $ 30b user 1234 --- 30boxes user name : Hamish McDonald id : 1234 personalSite : http://hamish.example.com/ avatar : ... createDate : 2006-02-05 startDay : 0 use24HourClock : False feeds : - hamish's Photos (http://www.flickr.com/services/feeds/pho... The default output of each command is YAML. You can also get short-form output (one line per item) with '-s' or '--short'. $ 30b -s user 1234 user Hamish McDonald (1234): http://hamish.example.com/ The command-line interface should be self-documenting. Use the "help" subcommand to see how to use other subcommands: $ 30b help events ...help for the "events" command

Change Log

### v0.5.0 - New `ThirtyBoxes' class for main API methods. Method names are shorter and put a cleaner veneer on the raw 30boxes API names. Results are parsed into a reasonable Python complex data structure. (This adds a dependency on the ElementTree XML library.) - Cleaner command-line interface. Nicer output (default output format is YAML). - `RawThirtyBoxes' API class that just does the raw interface: methods mirror 30boxes.com/api methods, XML is returned. - The v0.1.0 top-level functions are deprecated. ### v0.1.0 - First release. - Top-level functions for each API method. - A simple command-line interface. (Run "python thirtyboxes.py" to get started.)