API and terminal-based CLI for Raindrop.io bookmark manager
Project description
Raindrop-IO-py
Python wrapper for the API to the Raindrop.io Bookmark Manager as well as a simple command-line interface to perform common operations.
Background
I wanted to use an existing API for the Raindrop Bookmark Manager (python-raindropio) to perform some bulk operations through a simple command-line interface. However, the API available was incomplete and didn't contain any user-interface. Thus, this is a fork and significant extension of python-raindropio (ht Atsuo Ishimoto).
This package includes:
- An API providing access to the Raindrop environment. For instance: create, update, delete link/file-based Raindrops; create, update delete Raindrop collections, tags etc.
- A terminal-based user-interface that both tests the API as well as providing (me) a fast, simple interface to my Raindrop collections.
Status
As the API layer is based on a fork of an existing package, it's reasonably stable. However, the command-line interface (CLI) is brand new (and lacking tests, ie. "works for me!" ;-).
Requirements
Requires Python 3.10 or later (well, at least I'm developing against 3.10.9).
Install
[.venv] python -m pip install raindrop-io-py
Setup
To use this package, besides your own account on Raindrop, you'll need to create an integration app
on the Raindrop.io site from which you can create API token(s).
-
Go to https://app.draindrop.api/settings/integrations and select
+ create new app
. -
Give it a descriptive name and then select the app you just created.
-
Select
Create test token
and copy the token provided. Note that the basis for calling it a test token is that it only gives you access to bookmarks within your own account. Raindrop allows you to use their API against other people's environments using oAuth (see untested/unsupportedflask_oauth.py
file in /examples) -
Save your token into your environment (we use python-dotenv so a simple .env/.envrc file containing your token should suffice), for example:
# If you use direnv or it's equivalent, place something like this in a .env file:
RAINDROP_TOKEN=01234567890-abcdefghf-aSample-API-Token-01234567890-abcdefghf
# Or for bash:
export RAINDROP_TOKEN=01234567890-abcdefghf-aSample-API-Token-01234567890-abcdefghf
# Or for fish:
set -gx RAINDROP_TOKEN 01234567890-abcdefghf-aSample-API-Token-01234567890-abcdefghf
# etc...
Examples
A full suite of examples are provided in the examples
directory. Each can be run independently as:
[.venv] % python examples/list_collections.py
or a wrapper script is available to run all of them, in logical order with a small wait to be nice to Raindrop's API:
[.venv] % python examples/RUN_ALL.py
API Examples
Here are a few examples of API usage (all of these should be able to be executed "as-is"):
Display All Collections and Unsorted Bookmarks:
This example shows the intended usage of the API as a context-manager, from which any number of calls can be made:
import os
from dotenv import load_dotenv
from raindropiopy.api import API, Collection, CollectionRef, Raindrop
load_dotenv()
with API(os.environ["RAINDROP_TOKEN"]) as api:
print("Current Collections:"
for collection in Collection.get_collections(api):
print(collection.title)
print("\nUnsorted Raindrop Bookmarks:"
for item in Raindrop.search(api, collection=CollectionRef.Unsorted):
print(item.title)
Create a New Raindrop Bookmark to a URL
import os
from dotenv import load_dotenv
from raindropiopy.api import API, Raindrop
load_dotenv()
with API(os.environ["RAINDROP_TOKEN"]) as api:
link, title = "https://www.python.org/", "Our Benevolent Dictator's Creation"
print(f"Creating Raindrop to: '{link}' with title: '{title}'...", flush=True, end="")
raindrop = Raindrop.create_link(api, link=link, title=title, tags=["abc", "def"])
print(f"Done, id={raindrop.id}")
(after this has executed, go to your Raindrop.io environment (site or app) and you should see this Raindrop to python.org available)
Create a New Raindrop Collection
import os
import sys
from datetime import datetime
from getpass import getuser
from dotenv import load_dotenv
from raindropiopy.api import API, Collection
load_dotenv()
with API(os.environ["RAINDROP_TOKEN"]) as api:
title = f"TEST Collection ({getuser()}@{datetime.now():%Y-%m-%dT%H:%M:%S})"
print(f"Creating collection: '{title}'...", flush=True, end="")
collection = Collection.create(api, title=title)
print(f"Done, {collection.id=}.")
(after this has executed, go to your Raindrop.io environment (site or app) and you should see this collection available)
Command-Line Interface Usage
[.v
env] % raindropiopy
Note: remember to setup RAINDROP-TOKEN
in your environment!
Acknowledgments
License
The project is licensed under the MIT License.
Release History
Unreleased
v0.0.14 - 2023-02-09
- FIXED:
Raindrop.cache.size
andRaindrop.cache.created
attributes are now optional (RaindropIO's API doesn't always provide them). - FIXED: README examples corrected to reflect simpler Raindrop.search call.
v0.0.13 - 2023-02-07
- CHANGED: Cross-referenced the fields available from the Raindrop API with our API; most available but several optional ones skipped for now.
- CHANGED: (Internal) Remove dependency on "jashin" library by moving to pydantic for all Raindrop API models.
v0.0.12 - 2023-02-06
- CHANGED: (Internal) Move from README.org to README.md to allow PyPI to display project information correctly.
v0.0.11 - 2023-02-06
- CHANGED: Raindrop search API call is now non-paged (the "paged" version is still available as
Raindrop.search_paged
).
v0.0.10 - 2023-02-05
- ADDED: Ability to specify raindrop field: Description on a created Raindrop (either file or link-based).
- ADDED: Ability to re-query existing search results (eg. after changes) and smoothed out post-search interactions.
v0.0.9 - 2023-02-04
- ADDED: An ability to view, edit and delete raindrops returned from a search.
- ADDED: A simple
RUN_ALL.py
script to the examples directory to...well, run all the examples in order! - CHANGED: The display of raindrops returned from a search to include tags and to only show Collection name if all raindrops are across multiple collections.
v0.0.8 - 2023-01-25
- CHANGED: Added simple version method in root package:
from raindropiopy import version
print(version())
v0.0.7 - 2023-01-25
- CHANGED: Moved from keeping README in markdown to org file format. Incorporated package's ChangeLog into README as well (at the bottom).
- CHANGED: Added new manage.py release automation capability (internal only, nothing public-facing).
v0.0.6 - 2023-01-22
- FIXED: CLI autocomplete now works again after adding support for "single-letter" command-shortcuts.
- ADDED: A set of missing attributes to the Raindrop API model type, eg. file, cache etc. Only attribute still missing is "highlights".
v0.0.5 - 2023-01-21
- ADDED: Support use of Vulture for dead-code analysis (not in pre-commit through due to conflict with ruff's McCabe complexity metric)
- CHANGED: Moved internal module name to match that of package name. Since we couldn't use raindroppy as a package name on PyPI due to similarities with existing packages (one of which was for a crypto package), we renamed this package to raindrop-io-py. In concert, the internal module is now
raindropiopy
:
from raindroiopy.api import API
- FIXED: Sample file upload specification in
examples/create_raindrop_file.py
is now correct.
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 raindrop_io_py-0.0.14-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d854c325127e314ac2a17818c45a70328128d9abe48a3d60b5e9d3eb0d6d995f |
|
MD5 | 4947cc19f499dfb6bbd820bbb9720cd2 |
|
BLAKE2b-256 | d205e570974f036e1cd0ee5a416bf4f1867029ebb5b2091bdba1145bc4a6cbf4 |