rmcl：reMarkable 云库

rmcl 是一个用于与 reMarkable 云交互的 Python 库。它支持文件树视图，公开元数据，并提供对原始 PDF 或 EPUB 文档的访问。如果 安装了rmrl，它还可以生成包含注释的任何类型文档的 PDF 版本。rmcl 可以从 reMarkable 云中创建、更新和删除项目。

快速演示

作为一种体验，此代码将列出 reMarkable 云根目录中的所有文件及其类型。

from rmcl import Item, Document, Folder
import trio

async def list_files():
    root = await Item.get_by_id('')  # The root folder has ID of empty string
    for child in root.children:
        if isinstance(child, Folder):
            print(f"{child.name}: folder")
        elif isinstance(child, Document):  # The only other possibility
            print(f"{child.name}: {await child.type()}")

trio.run(list_files)

安装

rmcl 需要 Python 3.7 或更高版本。如果已安装，最简单的安装是执行

pip install rmcl

或者，您可以克隆此存储库。 诗歌用于开发，因此一旦安装，您就可以运行

poetry install

设置一个虚拟环境。

rmcl 是异步的，必须与 trio异步库一起使用。

特征

异步

rmcl 的核心是异步的。这使它在它使用的许多 HTTP 事务期间不会阻塞。大多数方法都是async，因此必须使用await关键字调用。rmcl 旨在与trio异步库一起使用。

同步选项

异步代码对于简单的脚本来说可能是多余的，因此 rmcl 提供了所有异步函数的同步版本。这些函数的名称中有后缀'_s'。这意味着上面的例子可以写成

def list_files_sync():
    root = Item.get_by_id_s('')
    for child in root.children:
        if isinstance(child, Folder):
            print(f"{child.name}: folder")
        elif isinstance(child, Document):
            print(f"{child.name}: {child.type_s()}")

请注意，这些同步函数仍在调用异步低级代码。如果在另一个异步框架中调用它们可能会失败。

面向对象

rmcl 的主要接口是Item类及其两个子类， Folder以及Document. reMarkable 云为每个项目提供了一个 ID。如果 Item 的 ID 已知，则可以使用 Item.get_by_id()静态方法检索它。可以使用类方法创建新Folder的 s 和s，该方法期望作为参数的项目名称和父 ID。Document.new()

云 API 呈现平面目录结构，而 rmcl 将这些对象组装成文件树。每个Folder都有一个.children属性，即其中的Items 列表。每个Item都有一个.parent属性，它给出了其父级的 ID。（给出 ID 而不是父对象以避免循环引用。） 的父对象item可以用 查找await Item.get_by_id(item.parent)。

提供了两个“虚拟”文件夹。根文件夹 (ID = '') 包含所有Item没有明确父级的 s。垃圾文件夹 (ID = 'trash') 包含所有Item标记为已丢弃的 s。

各种元数据作为属性公开：.name、.id、.version、 .parent和.mtime, 用于修改时间。和 属性可以修改，从而更新底层元数据.name。.parent可以使用该方法将此类更改发送到云端.update_metadata()。

Document可以通过多种方式检索 s的内容。该 .raw()方法获取 reMarkable 云 API 用于传输文档的 zip 文件。该.contents()方法获取与Document. 如果 安装了rmrl，该.annotated() 方法会生成一个带有用户注释的 PDF 文件。所有三个方法都返回一个类似文件的对象，但不能保证确切的类型，并且将来可能会有所不同。对给定方法的多次调用可能会返回同一个对象；用户负责协调reads 和 seeks 以避免争用。

新Item的或已有Document的新内容可以通过.upload()方法上传到云端。

智能更新

rmcl 保留 reMarkable 云中所有文档的列表，因此它不需要查询 API 的每一位信息。为确保此列表是最新的，它会在您 Item.get_by_id()上次刷新后使用超过五分钟时自动刷新。您也可以通过调用rmcl.invalidate_cache() before来触发此行为Item.get_by_id()。

rmcl 仅更新具有新版本的对象，因此现有对象仍然有效。尽管如此，最好Item.get_by_id() 经常调用，而不是保留自己的Items 列表。

缓存昂贵的操作

其中一些信息，如文档类型和大小，需要多次往返才能计算。rmcl 将这些值存储在本地，因此不需要每次都重新计算。它们存储在持久数据库中，因此当进程停止时，这些信息不会丢失。数据库按版本存储此信息，因此它知道何时必须重新计算。

处理身份验证

reMarkable 云需要两个令牌：设备令牌标识您的设备，只需设置一次。用户令牌用于大多数请求，应不时更新。rmcl 每天自动更新一次用户令牌，或者当它收到来自 API 的身份验证错误时。

获取设备令牌需要在第一次运行程序时进行用户交互。如果 rmcl 检测到它正在以交互方式运行，它将打印指令并提示用户输入新的设备令牌。否则，它会抛出一个rmcl.exceptions.AuthError. 您必须 使用从https://my.remarkable.com/connect/desktopregister_device(code)获得的代码进行 调用。一旦获得，设备令牌将被存储以备将来使用。

与 rMapy 的比较

rmcl 最初是rMapy的一个分支。当我们开始朝着一个完全不同的方向前进时，我们决定将其纳入自己的项目会更好。此时，只剩下 rMapy 的一些低级 API 代码。

为了帮助用户决定哪个库最适合他们的需求，主要区别如下：

• rmcl 是异步的，而 rMapy 是同步的。这意味着 rmcl 在向 reMarkable API 发出 HTTP 请求时不会阻塞。rmcl 的同步函数会阻塞，很像 rMapy。
• rmcl 具有更简单的对象结构，主要集中在Item及其子类Document和Folder. rMapy 有类似的对象（Meta、Document和Folder），但它也有 aClient和 Collection单例对象，获取文档或列出目录等操作都是由这些单例提供的。
• rmcl 抽象了 reMarkable 云 API 的一些细节，而 rMapy 提供了 API 到 Python 的更直接的映射。例如，rMapy 项目有一个.VissibleName [sic]属性，因为这是 API 提供的。rmcl 把它变成一个.name属性。在 rmcl 中，Folders 有一个孩子列表，但在 rMapy 中，必须通过单例查找孩子Collection。（API 提供了一个平面文件列表。）
• rMapy 比 rmcl 更完整。rMapy 将所有元数据作为属性公开，而 rmcl 仅公开一些元数据项。rMapy 为 API 提供的 zip 文件提供对象模型，而 rmcl 只是公开 zip 文件本身。
• rMapy 比 rmcl 有更好的文档 。（但我们正在努力！）

商标

reMarkable(R) 是 reMarkable AS 的注册商标。rmrl 不隶属于 reMarkable AS，也不受其认可。本作品中使用的“reMarkable”是指该公司的电子纸平板产品。

版权

版权所有 2019 Stijn Van Campenhout

版权所有 2020-2021 罗伯特·施罗尔

rmcl 在 MIT 许可下发布。有关详细信息，请参阅 LICENSE.txt。