Problem
New users repeatedly get stuck on Python-environment setup before tycoon ever runs. Concrete case: a beta tester's machine defaulted to Python 3.14 (no dbt-core/dbt-duckdb wheels), so tycoon data transform run broke (#55). The v0.1.8 requires-python = ">=3.12,<3.14" cap only converts that into an install-time resolver error and assumes the user already uses uv. And tycoon doctor never checks the interpreter, so the failure is invisible until a dbt command fails — far from its cause.
Root cause: tycoon inherits whatever python3/pip the user happens to have, instead of owning the interpreter choice.
Approach — decided: Option A, a single project-local env
tycoon manages a project-local .venv/ containing tycoon + dbt + dlt + duckdb, created with a pinned, compatible interpreter via uv. tycoon already assumes a single env (in-process dlt/duckdb; dbt resolved at Path(sys.executable).parent / "dbt"), so this is the low-churn fit.
Getting the version right (the crux):
uv venv --python <X> where X satisfies >=3.12,<3.14. uv auto-downloads a python-build-standalone CPython if the system has no compatible interpreter — so a machine with only 3.14 still works with zero manual installs.- Write
.python-version (3.12) into the project dir to pin subsequent uv commands. (Safe here — this only bit CI when placed at the package repo root.)
- New
tycoon doctor check: verify the active interpreter is in [3.12, 3.14); on failure, actionable message + tycoon doctor --fix / tycoon setup that (re)builds .venv correctly.
Bootstrap (chicken-and-egg): a tiny entry like uvx database-tycoon init (or a one-line installer) creates .venv with the right Python and installs everything into it; thereafter the user just uses that .venv.
Scope (proposed)
Out of scope / future
- Option B — tycoon installed once as a global
uv tool, with the project .venv a separate dbt/dlt env tycoon shells into. More flexible, but needs the in-process dlt/duckdb calls refactored to subprocess + introduces two-environment confusion. Revisit later.
- Standalone compiled binary (dbt-Fusion-style). Not now.
References
Target: v0.1.9.
Problem
New users repeatedly get stuck on Python-environment setup before tycoon ever runs. Concrete case: a beta tester's machine defaulted to Python 3.14 (no dbt-core/dbt-duckdb wheels), so
tycoon data transform runbroke (#55). The v0.1.8requires-python = ">=3.12,<3.14"cap only converts that into an install-time resolver error and assumes the user already uses uv. Andtycoon doctornever checks the interpreter, so the failure is invisible until a dbt command fails — far from its cause.Root cause: tycoon inherits whatever
python3/pipthe user happens to have, instead of owning the interpreter choice.Approach — decided: Option A, a single project-local env
tycoon manages a project-local
.venv/containing tycoon + dbt + dlt + duckdb, created with a pinned, compatible interpreter via uv. tycoon already assumes a single env (in-processdlt/duckdb; dbt resolved atPath(sys.executable).parent / "dbt"), so this is the low-churn fit.Getting the version right (the crux):
uv venv --python <X>where X satisfies>=3.12,<3.14. uv auto-downloads a python-build-standalone CPython if the system has no compatible interpreter — so a machine with only 3.14 still works with zero manual installs..python-version(3.12) into the project dir to pin subsequent uv commands. (Safe here — this only bit CI when placed at the package repo root.)tycoon doctorcheck: verify the active interpreter is in[3.12, 3.14); on failure, actionable message +tycoon doctor --fix/tycoon setupthat (re)builds.venvcorrectly.Bootstrap (chicken-and-egg): a tiny entry like
uvx database-tycoon init(or a one-line installer) creates.venvwith the right Python and installs everything into it; thereafter the user just uses that.venv.Scope (proposed)
tycoon setup(and/ortycoon initintegration): create/validate project.venvvia uv (uv venv --python, auto-download), install tycoon + data deps..python-versioninto the project dir.tycoon doctorinterpreter check (range[3.12,3.14)) +--fix. Highest-leverage piece — closes the blind spot that hid requires-python has no upper bound → Python 3.14 gets selected, dbt breaks #55.shutil.which("uv"); offer to bootstrap via the standalone installer if absent (with consent). Confirm whether theuvwheel's binary-location API (uv.find_uv_bin()) is usable at impl time.Out of scope / future
uv tool, with the project.venva separate dbt/dlt env tycoon shells into. More flexible, but needs the in-processdlt/duckdbcalls refactored to subprocess + introduces two-environment confusion. Revisit later.References
requires-pythoncap).Target: v0.1.9.