teng-lin--notebooklm-py/docs/deprecations.md

Deprecations

This page is the single source of truth for currently-deprecated APIs in notebooklm-py. Each row lists what is deprecated, the recommended replacement, when the deprecation was introduced, when it is scheduled for removal, and any cross-references.

docs/stability.md links here rather than duplicating the table; if you need the broader stability policy (semver promise, supported Python versions, the 0.x pre-1.0 semantics), start there.

Upgrading to v0.8.0? The breaking error-and-return contract changes shipped in v0.8.0. See the consolidated Upgrading to v0.8.0 guide for the full set and the exact before→after migration for each. The NOTEBOOKLM_FUTURE_ERRORS preview flag that staged these changes in v0.7.0 has been removed (it is now a no-op).

Scheduled for removal

Deprecated	Replacement	Since	Removal	Notes
Awaiting NotebookLMClient.from_storage(...)	async with NotebookLMClient.from_storage(...) as client:	v0.5.0	v1.0	The __await__ form still works. Warning emitted via src/notebooklm/_deprecation.py::warn_deprecated; suppress with NOTEBOOKLM_QUIET_DEPRECATIONS=1 (#1369)
MCP research_status(task_id=…) / research_import(task_id=…) / research_cancel(run_id=…)	The same value under poll_task_id=… on all three	v0.8.0	v0.9.0	The three tools each accept the id that research_start / research_status surface as poll_task_id — renamed so the value copies verbatim between tools. The old task_id / run_id param names still work as aliases but emit a DeprecationWarning (via warn_deprecated) and add a deprecation note to the tool result; passing both names with different values is a validation error. (#1789)

The v0.8.0 error-contract runways (get()-returns-None, the wait_for_completion(interval=...) alias, the dict-subscript bridge, NotebooksAPI.share(), and the ambiguous research.poll(task_id=None) guard) all completed their removal cycle in v0.8.0 — see Removed in v0.8.0 below.

Removed in v0.8.0

These error-and-return contract changes completed their v0.7.0 deprecation / preview cycle and are now the default behavior. The full before→after migration for each is in docs/upgrading-to-0.8.0.md.

Removed	Replacement	Deprecated since	Removed in	Notes
sources.get() / artifacts.get() / notes.get() / mind_maps.get() returning None on a miss	get_or_none() (warning-free None-on-miss), or try/except SourceNotFoundError / ArtifactNotFoundError / NoteNotFoundError / MindMapNotFoundError	v0.7.0	v0.8.0	A miss now raises the matching *NotFoundError, unifying the not-found contract with notebooks.get(); return annotations narrow from X | None to X. The v0.7.0 DeprecationWarning (and the warn_get_returns_none helper) are gone. #1247
Dict-subscript access (result["status"]) on research.poll / research.start / research.wait_for_completion, artifacts.generate_mind_map, and sources.get_guide returns	Attribute access (result.status, result.sources, guide.summary, …)	v0.7.0	v0.8.0	The typed returns (ResearchTask / ResearchStart / MindMapResult / SourceGuide / ResearchSource) are now pure attribute-only frozen dataclasses: result["key"] raises TypeError; result.get(...) / .keys() / .items() / .values() raise AttributeError; "k" in result / iter(result) / len(result) raise TypeError. Only attribute access and to_public_dict() survive. ResearchStatus stays a str-enum, so status == "completed" keeps working. The MappingCompatMixin bridge is removed. #1251
ResearchAPI.wait_for_completion(interval=...)	initial_interval=... — same cadence, matching SourcesAPI.wait_until_ready / ArtifactsAPI.wait_for_completion	v0.7.0	v0.8.0	The deprecated interval= keyword alias is gone; passing it now raises the standard TypeError for an unexpected keyword. The deprecated_kwarg helper that powered the alias is removed. #1254
sources.refresh() / chat.delete_conversation() returning True	(no replacement — discard the value)	n/a (clean break)	v0.8.0	Both now return None; their annotations change from -> bool to -> None. The True carried no information (any failure raised first). chat.clear_cache(...) is unchanged and stays -> bool. #1290
Synchronous generation-kickoff refusal swallowed into GenerationStatus(status="failed") / returned None	Catch the re-raised RateLimitError / RPCError / DecodingError / ArtifactFeatureUnavailableError	n/a (clean break)	v0.8.0	generate_* / revise_slide / _parse_generation_result / research.start now raise on a "couldn't-start" refusal instead of returning a soft-failed status. research.start's return narrows from ResearchStart | None to ResearchStart; with_rate_limit_retry retries only on a raised RateLimitError. #1342
Derived-read / lister drift collapsing malformed payloads to empty / None	Catch the raised DecodingError (distinct from a genuine miss)	n/a (clean break)	v0.8.0	sources.check_freshness(), the note lister, and the artifact raw lister now raise DecodingError on a structurally-unrecognized payload. Legitimate empty / stale shapes are unchanged. #1344
notes.update() / sources.rename(return_object=False) / artifacts.rename(return_object=False) silently succeeding on a missing target	Catch the raised *NotFoundError	n/a (clean break)	v0.8.0	These now run an existence preflight and raise NoteNotFoundError / SourceNotFoundError / ArtifactNotFoundError on a miss. return_object=False still returns None on success. #1362
NotebooksAPI.share()	client.sharing.set_public() + client.notebooks.get_share_url()	v0.5.0	v0.8.0	The deprecated no-behavior-change wrapper is removed. #1363
ResearchAPI.poll(task_id=None) / wait_for_completion(task_id=None) silently guessing among multiple in-flight tasks	Pass the explicit task_id from research.start	v0.6.0	v0.8.0	With two or more tasks in flight these now raise the new AmbiguousResearchTaskError instead of warning and returning the latest task; with a single in-flight task they resolve it silently. #1363
NOTEBOOKLM_FUTURE_ERRORS opt-in preview flag	(no replacement — the previewed behavior is now the default)	v0.7.0	v0.8.0	The forward-compat preview gate is removed; setting it is a no-op. The dict-subscript / get-returns-None / kwarg-alias deprecation helpers it gated are deleted with it. #1365
SettingsAPI.get_account_tier() + the AccountTier type (notebooklm.AccountTier / notebooklm.types.AccountTier)	client.settings.get_account_limits() — AccountLimits.tier for the subscription tier (since v0.9.0), plus .notebook_limit / .source_limit for quotas	n/a (clean break)	v0.8.0	The tier came from GET_USER_TIER (live method FetchRecommendations, a promotions endpoint), a promotion-eligibility signal that could not distinguish free from paid — both free and Pro accounts reported NOTEBOOKLM_TIER_PRO_CONSUMER_USER. The authoritative quota signal is AccountLimits. Update (v0.9.0): a correct tier signal is now back as AccountLimits.tier — an opaque enum read from the authoritative GET_USER_SETTINGS limits block (index 4), not the promotions RPC — and the MCP/REST server_info(include_account=True) account block exposes a tier key again (the removed plan_name string does not return).

wait_timeout was deliberately kept. The wait_timeout keyword on the SourcesAPI.add_* family (add_url / add_text / add_file / add_drive) was not renamed to timeout: on those methods timeout would be ambiguous with a per-request HTTP timeout, while wait_timeout reads as "how long to wait for readiness after adding". SourcesAPI.add_file(mime_type=...) and notebooklm source add --mime-type are likewise not deprecated — mime_type sets the resumable-upload content-type header.

notebooklm.rpc public surface tightened — not a removal (v0.8.0, #1589). notebooklm.rpc.__all__ now advertises only the two documented power-user imports, RPCMethod and resolve_rpc_id. The ~47 other names it used to list — the batchexecute wire helpers (encode_rpc_request, decode_response, extract_rpc_result, safe_index, …), the endpoint URL constants/helpers, and the enum / exception re-exports — are not removed: they remain importable as notebooklm.rpc.<name> for back-compat. They were never part of the supported public API (docs/stability.md has always marked notebooklm.rpc.* internal); this change only stops the compat gate from advertising them. New code should import the canonical public name where one exists: most enums as notebooklm.<X> / notebooklm.types.<X>, but ArtifactStatus and artifact_status_to_str only as notebooklm.types.<X>; the exceptions as notebooklm.<X> / notebooklm.exceptions.<X>. The wire helpers, the endpoint URL constants/helpers, safe_index, ArtifactTypeCode, and RPCErrorCode are internal with no blessed public alias and stay importable only as notebooklm.rpc.<name>. For raw-RPC power use, import from notebooklm.rpc import RPCMethod, resolve_rpc_id.

notebooklm.auth public surface tightened — not a removal (v0.8.0, #1592). auth.__all__ no longer advertises 23 internal re-exports that only first-party src/tests imported (cookie-snapshot/storage helpers, the WIZ-extraction helpers, authuser_query/format_authuser_value, load_httpx_cookies/normalize_cookie_map, ALLOWED_COOKIE_DOMAINS/MINIMUM_REQUIRED_COOKIES, the keepalive/refresh env + URL constants, load_auth_from_storage, fetch_tokens, recover_psidts_in_memory). These were migration leftovers from the _auth/* extraction (ADR-0003 → ADR-0014). They are not removed: each remains importable as notebooklm.auth.<name> for back-compat — first-party code now imports them from their notebooklm._auth.<sub> home. notebooklm.auth.* has always been internal (docs/stability.md) except the documented imports (AuthTokens, convert_rookiepy_cookies_to_storage_state, the cookie-domain constants) and the cohesive operations (enumerate_accounts, fetch_tokens_with_domains, fetch_tokens_passive, …), which are unchanged. A deeper service-interface refactor of the remaining cli/_app-forced names was evaluated and deferred (limited encapsulation payoff while names stay importable).

Removed in v0.7.0

Removed	Replacement	Deprecated since	Removed in	Notes
NOTEBOOKLM_STRICT_DECODE=0 soft-mode opt-out	Unset the variable (strict is the only mode)	v0.5.0	v0.7.0	The env var is now ignored; safe_index always raises UnknownRPCMethodError on shape drift. Rationale in docs/stability.md "Strict decode" + ADR-0011
Positional wait / wait_timeout on SourcesAPI.add_url, SourcesAPI.add_text, SourcesAPI.add_file, SourcesAPI.add_drive	Pass wait=... and wait_timeout=... as keywords	v0.5.0	v0.7.0	wait / wait_timeout are now keyword-only; positional calls raise TypeError. CLI already used keyword arguments
ArtifactsAPI.wait_for_completion(poll_interval=...)	initial_interval=... — same cadence, clearer name	v0.5.0	v0.7.0	The poll_interval keyword was removed; passing it raises TypeError
NotesAPI.create_from_chat(...)	ChatAPI.save_answer_as_note(...)	v0.5.0	v0.7.0	Pure deprecated forwarder, now removed (two MINOR cycles of warnings served). ChatAPI.save_answer_as_note(...) is the canonical citation-rich saved-from-chat method and data owner (ADR-0013); call it directly.

Removed in v0.6.0

Removed	Replacement	Deprecated since	Removed in	Notes
NotebookLMClient.rpc_call(source_path=...)	Omit the argument; the canonical "/" default is applied unconditionally	v0.5.0	v0.6.0	Public escape-hatch wrapper kept; only the kwarg was cut. No public replacement — callers that need a non-"/" source path should add a typed sub-client method (open an issue) rather than reaching across the wrapper.
NotebookLMClient.rpc_call(_is_retry=...)	Omit the argument	v0.5.0	v0.6.0	Internal-only retry flag; never part of the supported public surface.
NotebookLMClient.rpc_call(operation_variant=...)	Omit the argument	v0.5.0	v0.6.0	Internal-only routing key for the mutating-RPC idempotency registry.

How deprecations work in this project

• Every deprecated surface emits a DeprecationWarning from the call site the user wrote, so the warning's filename/lineno point at user code rather than at the library internals.
• Default-shape calls remain silent. A deprecation only fires when the caller actually passes the deprecated argument or surface.
• NOTEBOOKLM_QUIET_DEPRECATIONS=1 suppresses every deprecation warning this project emits — the one-off warnings routed through src/notebooklm/_deprecation.py::warn_deprecated (e.g. awaiting from_storage(...)). All mechanics live in _deprecation.py; ADR-0018 forbids inline warnings.warn(..., DeprecationWarning) elsewhere and a lint (tests/_guardrails/test_no_inline_deprecation_warnings.py) enforces it. See docs/configuration.md.
• Not every inline warnings.warn(...) is a deprecation. The save_cookies_to_storage(original_snapshot=None) legacy full-merge path is a permanent public-API back-compat shim (see docs/auth-cookie-lifecycle.md §3.4.1), not a scheduled removal, so it emits a RuntimeWarning safety advisory about the stale-overwrite-fresh race — outside ADR-0018's scope and intentionally not silenced by NOTEBOOKLM_QUIET_DEPRECATIONS.
• NOTEBOOKLM_FUTURE_ERRORS was the v0.7.0 forward-compat preview gate for the v0.8.0 error contract; it was removed in v0.8.0 now that every break it staged is the default, and setting it is a no-op.
• See docs/stability.md "Deprecation Policy" for the broader timeline contract (one MINOR cycle of warnings before removal during 0.x).

Removed in past versions

For deprecations that have already completed their removal cycle, see docs/stability.md "Removed in v0.5.0".