API Reference

NamespaceBuilder

The main interface. Wraps a NamespaceSpec and provides all path operations.

Construction

NamespaceBuilder.from_yaml(config_path)   # Load from a YAML file
NamespaceBuilder.from_dict(data)          # Build from a plain dict

Serialisation

builder.to_dict()               # → dict (round-trips through from_dict)
builder.write_yaml(path)        # Write the spec back to a YAML file

Path building

builder.build_path(level, values)

Returns the path segment string for level constructed from values. Parent levels referenced in the template are resolved automatically.

builder.generate_path(level, values, include_optional_levels=True)

Returns the full filesystem path from root up to and including level, joining each hierarchy level with pathlib.Path. Pass include_optional_levels=False to skip optional levels.

Parsing and validation

builder.extract_level_values(level, name)

Parse a single level string and return a dict of template-field values. Raises ValueError if the string does not match the level's regex.

builder.validate_path(path, stop_at=None)

Walk a filesystem path level by level and return all captured values. Pass stop_at to stop after a specific hierarchy level.

builder.validate_path_level(level, segment, known_values)

Match a single segment against the regex for level. known_values are substituted into the pattern before matching.

---

NamespaceSpec

Pydantic v2 model holding the parsed YAML spec.

Field	Type
version	str
description	str
hierarchy	list[str]
optional_levels	list[str]
levels	dict[str, NamespaceLevelSpec]

---

NamespaceLevelSpec

Pydantic v2 model for a single hierarchy level.

Field	Type
template	str
regex	str
optional_fields	list[str]

---

Auto-generated reference

acquisition_namespace.NamespaceBuilder

Build and validate hierarchical acquisition paths from a YAML spec.

Each level in the hierarchy has a template (for construction) and a regex (for parsing/validation). Higher levels may reference lower-level names in their template; the builder resolves them recursively.

Typical usage::

b = NamespaceBuilder.from_yaml("my_namespace.yaml")

# Build a path segment for a given level
name = b.build_path("session", {"subject": "m01", "datetime": "20260101"})

# Build the full directory path from root to a level
path = b.generate_path("session", values)

# Parse an existing path back into its component values
parts = b.validate_path(path, stop_at="session")

# Extract values from a single level's string
parts = b.extract_level_values("session", name)

__init__(spec)

Initialise from a validated :class:NamespaceSpec.

build_path(level, values)

Return the path segment string for level constructed from values.

Parent levels referenced in the template are resolved automatically.

extract_level_values(level, name)

Parse name as a level segment and return template-field values.

Unlike :meth:validate_path (which walks a directory path), this matches a single string against a single level's regex.

Raises:

Type	Description
ValueError	If level is not in the hierarchy, or name does not match the level's regex.

from_dict(data) classmethod

Build from a plain dict (e.g. after :meth:to_dict).

from_yaml(config_path) classmethod

Load a :class:NamespaceSpec from config_path and return a builder.

generate_path(level, values, include_optional_levels=True, level_overrides=None)

Return the full path from root up to (and including) level.

Always joins with forward slashes so the result is a portable logical path: identical on Linux/macOS/Windows, safe to store in session files and use for cross-system data alignment.

Parameters:

Name	Type	Description	Default
level	str	Hierarchy level name to stop at (inclusive).	required
values	dict[str, str]	Template field values for building each level segment.	required
include_optional_levels	bool	If False, skip optional levels.	True
level_overrides	dict[str, str] | None	Pre-built segment strings keyed by level name. When a level appears here its value is used verbatim instead of being constructed from values. Use this when a segment comes from an external system (e.g. an OE acquisition name).	None

to_dict()

Return the spec as a plain dict suitable for serialisation.

validate_field(name, value)

Validate value against the named validator pattern.

Parameters:

Name	Type	Description	Default
name	str	Key in the validators dict of the loaded spec.	required
value	str	String to validate.	required

Returns:

Type	Description
str	value unchanged if it matches the pattern.

Raises:

Type	Description
ValueError	If name is not a known validator, or value does not fully match the pattern.

validate_path(path, stop_at=None)

Walk path level by level and return all captured values.

Parameters:

Name	Type	Description	Default
path	str | Path	Filesystem path to validate (absolute or relative).	required
stop_at	str | None	Stop after matching this hierarchy level. If None, walks the entire hierarchy.	None

Returns:

Type	Description
dict[str, str]	Dict mapping each hierarchy level name to its captured field values.

Raises:

Type	Description
ValueError	If any segment does not match the expected regex.

validate_path_level(level, segment, known_values)

Match segment against the regex for level and return captured groups.

Parameters:

Name	Type	Description	Default
level	str	Hierarchy level name whose regex is applied.	required
segment	str	Single path component string to match.	required
known_values	dict[str, str]	Previously captured field values; used to substitute literal values into the regex before matching, tightening the match for levels whose regex contains back-references to parent field values.	required

Returns:

Type	Description
dict[str, str]	Dict of named capture groups extracted from segment.

Raises:

Type	Description
ValueError	If segment does not match the level's regex.

write_yaml(path)

Serialise the spec back to a YAML file.

acquisition_namespace.NamespaceSpec

Bases: BaseModel

Full namespace specification loaded from a YAML config file.

Attributes:

Name	Type	Description
version	str	Semver string identifying the spec revision.
description	str	Human-readable summary of this namespace (optional).
hierarchy	list[str]	Ordered list of level names from root to leaf (e.g. ["subject", "session", "recording"]).
optional_levels	list[str]	Subset of hierarchy names that may be omitted when generating paths.
levels	dict[str, NamespaceLevelSpec]	Mapping from level name to its :class:NamespaceLevelSpec. Every name in hierarchy must appear here.
validators	dict[str, NamespaceValidatorSpec]	Named field patterns used as building blocks. ${name} tokens in level regexes are expanded to the corresponding pattern before compilation.

acquisition_namespace.NamespaceLevelSpec

Bases: BaseModel

Spec for one level in the acquisition namespace hierarchy.

Attributes:

Name	Type	Description
template	str	Python format-string used to construct the level's path segment (e.g. "{subject}_{session_date}").
regex	str	Named-group regular expression used to parse and validate a segment string. Must be compilable by :mod:re.
optional_fields	list[str]	Template fields that may be absent; the builder will not raise if their values are missing.