|
TRUST 1.9.8
HPC thermohydraulic platform
|
|
TRUST 1.9.8
HPC thermohydraulic platform
|
trustify is a Python package that turns the TRUST CFD code's input keyword declarations (// XD C++ comments in $TRUST_ROOT/src/, plus any baltik overlay you point it at) into a pydantic data model and a matching .data file parser. It's the reference Python implementation of the TRUST dataset grammar.
The same generated schema powers three workflows:
Each TRUST keyword becomes a Python class whose attributes are the keyword's attributes. For example read_med is a class with attributes fichier, mesh, etc.
This README covers the CLI — the principal entry point for baltik users. The programmatic API and the .trustify.json config each live on their own page; see Further reading below.
trustify ships with the TRUST conda environment. After sourcing it (source $TRUST_ROOT/env_TRUST.sh), the trustify command is on your PATH and from trustify import ... works.
For a manual install:
Project-resolution flags are GLOBAL and must come before the subcommand name. They tell trustify which TRUST source tree and which baltik overlays to scan when building the schema:
| Flag | Effect |
|---|---|
| --projects DIR, -p DIR | Baltik directory to overlay. Repeat for multiple (-p A -p B). Each must contain a project.cfg. |
| --trust-root DIR | The TRUST source tree. Defaults to $TRUST_ROOT. |
| --schema DIR | Reuse an already-generated schema directory. Mutually exclusive with the two above. Only valid for check, batch-check, batch-check-projects, generate_markdown, generate_keywords, generate_pdf. |
| --no-auto-deps | Do not auto-resolve transitive [dependencies] from each project's project.cfg. Equivalent to setting workspace.auto_resolve_dependencies: false in .trustify.json. |
When none of these are passed, the CLI walks upward from the current path looking for a .trustify.json and/or a project.cfg, falling back to $TRUST_ROOT / $project_directory. Full precedence ladder in the .trustify.json reference and in the project-resolution reference.
| Command | Purpose |
|---|---|
| generate_schema | Build the pydantic model + parser for the current project set; cache the result. |
| check | Validate one .data file against the schema (parse + round-trip). |
| batch-check | Run check on many files; emit an aggregate summary. |
| batch-check-projects | Run batch-check on a subdirectory (default tests/Reference) of each resolved project, filtered by --only role. |
| format | Reformat one .data file (pure text, no schema needed). |
| batch-format | Reformat many .data files in place. |
| modernize | Rewrite legacy XD-tag forms (brace flags, opt flags, long lines) in the resolved project source trees. |
| init-config | Freeze the currently-resolved workspace into a .trustify.json. |
| projects | Dump the resolved project list for shell scripting. |
| generate_markdown | Generate the keyword reference manual (markdown). |
| generate_pdf | Build the keyword reference manual as a single hyperlinked PDF (markdown → doxygen → LaTeX). |
| generate_keywords | Generate Keywords.txt and Keywords.Vim (vim/gedit syntax). |
| cache | Inspect and manage ~/.cache/trustify/. |
| install-completion | Install shell tab-completion (needs the [optional] extra). |
trustify <command> --help always prints the full set of options.
Walks --trust-root and each --projects baltik for // XD declarations, builds a TRAD2Content, then code-generates the parser and pydantic model. Outputs five files in ~/.cache/trustify/<hash>/ (or --out DIR if given):
The hash is computed from the trustify version + canonical TRAD2 text
Prints the cache directory to stdout. Exits 0 on success, non-zero on schema-extraction failure.
Options
Parses DATA_FILE against the schema, then writes it back and asserts the round-trip is byte-identical (modulo trailing content past the end/fin keyword). Prints one line:
A dataset carrying a # TRUSTIFY NOT # comment is reported as SKIPPED unless --no-skip is given. Use it to opt out files that aren't valid TRUST input (templates, intentional counter-examples, etc.). Two forms are accepted:
A malformed sentinel — TRUSTIFY NOT followed by tag text but no colon, e.g. # TRUSTIFY NOT toto # — is reported as FAILED with a clear "ill-formed TRUSTIFY NOT tag at line N" message rather than silently ignored. A typo of the colon would otherwise let an invalid dataset slip through the gate.
Exit codes: 0 on PASSED or SKIPPED, 1 on FAILED.
Options
Runs check on every .data file under each DATA_PATH. Each path may be a file or a directory; directories are recursed.
By default emits one progress line per file:
Each [SKIPPED] line carries the trailing justification when the opt-out tag uses the # TRUSTIFY NOT: <text> # inline form; the bare # TRUSTIFY NOT # form prints just the static message. The same suffix appears in the --summary-out file and on the [obsolete] ... warning lines emitted under --no-skip.
Exit codes: 0 when zero failures, 1 otherwise. SKIPPED files do not contribute to the failure count.
Options
Convenience wrapper over batch-check for "check the datasets shipped by the projects in my workspace". It resolves the same project set that trustify projects dumps, appends --subdir to each project root, and runs batch-check over the resulting directories. Equivalent to:
The directories selected are listed up front before the run begins.
Options (in addition to all batch-check options above):
Projects that lack the --subdir directory are skipped with a one-line note to stderr. Needs the workspace to resolve (run inside a baltik or pass --projects / --trust-root); errors otherwise.
Reformats DATA_FILE using the canonical rules: 4-space indentation proportional to brace depth, consecutive blank lines collapsed to one, blank lines immediately after { or before } removed. No schema is needed — this is pure text manipulation that runs on TRUST syntax, baltik datasets, or templated .data files alike (the formatter passes ${key} / $key placeholders through unchanged).
By default prints the formatted text to stdout. Mutually-exclusive output flags:
The formatter is intentionally parameter-free — every TRUST dataset is reformatted the same way regardless of editor settings, keeping files byte-identical across the ecosystem.
Same path expansion + --exclude semantics as batch-check.
Dry-run by default — prints the unified diff for every file that would change and exits 1 if there is at least one such file (exit 0 when every input is already canonical). --apply switches to in-place rewrite — every file is atomically replaced (temp-file + os.replace, so a crash mid-write leaves the source untouched). TRUSTIFY_FORCE_FORMAT set to any non-empty value in the env has the same effect as --apply — useful from Makefile targets that want a single env knob.
--follow-symlinks opts into following symbolic links during directory recursion (both dir and file symlinks). Default skips them — a symlinked file at a leaf emits a one-line skip warning to stderr so out-of-scope links don't sneak in. Explicit symlink args on the command line are always processed.
Mirrors modernize's pattern: destructive operations are opt-in, never the default. No schema is needed; no stdout / --out flags (this is the fleet operation — format is the single-file scalpel).
Rewrites legacy XD-tag forms in the current top-level project's <project>/src/**/*.{cpp,xd} tree. Three rules apply per file, in order:
Idempotent: existing XD_CONT blocks fold first, then re-split canonically. Running modernize on its own output is a no-op.
Dry-run by default — unified diff on stdout, one-line summary on stderr (summary: N files would change — A brace flags, B opt flags, C splits, U unsplittable). Exits 1 when changes are pending, matching ruff format --check semantics so CI can gate on it.
Scope. Modernize rewrites sources in place, so it deliberately opts OUT of the four-signal resolution other commands use. Rules (first match wins):
Failure modes (exit 2):
When CWD lives under $TRUST_ROOT, the implicit baltik signals (auto-detected project.cfg, $project_directory) are suppressed so a stale env from a previous source <baltik>/env.sh cannot smuggle a baltik rewrite into a plain modernize-from-trust.
Options
Cross-link: generate_schema separately emits a WARNING for each modernizable pattern it sees (long lines, legacy brace flags, legacy opt flags), each suggesting trustify modernize as the fix.
Resolves the workspace as usual (CLI flags > .trustify.json > baltik auto-detection > env vars, with transitive [dependencies] expanded), then writes the resolved workspace.projects + workspace.trust_root (plus a placeholder lsp block) into a fresh .trustify.json in DIR (default: current directory).
The result is a config frozen from the live env — think pip freeze > requirements.txt for trustify workspaces. Future invocations from inside that directory will use the captured project set without any env setup.
Options
Dumps the resolved project list in overlay order: trust_root first if any, then transitive dependencies in post-order, then explicitly-listed primaries last. One absolute path per line — designed for shell scripting:
Each entry carries a role:
Exit codes: 0 on success (including empty output after filtering), 2 when nothing resolves at all.
Options
Renders the keyword reference manual (one markdown file per top-level class, plus a master index) into --out DIR. The directory must not exist OR be empty.
generate_markdown consumes a schema — pass --schema DIR to point at one already generated, or omit and let it run generate_schema internally. Extras (LaTeX-style \input directives, image embeds) are pulled from each project's docs/trustify/extras/ directory.
Options
Exit codes: 0 on success, 2 on precondition errors (bad --out), 1 on content errors (missing referenced extras, duplicate extras, broken image copy).
Builds a single hyperlinked PDF of the keyword reference manual. By default it runs the whole pipeline end-to-end — schema → markdown → doxygen → LaTeX → PDF — using throwaway temporary directories, so a bare trustify generate_pdf --out manual.pdf is all you need. Pass --from-markdown DIR to reuse an existing generate_markdown output and skip schema resolution + generation.
Requires doxygen and a LaTeX toolchain (pdflatex, make) on PATH; both are probed up-front so a missing install fails fast, before the long doxygen pass. The orchestration lives in src/trustify/pdf.py; see Keyword Reference Manual as PDF for the standalone, install-free variant of the same pipeline.
Options
Exit codes: 0 on success, 2 on precondition errors (missing --out parent, an invalid --from-markdown directory), 1 on toolchain / build failures (doxygen or LaTeX errors).
Emits two files for downstream syntax-highlighting tooling:
The keyword set includes every block name + its synonyms, every attribute name + its synonyms, and every chaine(into=[...]) enum value. Abstract _base / _deriv classes are dropped, as are tokens containing {}#* (which would break downstream syntax files).
Options
Inspect and manage the schema cache at ~/.cache/trustify/ (or $TRUSTIFY_CACHE_DIR/ when that env var is set to a non-empty path — useful on HPC nodes with a quota'd / read-only $HOME, ephemeral CI runners, and multi-user shared TRUST installs that want one shared cache). Entries are 16-char hash directories; any unique prefix of a hash works as an ID (git-short-SHA style).
Table of entries with creation time, trustify version, project set, and on-disk size. --json emits the same data as machine-readable JSON.
Ambiguous prefixes are rejected with the full candidate list.
Copies one entry's generated files into DEST_DIR. The destination is created if absent; if it exists it must be empty. __pycache__ and *.pyc are filtered out.
Prints the absolute path of one entry. Useful for --schema $(trustify cache path <id>) plumbing.
Groups entries by project set and deletes all but the newest in each group. The same logic runs automatically after each generate_schema against the default cache root (unless cache.auto_trim: false in .trustify.json or TRUSTIFY_NO_AUTO_TRIM set to any non-empty value in the env opts out — the literal value is not parsed, so =0 also disables).
Installs a shell completion script generated via argcomplete. Requires the [optional] extra (pip install trustify[optional]). In a TRUST-bundled python, configurer_env already attempted this for you on a best-effort basis (warns rather than fails if your install host had no internet).
Defaults pick the right per-shell lazy-load destination:
Options
trustify uses pydantic v2 for the generated data model.
trustify is wired into the daily TRUST regression suite via make check (which runs trustify batch-check $TRUST_ROOT/tests --jobs $(nproc)). The check catches schema/dataset drift — if a keyword's documentation in the C++ source disagrees with how the dataset actually uses it, the round-trip fails. Same logic mirrored in each baltik via the generated trustify_check Make target.
The hello-world notebook lives at docs/examples/hello_world/HelloWorld.ipynb — useful as a starting point for scripting against the generated model.
To update the readthedocs documentation site, maintainers:
1.16.1