1 configs.authoring

configs.authoring

Comment-preserving, optimistic-concurrency authoring for trusted configs.

ConfigDocument is the filesystem seam used by CLI and Streamlit authoring. It parses TOML with :mod:tomlkit, validates the complete tree with a caller- supplied aria_nbv.utils.BaseConfig subtype, and promotes writes only when the originally observed file digest still matches.

1.1 Attributes

Name Description
ConfigScalar JSON/TOML scalar retained by the metadata-only authoring seam.
ConfigValue JSON/TOML-compatible value used by config descriptors and patches.

1.2 Classes

Name Description
ConfigAuthoringError Base error for parse, validation, policy, and write failures.
ConfigConflictError Raised when a source file changed after it was inspected.
ConfigDiff Canonical semantic changes for one authoring transaction.
ConfigDiffEntry One semantic value change between the opened and validated draft.
ConfigDocument Inspect, patch, diff, and atomically save one trusted TOML config.
ConfigFieldDescriptor Schema and source documentation for one editable field.
ConfigWriteReceipt Identity of one atomically promoted configuration file.

1.2.1 ConfigAuthoringError

configs.authoring.ConfigAuthoringError()

Base error for parse, validation, policy, and write failures.

1.2.2 ConfigConflictError

configs.authoring.ConfigConflictError()

Raised when a source file changed after it was inspected.

1.2.3 ConfigDiff

configs.authoring.ConfigDiff(entries)

Canonical semantic changes for one authoring transaction.

1.2.3.1 Attributes

Name Description
entries Changes sorted by dotted field path.
is_empty Return whether the validated draft is semantically unchanged.

1.2.4 ConfigDiffEntry

configs.authoring.ConfigDiffEntry(path, before, after)

One semantic value change between the opened and validated draft.

1.2.4.1 Attributes

Name Description
path Dotted field path.
before Original JSON-compatible value.
after Validated draft value.

1.2.5 ConfigDocument

configs.authoring.ConfigDocument(path, model, source_text, document, config)

Inspect, patch, diff, and atomically save one trusted TOML config.

open and describe are metadata-only: they validate values and read Python source/schema metadata but never call setup_target. A patch is applied to a tomlkit tree so unrelated comments, ordering, and whitespace survive. save_copy uses the digest observed at open as a compare- and-swap token and writes through a same-directory temporary file.

1.2.5.1 Methods

Name Description
open Open and validate a TOML file without constructing its runtime target.
describe Return schema-derived field descriptors without evaluating runtime targets.
validate_patch Apply a partial mapping to the TOML tree and validate the complete config.
diff Return semantic changes against the originally opened config.
save_copy Atomically promote the validated draft after source-digest verification.
1.2.5.1.1 open
configs.authoring.ConfigDocument.open(path, model)

Open and validate a TOML file without constructing its runtime target.

1.2.5.1.2 describe
configs.authoring.ConfigDocument.describe()

Return schema-derived field descriptors without evaluating runtime targets.

1.2.5.1.3 validate_patch
configs.authoring.ConfigDocument.validate_patch(patch)

Apply a partial mapping to the TOML tree and validate the complete config.

The validated draft becomes the value subsequently reported by :meth:diff and written by :meth:save_copy. Locked fields reject changes before validation; sensitive fields may still be changed by trusted callers but presentation surfaces must conceal them.

1.2.5.1.4 diff
configs.authoring.ConfigDocument.diff(updated=None)

Return semantic changes against the originally opened config.

1.2.5.1.5 save_copy
configs.authoring.ConfigDocument.save_copy(destination, *, expected_sha256)

Atomically promote the validated draft after source-digest verification.

1.2.5.1.5.1 Parameters
Name Type Description Default
destination Path New file or explicitly selected overwrite target. required
expected_sha256 str Digest returned when this document was opened. required
1.2.5.1.5.2 Raises
Name Type Description
ConfigConflictError If the opened source changed or the supplied digest is not the one observed by this document.

1.2.6 ConfigFieldDescriptor

configs.authoring.ConfigFieldDescriptor(
    path,
    title,
    annotation,
    documentation,
    required,
    default,
    choices,
    allows_none,
    minimum,
    maximum,
    editable,
    sensitive,
    theory_ids,
)

Schema and source documentation for one editable field.

1.2.6.1 Attributes

Name Type Description
path str Dotted path within the validated configuration tree.
title str Human-readable schema title.
annotation str Stable textual form of the Python annotation.
documentation str | None Inline field docstring from the nearest source owner.
required bool Whether the validated model requires the field.
default ConfigValue JSON-compatible default, or None when absent.
choices tuple[ConfigValue, …] Closed enum or Literal choices, if any.
allows_none bool Whether omission represents an explicit optional value.
minimum float | int | None Inclusive or exclusive lower numeric bound when declared.
maximum float | int | None Inclusive or exclusive upper numeric bound when declared.
editable bool Whether trusted authoring surfaces may change this field.
sensitive bool Whether presentation surfaces must conceal the value.
theory_ids tuple[str, …] Canonical Typst-derived theory identifiers relevant to the field.

1.2.7 ConfigWriteReceipt

configs.authoring.ConfigWriteReceipt(path, sha256, previous_sha256, changed)

Identity of one atomically promoted configuration file.

1.2.7.1 Attributes

Name Description
path Absolute destination path.
sha256 SHA-256 digest of the exact written TOML bytes.
previous_sha256 Digest of a replaced destination, when one existed.
changed Whether destination bytes differed from the promoted bytes.

1.3 Functions

Name Description
describe_config_model Return schema/documentation descriptors for an in-memory config model.

1.3.1 describe_config_model

configs.authoring.describe_config_model(model)

Return schema/documentation descriptors for an in-memory config model.

Back to top