63个隐藏开关:rentry metadata元数据选项完整指南
63个隐藏开关:rentry metadata元数据选项完整指南
rentry 是 rentry.co 官方出品的命令行 Markdown pastebin 工具,它的 metadata 元数据字段里藏着约 63 个隐藏开关——改页面标题、调文字颜色、隐藏浏览次数,甚至设置秘密邮箱与 raw 访问码,全都靠它一次搞定。本文基于仓库自带的官方 Python 客户端 src/rentry_client/,带你在 5 分钟内置换完所有常用选项,并讲清 replace 与 upsert 增量更新、SECRET_* 保护机制这两个最容易被坑的细节。
rentry metadata 是什么:藏在 API 里的 63 个开关
在 rentry 的 API 中,metadata 是一个独立字段,可以在 README.md 的「Metadata format」一节看到完整定义:
There are roughly 63 options in total, covering the page itself, sharing, safety, container and content styling, and secrets.
也就是说,这 63 个选项覆盖 5 大类:
| 类别 | 作用 | 典型选项 |
|---|---|---|
| 页面本身(page) | 标题等基础信息 | PAGE_TITLE |
| 分享/统计(sharing) | 是否公开浏览次数等 | OPTION_DISABLE_VIEWS |
| 安全(safety) | 邮箱、raw 访问码、验证码 | SECRET_EMAIL_ADDRESS、SECRET_RAW_ACCESS_CODE、SECRET_VERIFY |
| 容器样式(container) | 页面宽度、内边距 | CONTAINER_MAX_WIDTH、CONTAINER_PADDING |
| 内容样式(content) | 文字颜色等 | CONTENT_TEXT_COLOR |
完整的 63 项清单可在 rentry.co 站内的 metadata-how 页面查阅(站外不在此贴链接)。本文则聚焦「怎么用、怎么改、怎么删」这三件新手最常遇到的问题。
两种写法:rentry metadata 语法速查
metadata 接受两种等价写法(见 README.md):
写法一:换行分隔的 KEY = value 键值对(与网站编辑器一致)
PAGE_TITLE = Hello
CONTAINER_MAX_WIDTH = 600px
写法二:JSON 对象
{"OPTION_DISABLE_VIEWS": true, "CONTENT_TEXT_COLOR": ["grey", "red"]}
用库时更省心——直接把字典传进去,src/rentry_client/client.py 中的 _encode_metadata 会自动帮你序列化成 JSON 字符串:
from rentry_client import RentryClient
client = RentryClient()
# dict 会被自动编码为 JSON;传换行分隔的字符串也可以
page = client.new(
text='hello world',
metadata={'PAGE_TITLE': 'Hello', 'OPTION_DISABLE_VIEWS': True},
)
print(page['url'], page['edit_code'])
可运行的完整版本见 examples/new.py。
⚠️ 小提示:仓库根目录的单文件 CLI rentry.py 走的是纯文本流程,rentry new 命令本身不带 metadata 参数;需要设置元数据时,请用 rentry_client 库或直接调 API。
一键发布带元数据的页面
安装只需一行(无第三方依赖,见 pyproject.toml):
pip install rentry
也可以从源码安装:
git clone https://gitcode.com/gh_mirrors/re/rentry
cd rentry
pip install .
随后像下面这样创建一页「隐藏浏览次数、限宽 600px」的定制页面:
page = client.new(
text='hello world',
metadata={'OPTION_DISABLE_VIEWS': True, 'CONTAINER_MAX_WIDTH': '600px'},
)
print(page['status']) # '200' 表示成功
返回的 JSON 中,status == '200' 即成功;出错时具体原因在 content 与 errors 字段里(详见 client.py 的模块注释)。
replace vs upsert:增量更新别用错模式
这是新手最容易踩的坑。编辑接口有两种 update_mode(见 README.md):
- replace(默认):整页替换——text 和整套 metadata 全被覆盖。省略 text 会把页面清空,省略的选项会被删除。
- upsert:只改你传进来的部分。传了的选项新增或更新,没传的保持原样;用空值(
OPTION =)删除某个选项;省略 text 时正文原样保留。
examples/edit_upsert.py 给出了标准姿势:先建一页,再用 upsert 只加一个 CONTAINER_PADDING,其余选项分毫不动;最后用空值精准移除 CONTAINER_MAX_WIDTH:
# 只新增/更新 CONTAINER_PADDING,其余选项保留
result = client.edit(
page['url_short'], page['edit_code'],
update_mode='upsert',
metadata={'CONTAINER_PADDING': '10px'},
)
# upsert 模式下,空值 = 删除该选项
result = client.edit(
page['url_short'], page['edit_code'],
update_mode='upsert',
metadata={'CONTAINER_MAX_WIDTH': ''},
)
💡 典型场景:只想轮换 edit code、把页面搬到新 URL?加一个 update_mode='upsert' 就能避免 replace 模式「省略 text 清空页面」的副作用,examples/edit_change_url.py 正是这么做的。
SECRET_* 秘密选项保护机制:update_secret_metadata
三个 SECRET_* 选项——SECRET_EMAIL_ADDRESS、SECRET_RAW_ACCESS_CODE、SECRET_VERIFY——受特殊保护(见 README.md):
- 默认情况下(
update_secret_metadata为'false'或缺省),已设置的 SECRET_* 一律原样保留:不管你在请求里省略、留空还是传了新值,全部被忽略。 - 要修改或删除已有的 SECRET_*,必须显式传
update_secret_metadata='true'(库中写update_secret_metadata=True)。 - 新增一个页面原本没有的 SECRET_* 选项则不需要该标志。
最迷惑的一点在 examples/edit_secret_metadata.py 注释里写得很直白:不带标志去改 SECRET,API 会返回 status 200 假装成功,但值根本没变,响应里也没有任何错误。想真正生效,加上标志即可:
result = client.edit(
page['url_short'], page['edit_code'],
text='SECRET changed by this edit',
metadata={'SECRET_EMAIL_ADDRESS': 'new@example.com'},
update_secret_metadata=True, # 显式授权修改 SECRET_*
)
另外,SECRET_RAW_ACCESS_CODE 只能填管理员已签发的代码(向 support@rentry.co 申请),随便填会在编辑时直接被拒。设置后该页面即可被任何人 raw 读取,流程参考 examples/raw.py;CLI 侧对应 rentry raw -u example -a CODE。
验证元数据:用 fetch 拉取页面全部细节
改完记得验证。fetch 需要 edit_code(modify code 也可以),返回 text、views、三个日期,以及 metadata 对象(键值对形式,每个值是该选项的完整字符串)和 metadata_version(见 README.md):
details = client.fetch(page['url_short'], page['edit_code'])
print(details['content']['metadata'])
CLI 等价写法:rentry fetch -u example -p pw。库实现见 client.py,可运行示例见 examples/fetch.py。
5 个新手必知的避坑清单
- 响应永远是 HTTP 200。真正的状态在 JSON 体的
status里:200成功、400校验失败(看errors)、403拒绝、404不存在、429限流、503数据库暂不可用(见 README.md)。 - 匿名创建有频率限制,rentry.co 大约每分钟 10 次,收到
429就等一会再试(见 README.md)。 - replace 模式省略 text = 清空页面。只想改选项或轮换代码时,务必用 upsert。
- modify code 是受限编辑码:
m:xxx形式的代码可以编辑正文,但不能改 edit code、url、modify code 和 SECRET 选项,也不能删页(见 examples/edit_modify_code.py)。传new_modify_code='m:'可取消设置。 - 改 SECRET 未带标志会静默失败:返回 200 但值不变,排查时先抓
fetch的 metadata 对一遍。
结语:把 63 个开关变成你的工具箱
至此,rentry metadata 的核心套路已经齐了:两种语法写、replace/upsert 两种模式改、fetch 一个接口验。仓库的 examples/ 目录为每个 API 场景都备了一份可直接运行的脚本——从建页、改正文、换 URL 到删除、raw 读取,照着跑一遍,63 个隐藏开关就不再是「隐藏」的了。