Docs sweep: standardize extraction example blocks (3.1.0 release) - #41
Merged
Conversation
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` `<!-- extraction -->` 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>
Contributor
|
Droid finished @tyler5673's task —— View job Review complete. Docs updates look good and the examples remain copy-paste runnable with |
![factory-droid[bot]](https://avatars.githubusercontent.com/in/358017?s=60&v=4){kind=small}
Comment on lines
+131
to
+132
| You can also pass a dict matching `ExtractionTypedDict` — the SDK | ||
| normalizes at the method layer. `extraction` replaces the deprecated |
Contributor
There was a problem hiding this comment.
[P1] Fix misleading “normalizes” claim for ExtractionTypedDict
The README currently says the SDK “normalizes at the method layer”, but the implementation validates via Extraction.model_validate(...) and does not perform casing normalization, so dict inputs must use the exact enum value spellings (e.g., "full_page", "markdown") or enums or callers will hit a ValidationError.
Suggested change
| You can also pass a dict matching `ExtractionTypedDict` — the SDK | |
| normalizes at the method layer. `extraction` replaces the deprecated | |
| You can also pass a dict matching `ExtractionTypedDict` — the SDK | |
| validates it via Pydantic (strings must match the enum values). `extraction` replaces the deprecated |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Forward-ports the docs sweep from
dx-719-python-sdk-extractionontomainahead of the 3.1.0 release: switches theextractionparameter in three primary discoverable docs (README,docs/models/extraction.md, USAGE) to use the strictExtraction(...)model form everywhere. Adds a one-sentence teaching note on each so readers still learn theExtractionTypedDictdict alternative.MIGRATION.md"3.0.0 → 3.1.0" Before/after keeps both forms by design (explicitly labeled for pedagogical contrast).Verification
Upstream
Lands on top of
0135a8b(PR #40 merge) as merge commita90ba76. Taggedv3.1.0after this PR merges.