Regenerating Bindings

optixlog_gen.py (or your configured output file) is generated from your projects' live schemas. When a schema changes — new node types, new fields, changed enums — you must regenerate the file to keep your type-checked code in sync.

When to regenerate

Re-run optixlog generate whenever:

• A new node type is added to one of your projects.
• An existing node type gains, loses, or changes a field (type, name, required/optional).
• An enum field changes its member list.
• A new project is added to optixlog.toml.
• You upgrade the optixlog package and a new schema version is supported.

You do not need to regenerate when:

• You only change code that imports from optixlog_gen — the generated file itself is unchanged.
• You add a project to optixlog.toml but the project has no node types yet (the generated file will simply not include that project's types until they are defined).

How to regenerate

optixlog generate

This fetches the current schema from the server and overwrites the output file. The result is byte-deterministic — if the schema has not changed, the file content is identical to the previous version.

Against a fixture (offline)

optixlog generate --fixture tests/fixtures/schema.sample.json

Replace tests/fixtures/schema.sample.json with your actual fixture path.

Preview before writing

Use --dry-run to see what would be written without touching the file:

optixlog generate --dry-run

Diff against current

diff optixlog_gen.py <(optixlog generate --dry-run)

Committing optixlog_gen.py

Commit the generated file to version control. This gives every contributor access to up-to-date typed bindings without requiring each one to run generate themselves, and lets static analysis tools (pyright, mypy) work in editors and CI without an extra codegen step.

A typical workflow:

1. A schema change is deployed to the server.
2. A developer runs optixlog generate locally.
3. The updated optixlog_gen.py is committed and pushed.

Detecting drift with --check

optixlog generate --check compares a fresh render to the on-disk file without writing anything. Use it in CI to catch a committed file that is out of date relative to the current schema.

# Exit 0 if current, exit 1 if stale
optixlog generate --check

Output when current:

./optixlog_gen.py is up to date.

Output when stale (to stderr, exits 1):

./optixlog_gen.py is out of date; re-run `optixlog generate`.

Output when the file does not exist (exits 1):

./optixlog_gen.py is out of date; re-run `optixlog generate`.

--check in a CI step

- name: Verify bindings are current
  env:
    OPTIXLOG_API_KEY: ${{ secrets.OPTIXLOG_API_KEY }}
  run: optixlog generate --check

Or offline with a fixture:

- name: Verify bindings are current (offline)
  env:
    OPTIXLOG_FIXTURE: tests/fixtures/schema.sample.json
    OPTIXLOG_CONFIG_HOME: /tmp/optixlog-ci
  run: optixlog generate --check

After optixlog.toml changes

When you add or remove a [[projects]] entry (e.g. via optixlog init --force --all), always re-run generate immediately:

optixlog init --force --all --no-input
optixlog generate

Commit both files together:

git add optixlog.toml optixlog_gen.py
git commit -m "chore: add Modulator Program project and regenerate bindings"

Determinism guarantee

The generated module is byte-deterministic: no timestamps, no random values. Running generate twice with the same schema input produces an identical file. This means:

• --check is a reliable drift detector.
• git diff shows only meaningful schema changes.
• Reviewers can inspect exactly what changed in the schema by reading the diff.