Skip to content

registries

Generic EnumRegistry and DescriptorRegistry base classes for runtime-extensible registries.

T module-attribute 

T = TypeVar('T', bound=str)

K module-attribute 

K = TypeVar('K', bound=str | Enum)

V module-attribute 

V = TypeVar('V')

EnumRegistry

Minimal registry helper for enum-like string values.

meta_consts.py exposes many register/is_known pairs. Centralizing the semantics here keeps runtime-extensible enums consistent while still allowing static enums for IDE help.

Source code in src/horde_model_reference/registries.py 
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
class EnumRegistry[T]:
    """Minimal registry helper for enum-like string values.

    meta_consts.py exposes many ``register/is_known`` pairs. Centralizing the
    semantics here keeps runtime-extensible enums consistent while still
    allowing static enums for IDE help.
    """

    def __init__(self, initial: Iterable[T]) -> None:
        """Initialize the enum registry with an optional iterable of initial values.

        Args:
            initial (Iterable[T]): An iterable of initial string values to populate the registry with.

        """
        self._known: set[str] = {str(item) for item in initial}

    def is_known(self, value: str | Enum) -> bool:
        """Check if a value is known (registered) in the enum registry.

        Args:
            value (str | Enum): The value to check for membership in the registry.

        Returns:
            bool: True if the value is known (registered), False otherwise.

        """
        return str(value) in self._known

    def register(self, value: str | Enum) -> None:
        """Register a new value in the enum registry.

        Attempting to register a value that is already known is a no-op.

        Args:
            value (str | Enum): The value to register.

        """
        normalized = str(value)
        if normalized in self._known:
            return
        self._known.add(normalized)

    def values(self) -> set[str]:
        """Get a set of all known (registered) values in the enum registry.

        Returns:
            set[str]: A set of all known (registered) string values in the registry.

        """
        return set(self._known)

    def mutable_values(self) -> set[str]:
        """Expose a live set for backwards-compatible global aliases.

        Returns:
            set[str]: A live set of known values.

        """
        return self._known

_known instance-attribute 

_known: set[str] = {(str(item)) for item in initial}

__init__ 

__init__(initial: Iterable[T]) -> None

Initialize the enum registry with an optional iterable of initial values.

Parameters:

  • initial (Iterable[T]) –

    An iterable of initial string values to populate the registry with.

Source code in src/horde_model_reference/registries.py 
22
23
24
25
26
27
28
29
def __init__(self, initial: Iterable[T]) -> None:
    """Initialize the enum registry with an optional iterable of initial values.

    Args:
        initial (Iterable[T]): An iterable of initial string values to populate the registry with.

    """
    self._known: set[str] = {str(item) for item in initial}

is_known 

is_known(value: str | Enum) -> bool

Check if a value is known (registered) in the enum registry.

Parameters:

  • value (str | Enum) –

    The value to check for membership in the registry.

Returns:

  • bool ( bool ) –

    True if the value is known (registered), False otherwise.

Source code in src/horde_model_reference/registries.py 
31
32
33
34
35
36
37
38
39
40
41
def is_known(self, value: str | Enum) -> bool:
    """Check if a value is known (registered) in the enum registry.

    Args:
        value (str | Enum): The value to check for membership in the registry.

    Returns:
        bool: True if the value is known (registered), False otherwise.

    """
    return str(value) in self._known

register 

register(value: str | Enum) -> None

Register a new value in the enum registry.

Attempting to register a value that is already known is a no-op.

Parameters:

  • value (str | Enum) –

    The value to register.

Source code in src/horde_model_reference/registries.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
def register(self, value: str | Enum) -> None:
    """Register a new value in the enum registry.

    Attempting to register a value that is already known is a no-op.

    Args:
        value (str | Enum): The value to register.

    """
    normalized = str(value)
    if normalized in self._known:
        return
    self._known.add(normalized)

values 

values() -> set[str]

Get a set of all known (registered) values in the enum registry.

