DIP Python API

DIPL parsing, evaluation environments, tree traversal, and parameter nodes. The inspection functions expose evaluated value snapshots, ordered table metadata, in-memory slices, artifact loading, and structured DIP diagnostics. The adapter classes and runners are documented in the adapter guide.

For everyday node access, use Cursor for known paths and Select for discovery; see the Python guide. The request helpers below remain available for existing callers. request_value() returns a value with optional unit conversion or NumPy output. request_group() returns node snapshots with relative paths, matches any supplied tag, and raises an exception when no nodes match.

scinumtools3.dip.diagnostic_from_exception(error): Return the structured diagnostic attached to a DIP exception, if any.

class scinumtools3.dip.DIP

Parser and evaluator for DIPL source definitions.

add_file(self: scinumtools3._snt.dip.DIP, source_file: os.PathLike | str | bytes, source_name: str = '', absolute: bool = True) → None

Add a DIPL source file to the parser.

Args:: source_file: Path to the DIPL file. source_name: Optional registered source name; generated when empty. absolute: Accepted for compatibility; currently has no effect.

add_function_nodes(self: scinumtools3._snt.dip.DIP, name: str, callback: collections.abc.Callable) → None

Register a Python callback that returns nodes for a DIPL function.

Args:: name: Function name used in DIPL. callback: Callable receiving an Environment and returning value nodes.

add_function_value(self: scinumtools3._snt.dip.DIP, name: str, callback: collections.abc.Callable) → None

Register a Python callback that returns value data for a DIPL function.

Args:: name: Function name used in DIPL. callback: Callable receiving an Environment and returning ValueNodeData.

add_override_file(self: scinumtools3._snt.dip.DIP, source_file: os.PathLike | str | bytes) → None

Register an unwrapped override body from a file before evaluating nodes. Empty files make no changes.

Args:: source_file: Path to an unwrapped body of modifications and optional nested path prefixes.

add_override_string(self: scinumtools3._snt.dip.DIP, source_code: str) → None

Collect unwrapped value modifications before evaluating nodes. Empty bodies make no changes.

Args:: source_code: DIPL modifications with dotted paths or nested path prefixes.

add_project(self: scinumtools3._snt.dip.DIP, project_file: os.PathLike | str | bytes) → None

Add a DIPfile with units[], sources[], schemas[], overrides[], and ordered code[] entries. Schema entries have a name and exactly one file or string body. Override entries have a file containing value modifications without a $override wrapper. Relative paths resolve from the DIPfile directory.

Args:: project_file: Path to the DIPfile manifest.

add_schema_file(self: scinumtools3._snt.dip.DIP, name: str, source_file: os.PathLike | str | bytes) → None

Register a named schema body from a file, with the same rules as add_schema_string().

Args:: name: Unique schema name. source_file: Path to a file containing the unwrapped schema body.

add_schema_string(self: scinumtools3._snt.dip.DIP, name: str, source_code: str) → None

Register a named schema body without a $schema wrapper. Leading ? metadata describe the schema definition; metadata on a member follow that member into instances.

Args:: name: Unique schema name. source_code: Schema body starting at indentation zero.

add_source(self: scinumtools3._snt.dip.DIP, source_name: str, source_file: str) → None

Register a named DIPL source file.

Args:: source_name: Name used in references. source_file: Path to the source file.

add_string(self: scinumtools3._snt.dip.DIP, source_code: str) → None

Add DIPL source text to the parser.

Args:: source_code: Complete DIPL text to parse.

add_unit(self: scinumtools3._snt.dip.DIP, name: str, unit: str) → None

Register a custom unit definition.

Args:: name: Unit name. unit: PUEL expression defining the unit.

enter(self: scinumtools3._snt.dip.DIP) → scinumtools3._snt.dip.DIP

exit(self: scinumtools3._snt.dip.DIP, arg0: object, arg1: object, arg2: object) → None

parse(self: scinumtools3._snt.dip.DIP) → scinumtools3._snt.dip.Environment: Parse and evaluate all added DIPL inputs, including registered schemas.

