Workspaces & caching

Usage guide, with the merge rules and the cache-key/location details: Workspaces & caching.

Multi-file workspaces and a content-addressed model cache.

Loading

load is the universal entry point:

• a .sysml file -> parsed and built,

• a .json file -> imported via longeron.importer,

• a directory -> every *.sysml file beneath it (sorted, recursive), merged into one Model so cross-file imports and qualified references resolve.

Caching

Built models are cached as JSON in a content-addressed cache ($LONGERON_CACHE_DIR, $XDG_CACHE_HOME/longeron, or ~/.cache/longeron). Cache entries use the same lossless schema as longeron.to_json() – no pickles, so entries are inspectable text and never execute code on load. An entry’s key is the SHA-256 of the source text plus a fingerprint of the generated parser, builder, model, and AST code – editing a source file, regenerating the grammar, or upgrading the package all invalidate cleanly. Caching defaults to on – for single files as well as directories, since the dominant cold-load cost (ANTLR ATN warmup) is paid per process either way; pass cache=False to opt out.

longeron.workspace.cache_dir()

The directory used for cached models (created on demand).

Return type:

Path

longeron.workspace.clear_cache()

Delete all cached models; returns the number of entries removed.

Return type:

int

longeron.workspace.load_file(path, *, cache=True)

Parse and build a single .sysml file (optionally cached).

Return type:

Model

longeron.workspace.load_many(paths, *, cache=True)

Load several .sysml/.json files into one merged model.

Return type:

Model

longeron.workspace.load_dir(root, *, recursive=True, cache=True)

Load every *.sysml file under a directory into one model.

Files are loaded in sorted path order for determinism. .kerml files are ignored (KerML is parse/validate-only in this package). Every top-level member of the merged model records the file it came from (member.source_file), which is what longeron.export.save_workspace() writes edits back to.

Return type:

Model

longeron.workspace.merge_models(models, source_name='<merged>')

Combine the top-level members of several models under one root.

The inputs are left untouched: each model is deep-copied and the copies’ members are re-owned by the merged root, so mutating the result never aliases the sources (and vice versa).

Return type:

Model

longeron.workspace.load(path, *, cache=None)

Load a model from a .sysml file, a .json export, or a directory of .sysml files.

cache=None (the default) enables the model cache; pass cache=False to parse from source unconditionally.

Return type:

Model