Skip to content

Configuration

USC uses YAML files for all pipeline parameters. The configuration system supports:

  • YAML loading with recursive merging of nested dictionaries.
  • CLI overrides (-o key=value) that take precedence over file values, applied via dot-path notation.
  • Pydantic v2 validation with strict bounds checking, type coercion, and informative error messages on invalid inputs.
  • Manifest schemas for each pipeline stage, enabling re-entry at any stage.

See also: Configuration guide for user-facing parameter reference.

Config loader

urbansolarcarver.load_config

UrbanSolarCarver — Configuration loading and validation

Purpose

Read a YAML config, apply optional overrides from CLI or dicts, validate everything with Pydantic, and hand the pipeline a typed user_config. Also emits a human-readable sample YAML.

Highlights

• Strict schema: fails fast on typos or bad values
• Overrides: dotted keys supported (e.g. "thresholding.carve_fraction=0.7")
• Clear errors: aggregates Pydantic messages into one readable string
• Sample writer: exports a ready-to-edit template with sane defaults

This module does not touch geometry. It only prepares inputs for the carving and meshing stages.

parse_override_value(raw)

Convert a CLI override scalar into a Python type.

Accepted literals

• "true"/"false" → bool • "null"/"none" → None • ints and floats (simple forms) • everything else stays as a string

Examples:

>>> parse_override_value("true")  # bool
True
>>> parse_override_value("3.5")   # float
3.5
>>> parse_override_value("foofoo")   # str
'foofoo'

assign_override_path(root, path, value)

Set a nested key in-place using a path tuple.

Parameters:

Name Type Description Default
root dict

Target dictionary to mutate.

 required
path tuple[str, ...]

Dotted key split into parts, e.g. ("thresholding","carve_fraction").

 required
value Any

Value to assign at the nested location.

 required
Notes

Creates intermediate dictionaries as needed.

merge_dicts(base, update)

Recursively overlay update onto base in place.

Rules

• If both sides are dicts, merge recursively.
• Otherwise replace the value in base with the one from update.

load_config(path, overrides=None)

Load a YAML config, apply overrides, and return a validated user_config.

Parameters:

Name Type Description Default
path str

Path to the YAML file.

 required
overrides list[str] | Mapping[str, Any] | None

Optional overrides.
• list[str]: each item is "key=value" with dotted keys allowed
• mapping : nested dict mirroring YAML structure

 None

Returns:

Type Description
UserConfig

Raises:

Type Description
FileNotFoundError

If path does not exist.
ValueError

If validation fails. The error message aggregates all Pydantic errors.
Notes

• Scalars in CLI overrides are type-coerced by parse_override_value.
• Dotted keys in overrides are expanded via assign_override_path.
• The function does not mutate the YAML on disk.

Schemas

urbansolarcarver.pydantic_schemas

Pydantic schemas for YAML configuration validation and stage manifests.

Defines :class:user_config (the main pipeline configuration model), two stage manifest schemas (:class:PreprocessingManifest, :class:ThresholdingManifest), and the project-specific warning class :class:UrbanSolarCarverWarning.

All schemas use extra='forbid' so that typos in YAML keys are caught at load time rather than silently ignored.

UrbanSolarCarverWarning

Bases: UserWarning

Non-fatal configuration warning.

UserConfig

Bases: BaseModel

PreprocessingManifest

Bases: BaseModel

Manifest written by preprocessing, read by thresholding and exporting.

ThresholdingManifest

Bases: BaseModel

Manifest written by thresholding, read by exporting.

schema_from_json(cls, text)

Deserialize a JSON string into a Pydantic model instance.

schema_to_json(model, *, indent=2)

Serialize a Pydantic model to a JSON string.