Config

Loading, merging and validating configs: the Config object and the schema of the top-level keys. How to write a config: Configuration.

grasppanda.config

Config system: YAML with inheritance, strict validation and run snapshots.

Config

Bases: Mapping[str, Any]

A merged config tree with provenance.

Use :meth:load for files and :meth:from_dict for in-memory configs. Both validate by default and raise :class:ConfigError listing every problem.

sources property

Every file read, leaf first.

dropped property

Keys discarded because a node changed its type.

load(path, overrides=(), *, validate=True, command=None) classmethod

Load a config file (or shipped config name), apply overrides and validate.

from_dict(data, *, validate=True, command=None) classmethod

Build a config from a dictionary (Python API, tests).

validate(command=None)

Run all three validation layers; raise :class:ConfigError on any problem.

select(dotted_path, default=None)

Read a.b.0.c from the resolved tree (defaults included).

source_of(dotted_path)

File (or <command line>) that set a value.

to_dict()

The merged tree as written, without defaults.

resolved()

The merged tree with schema and component defaults filled in.

dump(*, defaults=False)

Serialise to YAML; with defaults every implicit value is written out.

digest()

Hash of what the experiment is: resolved config minus run-location keys.

Defaults of GraspPanda's own schema and components are part of it, so a changed default changes the hash. Defaults of classes of an installed library (an optimizer or a scheduler of PyTorch named by class) are not: they differ between versions of the library, and the hash of one config must be the same on every machine. The environment a run used is recorded next to it (env.json).

ConfigError

Bases: Exception

Raised with every problem found in one validation pass, not just the first.

Issue dataclass

One problem found in a config.

Attributes:

Name	Type	Description
path	str	Dotted config path (model.head.num_angle); empty for file-level problems.
message	str	What is wrong and, where possible, what to write instead.
source	str | None	File (or <command line>) that set the offending value.
kind	str | None	Why it is refused (:data:REFUSAL_KINDS); None for a rule of a project that does not say.

Refusal

Bases: str

A refusal message that knows its kind (:data:REFUSAL_KINDS) and its rule.

It is the message itself, a str, so everything that reads messages keeps working; kind and rule travel with it into the :class:Issue of the config check and into the report of grasppanda compose.

rule(function=None, *, kind=None)

rule(function: Rule) -> Rule

rule(*, kind: str) -> Callable[[Rule], Rule]

Register a cross-field rule, as @rule or @rule(kind="structural").

kind is what the rule's refusals are (:data:REFUSAL_KINDS). It is kept as the attribute kind of the function and given to every message that does not state its own.

available_configs()

Names of shipped runnable configs, e.g. gsnet/gsnet_sunet14_g1b-realsense_10e.

configs_root()

Directory of the shipped configs: packaged in a wheel, repo root in a checkout.

resolve_config_path(name)

Resolve a file path or the name of a shipped config.

parse_yaml(text)

Parse YAML text with the same rules as config files.

git_info(root=_REPO_ROOT)

Commit, branch and dirty flag of the checkout, or {"available": False}.

write_snapshot(config, run_dir, *, command=None)

Write the run snapshot into run_dir and return the content of run.json.

grasppanda.config.config.Config

Bases: Mapping[str, Any]

A merged config tree with provenance.

Use :meth:load for files and :meth:from_dict for in-memory configs. Both validate by default and raise :class:ConfigError listing every problem.

sources property

Every file read, leaf first.

dropped property

Keys discarded because a node changed its type.

load(path, overrides=(), *, validate=True, command=None) classmethod

Load a config file (or shipped config name), apply overrides and validate.

from_dict(data, *, validate=True, command=None) classmethod

Build a config from a dictionary (Python API, tests).

validate(command=None)

Run all three validation layers; raise :class:ConfigError on any problem.

select(dotted_path, default=None)

Read a.b.0.c from the resolved tree (defaults included).

source_of(dotted_path)

File (or <command line>) that set a value.

to_dict()

The merged tree as written, without defaults.

resolved()

The merged tree with schema and component defaults filled in.

dump(*, defaults=False)

Serialise to YAML; with defaults every implicit value is written out.

digest()

Hash of what the experiment is: resolved config minus run-location keys.

Defaults of GraspPanda's own schema and components are part of it, so a changed default changes the hash. Defaults of classes of an installed library (an optimizer or a scheduler of PyTorch named by class) are not: they differ between versions of the library, and the hash of one config must be the same on every machine. The environment a run used is recorded next to it (env.json).

grasppanda.config.schema

The closed top-level schema of a GraspPanda config.

Everything about a run lives here; no behaviour is reachable only through a CLI flag. Adding a field to one of these dataclasses is all it takes to make it a valid, validated, documented config key.