ncc python command reference¶

ncc python generates an importable namespace package for o6\Python. pyncc accepts identical arguments. See the quickstart for common usage.

ncc python <input> -o <dir> [options]

Argument	Meaning and default
`<input>`	Required target NodeSet XML file.
`-o`, `--output <dir>`	Required output parent; created if missing.
`-e`, `--existing <dependency>`	Repeatable bundled name or `shortname@package.prefix=path`. No dependencies are selected by default. See dependency syntax.
`--shortname <name>`	Package and namespace name. Defaults to the target naming rules.
`--description-cache <path>`	JSON mapping of description URLs to text. Defaults to `description_cache.json` in the working directory.
`-v`, `--verbose`	Repeatable: default `WARNING`, `-v` selects `INFO`, `-vv` or more selects `DEBUG`.
`-h`, `--help`	Show command help and exit.

All relative paths resolve from your working directory. For custom dependencies, an empty prefix selects a top-level import, such as -e 'base@=Base.NodeSet2.xml'. Supply every transitive dependency explicitly. Bare XML paths and SHORTNAME=PATH are not accepted by the o6\Python backend.

Output and regeneration¶

-o . --shortname mymodel writes a package to mymodel/ in your project. It does not create enclosing runtime packages or generate dependency packages. Files for empty node categories are omitted; see the package layout.

Regeneration replaces package contents

Existing generated files are overwritten. Additional .py and .pyi files directly inside the package directory are deleted, including handwritten files. Keep application code outside that directory.

Description cache¶

When a model's Description contains a URL instead of text, generation requires a cached description. Compilation does not fetch that URL. Plain XML description text needs no cache; supplementary dictionary-entry URLs are omitted.

Create a JSON object mapping each exact URL to its description text. For example, if your model contains <Description>https://example.org/Device</Description>, save this as description_cache.json:

{
  "https://example.org/Device": "A device exposed by the application."
}

Replace the example URL and text with values appropriate for your model, then run:

ncc python MyModel.NodeSet2.xml --shortname mymodel -e ns0 \
    --description-cache description_cache.json -o .

Replace MyModel.NodeSet2.xml with your model and add its dependencies with -e. Dependencies can also contain descriptions that require cache entries.

A diagnostic containing uncached Description URL identifies a missing entry. Add that URL and its text, verify the file is valid JSON, and rerun with the correct cache path. Keep the cache with your model inputs for reproducible generation.

Inspect a model¶

Use ncc inventory to inspect parsed nodes and references as JSON before generating C or Python code:

ncc inventory MyModel.NodeSet2.xml -e ns0 -o debug/inventory.json

For a visual diagram, use ncc graphviz.

Scripts and troubleshooting¶

Exit status 0 means success. CLI argument and dependency-declaration errors return 2; generation failures return 1. Output files go to the directory selected by -o. Diagnostics go to standard error; --help goes to standard output. Treat messages as diagnostic output, not a stable machine API. A failed run can leave an output directory or previous files; check the exit status.

Symptom	Fix
No supplied model binding for a namespace	Add the missing dependency with `-e`, including transitive dependencies.
An unsupported datatype or missing ancestry diagnostic	Supply the XML defining that datatype and its base types.
Missing `o6` when importing generated output	Install a compatible runtime in the application environment. Generation itself does not require o6.
`uncached Description URL`	Add an entry to the description cache described above.
Import fails after generation	Check the declared import paths and `PYTHONPATH`; see runtime requirements.