aiopinboard is a Python3, asyncio-focused library for interacting with the
Pinboard API.
pip install aiopinboardaiopinboard is currently supported on:
- Python 3.7
- Python 3.8
- Python 3.9
You can retrieve your Pinboard API token via your account's settings page.
aiopinboard endeavors to replicate all of the endpoints
the Pinboard API documentation with sane, usable responses.
All API usage starts with creating an API object that contains your Pinboard API token:
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
# do things!
asyncio.run(main())API endpoints that retrieve one or more bookmarks will return Bookmark objects, which
carry all of the expected properties of a bookmark:
hash: the unique identifier of the bookmarkhref: the bookmark's URLtitle: the bookmark's titledescription: the bookmark's descriptionlast_modified: the UTC date the bookmark was last modifiedtags: a list of tags applied to the bookmarkunread: whether the bookmark is unreadshared: whether the bookmark is shared
To get the UTC datetime of the last "change" (bookmark added, updated, or deleted):
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
last_change_dt = await.async_get_last_change_datetime()
# >>> datetime.datetime(2020, 9, 3, 13, 7, 19, tzinfo=<UTC>)
asyncio.run(main())This method should be used to determine whether additional API calls should be made – for example, if nothing has changed since the last time a request was made, the implementing library can halt.
To get a bookmark by its URL:
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.bookmark.async_get_bookmark_by_url("https://my.com/bookmark")
# >>> <Bookmark href="https://my.com/bookmark">
asyncio.run(main())To get all bookmarks
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.bookmark.async_get_all_bookmarks()
# >>> [<Bookmark ...>, <Bookmark ...>]
asyncio.run(main())You can specify several optional parameters while editing a bookmark:
tags: an optional list of tags to filter results bystart: the optional starting index to return (defaults to the start)results: the optional number of results (defaults to all)from_dt: the optional datetime to start fromto_dt: the optional datetime to end at
To get all bookmarks created on a certain date:
import asyncio
from datetime import date
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.bookmark.async_get_bookmarks_by_date(date.today())
# >>> [<Bookmark ...>, <Bookmark ...>]
# Optionally filter the results with a list of tags – note that only bookmarks that
# have all tags will be returned:
await api.bookmark.async_get_bookmarks_by_date(date.today(), tags=["tag1", "tag2"])
# >>> [<Bookmark ...>, <Bookmark ...>]
)
asyncio.run(main())To get recent bookmarks:
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.bookmark.async_get_recent_bookmarks(count=10)
# >>> [<Bookmark ...>, <Bookmark ...>]
# Optionally filter the results with a list of tags – note that only bookmarks that
# have all tags will be returned:
await api.bookmark.async_get_recent_bookmarks(count=20, tags=["tag1", "tag2"])
# >>> [<Bookmark ...>, <Bookmark ...>]
asyncio.run(main())To get a summary of dates and how many bookmarks were created on those dates:
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
dates = await api.bookmark.async_get_dates()
# >>> {datetime.date(2020, 09, 05): 4, ...}
asyncio.run(main())To add a bookmark:
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.bookmark.async_add_bookmark("https://my.com/bookmark", "My New Bookmark")
asyncio.run(main())You can specify several optional parameters while editing a bookmark:
description: the optional description of the bookmarktags: an optional list of tags to assign to the bookmarkcreated_datetime: the optional creation datetime to use (defaults to now)replace: whether this should replace a bookmark with the same URLshared: whether this bookmark should be sharedtoread: whether this bookmark should be unread
To delete a bookmark by its URL:
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.bookmark.async_delete_bookmark("https://my.com/bookmark")
asyncio.run(main())To get all tags for an account (and a count of how often each tag is used):
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.tag.async_get_tags()
# >>> {"tag1": 3, "tag2": 8}
asyncio.run(main())To get lists of popular (used by the community) and recommended (used by you) tags for a particular URL:
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.bookmark.async_get_suggested_tags("https://my.com/bookmark")
# >>> {"popular": ["tag1", "tag2"], "recommended": ["tag3"]}
asyncio.run(main())To delete a tag:
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.tag.async_delete_tag("tag1")
asyncio.run(main())To rename a tag:
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.tag.async_rename_tag("old-tag", "new-tag")
asyncio.run(main())API endpoints that retrieve one or more notes will return Note objects, which
carry all of the expected properties of a note:
note_id: the unique IDtitle: the titlehash: the computed hashcreated_at: the UTC datetime the note was createdupdated_at: the UTC datetime the note was updatedlength: the length
To get all notes for an account:
import asyncio
from aiopinboard import Client
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.note.async_get_notes()
# >>> [<Note ...>, <Note ...>]
asyncio.run(main())- Check for open features/bugs or initiate a discussion on one.
- Fork the repository.
- (optional, but highly recommended) Create a virtual environment:
python3 -m venv .venv - (optional, but highly recommended) Enter the virtual environment:
source ./.venv/bin/activate - Install the dev environment:
script/setup - Code your new feature or bug fix.
- Write tests that cover your new functionality.
- Run tests and ensure 100% code coverage:
script/test - Update
README.mdwith any new documentation. - Add yourself to
AUTHORS.md. - Submit a pull request!