Package: raindrop-io-py
|docs|Raindrop-IO-pyPython wrapper for the API to theRaindrop.ioBookmark Manager.Capabilities include the ability to create, update, delete both link & file-based Raindrops; create, update delete Raindrop collections, tags etc.BackgroundI 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 was incomplete didn't seem actively supported anymore. Thus, this is aforkand significant extension ofpython-raindropio(htAtsuo Ishimoto).StatusAs the API layer is based on a fork of an existing package, it's reasonably stable.RequirementsRequires Python 3.10 or later (well, at least we're developing against 3.11.3).Install[.venv]python-mpipinstallraindrop-io-pySetupTo use this package, you'll need two items:Somewhat obviously, your own account onRaindrop.However, to get API access to Raindrop, you'll need to create anintegration apponRaindropsite from which you can create API token(s).To setup yourintegration app:Go tohttps://app.draindrop.api/settings/integrationsand select+ create new app:Give it a descriptive name and then select the app you just created.SelectCreate test tokenand copy the token provided. Note that the basis for calling it atesttoken is that it only gives you access to bookmarks withinyour own account. Raindrop allows you to use their API against other people's environments using oAuth (see untested/unsupportedflask_oauth.pyfile 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:exportRAINDROP_TOKEN=01234567890-abcdefghf-aSample-API-Token-01234567890-abcdefghf# Or for fish:set-gxRAINDROP_TOKEN01234567890-abcdefghf-aSample-API-Token-01234567890-abcdefghf# etc...ExamplesA full suite of examples are provided in theexamplesdirectory. Each can be run independently as:[.venv]%pythonexamples/list_collections.pyor 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]%pythonexamples/RUN_ALL.pyAPI ExamplesHere are a few examples of API usage. Note that I don't have testing for the examples below (yet), but the examples folder helps significantly as it runs against yourliveRaindrop environment.Display All Collections andUnsortedBookmarks:This example shows the intended usage of the API as a context-manager, from which any number of calls can be made:importosfromdotenvimportload_dotenvfromraindropiopyimportAPI,Collection,CollectionRef,Raindropload_dotenv()withAPI(os.environ["RAINDROP_TOKEN"])asapi:print("Current Collections:"forcollectioninCollection.get_collections(api):print(collection.title)print("\nUnsorted Raindrop Bookmarks:"foriteminRaindrop.search(api,collection=CollectionRef.Unsorted):print(item.title)Create a New Raindrop Bookmark to a URLimportosfromdotenvimportload_dotenvfromraindropiopyimportAPI,Raindropload_dotenv()withAPI(os.environ["RAINDROP_TOKEN"])asapi: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 Collectionimportosimportsysfromdatetimeimportdatetimefromgetpassimportgetuserfromdotenvimportload_dotenvfromraindropiopyimportAPI,Collectionload_dotenv()withAPI(os.environ["RAINDROP_TOKEN"])asapi: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[.venv]%raindropiopyNote: remember to setupRAINDROP-TOKENin your environment!DocumentationWe useSphinxwithGoogle-style docstringsto document our API. Documentation is hosted byReadTheDocsand can be foundhere.Acknowledgmentspython-raindropiofromAtsuo Ishimoto.LicenseThe project is licensed under the MIT License.Release HistoryUnreleased0.2.2 - 2024-01-18INTERNAL: Create whitelist obo vulture to one set of method arguments that are used dynamically.INTERNAL: Moved from stand-alone manage.yaml to incorporate manage commands directly in pyproject.toml (based on manage's 0.2.0 release). Remove manage from local install (run from pipx instead).FIXED: Addressed error in nested Collections, handling case of parent reference as either a dict, an int or None.v0.2.1 - 2023-12-12FIXED: Minor bug in recently updated list_collections.CHANGED: Continued to remove redundant packages.v0.2.0 - 2023-12-12FIXED: Inability to correctly handle "sub" or child collections. We now correctly unpack 'parent' references on querying child collections...(ht to @limaceous-bushwhacker inissue #12).FIXED: Bugs inexamples/list_collections.pyandexamples\list_authorised_user.py) that were using old collection attributeinternal_instead of renamedother(to list theother/non-official attributes associated with a Collection).FIXED: False positives from tests associated with collections (noticed after adding test obo sub/child collections). There are a few tests not supported yet so the examples code (which runs against the live Raindrop environment is still valuable).CHANGED: Split the command-line portion of the library into a completely separate project. This reduces the size and complexity of the install for this package, allowing it to focus solely on the API interaction with Raindrop and allowing me to experiment more freely with different approaches to a command-line interface. If anyone WAS relying upon the CLI itself (hopefully not heavily), please let me know and I'll expedite the creation of the stand-alone CLI project/package.v0.1.8 - 2023-10-03FIXED: Addressed error in README.md (ht to @superkeyor inissue #7.CHANGED:SystemCollections.get_statushas been renamed toSystemCollections.get_countsto more accurately reflect that it only returns the counts of Raindrops in the 3 SystemCollections only.ADDED:SystemCollections.get_metato return the current "state" of your environment, in particular: the date-time associated with the last Raindrop change; if your account is Pro level also the number of "broken" and/or "duplicated" Raindrops in your account.ADDED: Reduced CLI startup time as CLI now keeps cached lists of Collections and Tags in conventional (but platform-specific) application state directory. If no changes to the Raindrop environment have occurred since last invocation (determined by theget_metamethod above), previous state will be used.SECURITY: Addressedgitpythonvulnerabilities (CVE-2023-40590 and CVE-2023-41040). The former is primarily a Windows issue butgitpythonis only used in the poetrydevgroup for release support.SECURITY: Addressedurllib3vulnerability (CVE-2023-43804) inherited from requests library. Similar to above, this is also only used in poetrydevgroup for release support (thus, will attempt to segregate a bit more strongly).v0.1.7 - 2023-08-22SECURITY: Anothertornadoupdate to address vulnerability in parsing Content-Length from header (has a CVE now ➡GHSA-qppv-j76h-2rpx).v0.1.6 - 2023-08-17SECURITY: Updatetornadoto address vulnerability in parsing Content-Length from header (moderate severity, no CVE).v0.1.5 - 2023-08-17SECURITY: Updatecertifito address potential security vulnerability (CVE-2023-37920) (second release attempt)v0.1.4 - 2023-08-17SECURITY: Updatecertifito address potential security vulnerability (CVE-2023-37920).v0.1.3 - 2023-07-20SECURITY: Updatepygmentsto 2.15.1 to address potential security vulnerability.CHANGED: Moved to py 3.11.3.v0.1.2 - 2023-07-08FIXED: Per Issue #5, cachesizemay come back from Raindrop as 0 in some cases, relax pydantic type from PositiveInt toint(Didn't hear anything back from Rustem regarding the cases in which this can (or should?) occur).v0.1.1 - 2023-06-06CHANGED:Raindrop.searchnow only takes a single search string (instead of word, tag or important), leaving search string blank results in correct wildcard search behaviour, addresses issue #4.v0.1.0 - 2023-02-16CHANGED:Raindrop.create_fileto handlecollectionargument consistent withRaindrop.create_link, specifically, either aCollection,CollectionRefor direct integer collection_id.ADDED: Beginning of documentation suite on Read-The-Docs.v0.0.15 - 2023-02-11CHANGED:Raindrop.search_pagedis now hidden (can't see a reason to explicitly use it overRaindrop.search)CHANGED: Several attributes that, while allowed to be set by RaindropIO's API, are nownotable to be set by this API. For example, you shouldn't be able to change "time" by settingcreatedorlast_updatefields on a Raindrop or Collection.CHANGED: TheCollection,RaindropandTag"remove" method is now "delete" to more accurately match with RaindropIO's API).v0.0.14 - 2023-02-09FIXED:Raindrop.cache.sizeandRaindrop.cache.createdattributes 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-07CHANGED: 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 topydanticfor all Raindrop API models.v0.0.12 - 2023-02-06CHANGED: (Internal) Move from README.org to README.md to allow PyPI to display project information correctly.v0.0.11 - 2023-02-06CHANGED: Raindrop search API call is now non-paged (the "paged" version is still available asRaindrop.search_paged).v0.0.10 - 2023-02-05ADDED: 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-04ADDED: An ability to view, edit and delete raindrops returned from a search.ADDED: A simpleRUN_ALL.pyscript 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-25CHANGED: Added simple version method in root package:fromraindropiopyimportversionprint(version())v0.0.7 - 2023-01-25CHANGED: 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-22FIXED: 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-21ADDED: Support use ofVulturefor 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 acryptopackage), we renamed this package to raindrop-io-py. In concert, the internal module is nowraindropiopy:fromraindroiopy.apiimportAPIFIXED: Sample file upload specification inexamples/create_raindrop_file.pyis now correct... |docs| image::https://readthedocs.org/projects/docs/badge/?version=latest:alt: Documentation Status
:scale: 100%
:target:https://docs.readthedocs.io/en/latest/?badge=latest