Pinboard

You can fetch, store and display data about all your bookmarks for one or more Pinboard accounts.

Set-up

In the Django admin, add an Account in the Pinboard app with your API token from https://pinboard.in/settings/password .

Then use the Management commands to download your Bookmarks.

Models

The models available in ditto.pinboard.models are:

Account: A single Pinboard account. (Note: other services, like Twitter and Flickr, have separate User and Account models. Pinboard is currently simpler.)
BookmarkTag: A custom version of a Taggit Tag model, trying to match the way Pinboard creates slugs for tags.
TaggedBookmark: The through model linking Bookmarks and BookmarkTags.
Bookmark: A single URL added to Pinboard by a particular Account.

Managers

Bookmark models have several managers:

Bookmark.objects.all(): The default manager fetches all Bookmarks, posted by all Accounts, whether they’re public or private.
Bookmark.public_objects.all(): To display all Bookmarks on public-facing pages, public_objects should be used. It won’t return Bookmarks marked as private.
Bookmark.toread_objects.all(): Returns all Bookmarks, public and private, that are marked as ‘To read’.
Bookmark.public_toread_objects.all(): Returns only public ‘To read’ Bookmarks. Private ‘To read’ Bookmarks will not be included.

Of course, these can all be filtered as usual. So, to display public ‘To read’ Bookmarks posted by a particular Account:

from ditto.pinboard.models import Account, Bookmark

account = Account.objects.get(username='philgyford')
bookmarks = Bookmark.public_to_read_objects.filter(account=account)

Template tags

There are two template tags available for displaying Bookmarks in your templates.

Annual Bookmark Counts

Get the number of bookmarks per year for all or one Account. This fetches totals for all Accounts:

{% load ditto_pinboard %}

{% annual_bookmark_counts as counts %}

{% for row in counts %}
    <p>
        {{ row.year }}: {{ row.count }}
    </p>
{% endfor %}

Both the year and count in each row are integers.

To restrict totals to a single Account:

{% annual_bookmark_counts account='philgyford' as counts %}

Day Bookmarks

To display Bookmarks posted to Pinboard on a particular day, use day_bookmarks. By default it gets Bookmarks posted by all Accounts. In this example, my_date is a datetime.datetime.date type:

{% load ditto_pinboard %}

{% day_bookmarks my_date as bookmarks %}

{% for bookmark in bookmarks %}
    <p><a href="{{ bookmark.url }}">{{ bookmark.title }}</a></p>
{% endfor %}

Or we can restrict this to the Boomarks posted by a single account on that day:

{% day_bookmarks my_date account='philgyford' as bookmarks %}

Recent Bookmarks

To display the most recently-posted Bookmarks use recent_bookmarks. By default it gets the 10 most recent Bookmarks posted by all Accounts:

{% load ditto_pinboard %}

{% recent_bookmarks as bookmarks %}

{% for bookmark in bookmarks %}
    <p><a href="{{ bookmark.url }}">{{ bookmark.title }}</a></p>
{% endfor %}

The tag can also fetch a different number of Bookmarks and/or only get Bookmarks from a single Account. Here we only get the 5 most recent Bookmarks posted by the Account with a username of 'philgyford'.:

{% recent_bookmarks account='philgyford' limit=5 as bookmarks %}

Popular Bookmark Tags

To display the most common public Tags on public Bookmarks use popular_bookmark_tags. By default it gets the 10 Tags used most across all Accounts.

{% load ditto_pinboard %}

{% popular_bookmark_tags as tags %}

{% for tag in tags %}
    <p>
        <a href="{% url 'pinboard:tag_detail' slug=tag.slug %}">
            {{ tag.name }}
        </a>
        ({{ tag.num_times }})
    </p>
{% endfor %}

The tag can also fetch a different number of Tags. Here we only get the 5 most popular Tags.:

{% popular_bookmark_tags limit=5 as tags %}

Management commands

Once you have set up an Account with your Pinboard API token (see above), you can fetch Bookmarks.

Fetch Bookmarks

Import all of your bookmarks:

$ ./manage.py fetch_pinboard_bookmarks --all

Periodically fetch the most recent bookmarks, eg 20 of them:

$ ./manage.py fetch_pinboard_bookmarks --recent=20

Or fetch bookmarks posted on one date:

$ ./manage.py fetch_pinboard_bookmarks --date=2015-06-20

Or fetch a single bookmark by its URL (eg, if you’ve changed the description of a particular bookmark you’ve alread fetched):

$ ./manage.py fetch_pinboard_bookmarks --url=http://new-aesthetic.tumblr.com/

The above commands fetch bookmark(s) for all Accounts you’ve added. To restrict to a single account use --account with the Pinboard username, eg:

$ ./manage.py fetch_pinboard_bookmarks --recent=20 --account=philgyford

Be aware of the rate limits: https://pinboard.in/api/#limits