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
andAccount
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 assignment 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