aiopinboard is a Python3, asyncio-focused library for interacting with the
Pinboard API.
pip install aiopinboard
aiopinboard is currently supported on:
You can retrieve your Pinboard API token via your account's settings page.
aiopinboard endeavors to replicate all of the endpoints in
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 API
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
# do things!
asyncio.run(main())
Bookmark ObjectAPI 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 sharedTo get the UTC datetime of the last "change" (bookmark added, updated, or deleted):
import asyncio
from aiopinboard import API
async def main() -> None:
"""Run!"""
api = API("<PINBOARD_API_TOKEN>")
last_change_dt = await api.bookmark.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 API
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 API
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 getting all bookmarks:
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 atTo get all bookmarks created on a certain date:
import asyncio
from datetime import date
from aiopinboard import API
async def main() -> None:
"""Run!"""
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 API
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 API
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 API
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 adding 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 unreadTo delete a bookmark by its URL:
import asyncio
from aiopinboard import API
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 API
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 API
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 API
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 API
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.tag.async_rename_tag("old-tag", "new-tag")
asyncio.run(main())
Note ObjectAPI 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 lengthTo get all notes for an account:
import asyncio
from aiopinboard import API
async def main() -> None:
api = API("<PINBOARD_API_TOKEN>")
await api.note.async_get_notes()
# >>> [<Note ...>, <Note ...>]
asyncio.run(main())
Thanks to all of our contributors so far!
python3 -m venv .venvsource ./.venv/bin/activatescript/setuppoetry run pytest --cov aiopinboard testsREADME.md with any new documentation.FAQs
A Python 3, asyncio-based library for the Pinboard API
We found that aiopinboard demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.