Core Classes¶

All data classes to interact with Raindrops API.

Raindrop.IO has a small set of core data entities (e.g. Raindrops aka bookmarks, Collections, Tags etc.). We deliver the services provided by Raindrop.IO as a set of class-based methods on these various data entities.

For example, to create a new raindrop, use Raindrop.create_link(…); a collection would be Collection.create(…) etc.

class raindropiopy.models.Access(*, level: AccessLevel, draggable: bool)¶

Bases: BaseModel

Represents Access control level of a Collection.

class raindropiopy.models.AccessLevel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: IntEnum

Map the Access levels defined by Raindrop’s API.

class raindropiopy.models.BrokenLevel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Enumerate user levels.

class raindropiopy.models.Cache(*, status: CacheStatus, size: int | None = None, created: datetime | None = None)¶

Bases: BaseModel

Represents the cache information of Raindrop.

class raindropiopy.models.CacheStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Represents the various states the cache of a Raindrop might be in.

class raindropiopy.models.Collection(*, _id: int = None, title: str, user: UserRef, access: Access | None = None, collaborators: list[Any] | None = None, color: str | None = None, count: NonNegativeInt, cover: list[str] | None = None, created: datetime | None = None, expanded: bool = False, last_update: datetime | None = None, parent: int | None = None, public: bool | None = None, sort: int | None = None, view: View | None = None, other: dict[str, Any] = {})¶

Bases: BaseModel

Represents a Raindrop Collection, ie. a group of Raindrop Bookmarks.

Variables:

id (int) – The id of the collection (required)
title (str) – The name of the collection.
user (raindropiopy.models.UserRef) – The user who created the collection.
access (raindropiopy.models.Access | None) – Describes current Access levels to the collection (eg. ReadOnly, OwnerOnly etc.).
collaborators (list[Any] | None) – Populated with list of collaborating users iff collection is shared.
color (str | None) – Primary color of the collection cover.
count (pydantic.types.NonNegativeInt) – Count of Raindrops in the collection.
cover (list[str] | None) – URL of the collection’s cover.
created (datetime.datetime | None) – When the collection was created.
expanded (bool) – Whether the collection’s sub-collection are expanded (on the interface)
last_update (datetime.datetime | None) – When the collection was last updated.
parent (int | None) – Parent ID of this is a sub-collection.
public (bool | None) – Are contents of this collection available to non-authenticated users?
sort (int | None) – The order of the collection. Defines the position of the collection against all other collections at the same level in the tree (only used for sub-collections?)
view (raindropiopy.models.View | None) – Current view style of the collection, e.g. list, simple, grid etc.
other (dict[str, Any]) – All other attributes received from Raindrop’s API (see Warning below)

Warning

Attributes in other are NOT OFFICIALLY SUPPORTED…use at your own risk!

Create a new Raindrop collection.

Parameters:

api – Required: API Handle to use for the request.
cover – Optional, URL of collection’s cover (as a list but only the first entry is used).
expanded – Optional, flag for whether or not any of the collection’s sub-collections are expanded.
parent – Optional, Id of the collection’s parent you want to create nested collections.
public – Optional, flag for whether or not the collection should be publically available.
sort – Optional, sort order for Raindrops created in this collection.
title – Required: Title of the collection to be created.
view – Optional, View associated with the default view to display Raindrops in this collection.

Returns:

Collection instance created.

classmethod delete(api: API, id: int) → None¶

Delete a Raindrop collection.

Parameters:

api – API Handle to use for the request.
id – Id of Collection to be deleted.

Returns:

None.

classmethod get(api: API, id: int) → Collection¶

Return a Raindrop Collection instance based on it’s id.

Parameters:

api – API Handle to use for the request.
id – Id of Collection to query for.

Returns:

Collection instance associated with the id provided.

Raises:

HTTPError – If the id provided could not be found (specifically 404)

classmethod get_child_collections(api: API) → list[Collection]¶

Get the child Raindrop collections (ie. all below root level).

Parameters:: api – API Handle to use for the request.
Returns:: The (potentially empty) list of non-system, non-top-level Collections associated with the API’s user.

Note

