API and terminal-based CLI for Raindrop.io bookmark manager
Project description
#+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
** Examples
A full suite of examples are provided in the `examples` directory. Each can be run independently as:
#+begin_src shell
[.venv] % python examples/list_collections.py
#+end_src
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:
#+begin_src shell
[.venv] % python examples/RUN_ALL.py
#+end_src
** API Usage
Here are a few examples of API usage (all of these should be able to be executed "as-is"):
*** 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.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:
#+begin_src python
from raindropiopy import version
print(version())
#+end_src
*** 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 [[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.10.tar.gz
(30.5 kB
view hashes)
Built Distribution
Close
Hashes for raindrop_io_py-0.0.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 345642baa3bd28453039981e96268ff21a5b32b08c667d5060bbb9e516ddc1bd |
|
MD5 | 626054913ad4d4365e8912b69f977e03 |
|
BLAKE2b-256 | 36d8100e07e7c0a9920a9f9b7f6b79c70fa9a795ae77dfc7821d0e50418decab |