Pyzotero 分页完全指南：用 everything()、follow() 与生成器攻克 Zotero API 的 100 条返回上限

Pyzotero 分页完全指南用 everything()、follow() 与生成器攻克 Zotero API 的 100 条返回上限【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skillsZotero 的 Web API 在单次请求中默认只返回 100 条条目而真实科研文献库动辄成千上万条。本文以本仓库中 pyzotero skill 的 pagination.md 为核心系统讲解everything()、follow()、iterfollow()、makeiter()以及手动start/limit五类分页方案的适用场景、调用语义与性能注意事项并结合 read-api.md、search-params.md 等关联文档与 SKILL.md 中的完整接入配置帮助你在同步、导出、全文检索等研究自动化工作流中稳定地取回全部数据。一、为什么需要分页Zotero API 的返回上限Pyzotero 是 Zotero Web API v3 的 Python 封装一个Zotero实例绑定到单个用户库或群组库所有读取方法都作用于该库见 SKILL.md。其核心约束是Pyzotero 默认每页返回 100 条条目Zotero API 自身默认只有 25 条。要取回全部数据必须借助分页方法。这一上限适用于所有「可能返回多条结果」的 Read API 调用包括 read-api.md 中列举的items()、top()、trash()、deleted()、publications()、collections()、collection_items()、tags()、groups()等。例如下面这段来自 SKILL.md 快速开始的代码import os from pyzotero import Zotero zot Zotero( library_idos.environ[ZOTERO_LIBRARY_ID], library_typeos.environ.get(ZOTERO_LIBRARY_TYPE, user), api_keyos.environ[ZOTERO_API_KEY], ) # Retrieve top-level items (returns 100 by default) items zot.top(limit10) for item in items: print(item[data][title], item[data][itemType])当items()只返回 100 条时后续条目并不会消失而是停留在 API 的下一页。分页的本质就是通过start/limit参数逐页游标推进或借助 pyzotero 封装好的everything()/follow()/ 生成器方法自动完成翻页。二、everything()一条语句取回全部结果everything()是获取全部结果的最简单方式。它接受任意一个返回多条结果的 Read API 调用自动翻页直至耗尽并返回合并后的完整列表# All items in the library all_items zot.everything(zot.items()) # All top-level items all_top zot.everything(zot.top()) # All items in a collection all_col zot.everything(zot.collection_items(COLKEY)) # All items matching a search all_results zot.everything(zot.items(qmachine learning, itemTypejournalArticle))注意everything()接受的是方法调用本身可迭代对象而非字符串查询参数。这一点与add_parameters()有细微区别若想对everything()内部翻页的每一页都统一设置参数如limit100可先调用zot.add_parameters(...)全局设定再执行zot.everything(zot.items())。everything()适用于所有可能返回多条结果的 Read API。在本仓库其他参考文档中这一模式被反复使用例如 tags.md 中按标签批量重命名时的zot.everything(zot.items(tagold-name))以及 collections.md 中遍历全部集合的zot.everything(zot.collections())。三、follow()手动逐页推进的序列化分页当你不希望一次性取回全部数据而是按批次处理时follow()提供了逐页推进的控制方式# Retrieve items in batches, manually advancing the page first_batch zot.top(limit25) second_batch zot.follow() # next 25 items third_batch zot.follow() # next 25 items警告follow()在无更多数据时会抛出StopIteration且它只对返回多条结果的方法有效不能在zot.item()这类单条查询后使用。其底层语义等价于「记住上一次请求的 start 与 limit下一次调用自动按相同 limit 向前偏移」因此在follow()之间不要穿插其他 Read 调用否则页游标可能被重置。四、iterfollow() 与 makeiter()用生成器惰性翻页面对超大文献库一次性把全部条目装入内存并不划算。pyzotero 提供了两种生成器方案按需逐页拉取。iterfollow()基于 follow() 的生成器# Create a generator over follow() first zot.top(limit10) lazy zot.iterfollow() # Retrieve subsequent pages second next(lazy) third next(lazy)iterfollow()在follow()之上建立惰性迭代每next()一次取回一页直到耗尽时抛出StopIteration。适合「先取首页、再按需翻页」的场景。makeiter()对任意方法创建生成器# Create a generator directly from a method call gen zot.makeiter(zot.top(limit25)) page1 next(gen) # first 25 items page2 next(gen) # next 25 items # Raises StopIteration when exhaustedmakeiter()不依赖预先调用 follow 状态直接把方法调用包装为生成器语义更独立。所有follow()、everything()、makeiter()都只对返回多条结果的方法有效对item()、collection()等单条方法使用会产生非预期行为。五、手动 start/limit 分页最透明的兜底方案当需要对分页过程做细粒度控制如断点续传、多线程并发抓取不同区间时可以绕过封装方法直接使用 search-params.md 中的start结果集偏移量与limit1–100或None参数page_size 50 offset 0 while True: batch zot.items(limitpage_size, startoffset) if not batch: break # process batch for item in batch: process(item) offset page_size该模式以「空列表」作为终止条件比依赖异常更稳健。需要强调的是limit的最大值为 100超出会被 API 拒绝同时 error-handling.md 提醒我们Zotero API 存在速率限制若批量抓取触发TooManyRequests应配合指数退避重试。一个混合示例按标签分页 手动偏移来自 search-params.md# Items with a specific tag, offset for pagination zot.items(tagto-read, limit25, start25)六、性能注意点与 since 增量同步pagination.md 给出了两条直接影响生产工作流的重要建议everything()会串行发起多次 API 请求。对于大型文献库完整取回可能耗时较长应避免在交互式脚本中无谓地全量拉取。对拥有数千条条目的库用sinceversion只取增量变更这特别适合同步类工作流。since参数在 search-params.md 中定义为「只返回该库版本之后修改的对象」。结合 read-api.md 中的版本相关接口可以搭建高效的增量同步管线# 记录当前库版本作为下次同步的起点 version zot.last_modified_version() # 下次同步时仅取回此版本之后的变更 changed_items zot.everything(zot.items(sinceversion)) # 或仅获取变更 key 与版本映射 item_versions zot.item_versions(sinceversion) # 删除项同样依赖 since 参数 deleted zot.deleted(sinceversion)把「首次全量everything() 之后since增量」结合起来即可让文献库同步既完整又高效。若要进一步限制增量范围还可叠加itemType、tag等过滤条件search-params.md 中tag支持 AND/OR/排除语法。七、在真实研究自动化流程中的应用pyzotero skill 在本仓库中属于文献检索与引用管理链条的关键一环见 examples.md 中与open-notebook、citation-management、literature-review、xlsx等 skill 的组合场景。分页方法在其中承担「完整取数」的职责。一个典型流程先zot.everything(zot.items(sincelast_sync))获取增量条目配合全文检索zot.items(qgene editing, qmodeeverything, limit10)search-params.md定位相关文献再交给下游 skill 做去重、分析与导出BibTeX/CSL-JSON见 SKILL.md。八、选择哪个分页方法方法语义适用场景everything()一次调用取回全部并合并列表库规模可控需要完整结果集follow()手动逐页推进耗尽抛StopIteration分批处理、控制拉取节奏iterfollow()follow()的生成器版本惰性逐页消费按需next()makeiter()将任意多结果方法包装为生成器独立创建分页生成器start/limit手动循环显式偏移量翻页空列表终止断点续传、并发分区抓取结合本文的示例代码与关联参考文档你可以针对不同规模的文献库选择合适的分页策略对于千条以上的库务必配合sinceversion增量同步见 read-api.md 的版本信息接口避免每次全量拉取带来的 API 请求压力与耗时。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考