From 0aa69f381dd523f99c8c99c48de01ef572314855 Mon Sep 17 00:00:00 2001 From: Tyler Eastman Date: Wed, 12 Aug 2026 09:32:51 -0700 Subject: [PATCH] docs: standardize extraction example blocks to use Extraction model form MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A surface sweep flagged that three docs showed the `extraction` parameter using a mix of two valid forms within or across code blocks — `Extraction(extraction_mode=ExtractionMode.HIGHLIGHTS, ...)` (the model's strict, validated form) and `extraction={"extraction_mode": "highlights", ...}` (a dict matching `ExtractionTypedDict`). The mixed-form presentation reads as an inconsistency to a first-time reader, even though both forms are equivalent on the wire. Standardized the three primary discoverable docs to the model form, which has the most type-safety and IDE help: * `README.md` "Page content extraction": both `you.search(...)` calls in the snippet now use `Extraction(...)`. Added `ExtractionFormat` to the import. * `docs/models/extraction.md` Example Usage: same. Added `ExtractionFormat` to the import. * `USAGE.md` `` snippet: switched the single `you.search(...)` call from dict form to `Extraction(...)`, matching the README + docs page. Imports updated. `MIGRATION.md` "3.0.0 → 3.1.0" Before/after keeps both forms by design — the section is explicitly labeled "After (3.1.0): extraction" (model) and then "Or as a plain dict (the SDK normalizes at the method layer)" (dict) as a teaching comparison. Left as-is. Each of the standardized docs gets one added sentence in the prose ("You can also pass a dict matching `ExtractionTypedDict`; the SDK normalizes at the method layer.") so callers still learn the alternative form without copy/paste confusion. Verified locally: * 88 unit tests pass (extraction, search, param_normalization, shims). * mypy clean across 81 source files. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- README.md | 22 ++++++++++++---------- USAGE.md | 11 ++++++----- docs/models/extraction.md | 13 ++++++++----- 3 files changed, 26 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 598fe51..9413a0c 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ Pass `extraction` to attach page content to each result. Two modes: ```python import os from youdotcom import You -from youdotcom.models import Extraction, ExtractionMode +from youdotcom.models import Extraction, ExtractionFormat, ExtractionMode with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you: # Query-relevant excerpts in `contents.highlights` (snippets are omitted). @@ -121,18 +121,20 @@ with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you: # Full HTML and/or Markdown in `contents.html` / `contents.markdown`. res = you.search( query="latest quantum computing breakthroughs", - extraction={ - "extraction_mode": "full_page", - "full_page": {"extraction_formats": ["markdown"]}, - }, + extraction=Extraction( + extraction_mode=ExtractionMode.FULL_PAGE, + full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]}, + ), ) ``` -`extraction` replaces the deprecated `livecrawl` / `livecrawl_formats` -parameters. Passing both raises `ValueError`, and top-level `crawl_timeout` -is ignored (stripped from the request body) when `extraction_mode == "highlights"`. -Unknown keys inside -`extraction` raise `ValidationError` locally, matching the server's 422. +You can also pass a dict matching `ExtractionTypedDict` — the SDK +normalizes at the method layer. `extraction` replaces the deprecated +`livecrawl` / `livecrawl_formats` parameters. Passing both raises +`ValueError`, and top-level `crawl_timeout` is ignored (stripped from +the request body) when `extraction_mode == "highlights"`. Unknown keys +inside `extraction` raise `ValidationError` locally, matching the +server's 422. ### Contents diff --git a/USAGE.md b/USAGE.md index a97f4dd..34efedd 100644 --- a/USAGE.md +++ b/USAGE.md @@ -58,7 +58,8 @@ asyncio.run(main()) ```python # Attach full Markdown content to each result via the new `extraction` parameter. import os -from youdotcom import You, models +from youdotcom import You +from youdotcom.models import Extraction, ExtractionFormat, ExtractionMode with You( @@ -68,10 +69,10 @@ with You( res = you.search( query="latest quantum computing breakthroughs", - extraction={ - "extraction_mode": "full_page", - "full_page": {"extraction_formats": ["markdown"]}, - }, + extraction=Extraction( + extraction_mode=ExtractionMode.FULL_PAGE, + full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]}, + ), ) for hit in res.results.web or []: diff --git a/docs/models/extraction.md b/docs/models/extraction.md index 475b87f..01297ef 100644 --- a/docs/models/extraction.md +++ b/docs/models/extraction.md @@ -12,7 +12,7 @@ The `extraction` parameter on `POST /v1/search` controls how page content is att ```python import os from youdotcom import You -from youdotcom.models import Extraction, ExtractionMode +from youdotcom.models import Extraction, ExtractionFormat, ExtractionMode with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you: # Query-relevant excerpts in contents.highlights @@ -24,13 +24,16 @@ with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you: # Full Markdown in contents.markdown res = you.search( query="latest quantum computing breakthroughs", - extraction={ - "extraction_mode": "full_page", - "full_page": {"extraction_formats": ["markdown"]}, - }, + extraction=Extraction( + extraction_mode=ExtractionMode.FULL_PAGE, + full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]}, + ), ) ``` +You can also pass a dict matching `ExtractionTypedDict`; the SDK +normalizes at the method layer. + ## Fields | Field | Type | Required | Description |