Introduction¶
This documentation does not specify what each Flickr API function does, nor what it returns. The Flickr API documentation is the source for that information, and will most likely be more up-to-date than this document could be. Since the Python Flickr API uses dynamic methods and introspection, you can call new Flickr methods as soon as they become available.
Concepts¶
To keep things simple, we do not write “he/she” or “(s)he”. We know that men and women can all be fine programmers and end users. Some people will be addressed as male, others as female.
To be able to easily talk about Flickr, its users, programmers and applications, here is an explanation of some concepts we use.
- you
The reader of this document. We assume you are a programmer and that you are using this Python Flickr API to create an application. In this document we shall address you as male.
- application
The Python application you are creating, that has to interface with Flickr.
- user
The user of the application, and thus (either directly or indirectly via your application) a Flickr user. In this document we shall address the user as female.
Installation¶
You can install Python FlickrAPI from the Python Package Index using:
pip install flickrapi
Installation from source is done using:
python setup.py install
Developers of the Python Flickr API code (that is, people working on the library code, rather than using the library) can install development dependencies using:
pip install -r requirements.txt
Requirements and compatibility¶
The Python Flickr API uses two external libraries, Requests and Six, and is compatible with Python 2.7 and 3.4+.
Rendering the documentation requires Sphinx.
Upgrading¶
This section describes how to upgrade from older versions.
From 1.x to 2.0¶
For this release the main goal was to quickly transition from the obsolete authentication method to OAuth. As a result, some features of the 1.x version have been dropped. If you want any of those features back, let me know at: https://bitbucket.org/sybren/flickrapi/issues?status=new&status=open
Authentication has been re-written to use OAuth. See the documentation on how to use this. Some results are:
You always have to pass both the API key and secret. In 1.x you could choose to pass only the API key, but this no longer works with OAuth.
The token cache is now based on SQLite3, and contains not only the authentication tokens, but also the user’s full name, username and NSID.
For non-web applications, a local HTTP server is started to receive the verification code. This means that the user does not have to copy and paste the verification code to the application.
The authentication callback functionality is gone. I’m not sure how many people still need this now that we’ve moved to OAuth.
The upload progress-callback functionality has been dropped. This was a hack on top of httplib, so this no longer works using Requests and OAuth.
Persistent connections have been dropped.
Flickr functions can be called with dotted notation. For example:
flickr.photos_getInfo(photo_id='123') now becomes:
flickr.photos.getInfo(photo_id='123')
^
| note the change from underscore to dot.
For backward compatibility the old underscore-notation still works.
From 1.1¶
Some methods have been deprecated in version 1.1, which are now removed. Those are the class methods:
test_failure
get_printable_error
get_rsp_error_code
get_rsp_error_msg
The default parser format has been changed from XMLNode to
ElementTree. Either convert your code to use the new ElementTree
parser, or pass the format='xmlnode'
parameter to the FlickrAPI
constructor.
The upload and replace methods now use the format parameter, so if you
use ElementTree as the parser, you’ll now also get an ElementTree
response from uploading and replacing photos. To keep the old
behaviour you can pass format='xmlnode'
to those methods.
From 0.15¶
A lot of name changes have occurred in version 0.16 to follow PEP 8.
Some properties have also had their name shortened. For example, an
XMLNode
now has a text
property instead of elementText
.
After all, the nodes describe XML elements, so what other text would
there be?
Here is a complete list of the publicly visible changes, broken down per class. Changes in the internals of the FlickrAPI aren’t documented here.
FlickrAPI
The constructor has its parameter
apiKey
changed toapi_key
.All methods names that were originally in “camelCase” are now written in Python style. For example,
getTokenPartOne
has been changed toget_token_part_one
. The same is true for the class variables that point to the Flickr API URLs. For example,flickrHost
becameflickr_host
.send_multipart
became a private method.The
main
method was removed. It only served as a simple example, which was obsoleted by the documentation.XMLNode
The method
parseXML
has becomeparse
, since it can’t parse anything but XML, so there is no need to state the obvious.Properties
elementName
andelementText
have been renamed toname
resp.text
.