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
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
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>, <prevphoto>, <nextphoto>
photo.info() return the full information about the photo. It calls
photo.people() return the people in the photo. It calls
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.
- Support uploading
- Unit tests
- Verify unicode support
- Asynchronous operation
- Support different HTTP libraries