to_string(self: scinumtools3._snt.dip.DIP) → str

class scinumtools3.dip.Environment

Evaluation environment containing DIPL sources, units, schemas, functions, and nodes.

applied_schemas(self: scinumtools3._snt.dip.Environment, path: str) → list[scinumtools3._snt.dip.SchemaInfo]

Return descriptive records for schemas applied along a value or collection path.

Args:: path: Fully qualified value or collection path.

contributing_schema(self: scinumtools3._snt.dip.Environment, path: str) → scinumtools3._snt.dip.SchemaInfo | None

Return the schema that supplied a value node, or None when it was not schema-derived.

Args:: path: Fully qualified value path.

generate(self: scinumtools3._snt.dip.Environment, format: scinumtools3._snt.dip.ExportFormat, file: os.PathLike | str | bytes) → None

Generate a static parameter list.

Args:: format: ExportFormat member selecting the output format. file: Output path; an existing file is overwritten.

generate_report(self: scinumtools3._snt.dip.Environment, format: scinumtools3._snt.dip.ReportFormat, file: os.PathLike | str | bytes, *, input_label: str = '', intro_file: os.PathLike | str | bytes | None = None, tex_compiler: str = 'pdflatex', title: str = 'DIP parameter report', author: str = '', date: str = '', version: str = '') → None: Write a report from this evaluated environment. PDF requires a local TeX compiler.

load(self: scinumtools3._snt.dip.Environment, file: os.PathLike | str | bytes) → None

Load evaluated nodes from DIPH5. Schema descriptions and provenance are available in schema_manifest; reusable definitions are not reconstructed.

Args:: file: Path to the DIPH5 file.

property nodes: Evaluated top-level nodes.

request_group(self: scinumtools3._snt.dip.Environment, path: str, tags: collections.abc.Sequence[str] = []) → list[scinumtools3._snt.dip.ValueNode]

Return node snapshots with paths relative to the requested root. A nonempty tags list matches any listed tag; an empty list imposes no restriction. Raise an error if no nodes match.

Args:: path: Reference query path. tags: Tags of which at least one must occur on each returned node.

request_value(self: scinumtools3._snt.dip.Environment, path: str, to_units: str = '', as_numpy: bool = False) → object

Return the value at a path, optionally converted to a NumPy array.

Args:: path: Reference query path. to_units: Requested output units; empty keeps the original units. as_numpy: Return a NumPy array when true.

save(self: scinumtools3._snt.dip.Environment, file: os.PathLike | str | bytes) → None

Save evaluated nodes to DIPH5 with descriptive schema metadata and provenance, but not reusable definitions.

Args:: file: Output DIPH5 path; an existing file is overwritten.

property schema_manifest: Schema identities, descriptions, citations, and source provenance; no reusable definitions.

property schemas: Registered schema definitions keyed by name. The mapping is a snapshot and remains valid independently of this environment. DIPH5 loading does not restore reusable schemas; use schema_manifest.

select(self: scinumtools3._snt.dip.Environment, path: str = '?', *, tags_all: collections.abc.Sequence[str] = [], tags_any: collections.abc.Sequence[str] = [], tags_none: collections.abc.Sequence[str] = []) → list[scinumtools3._snt.dip.ValueNode]

Select independent node snapshots with full paths, in environment order. Subtrees include value-bearing roots and collection members; each node appears once. Tags are explicit and not inherited. Filters combine with AND; empty filters impose no restriction. Selection does not modify the environment. No matches returns an empty list.

Args:: path: Query path; ? selects all, ?path. a subtree, and ?path an exact node. tags_all: Require every listed tag. tags_any: Require at least one listed tag. tags_none: Exclude nodes with any listed tag.

property size: Number of top-level nodes.

property source_manifest: Source identities and SHA-256 fingerprints available for this environment.

to_string(self: scinumtools3._snt.dip.Environment) → str

class scinumtools3.dip.Cursor

Cursor for traversing and querying evaluated DIPL nodes.

elements(self: scinumtools3._snt.dip.Cursor) → list[scinumtools3._snt.dip.Cursor]: Return child elements.

