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.3.0
• 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.

Install the current public release with pip install "keble-keepa>=1.3.0,<2". Version 1.3.0 requires the shared keble-db>=1.9.0 persistence and lease contract.

Runtime Contract

• Sync Keepa calls use requests; async Keepa calls use aiohttp and should respect standard proxy environment variables when configured by callers.
• Bestseller boards expose both request_best_sellers and genuine-aiohttp arequest_best_sellers; the async method uses the same typed Redis/Mongo cache key and emits usage only after real upstream I/O.
• 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

uv sync --group test
RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 RUN_DB_STACK=1 \
  uv run pytest -q -m "not live and not container"
uv run pytest -q -m "not live and not slow and not eval and not local_stack and not db_stack and not container"
uv run pytest -q -m eval
uv run npx --yes pyright .

The first command is the local-full Keble development proof and runs Mongo-backed integration tests with isolated cache collections. The second is the portable-offline fallback for no-DB machines. Selecting -m eval is the eval opt-in; there is no generic RUN_EVALS gate.

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.

Async cache tests receive a process-unique namespaced ExtendedAsyncRedis and delete all owned keys after every test. Keep this isolation when adding new cache consumers; an un-namespaced wrapper is a test and production leak risk.

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.