Returns:

  • set[str] –

    set[str]: A set of all known (registered) string values in the registry.

Source code in src/horde_model_reference/registries.py 
57
58
59
60
61
62
63
64
def values(self) -> set[str]:
    """Get a set of all known (registered) values in the enum registry.

    Returns:
        set[str]: A set of all known (registered) string values in the registry.

    """
    return set(self._known)

mutable_values 

mutable_values() -> set[str]

Expose a live set for backwards-compatible global aliases.

Returns:

  • set[str] –

    set[str]: A live set of known values.

Source code in src/horde_model_reference/registries.py 
66
67
68
69
70
71
72
73
def mutable_values(self) -> set[str]:
    """Expose a live set for backwards-compatible global aliases.

    Returns:
        set[str]: A live set of known values.

    """
    return self._known

DescriptorRegistry

Registry for keyed descriptors with a rebuild hook for derived data.

Category/baseline registries need to invalidate and rebuild derived lookups after mutation, but only once initialization is complete. This helper centralizes that lifecycle so new registries get the same safety guards by default.

Source code in src/horde_model_reference/registries.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
class DescriptorRegistry[K, V]:
    """Registry for keyed descriptors with a rebuild hook for derived data.

    Category/baseline registries need to invalidate and rebuild derived
    lookups after mutation, but only once initialization is complete. This
    helper centralizes that lifecycle so new registries get the same safety
    guards by default.
    """

    def __init__(self, rebuild: Callable[[dict[K, V]], None]) -> None:
        """Initialize the descriptor registry.

        Args:
            rebuild (Callable[[dict[K, V]], None]): Function to call to rebuild derived data when the registry is
                updated.

        """
        self._data: dict[K, V] = {}
        self._rebuild = rebuild
        self._init_complete = False

    def register(self, key: K, value: V) -> None:
        """Register a key-value pair, raising if the key is already registered.

        Args:
            key (K): The key to register.
            value (V): The value to associate with the key.

        Raises:
            ValueError: If the key is already registered.

        """
        if key in self._data:
            raise ValueError(f"{key!r} is already registered")
        self._data[key] = value
        if self._init_complete:
            self._rebuild(self._data)

    def update_value(self, key: K, value: V) -> None:
        """Update the value for an already registered key, raising if the key is not registered.

        Args:
            key (K): The key to update.
            value (V): The new value to associate with the key.

        Raises:
            ValueError: If the key is not already registered.

        """
        if key not in self._data:
            raise ValueError(f"{key!r} is not registered and cannot be updated")
        self._data[key] = value
        if self._init_complete:
            self._rebuild(self._data)

    def finalize(self) -> None:
        """Mark initialization complete and trigger a final rebuild with all registered data.

        Subsequent calls to register() will trigger immediate rebuilds, so this should only be called once after the
        initial batch of registrations is done.
        """
        if self._init_complete:
            return
        self._init_complete = True
        self._rebuild(self._data)

    def get(self, key: K) -> V:
        """Get the value for a registered key, or raise if the key is unknown.

        Args:
            key (K): The key to look up.

        Returns:
            V: The value associated with the key.

        """
        return self._data[key]

    def all(self) -> dict[K, V]:
        """Get a copy of all registered key-value pairs.

        Returns:
            dict[K, V]: A copy of all registered key-value pairs.

        """
        return dict(self._data)

    def contains(self, key: K) -> bool:
        """Check if a key is registered.

        Args:
            key (K): The key to check.

        Returns:
            bool: True if the key is registered, False otherwise.

        """
        return key in self._data

_data instance-attribute 

_data: dict[K, V] = {}

_rebuild instance-attribute 

_rebuild = rebuild

_init_complete instance-attribute 

_init_complete = False

__init__ 

__init__(rebuild: Callable[[dict[K, V]], None]) -> None

Initialize the descriptor registry.

Parameters:

  • rebuild (Callable[[dict[K, V]], None]) –

    Function to call to rebuild derived data when the registry is updated.

