Fix top backlog items: FacetSort enum, include-field semantics, docs#21
Merged
Conversation
- Convert FacetSort from Literal TypeAlias to str Enum matching SortOrder pattern; update FacetsFilter.sort default to FacetSort.COUNT_DESC and serialize with .value. - Export FacetSort from visor package root alongside FacetsFilter. - Add tests for FacetSort default, explicit enum, raw-string coercion, and wire values. - Add include-field semantics tests (None/[]/[...]) for ListingDetail.price_history, ListingSnapshot.price_history, and VehicleBuild.options. - Add comment in paginate_listings/paginate_dealers explaining why async generators use explicit item-yield instead of yield from. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Live probe (2026-06-17) confirmed the API omits price_history and options entirely from ListingSummary when include= is not passed — not null, not []. Pydantic default_factory=list is correct and unambiguous. Two release_gate integration tests now guard this: if the API ever starts sending null or [] for these fields without include=, the tests fail and signal that the model type needs review. Backlog P2 updated with findings. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
CHANGELOG: add Unreleased entries for the FacetSort enum conversion and the FacetsFilter.sort default/serialization fix. README: add Optional include fields section explaining the None/[]/[...] semantics for price_history and options, with a usage example and a note that ListingSummary variants are not include-backed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
CHANGELOG: split FacetSort Unreleased entry into Added (root export) and Changed (enum conversion, sort default); Fixed entry is unchanged. README: correct the include-field note for ListingSummary — those fields ARE include-backed via ListingsFilter(include=...) but default to [] when the key is absent, so callers cannot distinguish not-requested from requested-but-empty on summary listings. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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
FacetSortfrom aLiteraltype alias to astr, Enummatching theSortOrderpattern (COUNT,COUNT_DESC,METRIC,METRIC_DESC). Raw string values like-countstill coerce through Pydantic lax mode.FacetSortis now exported from thevisorpackage root.FacetsFilter.sortdefaults toFacetSort.COUNT_DESC;to_params()serializes via.value.None/[]/[...]contract forListingDetail.price_history,ListingSnapshot.price_history, andVehicleBuild.options. Live-verified (2026-06-17) that the API omitsprice_historyandoptionsentirely fromListingSummarywheninclude=is not passed; tworelease_gateintegration tests guard that invariant going forward.paginate_listingsandpaginate_dealersexplaining why async generators use explicityieldinstead ofyield from.[Unreleased]entry withAdded/Changed/Fixedsections; new### Optional include fieldssection in README explaining the three-state semantics with a usage example.Test plan
pytest— 256 unit tests passruff check/ruff format --check— cleanmypy— cleanpytest tests/integration --run-integration -k absent_without_include— 2 release_gate tests pass against live API🤖 Generated with Claude Code