che168-api 0.1.0__tar.gz

che168_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

che168_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 `cn`,
+  `car_id()`, `raw()` and `Che168Raw` types.

che168_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.

che168_api-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: che168-api
+Version: 0.1.0
+Summary: Che168 API client for Python: Chinese used-car listings from Che168 as JSON, from the apiauto.space team
+Project-URL: Homepage, https://apiauto.space/en/che168-api/
+Project-URL: Documentation, https://apiauto.space/en/docs/
+Project-URL: Repository, https://github.com/apiauto-space/che168-api
+Project-URL: Issues, https://github.com/apiauto-space/che168-api/issues
+Project-URL: Changelog, https://github.com/apiauto-space/che168-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 listings,che168,che168 api,china used cars,chinese cars,used cars,vehicle data
+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
+
+# che168-api — Che168 API client for Python
+
+[![PyPI version](https://img.shields.io/pypi/v/che168-api.svg)](https://pypi.org/project/che168-api/)
+[![Python versions](https://img.shields.io/pypi/pyversions/che168-api.svg)](https://pypi.org/project/che168-api/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/apiauto-space/che168-api/blob/main/LICENSE)
+
+`che168-api` gives you Chinese used-car listings from Che168 as clean JSON through the [apiauto.space](https://apiauto.space/en/che168-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 `cn`, plus types for the Che168-only fields. It comes from the apiauto.space team;
+the project is not affiliated with Che168 or Autohome.
+
+- Sync `Client` and `AsyncClient`, retries on 429 and 5xx, one exception class per API error
+- `car("59997075")` takes the Che168 listing number as well as the record id
+- `Che168Raw` types for the Che168-only fields in `car["raw"]`
+- Python 3.10+, `py.typed`, checked with `mypy --strict`
+
+## Install
+
+```bash
+pip install che168-api
+```
+
+The module you import is `che168_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 che168_api
+
+with che168_api.Client() as client:  # reads APIAUTO_KEY
+    page = client.cars(brand="BYD", year_min=2020, limit=20)
+    for car in page["items"]:
+        print(car["id"], car["title"], car["price"]["amount"], car["price"]["currency"])
+
+    one = client.car("59997075")  # a listing number or "che168:59997075"
+    print(one["listing_url"], one["photos"][:1])
+```
+
+A record looks like this (shortened; real values from the catalog):
+
+```json
+{
+  "id": "che168:59997075",
+  "market": "cn",
+  "source": "che168",
+  "source_id": "59997075",
+  "title": "2023 Lincoln Navigator",
+  "brand": "Lincoln",
+  "model": "Navigator",
+  "year": 2023,
+  "mileage_km": 80000,
+  "fuel": "gasoline",
+  "transmission": "automatic",
+  "body_type": "suv",
+  "price": {
+    "amount": "136000.00",
+    "currency": "CNY"
+  },
+  "price_usd": "20298.27",
+  "location": {
+    "country": "CN",
+    "region": null,
+    "city": "Shenzhen"
+  },
+  "listing_url": "https://www.che168.com/dealer/534107/59997075.html",
+  "is_active": true,
+  "first_seen_at": "2026-09-22T16:29:11.202005Z",
+  "photos": [
+    "https://api.apiauto.space/img/che168:59997075/1.jpg?exp=...&sig=..."
+  ],
+  "raw": {
+    "che168_infoid": "59997075",
+    "power_hp": 261,
+    "drive": "awd",
+    "first_registration": "2023-09-01",
+    "imported": false
+  }
+}
+```
+
+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 CNY, `price_usd` is converted at the ECB daily rate.
+
+## Methods
+
+| Method | What it does | Quota |
+|---|---|---|
+| `cars(**filters)` | One page of Che168 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 |
+
+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.
+
+## Che168-only fields
+
+```python
+from che168_api import raw
+
+extra = raw(car)  # typed as Che168Raw
+print(extra.get("source_values"))
+```
+
+`Che168Raw` lists the keys with comments; every key is optional, so read them with `.get`.
+
+## Links
+
+- [Che168 API on apiauto.space](https://apiauto.space/en/che168-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/), [`copart-api`](https://pypi.org/project/copart-api/), [`iaai-api`](https://pypi.org/project/iaai-api/)
+- [Examples in curl, Python, JavaScript and PHP](https://github.com/apiauto-space/che168-api-examples)
+- The JavaScript version of this client: [`che168-api` on npm](https://www.npmjs.com/package/che168-api)
+
+## License
+
+MIT. Che168 is a trademark of its owner; it is named here only to say which listings the client returns.

che168_api-0.1.0/README.md

@@ -0,0 +1,138 @@
+# che168-api — Che168 API client for Python
+
+[![PyPI version](https://img.shields.io/pypi/v/che168-api.svg)](https://pypi.org/project/che168-api/)
+[![Python versions](https://img.shields.io/pypi/pyversions/che168-api.svg)](https://pypi.org/project/che168-api/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/apiauto-space/che168-api/blob/main/LICENSE)
+
+`che168-api` gives you Chinese used-car listings from Che168 as clean JSON through the [apiauto.space](https://apiauto.space/en/che168-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 `cn`, plus types for the Che168-only fields. It comes from the apiauto.space team;
+the project is not affiliated with Che168 or Autohome.
+
+- Sync `Client` and `AsyncClient`, retries on 429 and 5xx, one exception class per API error
+- `car("59997075")` takes the Che168 listing number as well as the record id
+- `Che168Raw` types for the Che168-only fields in `car["raw"]`
+- Python 3.10+, `py.typed`, checked with `mypy --strict`
+
+## Install
+
+```bash
+pip install che168-api
+```
+
+The module you import is `che168_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 che168_api
+
+with che168_api.Client() as client:  # reads APIAUTO_KEY
+    page = client.cars(brand="BYD", year_min=2020, limit=20)
+    for car in page["items"]:
+        print(car["id"], car["title"], car["price"]["amount"], car["price"]["currency"])
+
+    one = client.car("59997075")  # a listing number or "che168:59997075"
+    print(one["listing_url"], one["photos"][:1])
+```
+
+A record looks like this (shortened; real values from the catalog):
+
+```json
+{
+  "id": "che168:59997075",
+  "market": "cn",
+  "source": "che168",
+  "source_id": "59997075",
+  "title": "2023 Lincoln Navigator",
+  "brand": "Lincoln",
+  "model": "Navigator",
+  "year": 2023,
+  "mileage_km": 80000,
+  "fuel": "gasoline",
+  "transmission": "automatic",
+  "body_type": "suv",
+  "price": {
+    "amount": "136000.00",
+    "currency": "CNY"
+  },
+  "price_usd": "20298.27",
+  "location": {
+    "country": "CN",
+    "region": null,
+    "city": "Shenzhen"
+  },
+  "listing_url": "https://www.che168.com/dealer/534107/59997075.html",
+  "is_active": true,
+  "first_seen_at": "2026-09-22T16:29:11.202005Z",
+  "photos": [
+    "https://api.apiauto.space/img/che168:59997075/1.jpg?exp=...&sig=..."
+  ],
+  "raw": {
+    "che168_infoid": "59997075",
+    "power_hp": 261,
+    "drive": "awd",
+    "first_registration": "2023-09-01",
+    "imported": false
+  }
+}
+```
+
+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 CNY, `price_usd` is converted at the ECB daily rate.
+
+## Methods
+
+| Method | What it does | Quota |
+|---|---|---|
+| `cars(**filters)` | One page of Che168 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 |
+
+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.
+
+## Che168-only fields
+
+```python
+from che168_api import raw
+
+extra = raw(car)  # typed as Che168Raw
+print(extra.get("source_values"))
+```
+
+`Che168Raw` lists the keys with comments; every key is optional, so read them with `.get`.
+
+## Links
+
+- [Che168 API on apiauto.space](https://apiauto.space/en/che168-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/), [`copart-api`](https://pypi.org/project/copart-api/), [`iaai-api`](https://pypi.org/project/iaai-api/)
+- [Examples in curl, Python, JavaScript and PHP](https://github.com/apiauto-space/che168-api-examples)
+- The JavaScript version of this client: [`che168-api` on npm](https://www.npmjs.com/package/che168-api)
+
+## License
+
+MIT. Che168 is a trademark of its owner; it is named here only to say which listings the client returns.

che168_api-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "che168-api"
+dynamic = ["version"]
+description = "Che168 API client for Python: Chinese used-car listings from Che168 as JSON, from the apiauto.space team"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "apiauto.space" }]
+keywords = ["che168", "che168 api", "chinese cars", "china used cars", "used cars", "car listings", "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/che168-api/"
+Documentation = "https://apiauto.space/en/docs/"
+Repository = "https://github.com/apiauto-space/che168-api"
+Issues = "https://github.com/apiauto-space/che168-api/issues"
+Changelog = "https://github.com/apiauto-space/che168-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/che168_api/_version.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "CHANGELOG.md", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/che168_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"]

che168_api-0.1.0/src/che168_api/__init__.py

@@ -0,0 +1,72 @@
+"""Che168 API client for Python: Chinese used-car listings from Che168 as JSON.
+
+A thin layer over the apiauto.space client (``apiauto``) with the market preset::
+
+    import che168_api
+
+    with che168_api.Client() as client:  # the key comes from APIAUTO_KEY
+        for car in client.cars(brand="BYD", year_min=2020, limit=20)["items"]:
+            print(car["id"], car["title"], car["price"]["amount"])
+
+From the apiauto.space team. Not affiliated with Che168 or Autohome.
+"""
+
+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 Che168Raw, FxQuote, raw
+
+__all__ = [
+    "MARKET",
+    "SHARED_MARKET",
+    "SOURCE",
+    "APIConnectionError",
+    "ApiautoError",
+    "AsyncClient",
+    "AuthenticationError",
+    "BadRequestError",
+    "Car",
+    "CarFilters",
+    "CarsPage",
+    "Change",
+    "ChangeType",
+    "ChangesPage",
+    "Che168Raw",
+    "Client",
+    "FxQuote",
+    "Market",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "Price",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ReferenceItem",
+    "ServerError",
+    "ServiceUnavailableError",
+    "Usage",
+    "__version__",
+    "car_id",
+    "raw",
+]

che168_api-0.1.0/src/che168_api/_client.py

@@ -0,0 +1,285 @@
+"""Che168 clients: the apiauto clients with the market preset to ``cn``."""
+
+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["cn"] = "cn"
+"""The apiauto.space market of Che168."""
+SOURCE: Literal["che168"] = "che168"
+"""The ``source`` of every record this package returns."""
+SHARED_MARKET = False
+"""``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 Che168 listing number: ``59997075`` -> ``che168:59997075``.
+
+    An id that already has the ``che168:`` 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 Che168 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:
+    """Che168 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 che168_api.Client() as client:
+            page = client.cars(brand="BYD", 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 Che168 cars: ``GET /cars?market=cn``.
+
+        Takes the filters of :meth:`apiauto.Client.cars`: ``brand``, ``model``, ``year_min``,
+        ``year_max``, ``price_min``, ``price_max`` (in CNY), ``mileage_max``, ``sort``,
+        ``limit``, ``cursor`` and more. Every car returned counts against the quota.
+        """
+        page = self.core.cars(MARKET, **filters)
+        return page
+
+    def iter_cars(self, *, max_items: int | None = None, **filters: Unpack[CarFilters]) -> Iterator[Car]:
+        """Every Che168 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.
+        """
+        yield from self.core.iter_cars(MARKET, max_items=max_items, **filters)
+
+    def car(self, listing: str | int) -> Car:
+        """One car by listing number (``59997075``) or record id (``che168:59997075``).
+
+        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 page
+
+    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``."""
+        yield from self.core.iter_changes(
+            MARKET, since, type=type, min_pct=min_pct, limit=limit, max_items=max_items
+        )
+
+    def brands(self) -> list[ReferenceItem]:
+        """Makes of the cn 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 cn 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()
+
+
+class AsyncClient:
+    """Che168 client of the apiauto.space API for asyncio; the methods of :class:`Client`.
+
+    ::
+
+        async with che168_api.AsyncClient() as client:
+            page = await client.cars(brand="BYD", 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 Che168 cars; see :meth:`Client.cars`."""
+        page = await self.core.cars(MARKET, **filters)
+        return page
+
+    async def iter_cars(
+        self, *, max_items: int | None = None, **filters: Unpack[CarFilters]
+    ) -> AsyncIterator[Car]:
+        """Every Che168 car matching the filters; see :meth:`Client.iter_cars`."""
+        async for car in self.core.iter_cars(MARKET, max_items=max_items, **filters):
+            yield car
+
+    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 page
+
+    async def brands(self) -> list[ReferenceItem]:
+        """Makes of the cn 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 cn 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()

che168_api-0.1.0/src/che168_api/_version.py

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

che168_api-0.1.0/src/che168_api/types.py

@@ -0,0 +1,54 @@
+"""Types of the Che168-only fields of a record.
+
+Every record has the same common keys in every market (see :class:`apiauto.Car`);
+the fields only Che168 has are in ``car["raw"]``. :func:`raw` returns them typed::
+
+    from che168_api import raw
+
+    extra = raw(car)
+    print(extra.get("source_values"))
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict, cast
+
+from apiauto import Car
+
+__all__ = ["Che168Raw", "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 Che168Raw(TypedDict, total=False):
+    """Che168-only fields of a record (``car["raw"]``). Keys can be missing; read them with ``.get``."""
+
+    che168_infoid: str
+    """The listing number on Che168."""
+    dealer_id: str | None
+    image_count: int
+    drive: str | None
+    """``fwd``, ``rwd``, ``awd`` or ``4wd``."""
+    power_hp: int | None
+    power_kw: int | None
+    seats: int | None
+    first_registration: str | None
+    """First registration date, ``YYYY-MM-DD``."""
+    imported: bool | None
+    """``True`` for an imported car, ``False`` for one made in China."""
+    source_values: dict[str, str | None]
+    """Che168's own Chinese spellings of make, model, fuel and transmission."""
+    fx: FxQuote | None
+
+
+def raw(car: Car) -> Che168Raw:
+    """The Che168-only fields of a record, typed as :class:`Che168Raw`."""
+    return cast(Che168Raw, car.get("raw") or {})

che168_api-0.1.0/tests/test_client.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+import pytest
+
+import che168_api
+
+KEY = "test-key-1234567890"
+
+
+def car(car_id: str) -> dict[str, Any]:
+    source = car_id.split(":", 1)[0]
+    return {"id": car_id, "market": "cn", "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]) -> che168_api.Client:
+    http = httpx.Client(transport=httpx.MockTransport(recorder))
+    return che168_api.Client(KEY, http_client=http, max_retries=0)
+
+
+def test_constants() -> None:
+    assert che168_api.MARKET == "cn"
+    assert che168_api.SOURCE == "che168"
+    assert che168_api.SHARED_MARKET is False
+    assert che168_api.__version__ == "0.1.0"
+
+
+def test_cars_presets_the_market() -> None:
+    rec = Recorder(page(["che168:1", "che168:2"], count=2))
+    with client(rec) as api:
+        result = api.cars(brand="BYD", year_min=2020, limit=2)
+    assert [c["id"] for c in result["items"]] == ["che168:1", "che168:2"]
+    assert rec.requests[0].url.path == "/v1/cars"
+    assert rec.params() == {"market": "cn", "brand": "BYD", "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"),
+    [
+        ("59997075", "/v1/cars/che168:59997075"),
+        (59997075, "/v1/cars/che168:59997075"),
+        ("che168:59997075", "/v1/cars/che168:59997075"),
+    ],
+)
+def test_car_accepts_number_or_id(listing: str | int, path: str) -> None:
+    rec = Recorder(car("che168:59997075"))
+    with client(rec) as api:
+        assert api.car(listing)["id"] == "che168:59997075"
+    assert rec.requests[0].url.path == path
+
+
+@pytest.mark.parametrize("bad", ["", "  ", "other:123", "che168:"])
+def test_car_id_rejects_foreign_ids(bad: str) -> None:
+    with pytest.raises(ValueError, match=r"\S"):
+        che168_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": "BYD", "count": 5}], [{"name": "Han", "count": 2}], markets)
+    with client(rec) as api:
+        assert api.brands()[0]["name"] == "BYD"
+        assert rec.params(0) == {"market": "cn"}
+        assert api.models("BYD")[0]["count"] == 2
+        assert rec.params(1) == {"market": "cn", "brand": "BYD"}
+        assert api.status()["market"] == "cn"
+
+
+def test_raw_is_typed_view() -> None:
+    record: Any = {"id": "che168:59997075", "raw": {"source_values": {"brand": "x"}}}
+    assert che168_api.raw(record).get("source_values") == {"brand": "x"}
+    assert che168_api.raw({"id": "che168:59997075"}) == {}  # type: ignore[typeddict-item]
+
+
+def test_iter_cars_passes_max_items_to_the_last_page() -> None:
+    rec = Recorder(page(["che168:1", "che168:2"], next_cursor="c2"), page(["che168:3"]))
+    with client(rec) as api:
+        ids = [c["id"] for c in api.iter_cars(max_items=3, limit=2)]
+    assert ids == ["che168:1", "che168:2", "che168:3"]
+    assert rec.params(1)["cursor"] == "c2"
+    assert rec.params(1)["limit"] == "1"
+
+
+def test_changes_presets_the_market() -> None:
+    rec = Recorder({"items": [{"id": 1, "car_id": "che168:1", "type": "added"}], "next_cursor": None})
+    with client(rec) as api:
+        result = api.changes("2026-11-01T00:00:00Z", type=["added", "price_drop"])
+    assert result["items"][0]["car_id"] == "che168:1"
+    assert rec.requests[0].url.params.get_list("type") == ["added", "price_drop"]
+    assert rec.params()["market"] == "cn"
+
+
+def test_async_client() -> None:
+    rec = Recorder(page(["che168:1"]), car("che168:59997075"), page(["che168:1"]))
+
+    async def run() -> list[str]:
+        http = httpx.AsyncClient(transport=httpx.MockTransport(rec))
+        async with che168_api.AsyncClient(KEY, http_client=http, max_retries=0) as api:
+            first = await api.cars(limit=1)
+            one = await api.car("59997075")
+            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()) == ["che168:1", "che168:59997075", "che168:1"]
+    assert all(r.url.params.get("market") in (None, "cn") 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(che168_api.NotFoundError):
+        api.car("1")

che168_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 che168_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 che168_api.Client() as api:
+        assert api.status()["market"] == "cn"
+        cars = list(api.iter_cars(max_items=3, limit=3))
+        assert cars, "the catalog returned no Che168 cars"
+        assert all(car["source"] == "che168" for car in cars)
+        one = api.car(cars[0]["source_id"])
+        assert one["id"] == cars[0]["id"]
+        assert isinstance(che168_api.raw(one), dict)