Flickr
######

You can fetch, store and display data about all your Photos and Photosets (Albums) for one or more `Flickr <https://flickr.com/>`_ accounts. By default the included models and templates will link to the photo files on flickr.com, but you can also download the original files to store locally. These can then be used to generate images in all other sizes, to be served locally.


Set-up
******

In the Django admin, create a new Account in the Flickr app, and add your Flickr API key and secret from https://www.flickr.com/services/apps/create/apply/

By default this will only allow the fetching of fully public photos. To fetch
all photos your Flickr account can access, you'll need to do this:

1. Enter your API key and secret in the indicated place in the file
   ``ditto/scripts/flickr_authorize.py``. (If you've installed Ditto using pip,
   it might be easier to `download this script from GitHub <https://github.com/philgyford/django-ditto/blob/master/ditto/scripts/flickr_authorize.py>`_.)

2. Run the script on the command line:

    .. code-block:: shell

        $ python ditto/scripts/flickr_authorize.py

3. Follow the instructions. A new browser window should open for you to
   authorize your Flickr account. You'll then get a code to paste into your
   Terminal.

Finally, for each of those Accounts, note its ID from the Django admin, and do this to fetch information about its associated Flickr user (replacing ``1`` with your ID, if different):

.. code-block:: shell

    $ ./manage.py fetch_flickr_account_user --id=1


Photo data
**********

Now you can fetch data about your Photos (including videos). This will fetch data for ALL Photos for ALL Accounts (for me it took about 75 minutes for 3,000 photos):

.. code-block:: shell

    $ ./manage.py fetch_flickr_photos --days=all

This will only fetch Photos uploaded in the past 3 days:

.. code-block:: shell

    $ ./manage.py fetch_flickr_photos --days=3

Both options can be restricted to only fetch for a single Account by adding the NSID of the Account's Flickr User, eg:

.. code-block:: shell

    $ ./manage.py fetch_flickr_photos --account=35034346050@N01 --days=3


Photo files
***********

The above only fetches data *about* the photos (title, locations, EXIF, tags, etc). To download the original photo and video files themselves, use the ``fetch_flickr_originals`` command, *after* fetching the photos' data:

.. code-block:: shell

    $ ./manage.py fetch_flickr_originals

This took over 90 minutes for about 3,000 photos (and very few videos) for me. By default this command will fetch all the original files that haven't yet been downloaded (so the first time, it will fetch all of them). To force it to download *all* the files again (if you've deleted them locally, but they're still on Flickr) then:

.. code-block:: shell

    $ ./manage.py fetch_flickr_originals --all

Both variants can be restricted to fetching files for a single account:

.. code-block:: shell

    $ ./manage.py fetch_flickr_originals --account=35034346050@N01

Files will be saved within your project's ``MEDIA_ROOT`` directory, as defined in ``settings.py``. There are two optional settings to customise the directories in which the files are saved. Their default values are as shown here::

   DITTO_FLICKR_DIR_BASE = 'flickr'
   DITTO_FLICKR_DIR_PHOTOS_FORMAT = '%Y/%m/%d'

These values are used if you don't specify your own settings.

If your ``MEDIA_ROOT`` was set to ``/var/www/example.com/media/`` then the above settings would save the Flickr photo ``1234567_987654_o.jpg`` to something like this, depending on the Flickr user's NSID and the date the photo was taken (not uploaded):

.. code-block:: shell

    /var/www/example.com/media/flickr/35034346050N01/photos/2016/08/31/1234567_987654_o.jpg

Note that videos will have *two* "original" files downloaded: the video itself and a JPG image that Flickr created for it.

Once you've downloaded the original image files, you can use these to generate all the different sizes of image required for your site, instead of linking direct to the image files on flickr.com. To do this, ensure ``imagekit`` is in your ``INSTALLED_APPS`` setting::

    INSTALLED_APPS = (
        # ...
        'imagekit',
        # ...
    )

And add this to your `settings.py` (its default value is ``False``)::

    DITTO_FLICKR_USE_LOCAL_MEDIA = True

Any requests in your templates for the URLs of photo files of any size will now use resized versions of your downloaded original files, generated by Imagekit.  The first time you load a page (especially if it lists many Flickr images) it will be slow, but the images are cached (in a ``CACHE`` directory in your media folder).

For example, before changing this setting, the URL of small image (``Photo.small_url``) would be something like this:

.. code-block:: shell

    https://farm8.static.flickr.com/7442/27289611500_d0debff24e_m.jpg

After choosing to use local photos, it would be something like this:

.. code-block:: shell

    /media/CACHE/images/flickr/35034346050N01/photos/2016/06/09/27289611500_d21f6f47a0_o/0ee894a3438233848e6e9d85e1985260.jpg

If you change your mind you can switch back to using the images hosted on flickr.com by removing the ``DITTO_FLICKR_USE_LOCAL_MEDIA`` setting or changing it to ``False``.

Note that Ditto currently can't do the same for videos, even if the original video file has been downloaded. No matter what the  value of ``DITTO_FLICKR_USE_LOCAL_MEDIA`` the flickr.com URL for videos is always used.


Photosets
*********

You can fetch data about your Photosets (also known as Albums) any time, but this won't fetch detailed data about Photos within them.

So, for best results, ensure all Photos are downloaded before fetching Photoset data.

To fetch Photosets for all Accounts:

.. code-block:: shell

    $ ./manage.py fetch_flickr_photosets

Or fetch for only one Account:

.. code-block:: shell

    $ ./manage.py fetch_flickr_photosets --account=35034346050@N01


Users
*****

Profile photos of Flickr Users are downloaded and stored in your project's ``MEDIA_ROOT`` directory. You can optionally set the ``DITTO_FLICKR_DIR_BASE`` setting to change the location. The default is::

   DITTO_FLICKR_DIR_BASE = 'flickr'

If your ``MEDIA_ROOT`` was set to ``/var/www/example.com/media/`` then the above setting would save the profile image for the user with NSID ``35034346050@N01`` to something like this:

.. code-block:: shell

    /var/www/example.com/media/flickr/46/05/35034346050N01/avatars/35034346050N01.jpg


