Package: aiopinboard
📌 aiopinboard: A Python 3 Library for Pinboardaiopinboardis a Python3,asyncio-focused library for interacting with thePinboardAPI.InstallationPython VersionsAPI TokenUsageBookmarksTheBookmarkObjectGetting the Last Change DatetimeGetting BookmarksAdding a BookmarkDeleting a BookmarkTagsGetting TagsGetting Suggested TagsDeleting a TagRenaming a TagNotesTheNoteObjectGetting NotesContributingInstallationpipinstallaiopinboardPython Versionsaiopinboardis currently supported on:Python 3.10Python 3.11Python 3.12API TokenYou can retrieve your Pinboard API token viayour account's settings page.Usageaiopinboardendeavors to replicate all of the endpoints inthe Pinboard API documentationwith sane, usable responses.All API usage starts with creating anAPIobject that contains your Pinboard API token:importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")# do things!asyncio.run(main())BookmarksTheBookmarkObjectAPI endpoints that retrieve one or more bookmarks will returnBookmarkobjects, 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 sharedGetting the Last Change DatetimeTo get the UTC datetime of the last "change" (bookmark added, updated, or deleted):importasynciofromaiopinboardimportAPIasyncdefmain()->None:"""Run!"""api=API("<PINBOARD_API_TOKEN>")last_change_dt=awaitapi.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.Getting BookmarksTo get a bookmark by its URL:importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")awaitapi.bookmark.async_get_bookmark_by_url("https://my.com/bookmark")# >>> <Bookmark href="https://my.com/bookmark">asyncio.run(main())To get all bookmarksimportasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")awaitapi.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:importasynciofromdatetimeimportdatefromaiopinboardimportAPIasyncdefmain()->None:"""Run!"""api=API("<PINBOARD_API_TOKEN>")awaitapi.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:awaitapi.bookmark.async_get_bookmarks_by_date(date.today(),tags=["tag1","tag2"])# >>> [<Bookmark ...>, <Bookmark ...>]asyncio.run(main())To get recent bookmarks:importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")awaitapi.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:awaitapi.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:importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")dates=awaitapi.bookmark.async_get_dates()# >>> {datetime.date(2020, 09, 05): 4, ...}asyncio.run(main())Adding a BookmarkTo add a bookmark:importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")awaitapi.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 unreadDeleting a BookmarkTo delete a bookmark by its URL:importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")awaitapi.bookmark.async_delete_bookmark("https://my.com/bookmark")asyncio.run(main())TagsGetting TagsTo get all tags for an account (and a count of how often each tag is used):importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")awaitapi.tag.async_get_tags()# >>> {"tag1": 3, "tag2": 8}asyncio.run(main())Getting Suggested TagsTo get lists of popular (used by the community) and recommended (used by you) tags for a
particular URL:importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")awaitapi.bookmark.async_get_suggested_tags("https://my.com/bookmark")# >>> {"popular": ["tag1", "tag2"], "recommended": ["tag3"]}asyncio.run(main())Deleting a TagTo delete a tag:importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")awaitapi.tag.async_delete_tag("tag1")asyncio.run(main())Renaming a TagTo rename a tag:importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")awaitapi.tag.async_rename_tag("old-tag","new-tag")asyncio.run(main())NotesTheNoteObjectAPI endpoints that retrieve one or more notes will returnNoteobjects, 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 lengthGetting NotesTo get all notes for an account:importasynciofromaiopinboardimportAPIasyncdefmain()->None:api=API("<PINBOARD_API_TOKEN>")awaitapi.note.async_get_notes()# >>> [<Note ...>, <Note ...>]asyncio.run(main())ContributingThanks to all ofour contributorsso far!Check for open features/bugsorinitiate 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/activateInstall the dev environment:script/setupCode your new feature or bug fix on a new branch.Write tests that cover your new functionality.Run tests and ensure 100% code coverage:poetry run pytest --cov aiopinboard testsUpdateREADME.mdwith any new documentation.Submit a pull request!