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 %}

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