an.project

Project init/load/save — the on-disk anatomy of an an project.

Layout (from spec §11):

my-scene/ ├── an.toml ├── scene.md ├── ir/scene.json ├── assets/{characters,props,environments,voices,styles,sounds}/ ├── artifacts/{audio,visemes,shots,previews}/ ├── output/ └── .an/{decisions.jsonl,verifier_runs/,memory.md}

Module Attributes

RENDER_REPORTS_GITIGNORE	A render report records what a render on THIS machine found — warnings, exception text — so it is per-machine output, not project source (an#254).
PROBES_GITIGNORE	Probe frames and contact sheets (an probe, an library sheet, an#347): looks at work in progress, which may show private-study material.
PROJECT_GITIGNORE	What a project's .gitignore keeps out of version control (an init adds each line a .gitignore lacks, never removing one).

Functions

init(project_dir, *[, name, force])	Create a fresh an project at project_dir.
keep_out_of_git(pdir, lines)	Add lines to an OLDER project's .gitignore (an an init from before they existed left them out) — conservatively: never a line whose folder the file already says anything about (a project may have chosen to commit its reports, !artifacts/render_reports/), never through a symlink (a shared ignore file), and never creating a .gitignore in a project that is not in a git work tree.
keep_reports_out_of_git(pdir)	Add RENDER_REPORTS_GITIGNORE to an older project's .gitignore the first time a render writes a report (an#309), by keep_out_of_git()'s rules.
load(project_dir, *[, check_kinds])	Load an existing project.
save(project)	Persist a Project's current scene back to disk (md + json).

Classes

Project(root, mall, scene)

A loaded an project: directory + mall + current scene.

an.project.PROBES_GITIGNORE: tuple[str, ...] = ('artifacts/probes/',)

Probe frames and contact sheets (an probe, an library sheet, an#347): looks at work in progress, which may show private-study material.

an.project.PROJECT_GITIGNORE: tuple[str, ...] = ('artifacts/render_reports/', 'artifacts/probes/')

What a project’s .gitignore keeps out of version control (an init adds each line a .gitignore lacks, never removing one).

class an.project.Project(root, mall, scene)

Bases: object

A loaded an project: directory + mall + current scene.

an.project.RENDER_REPORTS_GITIGNORE: tuple[str, ...] = ('artifacts/render_reports/',)

A render report records what a render on THIS machine found — warnings, exception text — so it is per-machine output, not project source (an#254).

an.project.init(project_dir, *, name=None, force=False)

Create a fresh an project at project_dir.

Idempotent unless the directory already contains a non-empty scene.md; pass force=True to overwrite. Returns the absolute project root. The project’s .gitignore gains PROJECT_GITIGNORE (lines it lacks).

Return type:

Path

an.project.keep_out_of_git(pdir, lines)

Add lines to an OLDER project’s .gitignore (an an init from before they existed left them out) — conservatively: never a line whose folder the file already says anything about (a project may have chosen to commit its reports, !artifacts/render_reports/), never through a symlink (a shared ignore file), and never creating a .gitignore in a project that is not in a git work tree.

Return type:

None

an.project.keep_reports_out_of_git(pdir)

Add RENDER_REPORTS_GITIGNORE to an older project’s .gitignore the first time a render writes a report (an#309), by keep_out_of_git()’s rules.

Return type:

None

an.project.load(project_dir, *, check_kinds=True)

Load an existing project. Reconciles scene.md / ir/scene.json first.

Registers the installed genres first (an.genres.load(), ADR 0001 decision 3: discovery is explicit, and loading a project is one of the places it happens), so the scene’s genre kinds — the cut-out genre’s play, expression and character — read as their own models.

Then refuses a scene that names an action kind, entity kind or renderer nothing registered (an.ir.validate.require_registered_kinds()): the schema holds those as str (ADR 0001 decision 2), so without this a typo’d kind: enviroment would load and render silently without its backdrop. check_kinds=False is for an validate, which reports them as findings instead.

Return type:

Project

an.project.save(project)

Persist a Project’s current scene back to disk (md + json).

Return type:

None