API and terminal-based CLI for Raindrop.io bookmark manager
Project description
#+options: toc:nil ^:nil
#+attr_html: :style width: 100px
#+toc: headlines 2
#+begin_export html
<div align="center">
<a href="https://choosealicense.com/licenses/mit/">
<img alt="MIT License"
src="https://img.shields.io/badge/License-MIT-green.svg" />
</a>
<a href="https://www.python.org/">
<img alt="Python Version"
src="https://img.shields.io/badge/python-3.10+-green" />
</a>
<a href="https://github.com/pre-commit/pre-commit">
<img alt="pre-commit"
src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit" />
</a>
</div>
#+end_export
* Raindrop-IO-py
Python wrapper for the API to the [[https://raindrop.io][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 ([[https://github.com/atsuoishimoto/python-raindropio][python-raindropio]]) to perform some bulk operations through a simple command-line interface. However, the API available was incomplete and didn't contain any interface. Thus, this is a _fork_ and significant extension of [[https://github.com/atsuoishimoto/python-raindropio][python-raindropio]] (thanks [[https://github.com/atsuoishimoto][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
#+BEGIN_SRC shell
[.venv] python -m pip install raindrop-io-py
#+END_SRC
** Setup
To use this package, besides your own account on [[https://raindrop.io][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.raindrop.io/settings/integrations][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/unsupported flask_oauth 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:
#+BEGIN_SRC shell
# 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...
#+END_SRC
** API Usage & Examples
A full suite of examples are provided in the `examples` directory, here are a few to give you some idea of the usage model:
*** Create a New Raindrop Bookmark to a URL
#+BEGIN_SRC python
import os
import sys
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}")
#+END_SRC
(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
#+BEGIN_SRC python
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=}.")
#+END_SRC
(after this has executed, go to your Raindrop.io environment (site or app) and you should see this collection available)
*** Display All Bookmarks from the *Unsorted* Raindrop Collection
#+BEGIN_SRC python
import os
from dotenv import load_dotenv
from raindropiopy.api import API, CollectionRef, Raindrop
load_dotenv()
with API(os.environ["RAINDROP_TOKEN"]) as api:
page = 0
while (items := Raindrop.search(api, collection=CollectionRef.Unsorted, page=page)):
for item in items:
print(item.title)
page += 1
#+END_SRC
** Command-Line Interface Usage
#+BEGIN_SRC shell
[.venv] % raindropiopy
#+END_SRC
Note: remember to setup RAINDROP_TOKEN in your environment!
** Acknowledgments
- [[https://github.com/atsuoishimoto/python-raindropio][python-raindropio]] from [[https://github.com/atsuoishimoto][Atsuo Ishimoto]].
** License
The project is licensed under the MIT License.
** Release History
*** Unreleased...
*** v0.0.7 - 2023-01-24
- CHANGED: Added simple version method in root package (~from raindropiopy import version;print(version())~)
- 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 [[https://github.com/jendrikseipp/vulture][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~:
#+BEGIN_SRC python
from raindroiopy.api import API
#+END_SRC
- 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
raindrop_io_py-0.0.7.tar.gz
(26.6 kB
view hashes)
Built Distribution
Close
Hashes for raindrop_io_py-0.0.7-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bde7426bc3d7647a23795d394ae4e0b20ee750e875a92779f3440dd6a1c2e1d7 |
|
MD5 | cb6a30e62678abaa4e758c45e5790287 |
|
BLAKE2b-256 | 4dd4f7ee09495a1741be73876a5e250c0f410558a0393303f9823f461ef625ea |