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.
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.
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)
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
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.
If Flickr returns an error then a FlipyFlickrError will be thrown whose value is the error string from Flickr.
Apart from the request and reponse conventions described above, Flipy provides a small API of its own for your convenience.
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')
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
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.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.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
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.