copart-api 0.1.0__tar.gz

copart_api-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# JavaScript
+node_modules/
+*.tgz
+coverage/
+
+# Secrets, editors, OS
+.env
+.env.*
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

copart_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0 — 2026-11-09
+
+- First release: `Client` and `AsyncClient` over `apiauto-space` with the market preset to `us`,
+  `car_id()`, `raw()` and `CopartRaw` types.

copart_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 apiauto.space
+
+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.

copart_api-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: copart-api
+Version: 0.1.0
+Summary: Copart API client for Python: Copart auction lots (USA) with VIN, damage and sale date as JSON, from the apiauto.space team
+Project-URL: Homepage, https://apiauto.space/en/copart-api/
+Project-URL: Documentation, https://apiauto.space/en/docs/
+Project-URL: Repository, https://github.com/apiauto-space/copart-api
+Project-URL: Issues, https://github.com/apiauto-space/copart-api/issues
+Project-URL: Changelog, https://github.com/apiauto-space/copart-api/blob/main/python/CHANGELOG.md
+Project-URL: Get a demo key, https://t.me/apiautospace_bot?start=demo
+Author: apiauto.space
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api client,car auction,copart,copart api,salvage cars,usa cars,used cars,vehicle data,vin
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: apiauto-space<0.2,>=0.1.1
+Description-Content-Type: text/markdown
+
+# copart-api — Copart API client for Python
+
+[![PyPI version](https://img.shields.io/pypi/v/copart-api.svg)](https://pypi.org/project/copart-api/)
+[![Python versions](https://img.shields.io/pypi/pyversions/copart-api.svg)](https://pypi.org/project/copart-api/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/apiauto-space/copart-api/blob/main/LICENSE)
+
+`copart-api` gives you Copart auction lots (USA) with VIN, damage and sale date as clean JSON through the [apiauto.space](https://apiauto.space/en/copart-api/)
+REST API, without writing or maintaining a scraper. Search by make, model, year, price and mileage, page
+through the whole catalog, fetch one listing by its number and follow a feed of new cars, cars taken off sale
+and price changes.
+
+It is a thin layer over the general [`apiauto-space`](https://pypi.org/project/apiauto-space/) client with
+the market preset to `us`, plus types for the Copart-only fields. It comes from the apiauto.space team;
+the project is not affiliated with Copart.
+
+- Sync `Client` and `AsyncClient`, retries on 429 and 5xx, one exception class per API error
+- `car("68055056")` takes the Copart listing number as well as the record id
+- `CopartRaw` types for the Copart-only fields in `car["raw"]`
+- Python 3.10+, `py.typed`, checked with `mypy --strict`
+
+## Install
+
+```bash
+pip install copart-api
+```
+
+The module you import is `copart_api`.
+
+## Get a key
+
+Open the Telegram bot [@apiautospace_bot](https://t.me/apiautospace_bot?start=demo) and take a free demo
+key: one day, 100 data requests, up to 20 cars per request. Paid plans are on the
+[pricing page](https://apiauto.space/en/#pricing).
+
+Save the key in the `APIAUTO_KEY` environment variable — the client reads it from there:
+
+```bash
+export APIAUTO_KEY="your-key"
+```
+
+Keep the key on your server: the API does not accept browser requests.
+
+## Quick start
+
+```python
+import copart_api
+
+with copart_api.Client() as client:  # reads APIAUTO_KEY
+    page = client.cars(brand="Toyota", year_min=2020, limit=20)
+    for car in page["items"]:
+        print(car["id"], car["title"], car["price"]["amount"], car["price"]["currency"])
+
+    one = client.car("68055056")  # a listing number or "copart:68055056"
+    print(one["listing_url"], one["photos"][:1])
+```
+
+A record looks like this (shortened; real values from the catalog):
+
+```json
+{
+  "id": "copart:68055056",
+  "market": "us",
+  "source": "copart",
+  "source_id": "68055056",
+  "title": "2019 Hyundai Elantra",
+  "brand": "Hyundai",
+  "model": "Elantra",
+  "year": 2019,
+  "mileage_km": 239240,
+  "fuel": "gasoline",
+  "transmission": "automatic",
+  "body_type": null,
+  "vin": "5NPD84LF8KH406860",
+  "price": {
+    "amount": "4000.00",
+    "currency": "USD"
+  },
+  "price_usd": "4000.00",
+  "location": {
+    "country": "US",
+    "region": "TN",
+    "city": "Nashville"
+  },
+  "listing_url": null,
+  "is_active": true,
+  "first_seen_at": "2026-09-23T00:21:16.304888Z",
+  "photos": [
+    "https://api.apiauto.space/img/copart:68055056/1.jpg?exp=...&sig=..."
+  ],
+  "raw": {
+    "lot_number": "68055056",
+    "sale_date": "2026-09-28T17:00:00+00:00",
+    "buy_now": 4000,
+    "damage_main": "front",
+    "title_doc": "clean",
+    "location_branch": "Nashville (TN)"
+  }
+}
+```
+
+Every record has the same keys as in the other apiauto.space markets; a value the source does not provide is
+`None`. Prices are decimal strings in USD, `price_usd` is converted at the ECB daily rate.
+
+## Copart and IAAI share one market
+
+The API keeps Copart and IAAI lots together in the `us` market and does not filter by auction yet. This client
+asks for `us` cars and keeps only Copart lots on the client side. What that means for you:
+
+- a page from `cars()` can hold fewer than `limit` lots, and its `count` is `None`;
+- the IAAI lots that were dropped still count against your quota;
+- `iter_cars(max_items=...)` reads pages until it has collected `max_items` Copart lots.
+
+When you need both auctions, use the general `apiauto` client with `client.cars("us")`.
+
+## Methods
+
+| Method | What it does | Quota |
+|---|---|---|
+| `cars(**filters)` | One page of Copart cars: `brand`, `model`, `year_min`, `year_max`, `price_min`, `price_max`, `mileage_max`, `fuel`, `body_type`, `sort`, `limit`, `cursor` | Cars returned |
+| `iter_cars(max_items=None, **filters)` | Every matching car, page after page | Cars returned |
+| `car(listing)` | One car by listing number or id, including cars taken off sale in the last 14 days | 1 record |
+| `changes(since, type=None)` / `iter_changes(...)` | Feed of `added`, `disappeared`, `price_drop`, `price_up` events | Events returned |
+| `brands()` / `models(brand)` | Makes and models with car counts | Free |
+| `status()` | Plan access, data age and the number of active cars of the market | Free |
+| `usage()` | Your plan, its term and the quota spent | Free |
+| `live(make=..., model=...)` | Live search at the auction data provider for lots not in the catalog yet, Pro and Max plans | Separate counter |
+
+The general client is at `client.core` for anything else. Errors are the `apiauto` exceptions, re-exported
+here: `QuotaExceededError`, `RateLimitError`, `NotFoundError`, `AuthenticationError` and the rest.
+
+## Copart-only fields
+
+```python
+from copart_api import raw
+
+extra = raw(car)  # typed as CopartRaw
+print(extra.get("source_values"))
+```
+
+`CopartRaw` lists the keys with comments; every key is optional, so read them with `.get`.
+
+## Links
+
+- [Copart API on apiauto.space](https://apiauto.space/en/copart-api/) and the [API documentation](https://apiauto.space/en/docs/)
+- [`apiauto-space`](https://pypi.org/project/apiauto-space/): the general client for all markets
+- Clients for the other sources: [`encar-api-client`](https://pypi.org/project/encar-api-client/), [`che168-api`](https://pypi.org/project/che168-api/), [`iaai-api`](https://pypi.org/project/iaai-api/)
+- [Examples in curl, Python, JavaScript and PHP](https://github.com/apiauto-space/copart-api-examples)
+- The JavaScript version of this client: [`copart-api` on npm](https://www.npmjs.com/package/copart-api)
+
+## License
+
+MIT. Copart is a trademark of its owner; it is named here only to say which listings the client returns.

copart_api-0.1.0/README.md

@@ -0,0 +1,152 @@
+# copart-api — Copart API client for Python
+
+[![PyPI version](https://img.shields.io/pypi/v/copart-api.svg)](https://pypi.org/project/copart-api/)
+[![Python versions](https://img.shields.io/pypi/pyversions/copart-api.svg)](https://pypi.org/project/copart-api/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/apiauto-space/copart-api/blob/main/LICENSE)
+
+`copart-api` gives you Copart auction lots (USA) with VIN, damage and sale date as clean JSON through the [apiauto.space](https://apiauto.space/en/copart-api/)
+REST API, without writing or maintaining a scraper. Search by make, model, year, price and mileage, page
+through the whole catalog, fetch one listing by its number and follow a feed of new cars, cars taken off sale
+and price changes.
+
+It is a thin layer over the general [`apiauto-space`](https://pypi.org/project/apiauto-space/) client with
+the market preset to `us`, plus types for the Copart-only fields. It comes from the apiauto.space team;
+the project is not affiliated with Copart.
+
+- Sync `Client` and `AsyncClient`, retries on 429 and 5xx, one exception class per API error
+- `car("68055056")` takes the Copart listing number as well as the record id
+- `CopartRaw` types for the Copart-only fields in `car["raw"]`
+- Python 3.10+, `py.typed`, checked with `mypy --strict`
+
+## Install
+
+```bash
+pip install copart-api
+```
+
+The module you import is `copart_api`.
+
+## Get a key
+
+Open the Telegram bot [@apiautospace_bot](https://t.me/apiautospace_bot?start=demo) and take a free demo
+key: one day, 100 data requests, up to 20 cars per request. Paid plans are on the
+[pricing page](https://apiauto.space/en/#pricing).
+
+Save the key in the `APIAUTO_KEY` environment variable — the client reads it from there:
+
+```bash
+export APIAUTO_KEY="your-key"
+```
+
+Keep the key on your server: the API does not accept browser requests.
+
+## Quick start
+
+```python
+import copart_api
+
+with copart_api.Client() as client:  # reads APIAUTO_KEY
+    page = client.cars(brand="Toyota", year_min=2020, limit=20)
+    for car in page["items"]:
+        print(car["id"], car["title"], car["price"]["amount"], car["price"]["currency"])
+
+    one = client.car("68055056")  # a listing number or "copart:68055056"
+    print(one["listing_url"], one["photos"][:1])
+```
+
+A record looks like this (shortened; real values from the catalog):
+
+```json
+{
+  "id": "copart:68055056",
+  "market": "us",
+  "source": "copart",
+  "source_id": "68055056",
+  "title": "2019 Hyundai Elantra",
+  "brand": "Hyundai",
+  "model": "Elantra",
+  "year": 2019,
+  "mileage_km": 239240,
+  "fuel": "gasoline",
+  "transmission": "automatic",
+  "body_type": null,
+  "vin": "5NPD84LF8KH406860",
+  "price": {
+    "amount": "4000.00",
+    "currency": "USD"
+  },
+  "price_usd": "4000.00",
+  "location": {
+    "country": "US",
+    "region": "TN",
+    "city": "Nashville"
+  },
+  "listing_url": null,
+  "is_active": true,
+  "first_seen_at": "2026-09-23T00:21:16.304888Z",
+  "photos": [
+    "https://api.apiauto.space/img/copart:68055056/1.jpg?exp=...&sig=..."
+  ],
+  "raw": {
+    "lot_number": "68055056",
+    "sale_date": "2026-09-28T17:00:00+00:00",
+    "buy_now": 4000,
+    "damage_main": "front",
+    "title_doc": "clean",
+    "location_branch": "Nashville (TN)"
+  }
+}
+```
+
+Every record has the same keys as in the other apiauto.space markets; a value the source does not provide is
+`None`. Prices are decimal strings in USD, `price_usd` is converted at the ECB daily rate.
+
+## Copart and IAAI share one market
+
+The API keeps Copart and IAAI lots together in the `us` market and does not filter by auction yet. This client
+asks for `us` cars and keeps only Copart lots on the client side. What that means for you:
+
+- a page from `cars()` can hold fewer than `limit` lots, and its `count` is `None`;
+- the IAAI lots that were dropped still count against your quota;
+- `iter_cars(max_items=...)` reads pages until it has collected `max_items` Copart lots.
+
+When you need both auctions, use the general `apiauto` client with `client.cars("us")`.
+
+## Methods
+
+| Method | What it does | Quota |
+|---|---|---|
+| `cars(**filters)` | One page of Copart cars: `brand`, `model`, `year_min`, `year_max`, `price_min`, `price_max`, `mileage_max`, `fuel`, `body_type`, `sort`, `limit`, `cursor` | Cars returned |
+| `iter_cars(max_items=None, **filters)` | Every matching car, page after page | Cars returned |
+| `car(listing)` | One car by listing number or id, including cars taken off sale in the last 14 days | 1 record |
+| `changes(since, type=None)` / `iter_changes(...)` | Feed of `added`, `disappeared`, `price_drop`, `price_up` events | Events returned |
+| `brands()` / `models(brand)` | Makes and models with car counts | Free |
+| `status()` | Plan access, data age and the number of active cars of the market | Free |
+| `usage()` | Your plan, its term and the quota spent | Free |
+| `live(make=..., model=...)` | Live search at the auction data provider for lots not in the catalog yet, Pro and Max plans | Separate counter |
+
+The general client is at `client.core` for anything else. Errors are the `apiauto` exceptions, re-exported
+here: `QuotaExceededError`, `RateLimitError`, `NotFoundError`, `AuthenticationError` and the rest.
+
+## Copart-only fields
+
+```python
+from copart_api import raw
+
+extra = raw(car)  # typed as CopartRaw
+print(extra.get("source_values"))
+```
+
+`CopartRaw` lists the keys with comments; every key is optional, so read them with `.get`.
+
+## Links
+
+- [Copart API on apiauto.space](https://apiauto.space/en/copart-api/) and the [API documentation](https://apiauto.space/en/docs/)
+- [`apiauto-space`](https://pypi.org/project/apiauto-space/): the general client for all markets
+- Clients for the other sources: [`encar-api-client`](https://pypi.org/project/encar-api-client/), [`che168-api`](https://pypi.org/project/che168-api/), [`iaai-api`](https://pypi.org/project/iaai-api/)
+- [Examples in curl, Python, JavaScript and PHP](https://github.com/apiauto-space/copart-api-examples)
+- The JavaScript version of this client: [`copart-api` on npm](https://www.npmjs.com/package/copart-api)
+
+## License
+
+MIT. Copart is a trademark of its owner; it is named here only to say which listings the client returns.

copart_api-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "copart-api"
+dynamic = ["version"]
+description = "Copart API client for Python: Copart auction lots (USA) with VIN, damage and sale date as JSON, from the apiauto.space team"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "apiauto.space" }]
+keywords = ["copart", "copart api", "car auction", "salvage cars", "usa cars", "vin", "used cars", "vehicle data", "api client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["apiauto-space>=0.1.1,<0.2"]
+
+[project.urls]
+Homepage = "https://apiauto.space/en/copart-api/"
+Documentation = "https://apiauto.space/en/docs/"
+Repository = "https://github.com/apiauto-space/copart-api"
+Issues = "https://github.com/apiauto-space/copart-api/issues"
+Changelog = "https://github.com/apiauto-space/copart-api/blob/main/python/CHANGELOG.md"
+"Get a demo key" = "https://t.me/apiautospace_bot?start=demo"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.15", "mypy>=1.15", "typing_extensions>=4.12"]
+
+[tool.hatch.version]
+path = "src/copart_api/_version.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "CHANGELOG.md", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/copart_api"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "A", "C4", "SIM", "PT", "RUF", "S", "T20"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "S105", "S106"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src", "tests"]

copart_api-0.1.0/src/copart_api/__init__.py

@@ -0,0 +1,72 @@
+"""Copart API client for Python: Copart auction lots (USA) with VIN, damage and sale date as JSON.
+
+A thin layer over the apiauto.space client (``apiauto``) with the market preset::
+
+    import copart_api
+
+    with copart_api.Client() as client:  # the key comes from APIAUTO_KEY
+        for car in client.cars(brand="Toyota", year_min=2020, limit=20)["items"]:
+            print(car["id"], car["title"], car["price"]["amount"])
+
+From the apiauto.space team. Not affiliated with Copart.
+"""
+
+from apiauto import (
+    ApiautoError,
+    APIConnectionError,
+    AuthenticationError,
+    BadRequestError,
+    Car,
+    CarFilters,
+    CarsPage,
+    Change,
+    ChangesPage,
+    ChangeType,
+    Market,
+    NotFoundError,
+    PermissionDeniedError,
+    Price,
+    QuotaExceededError,
+    RateLimitError,
+    ReferenceItem,
+    ServerError,
+    ServiceUnavailableError,
+    Usage,
+)
+
+from ._client import MARKET, SHARED_MARKET, SOURCE, AsyncClient, Client, car_id
+from ._version import __version__
+from .types import CopartRaw, FxQuote, raw
+
+__all__ = [
+    "MARKET",
+    "SHARED_MARKET",
+    "SOURCE",
+    "APIConnectionError",
+    "ApiautoError",
+    "AsyncClient",
+    "AuthenticationError",
+    "BadRequestError",
+    "Car",
+    "CarFilters",
+    "CarsPage",
+    "Change",
+    "ChangeType",
+    "ChangesPage",
+    "Client",
+    "CopartRaw",
+    "FxQuote",
+    "Market",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "Price",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ReferenceItem",
+    "ServerError",
+    "ServiceUnavailableError",
+    "Usage",
+    "__version__",
+    "car_id",
+    "raw",
+]

copart_api-0.1.0/src/copart_api/_client.py

@@ -0,0 +1,342 @@
+"""Copart clients: the apiauto clients with the market preset to ``us``."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Sequence
+from datetime import datetime
+from decimal import Decimal
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, Literal
+
+import apiauto
+from apiauto import (
+    Car,
+    CarsPage,
+    Change,
+    ChangesPage,
+    ChangeType,
+    Dictionaries,
+    Market,
+    ReferenceItem,
+    Usage,
+)
+
+if TYPE_CHECKING:
+    import httpx
+    from apiauto import CarFilters
+    from typing_extensions import Self, Unpack
+
+MARKET: Literal["us"] = "us"
+"""The apiauto.space market of Copart."""
+SOURCE: Literal["copart"] = "copart"
+"""The ``source`` of every record this package returns."""
+SHARED_MARKET = True
+"""``True`` when the market also holds another source and records are filtered on the client."""
+
+
+def car_id(listing: str | int) -> str:
+    """The full record id for a Copart listing number: ``68055056`` -> ``copart:68055056``.
+
+    An id that already has the ``copart:`` prefix is returned as is; another
+    source's prefix raises ``ValueError``.
+    """
+    text = str(listing).strip()
+    if not text:
+        raise ValueError("listing must not be empty")
+    prefix, sep, number = text.partition(":")
+    if not sep:
+        return f"{SOURCE}:{text}"
+    if prefix != SOURCE or not number:
+        raise ValueError(f"not a Copart id: {text!r}")
+    return text
+
+
+def _ours(car: Car) -> bool:
+    return car.get("source") == SOURCE
+
+
+def _our_change(change: Change) -> bool:
+    return change["car_id"].startswith(SOURCE + ":")
+
+
+def _core_options(base_url: str | None) -> dict[str, Any]:
+    return {} if base_url is None else {"base_url": base_url}
+
+
+def _own_market(markets: list[Market]) -> Market:
+    for market in markets:
+        if market["market"] == MARKET:
+            return market
+    raise apiauto.ApiautoError(f"the API did not list the {MARKET} market")
+
+
+class Client:
+    """Copart client of the apiauto.space API, synchronous.
+
+    Args:
+        api_key: Your key; defaults to the ``APIAUTO_KEY`` environment variable.
+        base_url: The API root; ``https://api.apiauto.space/v1`` when omitted.
+        timeout: Seconds to wait for a response.
+        max_retries: Retries after 429, 5xx or a network error.
+        http_client: Your own ``httpx.Client``; the client does not close it.
+
+    Use it as a context manager or call :meth:`close`::
+
+        with copart_api.Client() as client:
+            page = client.cars(brand="Toyota", limit=20)
+
+    The general client is available as :attr:`core` for anything this one does not wrap.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.core = apiauto.Client(
+            api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+            **_core_options(base_url),
+        )
+
+    def close(self) -> None:
+        """Close the HTTP connections (unless the ``http_client`` was yours)."""
+        self.core.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def cars(self, **filters: Unpack[CarFilters]) -> CarsPage:
+        """One page of Copart cars: ``GET /cars?market=us``.
+
+        Takes the filters of :meth:`apiauto.Client.cars`: ``brand``, ``model``, ``year_min``,
+        ``year_max``, ``price_min``, ``price_max`` (in USD), ``mileage_max``, ``sort``,
+        ``limit``, ``cursor`` and more. Every car returned counts against the quota.
+        """
+        page = self.core.cars(MARKET, **filters)
+        # The us market mixes Copart and IAAI: keep this source's lots. The page can hold
+        # fewer than `limit` cars, and `count` is unknown for one source.
+        return {
+            "items": [car for car in page["items"] if _ours(car)],
+            "next_cursor": page["next_cursor"],
+            "count": None,
+        }
+
+    def iter_cars(self, *, max_items: int | None = None, **filters: Unpack[CarFilters]) -> Iterator[Car]:
+        """Every Copart car matching the filters, following ``next_cursor``.
+
+        Args:
+            max_items: Stop after this many cars.
+            **filters: The filters of :meth:`cars`; ``limit`` sets the page size.
+        """
+        if max_items is not None and max_items <= 0:
+            return
+        taken = 0
+        for car in self.core.iter_cars(MARKET, **filters):
+            if _ours(car):
+                yield car
+                taken += 1
+                if max_items is not None and taken >= max_items:
+                    return
+
+    def car(self, listing: str | int) -> Car:
+        """One car by listing number (``68055056``) or record id (``copart:68055056``).
+
+        Cars taken off sale stay available for 14 days with ``is_active=False``.
+        """
+        return self.core.car(car_id(listing))
+
+    def changes(
+        self,
+        since: datetime | str,
+        *,
+        type: ChangeType | Sequence[ChangeType] | None = None,  # noqa: A002
+        min_pct: float | Decimal | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> ChangesPage:
+        """One page of the change feed: new cars, cars taken off sale and price changes since a moment."""
+        page = self.core.changes(MARKET, since, type=type, min_pct=min_pct, limit=limit, cursor=cursor)
+        return {
+            "items": [change for change in page["items"] if _our_change(change)],
+            "next_cursor": page["next_cursor"],
+        }
+
+    def iter_changes(
+        self,
+        since: datetime | str,
+        *,
+        type: ChangeType | Sequence[ChangeType] | None = None,  # noqa: A002
+        min_pct: float | Decimal | None = None,
+        limit: int | None = None,
+        max_items: int | None = None,
+    ) -> Iterator[Change]:
+        """Every event of the change feed since a moment, following ``next_cursor``."""
+        if max_items is not None and max_items <= 0:
+            return
+        taken = 0
+        for change in self.core.iter_changes(MARKET, since, type=type, min_pct=min_pct, limit=limit):
+            if _our_change(change):
+                yield change
+                taken += 1
+                if max_items is not None and taken >= max_items:
+                    return
+
+    def brands(self) -> list[ReferenceItem]:
+        """Makes of the us market with car counts, most frequent first. Free."""
+        return self.core.brands(MARKET)
+
+    def models(self, brand: str) -> list[ReferenceItem]:
+        """Models of a make with car counts. Free."""
+        return self.core.models(MARKET, brand)
+
+    def dictionaries(self) -> Dictionaries:
+        """Canonical values of ``fuel``, ``transmission``, ``body_type`` and more. Free."""
+        return self.core.dictionaries()
+
+    def status(self) -> Market:
+        """The us market: plan access, data age and the number of active cars. Free."""
+        return _own_market(self.core.markets())
+
+    def usage(self) -> Usage:
+        """The plan, its term and how much of the quota is spent. Free."""
+        return self.core.usage()
+
+    def live(
+        self,
+        *,
+        make: str | None = None,
+        model: str | None = None,
+        year_min: int | None = None,
+        year_max: int | None = None,
+        price_max: int | None = None,
+        page: int | None = None,
+    ) -> list[Car]:
+        """Search lots live at the auction data provider: ``GET /us/live``, this source's lots only.
+
+        For lots that are not in the catalog copy yet. Pro and Max plans; it spends a
+        separate monthly counter. ``price_max`` is in US dollars, ``page`` is 1-100.
+        """
+        lots = self.core.us_live(
+            make=make, model=model, year_min=year_min, year_max=year_max, price_max=price_max, page=page
+        )
+        return [car for car in lots if _ours(car)]
+
+
+class AsyncClient:
+    """Copart client of the apiauto.space API for asyncio; the methods of :class:`Client`.
+
+    ::
+
+        async with copart_api.AsyncClient() as client:
+            page = await client.cars(brand="Toyota", limit=20)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.core = apiauto.AsyncClient(
+            api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+            **_core_options(base_url),
+        )
+
+    async def close(self) -> None:
+        """Close the HTTP connections (unless the ``http_client`` was yours)."""
+        await self.core.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def cars(self, **filters: Unpack[CarFilters]) -> CarsPage:
+        """One page of Copart cars; see :meth:`Client.cars`."""
+        page = await self.core.cars(MARKET, **filters)
+        return {
+            "items": [car for car in page["items"] if _ours(car)],
+            "next_cursor": page["next_cursor"],
+            "count": None,
+        }
+
+    async def iter_cars(
+        self, *, max_items: int | None = None, **filters: Unpack[CarFilters]
+    ) -> AsyncIterator[Car]:
+        """Every Copart car matching the filters; see :meth:`Client.iter_cars`."""
+        if max_items is not None and max_items <= 0:
+            return
+        taken = 0
+        async for car in self.core.iter_cars(MARKET, **filters):
+            if _ours(car):
+                yield car
+                taken += 1
+                if max_items is not None and taken >= max_items:
+                    return
+
+    async def car(self, listing: str | int) -> Car:
+        """One car by listing number or record id; see :meth:`Client.car`."""
+        return await self.core.car(car_id(listing))
+
+    async def changes(
+        self,
+        since: datetime | str,
+        *,
+        type: ChangeType | Sequence[ChangeType] | None = None,  # noqa: A002
+        min_pct: float | Decimal | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> ChangesPage:
+        """One page of the change feed; see :meth:`Client.changes`."""
+        page = await self.core.changes(MARKET, since, type=type, min_pct=min_pct, limit=limit, cursor=cursor)
+        return {
+            "items": [change for change in page["items"] if _our_change(change)],
+            "next_cursor": page["next_cursor"],
+        }
+
+    async def brands(self) -> list[ReferenceItem]:
+        """Makes of the us market with car counts. Free."""
+        return await self.core.brands(MARKET)
+
+    async def models(self, brand: str) -> list[ReferenceItem]:
+        """Models of a make with car counts. Free."""
+        return await self.core.models(MARKET, brand)
+
+    async def dictionaries(self) -> Dictionaries:
+        """Canonical values of ``fuel``, ``transmission``, ``body_type`` and more. Free."""
+        return await self.core.dictionaries()
+
+    async def status(self) -> Market:
+        """The us market: plan access, data age and the number of active cars. Free."""
+        return _own_market(await self.core.markets())
+
+    async def usage(self) -> Usage:
+        """The plan, its term and how much of the quota is spent. Free."""
+        return await self.core.usage()

copart_api-0.1.0/src/copart_api/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

copart_api-0.1.0/src/copart_api/types.py

@@ -0,0 +1,77 @@
+"""Types of the Copart-only fields of a record.
+
+Every record has the same common keys in every market (see :class:`apiauto.Car`);
+the fields only Copart has are in ``car["raw"]``. :func:`raw` returns them typed::
+
+    from copart_api import raw
+
+    extra = raw(car)
+    print(extra.get("source_values"))
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict, cast
+
+from apiauto import Car
+
+__all__ = ["CopartRaw", "FxQuote", "raw"]
+
+
+class FxQuote(TypedDict):
+    """The ECB daily rate behind ``price_usd``."""
+
+    currency: str
+    usd_per_unit: str
+    """Decimal string: US dollars for one unit of ``currency``."""
+    date: str
+    source: str
+
+
+class CopartRaw(TypedDict, total=False):
+    """Copart-only fields of a record (``car["raw"]``). Keys can be missing; read them with ``.get``."""
+
+    lot_number: str | None
+    """The lot number at the auction."""
+    status: int | None
+    sale_date: str | None
+    """Auction date and time, ISO 8601."""
+    bid: int | float | None
+    """The current bid, US dollars."""
+    buy_now: int | float | None
+    """Buy-now price, US dollars."""
+    final_bid: int | float | None
+    """The final bid of a sold lot, US dollars."""
+    damage_main: str | None
+    """Primary damage, a canonical value such as ``front`` or ``rear``."""
+    damage_second: str | None
+    title_doc: str | None
+    """Title document type, a canonical value such as ``clean`` or ``salvage``."""
+    keys_available: bool | None
+    airbags: Any
+    odometer_mi: int | None
+    """Odometer in miles as the auction shows it (``mileage_km`` is converted)."""
+    odometer_status: Any
+    condition: Any
+    grade_iaai: Any
+    estimate_repair_price: int | float | None
+    pre_accident_price: int | float | None
+    clean_wholesale_price: int | float | None
+    seller: str | None
+    seller_type: Any
+    location_branch: str | None
+    """The auction yard, for example ``Nashville (TN)``."""
+    latitude: float | None
+    longitude: float | None
+    video_url: str | None
+    drive: str | None
+    """``fwd``, ``rwd``, ``awd`` or ``4wd``."""
+    cylinders: int | None
+    source_values: dict[str, str | None]
+    """The auction's own spellings of make, model, fuel, damage and more."""
+    fx: FxQuote | None
+
+
+def raw(car: Car) -> CopartRaw:
+    """The Copart-only fields of a record, typed as :class:`CopartRaw`."""
+    return cast(CopartRaw, car.get("raw") or {})

copart_api-0.1.0/tests/test_client.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+import pytest
+
+import copart_api
+
+KEY = "test-key-1234567890"
+
+
+def car(car_id: str) -> dict[str, Any]:
+    source = car_id.split(":", 1)[0]
+    return {"id": car_id, "market": "us", "source": source, "title": "car", "price": {"amount": "1.00"}}
+
+
+def page(ids: list[str], next_cursor: str | None = None, count: int | None = None) -> dict[str, Any]:
+    return {"items": [car(i) for i in ids], "next_cursor": next_cursor, "count": count}
+
+
+class Recorder:
+    """Replays queued JSON bodies and records the requests."""
+
+    def __init__(self, *bodies: Any) -> None:
+        self.bodies = list(bodies)
+        self.requests: list[httpx.Request] = []
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        return httpx.Response(200, json=self.bodies.pop(0))
+
+    def params(self, index: int = -1) -> dict[str, str]:
+        return dict(self.requests[index].url.params)
+
+
+def client(recorder: Callable[[httpx.Request], httpx.Response]) -> copart_api.Client:
+    http = httpx.Client(transport=httpx.MockTransport(recorder))
+    return copart_api.Client(KEY, http_client=http, max_retries=0)
+
+
+def test_constants() -> None:
+    assert copart_api.MARKET == "us"
+    assert copart_api.SOURCE == "copart"
+    assert copart_api.SHARED_MARKET is True
+    assert copart_api.__version__ == "0.1.0"
+
+
+def test_cars_presets_the_market() -> None:
+    rec = Recorder(page(["copart:1", "copart:2"], count=2))
+    with client(rec) as api:
+        result = api.cars(brand="Toyota", year_min=2020, limit=2)
+    assert [c["id"] for c in result["items"]] == ["copart:1", "copart:2"]
+    assert rec.requests[0].url.path == "/v1/cars"
+    assert rec.params() == {"market": "us", "brand": "Toyota", "year_min": "2020", "limit": "2"}
+    assert rec.requests[0].headers["x-api-key"] == KEY
+
+
+def test_unknown_filter_is_rejected() -> None:
+    with client(Recorder()) as api, pytest.raises(TypeError):
+        api.cars(market="kr")  # type: ignore[call-arg]
+
+
+@pytest.mark.parametrize(
+    ("listing", "path"),
+    [
+        ("68055056", "/v1/cars/copart:68055056"),
+        (68055056, "/v1/cars/copart:68055056"),
+        ("copart:68055056", "/v1/cars/copart:68055056"),
+    ],
+)
+def test_car_accepts_number_or_id(listing: str | int, path: str) -> None:
+    rec = Recorder(car("copart:68055056"))
+    with client(rec) as api:
+        assert api.car(listing)["id"] == "copart:68055056"
+    assert rec.requests[0].url.path == path
+
+
+@pytest.mark.parametrize("bad", ["", "  ", "other:123", "copart:"])
+def test_car_id_rejects_foreign_ids(bad: str) -> None:
+    with pytest.raises(ValueError, match=r"\S"):
+        copart_api.car_id(bad)
+
+
+def test_brands_models_and_status() -> None:
+    markets = {
+        "items": [
+            {"market": "kr", "source": "encar", "active_cars": 1},
+            {"market": "cn", "source": "che168", "active_cars": 2},
+            {"market": "us", "source": "copart+iaai", "active_cars": 3},
+        ]
+    }
+    rec = Recorder([{"name": "Toyota", "count": 5}], [{"name": "Camry", "count": 2}], markets)
+    with client(rec) as api:
+        assert api.brands()[0]["name"] == "Toyota"
+        assert rec.params(0) == {"market": "us"}
+        assert api.models("Toyota")[0]["count"] == 2
+        assert rec.params(1) == {"market": "us", "brand": "Toyota"}
+        assert api.status()["market"] == "us"
+
+
+def test_raw_is_typed_view() -> None:
+    record: Any = {"id": "copart:68055056", "raw": {"source_values": {"brand": "x"}}}
+    assert copart_api.raw(record).get("source_values") == {"brand": "x"}
+    assert copart_api.raw({"id": "copart:68055056"}) == {}  # type: ignore[typeddict-item]
+
+
+def test_cars_keeps_only_this_auction() -> None:
+    rec = Recorder(page(["copart:1", "other:2", "copart:3"], next_cursor="c2", count=3))
+    with client(rec) as api:
+        result = api.cars(limit=3)
+    assert [c["id"] for c in result["items"]] == ["copart:1", "copart:3"]
+    assert result["next_cursor"] == "c2"
+    assert result["count"] is None
+
+
+def test_iter_cars_collects_max_items_across_pages() -> None:
+    rec = Recorder(
+        page(["other:1", "copart:2"], next_cursor="c2"),
+        page(["other:3", "other:4"], next_cursor="c3"),
+        page(["copart:5", "copart:6"], next_cursor="c4"),
+    )
+    with client(rec) as api:
+        ids = [c["id"] for c in api.iter_cars(max_items=2, limit=2)]
+    assert ids == ["copart:2", "copart:5"]
+    assert len(rec.requests) == 3
+    assert all(r.url.params["market"] == "us" for r in rec.requests)
+
+
+def test_iter_cars_zero_items_makes_no_request() -> None:
+    rec = Recorder()
+    with client(rec) as api:
+        assert list(api.iter_cars(max_items=0)) == []
+    assert rec.requests == []
+
+
+def test_changes_keep_only_this_auction() -> None:
+    feed = {
+        "items": [
+            {"id": 1, "car_id": "copart:1", "type": "added"},
+            {"id": 2, "car_id": "other:2", "type": "added"},
+        ],
+        "next_cursor": None,
+    }
+    rec = Recorder(feed, feed)
+    with client(rec) as api:
+        assert [c["car_id"] for c in api.changes("2026-11-01T00:00:00Z")["items"]] == ["copart:1"]
+        assert [c["id"] for c in api.iter_changes("2026-11-01T00:00:00Z", max_items=5)] == [1]
+
+
+def test_live_keeps_only_this_auction() -> None:
+    rec = Recorder([car("copart:1"), car("other:2")])
+    with client(rec) as api:
+        lots = api.live(make="Toyota", page=1)
+    assert [c["id"] for c in lots] == ["copart:1"]
+    assert rec.requests[0].url.path == "/v1/us/live"
+    assert rec.params() == {"make": "Toyota", "page": "1"}
+
+
+def test_async_client() -> None:
+    rec = Recorder(page(["copart:1"]), car("copart:68055056"), page(["copart:1"]))
+
+    async def run() -> list[str]:
+        http = httpx.AsyncClient(transport=httpx.MockTransport(rec))
+        async with copart_api.AsyncClient(KEY, http_client=http, max_retries=0) as api:
+            first = await api.cars(limit=1)
+            one = await api.car("68055056")
+            more = [c["id"] async for c in api.iter_cars(max_items=1, limit=1)]
+        await http.aclose()
+        return [first["items"][0]["id"], one["id"], *more]
+
+    assert asyncio.run(run()) == ["copart:1", "copart:68055056", "copart:1"]
+    assert all(r.url.params.get("market") in (None, "us") for r in rec.requests)
+
+
+def test_errors_are_the_apiauto_ones() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = {"error": {"code": "not_found", "message": "no such car"}}
+        return httpx.Response(404, content=json.dumps(body), headers={"content-type": "application/json"})
+
+    with client(handler) as api, pytest.raises(copart_api.NotFoundError):
+        api.car("1")

copart_api-0.1.0/tests/test_live.py

@@ -0,0 +1,22 @@
+"""Smoke test against the live API; runs only when APIAUTO_KEY is set and spends a few records."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+import copart_api
+
+pytestmark = pytest.mark.skipif(not os.environ.get("APIAUTO_KEY"), reason="set APIAUTO_KEY to run")
+
+
+def test_live_cars_and_car() -> None:
+    with copart_api.Client() as api:
+        assert api.status()["market"] == "us"
+        cars = list(api.iter_cars(max_items=3, limit=10))
+        assert cars, "the catalog returned no Copart cars"
+        assert all(car["source"] == "copart" for car in cars)
+        one = api.car(cars[0]["source_id"])
+        assert one["id"] == cars[0]["id"]
+        assert isinstance(copart_api.raw(one), dict)