p4a.upcoming usage
==================

You need to get a api_key and frob from upcoming.yahoo.com.


A simple search:

   >>> from p4a.upcoming import Service
   
   >>> service = Service(api_key='44d5e34cb7')
   >>> result = service.call('event.search', search_text='Shins')
   
The result is a dictionary. All correct results have a status and a version

   >>> result['stat']
   'ok'
   >>> result['version']
   '1.0'
   
The rest of the data depends on the scheme of the query. A search has an 
attribute "event" that is a list of the matching events:

   >>> len(result['event'])
   5
   
Each event is also a dictionary, with the events attributes:

   >>> result['event'][0]['venue_city']
   'tokyo'
   

Adding an event
===============

When changing stuff, you need to authenticate. The Service keeps track of
which methods require authentication, and raises an error if you haven't
provided a frob as well as an api_key.

   >>> service.call('event.add', name='p4a.upcoming tests')
   Traceback (most recent call last):
   ...
   ValueError: If you want to be able to authenticate, you must provide a frob to Service().

So, lets try with a frob, but not enough parameters. This should raise a
value error with the error text that we returned by Upcoming.

   >>> service = Service(api_key='44d5e34cb7', frob='addyourfrobhere')

   >>> service.call('event.add', name='Regebro test', start_date='2008-12-12')
   Traceback (most recent call last):
   ...
   ValueError: Invalid category_id parameter.
   
We need to pass in a venue and category. These are ID's, so we need to 
find them. The category is a fixed list.

   >>> result = service.call('category.getList')
   >>> result['category'][8]['name']
   'Other'
   
Venues can be added, modified and searched for. Lets search for a venue:

   >>> result = service.call('venue.search', search_text="Le Zenith, Paris")
   >>> result['venue'][0]['name']
   'Le Zenith'

Let's use this venue for the event creation:

   >>> venue_id = result['venue'][0]['id']

Now, lets do the event creation properly:


   >>> result = service.call('event.add', name='p4a.upcoming test',
   ...          start_date='2008-12-12', category_id=10, venue_id=venue_id)
   
The result includes the information associated with the event, including such
calculated from the venue.

   >>> result['stat']
   'ok'
   >>> result['event'][0]['venue_city']
   'Paris'

You can't delete events through this API, but at least we can make it "personal",
and so not publicly shown.

   >>> event = result['event'][0]
   >>> event['personal'] = 1
   
The event id is returned as 'id', but must be posted as 'event_id'.

   >>> event['event_id'] = event['id']
   >>> result = service.call('event.edit', **event)
   >>> result['event'][0]['personal']
   '1'

Since it's now marked as personal, searching for it will fail, but 
we can still get it, if we force authentication

   >>> result = service.call('event.search', authenticate=True, 
   ...                        search_text='p4a.upcoming test')
   >>> result['stat']
   'ok'
   >>> len(result['event']) > 0
   True
   >>> result['event'][0]['venue_city']
   'Paris'

We can also set the Service() to always autenticate:

   >>> service = Service(api_key='44d5e34cb7', always_authenticate=True,
   ...                   frob='addyourfrobhere')
   >>> result = service.call('event.search', search_text='p4a.upcoming test')
   >>> result['stat']
   'ok'
   >>> len(result['event']) > 0
   True
   >>> result['event'][0]['venue_city']
   'Paris'