aiopinboard 2024.1.0

Description:

aiopinboard 2024.1.0

📌 aiopinboard: A Python 3 Library for Pinboard







aiopinboard is a Python3, asyncio-focused library for interacting with the
Pinboard API.

Installation
Python Versions
API Token
Usage

Bookmarks

The Bookmark Object
Getting the Last Change Datetime
Getting Bookmarks
Adding a Bookmark
Deleting a Bookmark


Tags

Getting Tags
Getting Suggested Tags
Deleting a Tag
Renaming a Tag


Notes

The Note Object
Getting Notes




Contributing

Installation
pip install aiopinboard

Python Versions
aiopinboard is currently supported on:

Python 3.10
Python 3.11
Python 3.12

API Token
You can retrieve your Pinboard API token via
your account's settings page.
Usage
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())

Bookmarks
The Bookmark Object
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 bookmark
href: the bookmark's URL
title: the bookmark's title
description: the bookmark's description
last_modified: the UTC date the bookmark was last modified
tags: a list of tags applied to the bookmark
unread: whether the bookmark is unread
shared: whether the bookmark is shared

Getting the Last Change Datetime
To 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.
Getting Bookmarks
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 by
start: 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 from
to_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 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())

Adding a Bookmark
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 bookmark
tags: an optional list of tags to assign to the bookmark
created_datetime: the optional creation datetime to use (defaults to now)
replace: whether this should replace a bookmark with the same URL
shared: whether this bookmark should be shared
toread: whether this bookmark should be unread

Deleting a Bookmark
To 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())

Tags
Getting Tags
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())

Getting Suggested Tags
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())

Deleting a Tag
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())

Renaming a Tag
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())

Notes
The Note Object
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 ID
title: the title
hash: the computed hash
created_at: the UTC datetime the note was created
updated_at: the UTC datetime the note was updated
length: the length

Getting Notes
To 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())

Contributing
Thanks to all of our contributors so far!

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 on a new branch.
Write tests that cover your new functionality.
Run tests and ensure 100% code coverage: poetry run pytest --cov aiopinboard tests
Update README.md with any new documentation.
Submit a pull request!