Metadata-Version: 2.4
Name: keble-keepa
Version: 1.2.3
Author-email: zhenhao-ma <bob0103779@gmail.com>
Requires-Python: <3.14,>=3.13
Requires-Dist: aiohttp<4.0.0,>=3
Requires-Dist: keble-db<2.0.0,>=1.8.1
Requires-Dist: keble-exceptions<1.0.0,>=0
Requires-Dist: keble-helpers<2.0.0,>=1.12.17
Requires-Dist: python-dateutil<3.0.0,>=2
Requires-Dist: requests<3.0.0,>=2
Requires-Dist: tenacity<10,>=8
Provides-Extra: test
Requires-Dist: pytest-asyncio<1.0.0,>=0; extra == 'test'
Requires-Dist: pytest-recording<1.0.0,>=0; extra == 'test'
Requires-Dist: pytest<9.0.0,>=8; extra == 'test'
Requires-Dist: vcrpy<8.0.0,>=6; extra == 'test'
Description-Content-Type: text/markdown

# keble-keepa

`keble-keepa` is Keble's Keepa API and cache package. It owns Keepa object
schemas, sync/async API access, Mongo cache CRUD, batch loading, time
conversion helpers, and pytest fixtures/fakes for downstream packages.

## Verified State

Checked on 2026-06-30 against `pyproject.toml`, package exports,
`keble_keepa/`, and tests.

- Package: `keble-keepa 1.2.3`
- Python: `>=3.13,<3.14`
- Critical deps: `aiohttp`, `requests`, `keble-db`, `keble-helpers`,
  `keble-exceptions`, `python-dateutil`, `tenacity`
- Source roots: `api/`, `crud/`, `schemas/`, `testing/`, `utils/`
- Public exports: Keepa API objects, batch loader, cache helpers, time
  conversion helpers, and the `keble_keepa.testing` pytest plugin.

## Runtime Contract

- Sync Keepa calls use `requests`; async Keepa calls use `aiohttp` and should
  respect standard proxy environment variables when configured by callers.
- Cache reads and writes must stay explicit about key, marketplace, and
  freshness behavior. Do not hide broad cache scans behind convenience APIs.
- Downstream tests should use `keble_keepa.testing` fixtures/fakes before
  inventing package-local Keepa mocks.

## Testing

```bash
uv sync --group test
uv run pytest -m "not live and not slow and not eval and not local_stack and not db_stack and not container"
uv run npx --yes pyright .
```

Real Keepa calls belong only in marked/env-gated live tests.
Package-owned test helpers live under `keble_keepa.testing`; do not recreate
root-level `tests/config.py`, root test packages, or legacy `tests/test_*`
source folders.

Mongo/Redis/Keepa live settings load explicit process env first, then
`tests/.env`, then the umbrella `keble.backend/.env` through
`keble_db.testing.resolve_test_env`. Set
`KEBLE_BACKEND_ENV_FILE=/path/to/.env` from unusual worktree or CI layouts.
Do not copy backend secrets into this repo.

Live Keepa canaries should make one real provider call against an isolated cache
collection. Do not add Keepa response-cache replay to live tests for speed;
cache correctness belongs in integration tests with fake/shared fixtures.

## Change Logs

Historical release notes and long AI change history live under `logs/`.

## Side Effect If Changes

- Backend report generation, product discovery, `keble-keepa-analysis`, and
  AMZ product-report workflows depend on this package for Keepa access.
- Cache query/index changes can affect production cache repair and live
  report correctness; verify query shape and cleanup.