has_item(self: scinumtools3._snt.dip.Cursor, name: str) → bool

Return whether a named child exists.

Args:: name: Child name to check.

items(self: scinumtools3._snt.dip.Cursor) → list: Return child names and values as pairs.

property kind: Kind of DIPL path represented by this cursor.

property metadata: Documentation and provenance metadata for the value at this path.

property path: Path of this cursor in the DIPL environment.

property provenance: Source and citation provenance for the value at this path.

property shape: Shape of the value at this path.

to_numpy(self: scinumtools3._snt.dip.Cursor) → object: Return the cursor value as a NumPy array.

to_string(self: scinumtools3._snt.dip.Cursor) → str: Format the cursor as text.

property units: Unit string for a dimensional value, or None when the value is unitless.

property value: Python value stored at this path (scalar, string, list, or NumPy-compatible array).

class scinumtools3.dip.ValueNode

A DIPL parameter node with value, type, units, and metadata.

property dtype: SNT data type of the stored value.

property metadata: Documentation and provenance metadata attached to this value node.

property name: Name of the parameter node.

property override: Whether an explicit $override supplied the effective value.

property schema_id: Trace ID of the schema that supplied this node, or an empty string.

property shape: Shape of the stored value.

property tags: Copy of the node’s explicitly assigned tags. Editing this Python list does not change the environment.

to_numpy(self: scinumtools3._snt.dip.ValueNode) → object: Return the stored value as a NumPy array.

to_string(self: scinumtools3._snt.dip.ValueNode, format: scinumtools3._snt.core.StringFormatType = <StringFormatType specifier='g', valuePrecision=4, uncertaintyPrecision=2, thresholdScientific=3, paddingZeros=False, paddingSize=0, stringQuotes=True>) → str: Format this node as text.

property units: Quantity units attached to the node, or None.

property value: Python value stored by the node.

class scinumtools3.dip.ValueNodeData: Evaluated value data returned by DIPL functions and nodes.

Application adapters

class scinumtools3.dip.Adapter

Subclass and implement plan(env, context).

plan(self: scinumtools3._snt.dip.Adapter, env: scinumtools3._snt.dip.Environment, context: scinumtools3._snt.dip.AdapterContext) → None: Select values, validate them for the target application, and register its files.

class scinumtools3.dip.AdapterContext

Outputs planned for one adapter run.

add_binary(self: scinumtools3._snt.dip.AdapterContext, path: os.PathLike | str | bytes, data: bytes) → None: Register raw bytes without encoding or newline changes.

add_stream(self: scinumtools3._snt.dip.AdapterContext, path: os.PathLike | str | bytes, callback: collections.abc.Callable) → None: Register a callback called after path validation with a write(bytes) function.

add_text(self: scinumtools3._snt.dip.AdapterContext, path: os.PathLike | str | bytes, text: str) → None: Register application-defined text at a relative output path.

scinumtools3.dip.run_adapter(env: scinumtools3._snt.dip.Environment, adapter: scinumtools3._snt.dip.Adapter, output_dir: os.PathLike | str | bytes, snapshot: os.PathLike | str | bytes | None = None) → list[pathlib.Path]: Plan and write outputs from an existing Environment. Paths must be relative and absent. Returns written paths in registration order, followed by an optional DIPH5 snapshot.

scinumtools3.dip.run_adapter_project(project: os.PathLike | str | bytes, adapter: scinumtools3._snt.dip.Adapter, output_dir: os.PathLike | str | bytes, snapshot: os.PathLike | str | bytes | None = None) → list[pathlib.Path]: Parse a DIPfile, then plan and write adapter outputs. Returns written paths.

scinumtools3.dip.run_adapter_snapshot(input: os.PathLike | str | bytes, adapter: scinumtools3._snt.dip.Adapter, output_dir: os.PathLike | str | bytes, snapshot: os.PathLike | str | bytes | None = None) → list[pathlib.Path]: Load a DIPH5 snapshot, then plan and write adapter outputs. Returns written paths.