Appendix A — Python Setup
Goal
Run the ShopOps reference code on Python 3.11+ with typing and tests.
Install
cd manuscript/code/shopops
python3.11 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest -q
No model API key is required for mock/scripted policies. Set MODEL_API_KEY only when exercising live gateway paths.
Typing
- Prefer
list[str],dict[str, Any],X | None(3.10+). - Use
dataclassforState/Action/Observation. - Use
Protocolfor stores and executors you will swap in tests.
Example:
from typing import Protocol
class MemoryStore(Protocol):
def get(self, key: str) -> dict | None: ...
def put(self, key: str, value: dict) -> None: ...
Testing rings
| Ring | Command | Intent |
|---|---|---|
| 0 | pytest tests/ -q | Pure units: policy, FSM, schemas |
| 1 | pytest evals/ -q | Trajectory properties on fixtures |
| 2 | nightly simulator | Fault injection (optional) |
Put regression fixtures next to the behaviour they protect. A red send-window test blocks merge.
Project layout reminder
See manuscript/code/shopops/README.md and manuscript/code-plan.md. Teaching scripts may live under examples/chXX_.
Common issues
| Issue | Fix |
|---|---|
| Wrong Python | python3 --version ≥ 3.11 |
| Imports fail | pip install -e . from shopops/ root |
| Tests miss package | pythonpath = ["."] in pyproject.toml |
| Docker smoke | Appendix C / docker compose up |
Optional tools
ruff/mypy— author recommendation for larger forks; not required to read the book.httpx— when chapters introduce real HTTP tools.