API

Public module

Public API for Sygaldry.

Component factory that loads, merges, and resolves config into objects.

property config: dict[str, Any]

The loaded, merged, and interpolated configuration (before resolution).

Returns:: Prepared configuration mapping.
Return type:: dict[str, Any]

resolve() → dict[str, Any]

Validate and resolve the full config mapping into objects.

Returns:: Resolved configuration mapping.
Return type:: dict[str, Any]

sygaldry.load(path: str | Path, *, cache: Instances | None = None, transient: bool = False) → dict[str, Any]

Load, interpolate, and resolve a config file.

Parameters:

path (str | pathlib.Path) – Path to a YAML or TOML config file.
cache (Instances | None) – Optional instance cache.
transient (bool) – If True, bypass caching.

Returns:

Resolved configuration mapping.

Return type:

dict[str, Any]

Artificery module

class sygaldry.artificery.Reference(path: str): Reference to a dotted config path.

class sygaldry.artificery.ConstructorSpec(target: str, args: tuple[Any, ...], kwargs: dict[str, Any], instance: str | None): Constructor specification for a component.

class sygaldry.artificery.Node(name: str, children: tuple[str, ...], bindings: dict[str, Any]): Intermediate node representation for optional IR usage.

sygaldry.artificery.load_config_file(path: str | Path) → dict[str, Any]

Load a config file without resolving components.

Parameters:: path (str | pathlib.Path) – Path to a YAML or TOML config file.
Returns:: Parsed and interpolated mapping.
Return type:: dict[str, Any]

class sygaldry.artificery.ArtificeryLoader(path: str | Path)

Lightweight loader wrapper for config files.

load() → dict[str, Any]

Load and return the config mapping.

Returns:: Parsed and interpolated configuration mapping.
Return type:: dict[str, Any]

sygaldry.artificery.resolve_config(config: dict[str, Any], *, file_path: str | None = None, cache: Instances | None = None, transient: bool = False) → dict[str, Any]

Resolve a config mapping into an instantiated object graph.

Parameters:

config (dict[str, Any]) – Configuration mapping.
file_path (str | None) – Source config path for context.
cache (Instances | None) – Optional instance cache.
transient (bool) – If True, bypass caching.

Returns:

Resolved configuration mapping.

Return type:

dict[str, Any]

Component factory that loads, merges, and resolves config into objects.

property config: dict[str, Any]

The loaded, merged, and interpolated configuration (before resolution).

Returns:: Prepared configuration mapping.
Return type:: dict[str, Any]

resolve() → dict[str, Any]

Validate and resolve the full config mapping into objects.

Returns:: Resolved configuration mapping.
Return type:: dict[str, Any]

Loader module

Config loading with includes, deep merge, and interpolation.

sygaldry.loader.load_config(path: Path) → dict[str, Any]

Load and interpolate a config file.

Parameters:: path (pathlib.Path) – Path to a YAML or TOML config file.
Returns:: Merged, interpolated configuration mapping.
Return type:: dict[str, Any]

Cache module

Instance cache with hash conflict detection.

class sygaldry.cache.CacheEntry(value: Any, spec_hash: str): Cached instance entry with hash for conflict detection.

class sygaldry.cache.Instances

Per-factory cache keyed by (type_path, instance tag or spec hash).

get(type_path: str, instance: str | None, *, expected_hash: str | None = None, file_path: str | None = None, config_path: str | None = None) → Any

Return a cached instance if present.

Parameters:

type_path (str) – Dotted type path used as cache key.
instance (str | None) – Optional instance tag.
expected_hash (str | None) – Optional hash to validate cache entry.
file_path (str | None) – Source config file path, if known.
config_path (str | None) – Dotted config path for context.

Returns:

Cached instance if found, or _NOT_FOUND sentinel.

Return type:

object

Raises:

ConfigConflictError – If the cached hash conflicts.

set(type_path: str, instance: str | None, value: Any, *, spec_hash: str, file_path: str | None = None, config_path: str | None = None) → Any

Insert or validate a cache entry.

Parameters:

type_path (str) – Dotted type path used as cache key.
instance (str | None) – Optional instance tag.
value (object) – Resolved object instance.
spec_hash (str) – Hash for the constructor spec.
file_path (str | None) – Source config file path, if known.
config_path (str | None) – Dotted config path for context.

Returns:

The inserted instance.

Return type:

object

Raises:

ConfigConflictError – If an existing entry conflicts.

get_or_create(type_path: str, instance: str | None, args: tuple[Any, ...], kwargs: dict[str, Any], factory: Callable[[], Any], *, transient: bool = False, file_path: str | None = None, config_path: str | None = None) → Any

Get or create a cached instance.

Parameters:

type_path (str) – Dotted type path used as cache key.
instance (str | None) – Optional instance tag.
args (tuple[Any, ...]) – Resolved positional args.
kwargs (dict[str, Any]) – Resolved keyword args.
factory (collections.abc.Callable[[], Any]) – Callable that constructs the instance.
transient (bool) – If True, bypass caching.
file_path (str | None) – Source config file path, if known.
config_path (str | None) – Dotted config path for context.

Returns:

Cached or newly created instance.

Return type:

object

Checker module

