visor-python 0.1.0__py3-none-any.whl

visor/models/listings.py

@@ -0,0 +1,205 @@
+from datetime import date
+from typing import Literal
+
+from pydantic import Field, field_validator
+
+from visor.models._base import (
+    DealerRef,
+    ListingsFilterBase,
+    Pagination,
+    PriceHistoryEntry,
+    SortOrder,
+    VehicleOption,
+    VehicleRecord,
+    VisorResponseModel,
+)
+
+LISTING_FIELDS = {
+    "default",
+    "id",
+    "vin",
+    "year",
+    "make",
+    "model",
+    "trim",
+    "version",
+    "body_type",
+    "drivetrain",
+    "fuel_type",
+    "powertrain_type",
+    "transmission",
+    "engine",
+    "cylinders",
+    "doors",
+    "seating_capacity",
+    "exterior_color",
+    "interior_color",
+    "base_exterior_color",
+    "base_interior_color",
+    "msrp",
+    "discount_from_msrp",
+    "price",
+    "miles",
+    "days_on_market",
+    "status",
+    "inventory_status",
+    "inventory_type",
+    "stock_number",
+    "vdp_url",
+    "sold_date",
+    "dealer_id",
+    "dealer_name",
+    "dealer_type",
+    "city",
+    "state",
+    "latitude",
+    "longitude",
+    "distance_miles",
+    "photo_urls",
+    "features",
+    "options_packages",
+}
+
+
+class ListingsFilter(ListingsFilterBase):
+    limit: int = 50
+    offset: int = 0
+    sort: SortOrder = SortOrder.DAYS_ON_MARKET
+    fields: list[str] | None = None
+    include: list[Literal["price_history", "options"]] | None = None
+
+    @field_validator("limit")
+    @classmethod
+    def _limit_max(cls, v: int) -> int:
+        if v > 100:
+            raise ValueError("limit maximum is 100")
+        return v
+
+    @field_validator("fields")
+    @classmethod
+    def _validate_fields(cls, v: list[str] | None) -> list[str] | None:
+        if v is not None:
+            unknown = set(v) - LISTING_FIELDS
+            if unknown:
+                raise ValueError(f"unknown fields: {unknown}")
+        return v
+
+    def to_params(self) -> dict[str, str]:
+        params = super().to_params()
+        params["limit"] = str(self.limit)
+        params["offset"] = str(self.offset)
+        params["sort"] = self.sort.value
+        if self.fields:
+            params["fields"] = ",".join(self.fields)
+        if self.include:
+            params["include"] = ",".join(self.include)
+        return params
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+
+class ListingSummary(VisorResponseModel):
+    """Returned by filter_listings() and dealer_inventory().
+
+    id and vin are always present; the API returns them regardless of fields
+    projection. All other fields are optional because the caller controls which
+    fields are returned via ListingsFilter.fields.
+    """
+
+    id: str
+    vin: str
+    year: int | None = None
+    make: str | None = None
+    model: str | None = None
+    trim: str | None = None
+    version: str | None = None
+    body_type: str | None = None
+    drivetrain: str | None = None
+    fuel_type: str | None = None
+    powertrain_type: str | None = None
+    transmission: str | None = None
+    engine: str | None = None
+    cylinders: int | None = None
+    doors: int | None = None
+    seating_capacity: int | None = None
+    exterior_color: str | None = None
+    interior_color: str | None = None
+    base_exterior_color: str | None = None
+    base_interior_color: str | None = None
+    msrp: int | None = None
+    discount_from_msrp: int | None = None
+    price: int | None = None
+    miles: int | None = None
+    days_on_market: int | None = None
+    status: str | None = None
+    inventory_status: str | None = None
+    inventory_type: str | None = None
+    stock_number: str | None = None
+    vdp_url: str | None = None
+    sold_date: date | None = None
+    dealer_id: str | None = None
+    dealer_name: str | None = None
+    dealer_type: str | None = None
+    city: str | None = None
+    state: str | None = None
+    latitude: float | None = None
+    longitude: float | None = None
+    distance_miles: float | None = None
+    photo_urls: list[str] = Field(default_factory=list)
+    features: list[str] = Field(default_factory=list)
+    options_packages: list[str] = Field(default_factory=list)
+    price_history: list[PriceHistoryEntry] = Field(default_factory=list)
+    options: list[VehicleOption] = Field(default_factory=list)
+
+
+class ListingDetail(VisorResponseModel):
+    """Returned by get_listing() — always fully populated."""
+
+    id: str
+    vin: str
+    status: str
+    price: int | None = None
+    miles: int | None = None
+    inventory_type: str
+    stock_number: str | None = None
+    vdp_url: str | None = None
+    vhr_url: str | None = None
+    photo_urls: list[str] = Field(default_factory=list)
+    photo_url_primary: str | None = None
+    inventory_date: date | None = None
+    sold_date: date | None = None
+    last_checked_at: str | None = None
+    dealer: DealerRef
+    vehicle: VehicleRecord
+    price_history: list[PriceHistoryEntry] | None = None
+
+
+class ListingSnapshot(VisorResponseModel):
+    """Embedded listing inside VinDetail.latest_listing.
+
+    Differs from ListingDetail: no top-level vin/status/vehicle fields.
+    """
+
+    id: str
+    price: int | None = None
+    miles: int | None = None
+    inventory_type: str
+    stock_number: str | None = None
+    vdp_url: str | None = None
+    vhr_url: str | None = None
+    photo_urls: list[str] = Field(default_factory=list)
+    photo_url_primary: str | None = None
+    inventory_date: date | None = None
+    sold_date: date | None = None
+    last_checked_at: str | None = None
+    dealer: DealerRef
+    price_history: list[PriceHistoryEntry] | None = None
+
+
+class ListingsPage(VisorResponseModel):
+    data: list[ListingSummary]
+    pagination: Pagination
+    meta: dict[str, object] = Field(default_factory=dict)

