把rentry写进你的代码:rentry_client库与RentryClient Python API实战
把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 | 用访问码读取原文 |
最佳实践清单
- 限流意识:匿名创建按 IP 限流(官方实例约每分钟 10 次),收到
429请指数退避重试 - 删除谨慎:
delete()只认完整编辑码,modify code 无法删除 - fetch 返回丰富:包含
views、pub_date、edit_date、modify_code_set等字段,适合做监控或审计 - 自托管友好:
RentryClient('https://your-server')一行切换实例,也可用.env里的BASE_PROTOCOL/BASE_URL统一配置
掌握以上内容,你就能在自己的 Python 项目里把 rentry 当作可靠的 Markdown 发布后端——从日志归档、报告分发到动态页面更新,几行 RentryClient 调用即可搞定。