Source code in src/horde_model_reference/registries.py 
85
86
87
88
89
90
91
92
93
94
95
def __init__(self, rebuild: Callable[[dict[K, V]], None]) -> None:
    """Initialize the descriptor registry.

    Args:
        rebuild (Callable[[dict[K, V]], None]): Function to call to rebuild derived data when the registry is
            updated.

    """
    self._data: dict[K, V] = {}
    self._rebuild = rebuild
    self._init_complete = False

register 

register(key: K, value: V) -> None

Register a key-value pair, raising if the key is already registered.

Parameters:

  • key (K) –

    The key to register.

  • value (V) –

    The value to associate with the key.

Raises:

  • ValueError –

    If the key is already registered.

Source code in src/horde_model_reference/registries.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def register(self, key: K, value: V) -> None:
    """Register a key-value pair, raising if the key is already registered.

    Args:
        key (K): The key to register.
        value (V): The value to associate with the key.

    Raises:
        ValueError: If the key is already registered.

    """
    if key in self._data:
        raise ValueError(f"{key!r} is already registered")
    self._data[key] = value
    if self._init_complete:
        self._rebuild(self._data)

update_value 

update_value(key: K, value: V) -> None

Update the value for an already registered key, raising if the key is not registered.

Parameters:

  • key (K) –

    The key to update.

  • value (V) –

    The new value to associate with the key.

Raises:

  • ValueError –

    If the key is not already registered.

Source code in src/horde_model_reference/registries.py 
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def update_value(self, key: K, value: V) -> None:
    """Update the value for an already registered key, raising if the key is not registered.

    Args:
        key (K): The key to update.
        value (V): The new value to associate with the key.

    Raises:
        ValueError: If the key is not already registered.

    """
    if key not in self._data:
        raise ValueError(f"{key!r} is not registered and cannot be updated")
    self._data[key] = value
    if self._init_complete:
        self._rebuild(self._data)

finalize 

finalize() -> None

Mark initialization complete and trigger a final rebuild with all registered data.

Subsequent calls to register() will trigger immediate rebuilds, so this should only be called once after the initial batch of registrations is done.

Source code in src/horde_model_reference/registries.py 
131
132
133
134
135
136
137
138
139
140
def finalize(self) -> None:
    """Mark initialization complete and trigger a final rebuild with all registered data.

    Subsequent calls to register() will trigger immediate rebuilds, so this should only be called once after the
    initial batch of registrations is done.
    """
    if self._init_complete:
        return
    self._init_complete = True
    self._rebuild(self._data)

get 

get(key: K) -> V

Get the value for a registered key, or raise if the key is unknown.

Parameters:

  • key (K) –

    The key to look up.

Returns:

  • V ( V ) –

    The value associated with the key.

Source code in src/horde_model_reference/registries.py 
142
143
144
145
146
147
148
149
150
151
152
def get(self, key: K) -> V:
    """Get the value for a registered key, or raise if the key is unknown.

    Args:
        key (K): The key to look up.

    Returns:
        V: The value associated with the key.

    """
    return self._data[key]

all 

all() -> dict[K, V]

Get a copy of all registered key-value pairs.

Returns:

  • dict[K, V] –

    dict[K, V]: A copy of all registered key-value pairs.

Source code in src/horde_model_reference/registries.py 
154
155
156
157
158
159
160
161
def all(self) -> dict[K, V]:
    """Get a copy of all registered key-value pairs.

    Returns:
        dict[K, V]: A copy of all registered key-value pairs.

    """
    return dict(self._data)

contains 

contains(key: K) -> bool

Check if a key is registered.

Parameters:

  • key (K) –

    The key to check.

Returns:

  • bool ( bool ) –

    True if the key is registered, False otherwise.

Source code in src/horde_model_reference/registries.py 
163
164
165
166
167
168
169
170
171
172
173
def contains(self, key: K) -> bool:
    """Check if a key is registered.

    Args:
        key (K): The key to check.

    Returns:
        bool: True if the key is registered, False otherwise.

    """
    return key in self._data