visor/models/usage.py

@@ -0,0 +1,30 @@
+from datetime import date
+
+from visor.models._base import VisorResponseModel
+
+
+class UsageRecord(VisorResponseModel):
+    date: date
+    metering_class: str
+    requests: int
+    charged_micros: int
+
+
+class UsageTotals(VisorResponseModel):
+    requests: int
+    charged_micros: int
+
+
+class UsageMeta(VisorResponseModel):
+    start_date: date
+    end_date: date
+    interval: str
+    currency: str
+    source: str
+    freshness: str
+
+
+class UsageSummary(VisorResponseModel):
+    data: list[UsageRecord]
+    totals: UsageTotals
+    meta: UsageMeta

visor/models/vins.py

@@ -0,0 +1,9 @@
+from visor.models._base import VehicleBuild, VisorResponseModel
+from visor.models.listings import ListingSnapshot
+
+
+class VinDetail(VisorResponseModel):
+    vin: str
+    status: str
+    build: VehicleBuild
+    latest_listing: ListingSnapshot | None = None

visor_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: visor-python
+Version: 0.1.0
+Summary: Python SDK for the Visor Public API
+Project-URL: Homepage, https://visor.vin
+Project-URL: Repository, https://github.com/whitewalls86/visor-python
+Project-URL: Issues, https://github.com/whitewalls86/visor-python/issues
+Project-URL: Changelog, https://github.com/whitewalls86/visor-python/blob/master/CHANGELOG.md
+Author-email: Andrew Miller <miller.andrew.preston@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,automotive,car,inventory,listings,sdk,vehicle,visor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# visor-python
+
+[![CI](https://github.com/whitewalls86/visor-python/actions/workflows/ci.yml/badge.svg)](https://github.com/whitewalls86/visor-python/actions/workflows/ci.yml)
+
+**visor-python** is an unofficial community Python SDK for the [Visor Public API](https://api.visor.vin) — a vehicle inventory search platform covering new, used, and certified pre-owned listings from dealers across the US. It provides a thin, fully-typed wrapper around the REST API with sync and async clients, Pydantic response models, and auto-pagination helpers.
+
+> **Disclaimer:** This is an unofficial community SDK and is not affiliated with or endorsed by Visor (Currents Systems Inc.).
+
+> **Pre-1.0 notice:** This package is in initial development (`0.x`). Minor version bumps may include breaking changes. Pin to a specific minor version in production and review the [CHANGELOG](CHANGELOG.md) before upgrading.
+
+## Install
+
+```bash
+pip install visor-python
+```
+
+Requires Python 3.10+ and no non-standard runtime dependencies beyond `httpx` and `pydantic`.
+
+## Quick start
+
+```python
+from visor import VisorClient, ListingsFilter, iter_listings
+
+with VisorClient() as client:  # reads VISOR_API_KEY from env
+    # Search for used Toyota Tacomas in Texas under $40k
+    page = client.filter_listings(
+        ListingsFilter(
+            make=["Toyota"],
+            model=["Tacoma"],
+            inventory_type=["used"],
+            state=["TX"],
+            max_price=40_000,
+        )
+    )
+    for listing in page.data:
+        price = f"${listing.price:,}" if listing.price is not None else "N/A"
+        print(f"{listing.year} {listing.make} {listing.model} — {price}")
+
+    # Look up a specific VIN
+    vin = client.lookup_vin("4T1DAACKXTU765422", include=["price_history"])
+    msrp = f"${vin.build.combined_msrp:,}" if vin.build.combined_msrp is not None else "N/A"
+    print(msrp)
+```
+
+### Geo filtering
+
+Pass a `postal_code` and `radius` (miles) to search near a location:
+
+```python
+page = client.filter_listings(
+    ListingsFilter(
+        make=["Honda"],
+        model=["CR-V"],
+        postal_code="90210",
+        radius=50,
+    )
+)
+```
+
+`radius` requires exactly one of `postal_code` or `latitude`/`longitude`. Passing `radius` alone (or with neither) raises `ValueError` before any network call.
+
+### Paginating all results
+
+`iter_listings` (sync) and `paginate_listings` (async) iterate every page automatically:
+
+```python
+from visor import VisorClient, ListingsFilter, iter_listings
+
+with VisorClient() as client:
+    for listing in iter_listings(
+        client,
+        ListingsFilter(make=["Ford"], state=["TX"]),
+    ):
+        print(listing.vin, listing.price)
+```
+
+For dealers, use `iter_dealers` / `paginate_dealers` in the same way.
+
+`client.filter_listings(...)` returns a single page (`ListingsPage`). Use the
+`iter_*` / `paginate_*` helpers when you need all results.
+
+### Async
+
+```python
+import asyncio
+from visor import AsyncVisorClient, ListingsFilter, paginate_listings
+
+async def main() -> None:
+    async with AsyncVisorClient() as client:
+        # Single page
+        page = await client.filter_listings(
+            ListingsFilter(make=["Toyota"], state=["TX"], max_price=40_000)
+        )
+        for listing in page.data:
+            price = f"${listing.price:,}" if listing.price is not None else "N/A"
+            print(listing.vin, price)
+
+        # All pages
+        async for listing in paginate_listings(
+            client,
+            ListingsFilter(make=["Toyota"], state=["TX"]),
+        ):
+            print(listing.vin)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+### API key
+
+Pass your key explicitly or export `VISOR_API_KEY` before running:
+
+```python
+client = VisorClient(api_key="vsr_live_...")
+# or
+# export VISOR_API_KEY=vsr_live_...
+client = VisorClient()
+```
+
+You need your own Visor API key — see [api.visor.vin](https://api.visor.vin) for details. Use of the API is governed by Visor's API terms; you are responsible for complying with them.
+
+### Timeout
+
+Default request timeout is 30 seconds. Override at construction time:
+
+```python
+client = VisorClient(timeout=10.0)
+```
+
+### Base URL (advanced)
+
+`base_url` defaults to the production API. Override it for local testing or staging:
+
+```python
+client = VisorClient(base_url="http://localhost:8080")
+```
+
+## Key concepts
+
+### `ListingsFilter` is shared
+
+`ListingsFilter` is accepted by both `filter_listings()` and `dealer_inventory()`. Build one filter object and reuse it across both methods.
+
+### `fields` is response projection, not filtering
+
+`ListingsFilter.fields` controls which fields the API returns — it does not filter which listings match. Example:
+
+```python
+filter = ListingsFilter(
+    make=["Toyota"],
+    fields=["vin", "price", "miles"],
+)
+```
+
+`id` and `vin` are always returned by the API regardless of the `fields` projection.
+
+### Responses are Pydantic models
+
+All responses — `ListingsPage`, `ListingDetail`, `VinDetail`, etc. — are Pydantic v2 models. Access fields as attributes and use standard Pydantic methods (`.model_dump()`, `.model_json_schema()`, etc.) as needed.
+
+## Error handling
+
+All methods raise typed exceptions from `visor.exceptions`. The SDK does not retry automatically — `RateLimitError.retry_after` gives you the hint to build your own retry logic.
+
+```python
+import time
+from visor import VisorClient, ListingsFilter, RateLimitError, VisorAPIError
+
+def fetch_with_backoff(client: VisorClient, f: ListingsFilter) -> object:
+    for attempt in range(4):
+        try:
+            return client.filter_listings(f)
+        except RateLimitError as e:
+            wait = e.retry_after if e.retry_after is not None else 2 ** attempt
+            print(f"Rate limited — waiting {wait}s")
+            time.sleep(wait)
+        except VisorAPIError as e:
+            raise  # surface non-rate-limit errors immediately
+    raise RuntimeError("Exhausted retries")
+```
+
+Exception hierarchy:
+
+| Exception | When |
+|---|---|
+| `VisorAPIError` | Base for all API errors; has `.status_code` |
+| `AuthError` | 401 — invalid or missing API key |
+| `NotFoundError` | 404 — resource does not exist |
+| `RateLimitError` | 429 — includes `.retry_after` (seconds, or `None`) |
+
+## Debugging
+
+**Inspect the exception** — `VisorAPIError` carries `.status_code` and a message from the API.
+
+**Check `retry_after`** — for `RateLimitError`, `.retry_after` is the number of seconds to wait (or `None` if the API did not provide a value).
+
+**Request-level logging** — visor-python uses `httpx` internally. Enable httpx logging to see raw requests and responses:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+logging.getLogger("httpx").setLevel(logging.DEBUG)
+```
+
+## Community
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — how to contribute
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — community standards
+- [GitHub Issues](https://github.com/whitewalls86/visor-python/issues) — bug reports and feature requests
+
+## License
+
+MIT

visor_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+visor/__init__.py,sha256=ZwBV7OIrapXUndumE4_9E0PgLhAiPpLRPqlvycLka3k,1955
+visor/_client.py,sha256=rKqp0OOFE-oKtu5QOhGeXqjvOw5bh-M80uaX3ZmJlpg,23995
+visor/_pagination.py,sha256=uwTP5GwjYNphF2TXyBn_9XBF2yJodL9GHqMrrKbySCw,3561
+visor/_transport.py,sha256=coJb9ZTcADTH_QGF9u-PBU0B2LUUs8LLfUVabnVZtzU,3956
+visor/exceptions.py,sha256=Fk7zpkNeiingXqCep9abhP0FmVxa5DZNqDVgvlj7GoE,2313
+visor/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+visor/models/__init__.py,sha256=R2pOfwsLSTxIrJyehqVvhwXcEdpc77_iKHjh4hpUan8,1560
+visor/models/_base.py,sha256=pelgGdQK7LeA5AsX_TUrD_ymKKxU2C1T3yXhcvuddxs,11903
+visor/models/dealers.py,sha256=ravIxjhWxpRq5aCyJ0kIGbqoxjoiBpk-AX2IhiPAqpc,2178
+visor/models/facets.py,sha256=Kwi4XvMebow0o5SEyY17u_0PGsy1eJbLtGERpNoEke0,3712
+visor/models/listings.py,sha256=gwOC1q4z9BdIjKWOF8CvHZUD--7j2gD4Fz9R9SZ8Zss,5716
+visor/models/usage.py,sha256=tZCnQo3AVNllcmpLRW-g0lsN0bIvtUB8EY08nFl8XaY,546
+visor/models/vins.py,sha256=IsKKRJurGHHUuKEQIU8finljalPKT0I94iVzpKm0-kw,256
+visor_python-0.1.0.dist-info/METADATA,sha256=o4t-J2GseWoNYng1r0_U32R1VDFBhgDDNomtyKQQuic,8511
+visor_python-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+visor_python-0.1.0.dist-info/licenses/LICENSE,sha256=VyWYhOWf272yziUZJBZwHP54JIp4PG7TQp2GphWiWs4,1082
+visor_python-0.1.0.dist-info/RECORD,,

visor_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

visor_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 visor-python contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.