Since Raindrop allows for collections to be nested, the RaindropIO’s API distinguishes between Collections at the top-level/root of a collection hierarchy versus those all that are below the top level, aka ‘child’ collections. Thus, use get_root_collections to get all Collections without parents and get_child_collections for all Collections with parents.

classmethod get_collections(api: API) → list[Collection]¶

Query for all non-system collections (essentially a convenience wrapper, combining root & child Collections).

Parameters:: api – API Handle to use for the request.
Returns:: The (potentially empty) list of all non-system Collections associated with the API’s user, ie. hiding the distinction between root/child collections.

classmethod get_or_create(api: API, title: str) → Collection¶

Get a Raindrop collection based on it’s title, if it doesn’t exist, create it.

Parameters:

api – API Handle to use for the request.
title – Title of the collection.

Returns:

Collection with the specified collection title if it already exists or newly created: collection if it doesn’t.

classmethod get_root_collections(api: API) → list[Collection]¶

Get root Raindrop collections.

Parameters:: api – API Handle to use for the request.
Returns:: The (potentially empty) list of non-system, top-level Collections associated with the API’s user.

Note

Since Raindrop allows for collections to be nested, the RaindropIO’s API distinguishes between Collections at the top-level/root of a collection hierarchy versus those all that are below the top level, aka ‘child’ or ‘sub’ collections. Thus, use get_root_collections to get all Collections without parents and get_child_collections for all Collections with parents.

Update an existing Raindrop collection with any of the attribute values provided.

Parameters:

api – API Handle to use for the request.
id – Required, Id of Collection to be updated.
cover – URL of collection’s cover (as a list but only the first entry is used).
expanded – Flag for whether or not any of the collection’s sub-collections are expanded.
parent – Id of the collection’s parent to set the current collection to.
public – Flag for whether or not the collection should be publically available.
sort – Sort order for Raindrops created in this collection.
title – New collection title.
view – View enum associated with the default view to display Raindrops in this collection.

Returns:

Updated Collection instance.

class raindropiopy.models.CollectionRef(**extra_data: Any)¶

Bases: BaseModel

Represents a reference to a Raindrop Collection (essentially a TypeVar of id: int).

Note: We also instantiate three particular CollectionRefs associated with System Collections:

All, Trash and Unsorted.

System Collections always exist and can be explicitly used to query anywhere you’d use a Collection ID.

class raindropiopy.models.File(*, name: str, size: PositiveInt, type: str)¶

Bases: BaseModel

Represents the attributes associated with a file within a document-based Raindrop.

