metadata

Source location metadata tracking.

MetadataRegistry

Track source locations for config items.

Maintains a clean separation between config data and metadata about where config items came from. This avoids polluting config dictionaries with metadata keys.

Example

registry = MetadataRegistry()
registry.register("model::lr", SourceLocation("config.yaml", 10, 2, "model::lr"))

location = registry.get("model::lr")
print(location.filepath)  # "config.yaml"
print(location.line)      # 10

Source code in src/sparkwheel/metadata.py

class MetadataRegistry:
    """Track source locations for config items.

    Maintains a clean separation between config data and metadata about where
    config items came from. This avoids polluting config dictionaries with
    metadata keys.

    Example:
        ```python
        registry = MetadataRegistry()
        registry.register("model::lr", SourceLocation("config.yaml", 10, 2, "model::lr"))

        location = registry.get("model::lr")
        print(location.filepath)  # "config.yaml"
        print(location.line)      # 10
        ```
    """

    def __init__(self):
        """Initialize empty metadata registry."""
        self._locations: dict[str, SourceLocation] = {}

    def register(self, id_path: str, location: SourceLocation) -> None:
        """Register source location for a config path.

        Args:
            id_path: Configuration path (e.g., "model::lr", "optimizer::params::0")
            location: Source location information
        """
        self._locations[id_path] = location

    def get(self, id_path: str) -> SourceLocation | None:
        """Get source location for a config path.

        Args:
            id_path: Configuration path to look up

        Returns:
            SourceLocation if registered, None otherwise
        """
        return self._locations.get(id_path)

    def merge(self, other: "MetadataRegistry") -> None:
        """Merge another registry into this one.

        Args:
            other: MetadataRegistry to merge from
        """
        self._locations.update(other._locations)

    def copy(self) -> "MetadataRegistry":
        """Create a copy of this registry.

        Returns:
            New MetadataRegistry with same data
        """
        new_registry = MetadataRegistry()
        new_registry._locations = self._locations.copy()
        return new_registry

    def __len__(self) -> int:
        """Return number of registered locations."""
        return len(self._locations)

    def __contains__(self, id_path: str) -> bool:
        """Check if id_path has registered location."""
        return id_path in self._locations

__contains__(id_path)

Check if id_path has registered location.

Source code in src/sparkwheel/metadata.py

def __contains__(self, id_path: str) -> bool:
    """Check if id_path has registered location."""
    return id_path in self._locations

__init__()

Initialize empty metadata registry.

Source code in src/sparkwheel/metadata.py

def __init__(self):
    """Initialize empty metadata registry."""
    self._locations: dict[str, SourceLocation] = {}

__len__()

Return number of registered locations.

Source code in src/sparkwheel/metadata.py

def __len__(self) -> int:
    """Return number of registered locations."""
    return len(self._locations)

copy()

Create a copy of this registry.

Returns:

Type	Description
MetadataRegistry	New MetadataRegistry with same data

Source code in src/sparkwheel/metadata.py

def copy(self) -> "MetadataRegistry":
    """Create a copy of this registry.

    Returns:
        New MetadataRegistry with same data
    """
    new_registry = MetadataRegistry()
    new_registry._locations = self._locations.copy()
    return new_registry

get(id_path)

Get source location for a config path.

Parameters:

Name	Type	Description	Default
id_path	str	Configuration path to look up	required

Returns:

Type	Description
SourceLocation | None	SourceLocation if registered, None otherwise

Source code in src/sparkwheel/metadata.py

def get(self, id_path: str) -> SourceLocation | None:
    """Get source location for a config path.

    Args:
        id_path: Configuration path to look up

    Returns:
        SourceLocation if registered, None otherwise
    """
    return self._locations.get(id_path)

merge(other)

Merge another registry into this one.

Parameters:

Name	Type	Description	Default
other	MetadataRegistry	MetadataRegistry to merge from	required

Source code in src/sparkwheel/metadata.py

def merge(self, other: "MetadataRegistry") -> None:
    """Merge another registry into this one.

    Args:
        other: MetadataRegistry to merge from
    """
    self._locations.update(other._locations)

register(id_path, location)

Register source location for a config path.

Parameters:

Name	Type	Description	Default
id_path	str	Configuration path (e.g., "model::lr", "optimizer::params::0")	required
location	SourceLocation	Source location information	required

Source code in src/sparkwheel/metadata.py

def register(self, id_path: str, location: SourceLocation) -> None:
    """Register source location for a config path.

    Args:
        id_path: Configuration path (e.g., "model::lr", "optimizer::params::0")
        location: Source location information
    """
    self._locations[id_path] = location