Skip to content

locations

Location tracking for configuration keys.

LocationRegistry

Registry that tracks file locations for configuration keys.

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

Example 
registry = LocationRegistry()
registry.register("model::lr", Location("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/locations.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
class LocationRegistry:
    """Registry that tracks file locations for configuration keys.

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

    Example:
        ```python
        registry = LocationRegistry()
        registry.register("model::lr", Location("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 location registry."""
        self._locations: dict[str, Location] = {}

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

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

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

        Args:
            id_path: Configuration path to look up

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

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

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

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

        Returns:
            New LocationRegistry with same data
        """
        new_registry = LocationRegistry()
        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/locations.py 
72
73
74
def __contains__(self, id_path: str) -> bool:
    """Check if id_path has registered location."""
    return id_path in self._locations

__init__()

Initialize empty location registry.

Source code in src/sparkwheel/locations.py 
26
27
28
def __init__(self):
    """Initialize empty location registry."""
    self._locations: dict[str, Location] = {}

__len__()

Return number of registered locations.

Source code in src/sparkwheel/locations.py 
68
69
70
def __len__(self) -> int:
    """Return number of registered locations."""
    return len(self._locations)

copy()

Create a copy of this registry.

Returns:

Type Description
LocationRegistry

New LocationRegistry with same data
Source code in src/sparkwheel/locations.py 
58
59
60
61
62
63
64
65
66
def copy(self) -> "LocationRegistry":
    """Create a copy of this registry.

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

get(id_path)

Get location for a config path.

Parameters:

Name Type Description Default
id_path str

Configuration path to look up

 required

Returns:

Type Description
Location | None

Location if registered, None otherwise
Source code in src/sparkwheel/locations.py 
39
40
41
42
43
44
45
46
47
48
def get(self, id_path: str) -> Location | None:
    """Get location for a config path.

    Args:
        id_path: Configuration path to look up

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

merge(other)

Merge another registry into this one.

Parameters:

Name Type Description Default
other LocationRegistry

LocationRegistry to merge from

 required
Source code in src/sparkwheel/locations.py 
50
51
52
53
54
55
56
def merge(self, other: "LocationRegistry") -> None:
    """Merge another registry into this one.

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

register(id_path, location)

Register location for a config path.

Parameters:

Name Type Description Default
id_path str

Configuration path (e.g., "model::lr", "optimizer::params::0")

 required
location Location

Location information

 required
Source code in src/sparkwheel/locations.py 
30
31
32
33
34
35
36
37
def register(self, id_path: str, location: Location) -> None:
    """Register location for a config path.

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