从0.7升级到0.8notebooklm-py破坏性变更与错误返回契约迁移完整指南【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-pynotebooklm-py是一个非官方的 Google NotebookLM Python API 库让你通过 Python、CLI 和 Claude Code 等 AI 代理以编程方式管理笔记本、来源、对话和 AI 生成物——包括 Web 界面没有开放的能力。从0.7 升级到 0.8时你会遇到一组统一的错误与返回契约破坏性变更核心原则只有一条——返回值只表达成功与异步生命周期状态资源不存在、服务端拒绝、响应结构漂移一律抛出类型化异常。⚠️ 先说最重要的0.7.0 用来提前预览新契约的环境变量NOTEBOOKLM_FUTURE_ERRORS已在 0.8.0 中移除设置它不再有任何效果。如果你的 CI 里配了它直接删掉即可。为什么 0.8.0 是契约型版本在 0.7.x 里同一个没找到结果曾用过8 种不同表达方式返回None并告警、静默None、、not_found字符串、ValueError、空哨兵对象……这让调用方难以编写可靠的错误处理。0.8.0 基于 docs/adr/0019-error-and-return-contract.mdADR-0019把所有路径收敛为一句可记住的规则场景0.8.0 的行为资源不存在查不到某个 source/note/artifact抛出对应的*NotFoundError服务端同步拒绝生成限流等抛出RateLimitError/RPCError响应结构无法解析服务端 schema 漂移抛出DecodingError任务已启动但随后失败正常返回statusfailed真实异步数据不抛异常成功但无返回体返回None完整变更清单见 docs/upgrading-to-0.8.0.md版本记录见 CHANGELOG.md废弃 API 登记册见 docs/deprecations.md。9 个破坏性变更速查表#变更0.8.0 的替代写法1sources/artifacts/notes/mind_maps的.get()查不到时返回None改用get_or_none()或try/except *NotFoundError2research.poll等返回值不再支持result[key]字典式取值属性访问result.status、guide.summary3research.wait_for_completion(interval...)关键字别名删除改用initial_interval...4CLIgenerate mind-map默认--kind从 note-backed 翻转为 interactive显式传--kind note-backed或--kind interactive5NotebooksAPI.share()移除改用client.sharing.set_public(...)6多个 research 任务在途且未传task_id时静默取最新任务现在抛出AmbiguousResearchTaskError显式传task_id7生成请求被同步拒绝时返回statusfailed现在抛出RateLimitError/RPCError8notes.update/rename(return_objectFalse)对不存在目标静默成功现在抛出*NotFoundError9sources.refresh/chat.delete_conversation返回恒为True的bool改为返回None成功 不抛异常此外client.settings.get_account_tier()和AccountTier类型被移除旧的等级来自促销接口无法区分免费与付费账号请改用client.settings.get_account_limits()通过AccountLimits.notebook_limit/source_limit读取配额。高频变更详解迁移写法前后通用官方迁移指南给出的所有迁移写法都是前向兼容的——即 0.7.0 和 0.8.0 上都能运行你可以先改代码、再升版本无需停机日。1get()未命中从判空到捕获异常0.8.0 里四个命名空间sources、artifacts、notes、mind_maps的get()未命中时抛出类型化异常如SourceNotFoundError与notebooks.get()保持一致。想要查不到返回 None的老行为用新增的get_or_none()它永远不告警src await client.sources.get_or_none(nb_id, source_id) # 未命中 - None # 或者 try: src await client.sources.get(nb_id, source_id) except SourceNotFoundError: ...所有*NotFoundError类定义在 src/notebooklm/exceptions.py可从notebooklm或notebooklm.exceptions直接导入。2返回值改为纯属性访问research.poll/research.start/artifacts.generate_mind_map/sources.get_guide的返回值ResearchTask、MindMapResult、SourceGuide等现在是纯属性的冻结 dataclassresult[status]抛TypeErrorresult.get(...)、.keys()抛AttributeError。唯一幸存的映射接口是to_public_dict()result await client.research.poll(nb_id) if result.status completed: # ResearchStatus 是 str 枚举字符串比较仍然有效 for source in result.sources: print(source.title, source.url)3CLI 心智地图默认种类翻转0.8.0 里notebooklm generate mind-map默认生成interactive交互式地图与 NotebookLM Web 端一致note-backed 树形模式未废弃显式指定即可notebooklm generate mind-map -n notebook-id --kind note-backed这是纯 CLI 变更Python API 不受影响。命令细节可查 docs/cli-reference.md。4生成被拒绝捕获限流而不是检查状态generate_audio/generate_video等启动类调用被服务端同步拒绝典型如限流时0.7.0 会把它吞进GenerationStatus(statusfailed)——你无法区分没启动和启动后失败。0.8.0 直接抛RateLimitErrorfrom notebooklm import RateLimitError try: status await client.artifacts.generate_audio(nb_id) except RateLimitError: ... # 同步拒绝稍后重试如果只是想要自动重试到成功推荐用内置的with_rate_limit_retry辅助函数它对新契约做了重写0.7.0/0.8.0 双兼容。三步迁移执行清单 暴露所有隐藏告警。Python 默认隐藏DeprecationWarning0.7.x 下先跑一次python -W error::DeprecationWarning -m pytest带告警的变更上表 ✅ 类会逐条指认需要迁移的位置❌ 类是静默破坏需按上文对照检查。应用前向兼容写法。按 docs/upgrading-to-0.8.0.md 中每个条目的 AFTER 写法替换代码——这些写法在 0.7.0 与 0.8.0 上同时有效。过渡期间可用NOTEBOOKLM_QUIET_DEPRECATIONS1静音告警。升级并删除预览开关。升级依赖到 0.8.0 后从环境/CI 配置中删除NOTEBOOKLM_FUTURE_ERRORS它是 no-op然后直接对 0.8.0 验证静默破坏项返回值翻转、拒绝抛错、改名失败 loudly 报错。需要更完整的语义保证semver 承诺、0.x 阶段的废弃策略参考 docs/stability.md想快速上手新版 API 的可运行示例见 examples/ 目录如 examples/chat.py。迁移后常见问题if await client.sources.refresh(...):这种行为翻转了吗是。它 0.7.0 返回True、0.8.0 返回None没有任何前向兼容单行写法——直接删掉真值判断没抛异常即成功。单个 research 任务在途时不传task_id会出错吗不会单任务时仍自动解析只有 ≥2 个任务在途才会抛错。statusfailed以后还能看到吗能——但只表示任务已启动、随后到达终态失败这一真实的异步生命周期数据。按这份清单走从 0.7 到 0.8 的迁移可以完全在应用代码层面完成无数据库、无配置文件的额外动作。✅【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
从0.7升级到0.8：notebooklm-py破坏性变更与错误返回契约迁移完整指南
从0.7升级到0.8notebooklm-py破坏性变更与错误返回契约迁移完整指南【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-pynotebooklm-py是一个非官方的 Google NotebookLM Python API 库让你通过 Python、CLI 和 Claude Code 等 AI 代理以编程方式管理笔记本、来源、对话和 AI 生成物——包括 Web 界面没有开放的能力。从0.7 升级到 0.8时你会遇到一组统一的错误与返回契约破坏性变更核心原则只有一条——返回值只表达成功与异步生命周期状态资源不存在、服务端拒绝、响应结构漂移一律抛出类型化异常。⚠️ 先说最重要的0.7.0 用来提前预览新契约的环境变量NOTEBOOKLM_FUTURE_ERRORS已在 0.8.0 中移除设置它不再有任何效果。如果你的 CI 里配了它直接删掉即可。为什么 0.8.0 是契约型版本在 0.7.x 里同一个没找到结果曾用过8 种不同表达方式返回None并告警、静默None、、not_found字符串、ValueError、空哨兵对象……这让调用方难以编写可靠的错误处理。0.8.0 基于 docs/adr/0019-error-and-return-contract.mdADR-0019把所有路径收敛为一句可记住的规则场景0.8.0 的行为资源不存在查不到某个 source/note/artifact抛出对应的*NotFoundError服务端同步拒绝生成限流等抛出RateLimitError/RPCError响应结构无法解析服务端 schema 漂移抛出DecodingError任务已启动但随后失败正常返回statusfailed真实异步数据不抛异常成功但无返回体返回None完整变更清单见 docs/upgrading-to-0.8.0.md版本记录见 CHANGELOG.md废弃 API 登记册见 docs/deprecations.md。9 个破坏性变更速查表#变更0.8.0 的替代写法1sources/artifacts/notes/mind_maps的.get()查不到时返回None改用get_or_none()或try/except *NotFoundError2research.poll等返回值不再支持result[key]字典式取值属性访问result.status、guide.summary3research.wait_for_completion(interval...)关键字别名删除改用initial_interval...4CLIgenerate mind-map默认--kind从 note-backed 翻转为 interactive显式传--kind note-backed或--kind interactive5NotebooksAPI.share()移除改用client.sharing.set_public(...)6多个 research 任务在途且未传task_id时静默取最新任务现在抛出AmbiguousResearchTaskError显式传task_id7生成请求被同步拒绝时返回statusfailed现在抛出RateLimitError/RPCError8notes.update/rename(return_objectFalse)对不存在目标静默成功现在抛出*NotFoundError9sources.refresh/chat.delete_conversation返回恒为True的bool改为返回None成功 不抛异常此外client.settings.get_account_tier()和AccountTier类型被移除旧的等级来自促销接口无法区分免费与付费账号请改用client.settings.get_account_limits()通过AccountLimits.notebook_limit/source_limit读取配额。高频变更详解迁移写法前后通用官方迁移指南给出的所有迁移写法都是前向兼容的——即 0.7.0 和 0.8.0 上都能运行你可以先改代码、再升版本无需停机日。1get()未命中从判空到捕获异常0.8.0 里四个命名空间sources、artifacts、notes、mind_maps的get()未命中时抛出类型化异常如SourceNotFoundError与notebooks.get()保持一致。想要查不到返回 None的老行为用新增的get_or_none()它永远不告警src await client.sources.get_or_none(nb_id, source_id) # 未命中 - None # 或者 try: src await client.sources.get(nb_id, source_id) except SourceNotFoundError: ...所有*NotFoundError类定义在 src/notebooklm/exceptions.py可从notebooklm或notebooklm.exceptions直接导入。2返回值改为纯属性访问research.poll/research.start/artifacts.generate_mind_map/sources.get_guide的返回值ResearchTask、MindMapResult、SourceGuide等现在是纯属性的冻结 dataclassresult[status]抛TypeErrorresult.get(...)、.keys()抛AttributeError。唯一幸存的映射接口是to_public_dict()result await client.research.poll(nb_id) if result.status completed: # ResearchStatus 是 str 枚举字符串比较仍然有效 for source in result.sources: print(source.title, source.url)3CLI 心智地图默认种类翻转0.8.0 里notebooklm generate mind-map默认生成interactive交互式地图与 NotebookLM Web 端一致note-backed 树形模式未废弃显式指定即可notebooklm generate mind-map -n notebook-id --kind note-backed这是纯 CLI 变更Python API 不受影响。命令细节可查 docs/cli-reference.md。4生成被拒绝捕获限流而不是检查状态generate_audio/generate_video等启动类调用被服务端同步拒绝典型如限流时0.7.0 会把它吞进GenerationStatus(statusfailed)——你无法区分没启动和启动后失败。0.8.0 直接抛RateLimitErrorfrom notebooklm import RateLimitError try: status await client.artifacts.generate_audio(nb_id) except RateLimitError: ... # 同步拒绝稍后重试如果只是想要自动重试到成功推荐用内置的with_rate_limit_retry辅助函数它对新契约做了重写0.7.0/0.8.0 双兼容。三步迁移执行清单 暴露所有隐藏告警。Python 默认隐藏DeprecationWarning0.7.x 下先跑一次python -W error::DeprecationWarning -m pytest带告警的变更上表 ✅ 类会逐条指认需要迁移的位置❌ 类是静默破坏需按上文对照检查。应用前向兼容写法。按 docs/upgrading-to-0.8.0.md 中每个条目的 AFTER 写法替换代码——这些写法在 0.7.0 与 0.8.0 上同时有效。过渡期间可用NOTEBOOKLM_QUIET_DEPRECATIONS1静音告警。升级并删除预览开关。升级依赖到 0.8.0 后从环境/CI 配置中删除NOTEBOOKLM_FUTURE_ERRORS它是 no-op然后直接对 0.8.0 验证静默破坏项返回值翻转、拒绝抛错、改名失败 loudly 报错。需要更完整的语义保证semver 承诺、0.x 阶段的废弃策略参考 docs/stability.md想快速上手新版 API 的可运行示例见 examples/ 目录如 examples/chat.py。迁移后常见问题if await client.sources.refresh(...):这种行为翻转了吗是。它 0.7.0 返回True、0.8.0 返回None没有任何前向兼容单行写法——直接删掉真值判断没抛异常即成功。单个 research 任务在途时不传task_id会出错吗不会单任务时仍自动解析只有 ≥2 个任务在途才会抛错。statusfailed以后还能看到吗能——但只表示任务已启动、随后到达终态失败这一真实的异步生命周期数据。按这份清单走从 0.7 到 0.8 的迁移可以完全在应用代码层面完成无数据库、无配置文件的额外动作。✅【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考