A Python3, async interface to the linkding REST API
Project description
🔖 aiolinkding: a Python3, async library to the linkding REST API
aiolinkding
is a Python3, async library that interfaces with
linkding instances. It is intended to be a
reasonably light wrapper around the linkding API (meaning that instead of drowning the user
in custom objects/etc., it focuses on returning JSON straight from the API).
- Python Versions
- Usage
- Contributing
Installation
pip install aiolinkding
Python Versions
aiolinkding
is currently supported on:
- Python 3.8
- Python 3.9
- Python 3.10
Usage
Creating a Client
It's easy to create an API client for a linkding instance. All you need are two parameters:
- A URL to a linkding instance
- A linkding API token
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
asyncio.run(main())
Working with Bookmarks
The Client
object provides easy access to several bookmark-related API operations.
Getting All Bookmarks
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
# Get all bookmarks:
bookmarks = await client.bookmarks.async_get_all()
# >>> { "count": 100, "next": null, "previous": null, "results": [...] }
asyncio.run(main())
client.bookmarks.async_get_all()
takes three optional parameters:
query
: a string query to filter the returned bookmarkslimit
: the maximum number of results that should be returnedoffset
: the index from which to return results (e.g.,5
starts at the fifth bookmark)
Getting Archived Bookmarks
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
# Get all archived bookmarks:
bookmarks = await client.bookmarks.async_get_archived()
# >>> { "count": 100, "next": null, "previous": null, "results": [...] }
asyncio.run(main())
client.bookmarks.async_get_archived()
takes three optional parameters:
query
: a string query to filter the returned bookmarkslimit
: the maximum number of results that should be returnedoffset
: the index from which to return results (e.g.,5
starts at the fifth bookmark)
Getting a Single Bookmark by ID
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
# Get a single bookmark:
bookmark = await client.bookmarks.async_get_single(37)
# >>> { "id": 37, "url": "https://example.com", "title": "Example title", ... }
asyncio.run(main())
Creating a New Bookmark
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
# Create a new bookmark:
created_bookmark = await client.bookmarks.async_create(
"https://example.com",
title="Example title",
description="Example description",
tag_names=[
"tag1",
"tag2",
],
)
# >>> { "id": 37, "url": "https://example.com", "title": "Example title", ... }
asyncio.run(main())
client.bookmarks.async_create()
takes three optional parameters:
title
: the bookmark's titledescription
: the bookmark's descriptiontag_names
: the tags to assign to the bookmark (represented as a list of strings)
Updating an Existing Bookmark by ID
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
# Update an existing bookmark:
updated_bookmark = await client.bookmarks.async_update(
37,
url="https://different-example.com",
title="Different example title",
description="Different example description",
tag_names=[
"tag1",
"tag2",
],
)
# >>> { "id": 37, "url": "https://different-example.com", ... }
asyncio.run(main())
client.bookmarks.async_update()
takes four optional parameters (inclusion of any parameter
will change that value for the existing bookmark):
url
: the bookmark's URLtitle
: the bookmark's titledescription
: the bookmark's descriptiontag_names
: the tags to assign to the bookmark (represented as a list of strings)
Archiving/Unarchiving a Bookmark
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
# Archive a bookmark by ID:
await client.bookmarks.async_archive(37)
# ...and unarchive it:
await client.bookmarks.async_unarchive(37)
asyncio.run(main())
Deleting a Bookmark
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
# Delete a bookmark by ID:
await client.bookmarks.async_delete(37)
asyncio.run(main())
Working with Tags
The Client
object also provides easy access to several tag-related API operations.
Getting All Tags
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
# Get all tags:
tags = await client.tags.async_get_all()
# >>> { "count": 100, "next": null, "previous": null, "results": [...] }
asyncio.run(main())
client.tags.async_get_all()
takes two optional parameters:
limit
: the maximum number of results that should be returnedoffset
: the index from which to return results (e.g.,5
starts at the fifth bookmark)
Getting a Single Tag by ID
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
# Get a single tag:
tag = await client.tags.async_get_single(22)
# >>> { "id": 22, "name": "example-tag", ... }
asyncio.run(main())
Creating a New Tag
import asyncio
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
client = Client("http://127.0.0.1:8000", "token_abcde12345")
# Create a new tag:
created_tag = await client.tags.async_create("example-tag")
# >>> { "id": 22, "name": "example-tag", ... }
asyncio.run(main())
Connection Pooling
By default, the library creates a new connection to linkding with each coroutine. If you
are calling a large number of coroutines (or merely want to squeeze out every second of
runtime savings possible), an
aiohttp
ClientSession
can be used for connection
pooling:
import asyncio
from aiohttp import ClientSession
from aiolinkding import Client
async def main() -> None:
"""Use aiolinkding for fun and profit."""
async with ClientSession() as session:
client = Client("http://127.0.0.1:8000", "token_abcde12345", session=session)
# Get to work...
asyncio.run(main())
Contributing
- 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:
nox -rs coverage
- Update
README.md
with any new documentation. - Add yourself to
AUTHORS.md
. - Submit a pull request!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for aiolinkding-2022.5.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 81725f5b9c421046bc8353f79ada0367b8224290ccd71215e41a69c30653202e |
|
MD5 | 807491297f7bb166e0fb90964ca723e9 |
|
BLAKE2b-256 | 7e1ff7ed5ca24b9ce2da92ce2be66075d0832ef968b25988d81636b3b3681e22 |