Flipy

Published:

Flipy is a new, simple Python library for accessing the Flickr API. The goal is to expose Flickr's API methods as-is, but for the responses to be as pythonic as possible.

Flipy is licensed under the GNU LGPL which means pretty much anyone should be able to use it for whatever. If you're having problems with the licensing let me know. Flipy is maintianed on github.

A basic use of the library is something like this:

from flipy import Flipy
flickr = Flipy(MY_API_KEY)
me = flickr.people.findByUsername(username='ianloic')
me_info = flickr.people.getInfo(user_id=me.nsid)
print 'My name is %s. I have %s photos at %s.' % (me_info.realname, me_info.photos.count, me_info.photosurl)

As you can see the method calls you make from Python exactly match Flickr's API documentation, but the objects returned obey Python conventions.

Requests

By convention you call your Flipy() instance flickr. Then you can call methods with the names described in Flickr's API documentation. Since Flickr takes named arguments, all arguments to must be passed by name.

Signed Requests

Requests will be signed if you supply an API secret, either as the second argument to the Flipy() constructor or by setting the secret field on your Flipy object. For example: 

# this works
flickr = Flipy(MY_API_KEY)
flickr.secret = MY_API_SECRET
# so does this
flickr = Flipy(MY_API_KEY, MY_API_SECRET)

Authenticated Requests

To authenticate, just use the normal Flickr API authentication calls. Flipy supports web, desktop and mobile because it simply wraps the existing API. If a Flipy object knows about the an auth token then it will be passed with all requests. The token can be assigned to the token field on the Flipy object or passed into the constructor. There's also a helper method on the Flipy object, authurl to return a signed authentication url. A desktop auth flow might look like: 

flickr = Flipy(MY_API_KEY, MY_API_SECRET)
frob = flickr.auth.getFrob()
print 'Go to: %s' % flickr.authurl(perms='read', frob=frob)
raw_input("Press enter when you've completed your Flickr auth flow...")
token_response = flickr.auth.getToken(frob=frob)
flickr.token = token_response.token
# now you can make authenticated requests

Responses

Response objects are mapped in a fairly simple, predictable manner. The outer <rsp> isn't present in Flipy's result objects. If there's an error you'll get an exception, currently not a very useful one, but that'll get better in the future. If there's no error you'll get either the root of the result (for most methods) or a list of the roots (if there more than one, such as for flickr.reflection.getMethodInfo).

For each XML node in the result there's a Python object. If the node has no attributes or child nodes then it will just be a string of its text value. All node attributes are represented as properties. If a node name is a plural (eg: <photos>) and similar but non-plural children (eg: <photo>) will be represented as items - ie: you can iterate over the node. Other child nodes are represented as properties. Some responses contain multiple children with the same name, but don't match the simple plural/singular naming, in that case the property will be an array of all of the values. If there are unexpected name conflicts an exception will be thrown, if you see that please report it and I'll update the code to handle the case.

Errors

If Flickr returns an error then a FlipyFlickrError will be thrown whose value is the error string from Flickr.

API

Apart from the request and reponse conventions described above, Flipy provides a small API of its own for your convenience.

Flipy object

The Flipy constructor takes an API key, an optional API secret and an optional auth token. 

flickr = Flipy(API_KEY, [API_SECRET, [AUTH_TOKEN]])
The secret and auth token can be set later on fields on the instance: 
flickr.secret = API_SECRET
flickr.token = AUTH_TOKEN

There are methods to get various kinds of request URL, but users of the API shouldn't ever need to call them. They handle signing automatically. 

flickr.resturl(method='flickr.my.method', foo='bar', baz='fuz')
flickr.authurl(frob='frob')

Method objects

Some Flickr API methods (such as flickr.photos.search) paginate their results. You need to make multiple calls to the server to get all of the results. For methods such as this you can call paginate() on the method to get a generator that will return all of the results. For example: 

for photo in flickr.photos.search.paginate(user_id='76722295@N00'):
  print photo.id

Response objects

All response objects have a response.pprint() method that can be used to print a relatively human readable version of their structure. It's useful when trying to work out how to get the information you want out.

Some response objects have extra methods to make the API feel a little more object-oriented. I've only added a few but if you can think of more that make sense that you would like then please let me know.

<photo>, <prevphoto>, <nextphoto>

photo.info() return the full information about the photo. It calls flickr.photos.getInfo.

photo.people() return the people in the photo. It calls flickr.photos.people.getList.

<user>

user.photos() return all photos uploaded by the user. It calls flickr.photos.search internally so you can pass any appropriate additional parameters

user.photosOf() return all photos of the user. It calls flickr.people.getPhotosOf internally so you can pass any appropriate additional parameters

Extending

Flipy's method and response handling can be extended by supplying custom classes (or methods). To provide a custom response wrapper for the response elements named <foo> that adds a method just: 

from flipy import Response
@Response.custom('foo')
class FooResponse(Response):
  def myMethod(self):
    print 'this is my custom method'
This is how custom response objects are implemented. There are a bunch of examples of this in flipy.py.

Future Plans