CodePot
Theme
Python packageSupported stable generatorAvailable now

Infer a normalized generation model from OpenAPI and apply bundled or project-owned Jinja template packs.

GitHubPyPIAll links
python -m pip install codepotg
On this page

paths.yaml planning

paths.yaml is the declarative generation plan for a template pack.

It answers four questions:

  1. Which normalized records are selected?
  2. Which template renders each selection?
  3. Where is each result written?
  4. Which generated facts depend on other emissions?

Complete graph example

Pack metadata

name and version identify the pack and help diagnostics, caching, and compatibility reporting.

write_policy

Write policy can define:

  • default lifecycle mode;
  • managed roots;
  • immutable roots;
  • protected roots;
  • clean roots.

See Lifecycle safety.

selections

A selection names a stable subset of normalized data.

Common concepts:

FieldMeaning
fromSource collection or selector
whereEquality or supported filter conditions
asAlias exposed to the template
scopeSelection scope where supported

Selectors should use documented normalized collections such as schemas.models, schemas.dtos, operations, resources, entities, or frontends.

emissions

An emission schedules a template against a selection.

An emission can control:

  • template path;
  • output path parts;
  • lifecycle mode;
  • per-item or grouped mode;
  • grouping key;
  • explicit providers;
  • provided facts;
  • import and dependency behavior.

Grouped emissions

Grouped mode collects selected records by a stable key and renders one file per group. The group context includes the grouped items and the resolved group owner where available.

Use grouped mode for services, routers, registries, modules, or other files that aggregate multiple operations or models.

Providers

Providers make cross-emission dependencies explicit.

A provider can supply facts such as:

  • generated output paths;
  • exported names;
  • dependencies;
  • imports;
  • related resource or schema records.

Templates should consume declared providers instead of searching the complete source graph.

Provided facts

An emission can declare facts that later emissions or barrels need. This creates a directed planning graph and allows cycle detection before rendering.

Barrels

A barrel is scheduled after the emissions it exports.

Barrels should consume planned member outputs, not scan the filesystem after writes.

Legacy folders

Legacy packs can define folder recipes with selection, alias, mode, lifecycle, and path parts. They remain supported but do not provide the same explicit dependency graph.

Validate a paths file

The command displays resolved selections, emissions, providers, barrels, template behavior, and lifecycle defaults.

Common errors

  • unknown selection name;
  • unknown source collection;
  • duplicate output paths;
  • provider cycle;
  • barrel export references an unknown emission;
  • template path escapes the pack root;
  • output path escapes allowed roots;
  • grouped emission lacks a valid grouping field.

Resolve planning errors before debugging Jinja content.