class raindropiopy.models.FontColor(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Enumerate user display themes available.

class raindropiopy.models.Group(*, title: str, hidden: bool, sort: NonNegativeInt, collections: list[int] = None)¶

Bases: BaseModel

Sub-model defining a Raindrop user group.

class raindropiopy.models.Raindrop(*, _id: int = None, collection: Collection | CollectionRef = CollectionRef(id=-1), cover: str | None = None, created: datetime | None = None, domain: str | None = None, excerpt: str | None = None, file: File | None = None, lastUpdate: datetime | None = None, link: HttpUrl | None = None, media: list[dict[str, Any]] | None = None, tags: list[str] | None = None, title: str | None = None, type: RaindropType | None = None, user: UserRef | None = None, broken: bool | None = None, important: bool | None = None, other: dict[str, Any] = {})¶

Bases: BaseModel

Core class of a Raindrop bookmark ‘item’.

A Raindrop/bookmark can be of two major types:

A link-based one, ie. a standard “bookmark” that points to a specific URL (in the link attribute).
A file-based one, into which a file (of the approved type) is uploaded and stored on the Raindrop service (details of which are in the file attribute).

Variables:

id (int) – The id of the Raindrop.
collection (raindropiopy.models.Collection | raindropiopy.models.CollectionRef) – Collection (or CollectionRef) this Raindrop currently resides in.
cover (str | None) – The URL of the Raindrop’s cover.
created (datetime.datetime | None) – The creation datetime of the Raindrop.
domain (str | None) – Hostname of a link, ie. if a Raindrop has link: https://www.google.com?search=SomeThing, domain is www.google.com.
excerpt (str | None) – Description associated with this Raindrop (maximum length: 10k!)
last_update (datetime.datetime | None) – When this Raindrop was last updated.
link (pydantic.networks.HttpUrl | None) – For a link-based Raindrop, the full URL.
media (list[dict[str, Any]] | None) – Covers list.
tags (list[str] | None) – A list of Tags associated with the Raindrop.
title (str | None) – The title of the Raindrop (maximum length: 1k).
type (raindropiopy.models.RaindropType | None) – The type of the Raindrop, e.g. link, document (I haven’t tested other types)
user (raindropiopy.models.UserRef | None) – The user who created the Raindrop.
broken (bool | None) – True of the link associated with the Raindrop is not reachable anymore.
cache (raindropiopy.models.Cache | None) – Details of the permanent cache associated with the Raindrop.
file (raindropiopy.models.File | None) – Details of the file associated with a file based Raindrop.
important (bool | None) – True if this Raindrop is marked as a Favorite.
other (dict[str, Any]) – All other attributes received from Raindrop’s API.

Warning

Attributes in other are NOT OFFICIALLY SUPPORTED!.

classmethod cache(api: API, id: int) → Response¶: Return the requests on behalf of a permanent copy of the specified Raindrop.

classmethod create_file(api: T_API, path: Path, content_type: str, collection: Collection | CollectionRef, int | None = CollectionRef(id=-1), tags: list[str] | None = None, title: str | None = None) → Raindrop¶

Create a new file-based Raindrop bookmark.

Parameters:

api – API Handle to use for the request.
path – Required, python Path to file to be uploaded.
content_type – Required, mime-type associated with the file.
collection – Optional, Collection (or CollectionRef) to place this Raindrop “into”. If not specified, new Raindrop will be in system Collection Unsorted.
tags – Optional, List of tags to associated with this Raindrop.
title – Optional, Title to associated with this Raindrop.

Returns:

Raindrop instance created.

Note

Only a limited number of file-types are supported by RaindropIO (minimally, “application/pdf”), specifically (as of 2023-02):

Images (jpeg, gif, png, webp, heic)
Videos (mp4, mov, wmv, webm)
Books (epub)
Documents (pdf, md, txt)

Create a new link-type Raindrop bookmark.

Parameters:

api – API Handle to use for the request.
link – Required, URL to associate with this Raindrop.
collection – Optional, Collection (or CollectionRef) to place this Raindrop “into”. If not specified, new Raindrop will be in system Collection “Unsorted”.
cover – Optional, URL of the Raindrop’s “cover”.
excerpt – Optional, long description for the Raindrop (internally, Raindrop call’s it an excerpt but on the UI it’s Description). Maximum length is 10k characters.
important – Optional, Flag to indicate if this Raindrop should be considered important nee a favorite.
media – Optional, List of media dictionaries (consult RaindropIO’s API for somewhat more information.
order – Optional, Order of Raindrop in respective collection, ie. set to 0 to make Raindrop first.
please_parse – Optional, Flag that asks API to automatically parse metadata in the background (not exactly sure which this implies, message me if you know! ;-)
tags – Optional, List of tags to associated with this Raindrop.
title – Optional, Title to associated with this Raindrop.

Returns:

Raindrop instance created.

Note

We don’t allow you to set either created or last_update attributes. They will be set appropriately by the RaindropIO service on your behalf.

classmethod delete(api: API, id: int) → None¶

Delete a Raindrop bookmark.

Parameters:

api – API Handle to use for the request.
id – Required id of Raindrop to be deleted.

Returns:

None.

classmethod get(api: API, id: int) → Raindrop¶: Return a Raindrop bookmark based on it’s id.

classmethod search(api: API, collection: Collection | CollectionRef = CollectionRef(id=0), search: str | None = None) → list[Raindrop]¶

Search for Raindrops.

Parameters:

api – API Handle to use for the request.
collection – Optional, Collection (or CollectionRef) to search over. Defaults to CollectionRef.All.
search – Optional, search string to search Raindrops for (see Raindrop.io Search Help for more information.

Returns:

A (potentially empty) list of Raindrops that match the search criteria provided.

Update an existing Raindrop bookmark, setting any of the attribute values provided.

Parameters:

api – API Handle to use for the request.
id – Required id of Raindrop to be updated.
collection – Optional, Collection (or CollectionRef) to move this Raindrop “into”. If not specified, Raindrop will remain in the same collection as it was.
cover – Optional, new URL to set as the Raindrop’s “cover”.
excerpt – Optional, new long description for the Raindrop. Maximum length is 10,000 characters.
important – Optional, Flag to indicate if this Raindrop should be considered important nee a favorite.
link – Required, New URL to associate with this Raindrop.
media – Optional, Updated list of media dictionaries (consult RaindropIO’s API for somewhat more information.
order – Optional, Change order of Raindrop in respective collection.
please_parse – Optional, Flag that asks API to automatically parse metadata in the background (not exactly sure which this implies, message me if you know! ;-)
tags – Optional, New list of tags to associate with this Raindrop.
title – Optional, New title for this Raindrop.

Returns:

Raindrop instance that was updated.

class raindropiopy.models.RaindropSort(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Enumerate Raindrop sort options available.

class raindropiopy.models.RaindropType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Map the types of Raindrop bookmarks possible (ie. what type of content they hold).

class raindropiopy.models.SystemCollection(*, _id: int = None, count: NonNegativeInt, title: str | None = None)¶

Bases: BaseModel

Raindrop System collection model, ie. collections for Unsorted, Trash and All.

Note

The All collection contains all currently active (ie. non-Trash) Raindrops held by the User.
The Unsorted collection contains Raindrops created that are not held within any other collection.
The Trash collection contains Raindrops that have been recently deleted.

You won’t use this class directly on behalf of individual Raindrops, rather, its definition is on behalf of a small set of simple “status” calls available from the Raindrop.io API, specifically get_counts and get_meta.

classmethod get_counts(api: API) → list[Collection]¶: Get the count of Raindrops in each of the 3 system collections.

classmethod get_meta(api: API) → dict¶

Get the ‘meta’ slug from the root/system Collection.

Contains information about:

Last date/time any bookmark was changed.
The number of broken links in bookmarks.
If your account is a “pro” level.

class raindropiopy.models.Tag(*, _id: str = None, count: int)¶

Bases: BaseModel

Represents existing Tags, either all or just a specific collection.

classmethod delete(api: API, tags: list[str]) → None¶

Delete one or more Tags.

Parameters:

api – API Handle to use for the request.
tags – List of tags to be deleted.

Returns:

None.

classmethod get(api: API, collection_id: int | None = None) → list[Tag]¶

Get all the tags currently defined, either in a specific collections or across all collections.

Parameters:

api – API Handle to use for the request.
collection_id – Optional, Id of specific collection to limit search for all tags.

Returns:

List of Tag.

class raindropiopy.models.User(*, _id: int = None, email: EmailStr, email_MD5: str | None = None, files: UserFiles, fullName: str = None, groups: list[Group], password: bool, pro: bool, proExpire: datetime | None = None, registered: datetime, config: UserConfig)¶

Bases: BaseModel

Raindrop User model.

classmethod get(api: API) → User¶: Get all the information about the Raindrop user associated with the API token.

class raindropiopy.models.UserConfig(*, broken_level: BrokenLevel = None, font_color: FontColor | None = None, font_size: int | None = None, lang: str | None = None, last_collection: CollectionRef | None = None, raindrops_sort: RaindropSort | None = None, raindrops_view: View | None = None, other: dict[str, Any] = {})¶

Bases: BaseModel

Sub-model defining a Raindrop user’s configuration.

Warning

Attributes in other are NOT OFFICIALLY SUPPORTED!.

classmethod cast_last_collection_to_ref(v)¶: Cast last_collection provided as a raw int to a valid CollectionRef.

class raindropiopy.models.UserFiles(*, used: int, size: PositiveInt, lastCheckpoint: datetime = None)¶

Bases: BaseModel

Sub-model defining a file associated with a user (?).

class raindropiopy.models.UserRef(**extra_data: Any)¶

Bases: BaseModel

Represents a reference to User object.

class raindropiopy.models.View(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Map the names of the views for Raindrop’s API.

Core Classes¶

Table of Contents

Previous topic

Next topic

This Page