From a956fbf566a93007dda46c22b2f51464b9bd59f4 Mon Sep 17 00:00:00 2001 From: Tyler Eastman Date: Fri, 21 Aug 2026 10:07:41 -0700 Subject: [PATCH] docs: reorder all MIGRATION.md sections newest-first MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 3.0.0 → 3.1.0 section was below 2.5.0 → 3.0.0, and the 1.x → 2.0 section was below 1.x → 2.3.0. All migration sections are now sorted by source version descending, matching the 3.1.2 section already at top. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- MIGRATION.md | 216 +++++++++++++++++++++++++-------------------------- 1 file changed, 108 insertions(+), 108 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 596d056..2804cf6 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -62,6 +62,114 @@ if evt.event == "completed": ... ``` +## 3.0.0 → 3.1.0 + +> **Recommended migration only — no code change required.** `livecrawl` and `livecrawl_formats` still work on `POST /v1/search` and now emit `DeprecationWarning`. Adopt `extraction` when convenient; removal is targeted for 4.0.0. + +### Why migrate + +`extraction` is a typed object with strict validation (`extra="forbid"`), so the SDK fails fast on unknown keys and wrong-mode couplings. `livecrawl` is stringly typed and only validates on the server. The new `extraction_mode="highlights"` also returns query-relevant excerpts in `contents.highlights` — closer to what most callers actually want — at a fraction of the tokens of `full_page`. + +### Migration mapping + +| Old | New | +|-----|-----| +| `livecrawl="web"` + `livecrawl_formats=["markdown"]` | `extraction={"extraction_mode": "full_page", "full_page": {"extraction_formats": ["markdown"]}}` | +| `livecrawl="all"` + `livecrawl_formats=["html", "markdown"]` | `extraction={"extraction_mode": "full_page", "full_page": {"extraction_formats": ["html", "markdown"]}}` | +| `livecrawl="news"` + `livecrawl_formats=["markdown"]` | `extraction={"extraction_mode": "full_page", "full_page": {"extraction_formats": ["markdown"]}}` (now covers both web and news) | +| Omitting `livecrawl` (snippets only) | Omit `extraction` (default behavior unchanged), or `extraction={"extraction_mode": "highlights"}` to swap snippets for query-relevant excerpts at the same latency | + +Notes: + +- `livecrawl` supported `"web"`, `"news"`, `"all"` modes. `extraction_mode` does not have a per-section switch — `"highlights"` and `"full_page"` apply to all sections in the response. + +### Before / after + +```python +import os + +from youdotcom import You +from youdotcom.models import ( + Extraction, + ExtractionFormat, + ExtractionMode, + LiveCrawl, + LiveCrawlFormats, +) + +with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you: + # Before (3.0.x): livecrawl + formats + you.search( + query="quantum computing tutorials", + count=5, + livecrawl=LiveCrawl.WEB, + livecrawl_formats=[LiveCrawlFormats.MARKDOWN], + ) + + # After (3.1.0): extraction + you.search( + query="quantum computing tutorials", + count=5, + extraction=Extraction( + extraction_mode=ExtractionMode.FULL_PAGE, + full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]}, + ), + ) + + # Or as a plain dict (the SDK normalizes at the method layer) + you.search( + query="quantum computing tutorials", + count=5, + extraction={ + "extraction_mode": "full_page", + "full_page": {"extraction_formats": ["markdown"]}, + }, + ) +``` + +### Highlights mode (new option that didn't exist with livecrawl) + +```python +import os + +from youdotcom import You + +with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you: + res = you.search( + query="how does X relate to Y", + extraction={"extraction_mode": "highlights"}, + ) +# Returns res.results.web[i].contents.highlights (List[str]) -- excerpts +# that match the query, not whole pages. Snippets are omitted in this mode. +``` + +### Conflict and plus-value rule + +`extraction` cannot be combined with `livecrawl` or `livecrawl_formats` (raises `ValueError` locally before round-tripping). And top-level `crawl_timeout` is invalid alongside `extraction_mode="highlights"` — the SDK strips `crawl_timeout` from the request body in that case (default silently, with `UserWarning` if you set a non-default value). + +### No upgrade-time action required + +Calls using `livecrawl` / `livecrawl_formats` continue to work, just with a `DeprecationWarning`: + +```python +import os +import warnings + +from youdotcom import You + +with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you: + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + you.search( + query="...", + livecrawl="web", + livecrawl_formats=["markdown"], + ) + deprecations = [w for w in caught if issubclass(w.category, DeprecationWarning)] + # str(deprecations[0].message) == "livecrawl is deprecated; use extraction instead" +``` + + ## 2.5.0 → 3.0.0 > **This release adds the Answer API, removes the Agents API, and makes `search()` a direct method on `You`.** The old sub-SDK patterns still work but emit `DeprecationWarning`. Migrate at your convenience. @@ -252,114 +360,6 @@ To see deprecation warnings in your code: python -W default::DeprecationWarning your_script.py ``` -## 3.0.0 → 3.1.0 - -> **Recommended migration only — no code change required.** `livecrawl` and `livecrawl_formats` still work on `POST /v1/search` and now emit `DeprecationWarning`. Adopt `extraction` when convenient; removal is targeted for 4.0.0. - -### Why migrate - -`extraction` is a typed object with strict validation (`extra="forbid"`), so the SDK fails fast on unknown keys and wrong-mode couplings. `livecrawl` is stringly typed and only validates on the server. The new `extraction_mode="highlights"` also returns query-relevant excerpts in `contents.highlights` — closer to what most callers actually want — at a fraction of the tokens of `full_page`. - -### Migration mapping - -| Old | New | -|-----|-----| -| `livecrawl="web"` + `livecrawl_formats=["markdown"]` | `extraction={"extraction_mode": "full_page", "full_page": {"extraction_formats": ["markdown"]}}` | -| `livecrawl="all"` + `livecrawl_formats=["html", "markdown"]` | `extraction={"extraction_mode": "full_page", "full_page": {"extraction_formats": ["html", "markdown"]}}` | -| `livecrawl="news"` + `livecrawl_formats=["markdown"]` | `extraction={"extraction_mode": "full_page", "full_page": {"extraction_formats": ["markdown"]}}` (now covers both web and news) | -| Omitting `livecrawl` (snippets only) | Omit `extraction` (default behavior unchanged), or `extraction={"extraction_mode": "highlights"}` to swap snippets for query-relevant excerpts at the same latency | - -Notes: - -- `livecrawl` supported `"web"`, `"news"`, `"all"` modes. `extraction_mode` does not have a per-section switch — `"highlights"` and `"full_page"` apply to all sections in the response. - -### Before / after - -```python -import os - -from youdotcom import You -from youdotcom.models import ( - Extraction, - ExtractionFormat, - ExtractionMode, - LiveCrawl, - LiveCrawlFormats, -) - -with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you: - # Before (3.0.x): livecrawl + formats - you.search( - query="quantum computing tutorials", - count=5, - livecrawl=LiveCrawl.WEB, - livecrawl_formats=[LiveCrawlFormats.MARKDOWN], - ) - - # After (3.1.0): extraction - you.search( - query="quantum computing tutorials", - count=5, - extraction=Extraction( - extraction_mode=ExtractionMode.FULL_PAGE, - full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]}, - ), - ) - - # Or as a plain dict (the SDK normalizes at the method layer) - you.search( - query="quantum computing tutorials", - count=5, - extraction={ - "extraction_mode": "full_page", - "full_page": {"extraction_formats": ["markdown"]}, - }, - ) -``` - -### Highlights mode (new option that didn't exist with livecrawl) - -```python -import os - -from youdotcom import You - -with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you: - res = you.search( - query="how does X relate to Y", - extraction={"extraction_mode": "highlights"}, - ) -# Returns res.results.web[i].contents.highlights (List[str]) -- excerpts -# that match the query, not whole pages. Snippets are omitted in this mode. -``` - -### Conflict and plus-value rule - -`extraction` cannot be combined with `livecrawl` or `livecrawl_formats` (raises `ValueError` locally before round-tripping). And top-level `crawl_timeout` is invalid alongside `extraction_mode="highlights"` — the SDK strips `crawl_timeout` from the request body in that case (default silently, with `UserWarning` if you set a non-default value). - -### No upgrade-time action required - -Calls using `livecrawl` / `livecrawl_formats` continue to work, just with a `DeprecationWarning`: - -```python -import os -import warnings - -from youdotcom import You - -with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you: - with warnings.catch_warnings(record=True) as caught: - warnings.simplefilter("always") - you.search( - query="...", - livecrawl="web", - livecrawl_formats=["markdown"], - ) - deprecations = [w for w in caught if issubclass(w.category, DeprecationWarning)] - # str(deprecations[0].message) == "livecrawl is deprecated; use extraction instead" -``` - - ## 2.4.0 → 2.5.0 ### New `frontier` Research Effort Tier