typhon.toml Overview

typhon.toml lives at the project root and drives every tyc subcommand. The default scaffold (tyc init) gets you started; this section enumerates every key.

The default

[project]
name = "myapp"
version = "0.1.0"
src = "src"
out = "build"

[python]
target = "3.13"
free-threaded = false

[optimise]
level = 0

[emit]
class-default = "dataclass"
format = true
skip-decoration-bases = []
model-extra = "forbid"
traceback-remap = false

[strictness]
no-implicit-any = true
unused-import = "warn"
exhaustive-match = "error"
methods-in-class-body = "warn"
nullable-use = "error"
require-with = "warn"
blocking-in-async = "warn"
stub-check = "error"
unintrospectable-dependency = "warn"
suggest-gather = true
suggest-perf = true
suggest-parallel = true
auto-memoise = false
auto-gather = false
auto-parallel = false
auto-parallel-reductions = false
parallel-min-size = 64
parallel-backend = "threads"
pgo-memoise = false
pgo-min-calls = 100
allow-secret-comptime = false

[checker]
external = "none"
external-args = []

[env]
required = ["DATABASE_URL"]

[dependencies]
requests = ">=2.31"

[dev-dependencies]
pytest = "8.2"

Sections

Section	Purpose	Page
[project]	Name, version, src/out dirs	→
[python]	Target version, free-threaded mode	→
[optimise]	Single-dial opt-in performance defaults	↓
[emit]	Class default, format toggle, framework-base skip list	→
[strictness]	Every strictness knob	→
[checker]	External type-checker integration	↓
[env]	Required build-time env vars	→
[dependencies] / [dev-dependencies]	Package manifest	→

See Recommended Presets for opinionated starting points.

Always-on behaviour

One emit policy is no longer configurable and runs unconditionally:

• PEP 561 .pyi stubs are emitted for every .dty file next to the project, so mypy / pyright / Pyrefly / ty can consume Typhon-authored libraries without an interop tax. The previously-documented [emit] pyi-stubs toggle has been removed.

Pydantic model classes now use [emit] model-extra (default "forbid") to control the ConfigDict(extra=…) value. See the [emit] reference for details.

[optimise]

A single project-wide dial that flips the default of four other opt-in [strictness] knobs — auto-memoise, auto-gather, auto-parallel, pgo-memoise — without touching each one individually.

[optimise]
level = 0

Key	Type	Default	Description
level	0 | 1	0	0 leaves every optimisation knob at its own default. 1 flips the default of auto-memoise / auto-gather / auto-parallel / pgo-memoise to true. Any other integer is rejected at config load.

Tip

An explicit [strictness] entry always wins over the level-derived default, so a project can opt into level = 1 and still keep one knob off:

[optimise]
level = 1               # auto-memoise / auto-gather / pgo-memoise default on…

[strictness]
auto-parallel = false   # …but this explicit entry keeps auto-parallel off

tyc build -O (or --optimise / --optimize) applies level = 1 for a single invocation without editing typhon.toml — it overrides a config level = 0 but, like the file-level level itself, never overrides an explicit [strictness] setting.

[checker]

Integrates an external type checker that runs over the emitted Python after a successful build. This is the only path that type-checks against typeshed, so it covers C-extension and stdlib APIs that runtime-venv introspection can’t see.

[checker]
external = "none"
external-args = []

Key	Type	Default	Description
external	"none" | "ty"	"none"	Which external checker to run over the emitted .py. "ty" runs Astral’s ty checker after the build.
external-args	list of strings	[]	Extra flags forwarded verbatim to the external checker.

When external = "ty", after a successful build tyc runs ty over the emitted Python. Because it checks against typeshed, it catches things runtime introspection misses — for example os.path.join(1, 2) is flagged. Any ty errors fail the build, and the diagnostics are re-attributed back to your .ty source via the .py.map sidecars, so the locations point at the code you wrote.

Requires ty on PATH:

pip install ty        # or: uv tool install ty

Tip

You can run the same pass for a single invocation without editing typhon.toml by passing --with-ty to tyc build or tyc check. tyc check --with-ty builds to a throwaway directory first, then runs ty over it.

Note

A Phase 2 embedded (in-process) ty checker is prototyped but not shipped — it depends on a git dependency that cargo deny disallows. For now, external ty is the supported path.

Conventions

• Boolean keys: lowercase true / false.
• Path keys: relative to the manifest directory.
• Enum keys: lowercase strings ("error", "warn", "off").
• Version selectors in [dependencies]: uv-compatible ("*", ">=2.31", "==8.2", bare version → "==N").