class sygaldry.checker.CheckError(config_path: str, message: str, severity: str = 'error'): A type error found in a config file.

sygaldry.checker.check(path: str | Path | None = None, *, type_checker: str | None = None, config: dict[str, Any] | None = None) → list[CheckError]

Type check a sygaldry config file.

Either path or config must be provided. When config is given the config dict is used directly (useful from the CLI after loading and applying overrides). When path is given, the file is loaded via load_config().

Parameters:

path – Path to a YAML/TOML config file.
type_checker – Which checker to run (ty, basedpyright, pyright, or mypy). Auto-detected when None.
config – Pre-loaded config dict.

Returns:

List of type errors found.

Code generation module

class sygaldry.codegen.SourceMapping(line: int, config_path: str): Map a generated line number to a config path.

class sygaldry.codegen.ComponentEntry(config_path: str, var_name: str, import_path: str, args: list[~typing.Any] = <factory>, kwargs: dict[str, ~typing.Any] = <factory>, is_func: bool = False): A typed component extracted from the config.

class sygaldry.codegen.PlainEntry(config_path: str, var_name: str, value: Any): A plain (non-typed) config value.

class sygaldry.codegen.RefExpression(target: str): A reference expression to be emitted as a variable or attribute access.

class sygaldry.codegen.EntriesExpression(items: list[tuple[Any, Any]]): A dict built from _entries.

class sygaldry.codegen.AnalysisResult(components: list[~sygaldry.codegen.ComponentEntry] = <factory>, plains: list[~sygaldry.codegen.PlainEntry] = <factory>, topological_order: list[str] = <factory>, imports: dict[str, tuple[str, str]] = <factory>): Result of analyzing a config dict.

class sygaldry.codegen.ConfigAnalyzer(config: dict[str, Any])

Walk a loaded config dict and extract typed component specs.

analyze() → AnalysisResult: Analyze the config and return structured results.

class sygaldry.codegen.CodeGenerator(analysis: AnalysisResult)

Generate Python source code from analysis results.

generate() → tuple[str, list[SourceMapping]]: Generate the full source code.

sygaldry.codegen.generate_check_source(config: dict[str, Any]) → tuple[str, list[SourceMapping]]

Generate type-checkable Python source from a sygaldry config.

Parameters:: config (dict) – Loaded, interpolated config mapping.
Returns:: (source_code, mappings) tuple.

CLI module

Types module

Shared constants and import helpers.

sygaldry.types.import_dotted_path(dotted_path: str, *, file_path: str | None = None, config_path: str | None = None) → object

Import a dotted path and return the target object. Resolves the longest importable module prefix and then walks remaining attributes. Raising and ImportResolutionError with context if it fails.

Parameters:

dotted_path (str) – Fully-qualified dotted import path.
file_path (str | None) – Source config file path, if known.
config_path (str | None) – Dotted config path for context.

Returns:

Imported module attribute or callable.

Return type:

object

Raises:

ImportResolutionError – If the module or attribute cannot be imported.

Errors

exception sygaldry.errors.SygaldryError(message: str, file_path: str | None = None, config_path: str | None = None)

Base error for all Sygaldry failures.

Parameters:

message (str) – Human-readable error message.
file_path (str | None) – Source config file path, if known.
config_path (str | None) – Dotted config path for context.

exception sygaldry.errors.LoadError(message: str, file_path: str | None = None, config_path: str | None = None): Errors during file loading or parsing.

exception sygaldry.errors.ParseError(message: str, file_path: str | None = None, config_path: str | None = None): Parsing failures for YAML or TOML.

exception sygaldry.errors.IncludeError(message: str, file_path: str | None = None, config_path: str | None = None): Errors during include resolution or deep merge.

exception sygaldry.errors.CircularIncludeError(message: str, file_path: str | None = None, config_path: str | None = None): Circular include detected.

exception sygaldry.errors.ValidationError(message: str, file_path: str | None = None, config_path: str | None = None): Schema or config validation failures.

exception sygaldry.errors.ConfigReferenceError(message: str, file_path: str | None = None, config_path: str | None = None): Missing or invalid _ref targets.

exception sygaldry.errors.CircularReferenceError(message: str, file_path: str | None = None, config_path: str | None = None): Circular _ref detected.

exception sygaldry.errors.InterpolationError(message: str, file_path: str | None = None, config_path: str | None = None): Interpolation failures.

exception sygaldry.errors.CircularInterpolationError(message: str, file_path: str | None = None, config_path: str | None = None): Circular interpolation detected.

exception sygaldry.errors.ImportResolutionError(message: str, file_path: str | None = None, config_path: str | None = None): Import or dotted path resolution failures.

exception sygaldry.errors.ResolutionError(message: str, file_path: str | None = None, config_path: str | None = None): Errors during recursive resolution.

exception sygaldry.errors.ConstructorError(message: str, file_path: str | None = None, config_path: str | None = None): Constructor invocation failures.

exception sygaldry.errors.ConfigConflictError(message: str, file_path: str | None = None, config_path: str | None = None): Cache conflicts for identical keys with differing specs.

exception sygaldry.errors.CLIError(message: str, file_path: str | None = None, config_path: str | None = None): Errors originating from CLI argument processing.