把rentry写进你的代码:rentry_client库与RentryClient Python API实战

原创2026-11-18 09:48:091,633 阅读

把rentry写进你的代码:rentry_client库与RentryClient Python API实战

rentry 是一个 Markdown 粘贴发布服务,而 rentry_client 就是它官方的 Python 客户端库:核心只有一个 RentryClient 类,零依赖、几行代码就能在你的项目里创建、编辑、读取和删除粘贴页面。本文将带你从零跑通 RentryClient Python API 的完整流程。

一键安装:rentry_client 怎么引入项目

一条命令即可,无需任何第三方依赖:

pip install rentry

这条命令会同时安装两样东西:

  • rentry 命令行工具:单文件、零依赖,适合临时在终端贴内容
  • rentry_client 库:可导入的 Python 包,本文的主角

如果希望从源码安装,可执行 git clone https://gitcode.com/gh_mirrors/re/rentry 后进入目录运行 pip install .。包的核心实现都在 client.py 这一个文件里,RentryClient 类从 init.py 导出,版本要求 Python ≥ 3.9(见 pyproject.toml)。

三步上手 RentryClient:创建、编辑、读取页面

创建客户端不需要传参,默认指向官方实例;如果想连接自己部署的实例,传入 base_url 即可。

from rentry_client import RentryClient

client = RentryClient()  # 或 RentryClient('https://my-instance.example')

# 第 1 步:创建页面(url 和 edit_code 不传则自动生成)
page = client.new(text='hello world',
                  metadata={'PAGE_TITLE': 'Hello'})
print(page['url'], page['edit_code'])

# 第 2 步:用编辑码修改文本
client.edit(page['url_short'], page['edit_code'], text='updated!')

# 第 3 步:拉取完整详情(文本、元数据、浏览量、时间戳)
print(client.fetch(page['url_short'], page['edit_code']))

每个方法都直接返回 解析好的 JSON 字典,不需要你再做 json.loads。client.new() 的参数与 new.py 示例一一对应;编辑的官方演示在 edit.py。

⚠️ 记住 edit_code!它只会在创建时展示一次,是后续编辑、删除的钥匙,建议存进数据库或密钥管理工具。

返回值怎么读:status、content 与 errors

所有方法都遵循同一个响应结构(API 端点始终返回 HTTP 200,真正的状态要看 JSON 内部):

字段 含义
status 状态码字符串,'200' 表示成功
content 成功时为具体数据;失败时为错误描述
errors 校验失败时的字段级错误信息

推荐的检查写法(示例脚本中普遍采用):

result = client.new(text='hello world')
assert result['status'] == '200', result['content']

需要重点处理的状态码:400 校验失败(详情在 errors)、403 拒绝访问(raw 访问码)、404 页面不存在、429 限流(退避后重试)、503 数据库暂时不可用。

只改一个配置项?用 upsert 避免整页覆盖

metadata 有两种等价写法:换行分隔的 KEY = value 字符串,或字典(字典会被自动转成 JSON 发送,见 _encode_metadata)。

edit() 的 update_mode 决定覆盖范围,这是最容易踩坑的地方:

  • replace(默认):整页替换。不传 text 会清空页面,元数据没传的配置项会被移除
  • upsert:只改动你传入的项,其余文本与元数据原样保留;传空值(OPTION = )可删除某项

只加一个配置项的正确姿势(完整演示见 edit_upsert.py):

client.edit(page['url_short'], page['edit_code'],
            update_mode='upsert',
            metadata={'CONTAINER_PADDING': '10px'})

💡 元数据总共约 63 个选项,涵盖页面、分享、安全、容器与内容样式等分类,具体语义以 rentry 官方 metadata 文档为准。

团队协作用 modify code:能编辑但抢不走

把完整 edit_code 发给别人,对方就拥有了"夺走"页面的能力。更安全的做法是设置一个 modify code(以 m: 开头):持码者可编辑文本,但不能修改编辑码、URL、SECRET 项,也不能删除页面。

# 用编辑码设置 modify code(传 'm:' 可解除)
client.edit(page['url_short'], page['edit_code'],
            new_modify_code='m:team-code')

# 之后直接用 modify code 编辑
client.edit(page['url_short'], 'm:team-code', text='edited by teammate')

该流程可对照 edit_modify_code.py 运行。

换 URL、轮换编辑码与 SECRET 元数据保护

迁移页面 + 轮换编辑码:用 upsert 模式同时指定 new_url 和 new_edit_code,文本与元数据不受影响,旧 URL 和旧编辑码随即失效(见 edit_change_url.py)。

SECRET 元数据保护:SECRET_EMAIL_ADDRESS、SECRET_RAW_ACCESS_CODE、SECRET_VERIFY 默认受保护——即使你发起 replace 模式的编辑,已设置的 SECRET 项也会被原样保留。若要修改或删除它们,必须显式传 update_secret_metadata=True(Python 布尔值即可,客户端会自动转成字符串 'true',实现见 client.py)。完整示例见 edit_secret_metadata.py。

raw 接口:读取原始 Markdown 文本

client.raw(url, auth_code=None) 用于获取页面的原始 Markdown。注意 raw 访问默认不开放,满足其一才放行:

  • 请求携带管理员签发的访问码(通过 auth_code 传入,对应 HTTP 头的 rentry-auth)
  • 页面自身设置了已签发的 SECRET_RAW_ACCESS_CODE

访问码需向 rentry 管理员申请。参考实现:raw.py,命令行对应写法见 rentry.py。

示例脚本导航:一个场景一个文件

examples/ 目录下每个脚本对应一种 API 用法,装上 python-dotenv(pip install -r requirements.txt)后可直接运行:

脚本 场景
new.py 创建带元数据的页面
edit.py 用编辑码更新文本
edit_upsert.py 局部修改元数据不覆盖其余项
edit_modify_code.py 设置 modify code 并用它编辑
edit_secret_metadata.py 修改/移除 SECRET_* 元数据
edit_change_url.py 换 URL 并轮换编辑码
fetch.py 拉取页面完整详情
delete.py 删除页面(需要完整编辑码)
raw.py 用访问码读取原文

最佳实践清单

  1. 限流意识:匿名创建按 IP 限流(官方实例约每分钟 10 次),收到 429 请指数退避重试
  2. 删除谨慎:delete() 只认完整编辑码,modify code 无法删除
  3. fetch 返回丰富:包含 views、pub_date、edit_date、modify_code_set 等字段,适合做监控或审计
  4. 自托管友好:RentryClient('https://your-server') 一行切换实例,也可用 .env 里的 BASE_PROTOCOL / BASE_URL 统一配置

掌握以上内容,你就能在自己的 Python 项目里把 rentry 当作可靠的 Markdown 发布后端——从日志归档、报告分发到动态页面更新,几行 RentryClient 调用即可搞定。

登录后查看全文
rentry