__init__.py
Summary
- Lines:
36 of 36 covered (100.0%)
- Branches:
4 of 4 taken (100.0%), 0 lines partially
- Coverage:
100.0%
- Directory:
Source
pyTooling/DataModel/__init__.pycoveredpartialuncoveredexcludednot executable
1# ==================================================================================================================== #
2# _____ _ _ ____ _ __ __ _ _ #
3# _ __ _ |_ _|__ ___ | (_)_ __ __ _ | _ \ __ _| |_ __ _| \/ | ___ __| | ___| | #
4# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` | | | | |/ _` | __/ _` | |\/| |/ _ \ / _` |/ _ \ | #
5# | |_) | |_| || | (_) | (_) | | | | | | (_| |_| |_| | (_| | || (_| | | | | (_) | (_| | __/ | #
6# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____/ \__,_|\__\__,_|_| |_|\___/ \__,_|\___|_| #
7# |_| |___/ |___/ #
8# ==================================================================================================================== #
9# Authors: #
10# Patrick Lehmann #
11# #
12# License: #
13# ==================================================================================================================== #
14# Copyright 2026-2026 Patrick Lehmann - Bötzingen, Germany #
15# #
16# Licensed under the Apache License, Version 2.0 (the "License"); #
17# you may not use this file except in compliance with the License. #
18# You may obtain a copy of the License at #
19# #
20# http://www.apache.org/licenses/LICENSE-2.0 #
21# #
22# Unless required by applicable law or agreed to in writing, software #
23# distributed under the License is distributed on an "AS IS" BASIS, #
24# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
25# See the License for the specific language governing permissions and #
26# limitations under the License. #
27# #
28# SPDX-License-Identifier: Apache-2.0 #
29# ==================================================================================================================== #
30#
31"""
32Foundations of data models: building blocks the classes of a data model share.
33
34A :class:`KeyValuePairsMixin` attaches arbitrary key-value-pairs to an element of a data model, accessed like a
35dictionary: :pycode:`element["runner.os"] = "Linux"`. :data:`Predicate` is the type of a function selecting
36elements, e.g. in an ``Iterate***`` method.
37
38.. hint::
39
40 See :ref:`high-level help <STRUCT/DataModel>` for explanations and usage examples.
41"""
42from __future__ import annotations
43
44from typing import Any, Callable, Hashable, Iterator, Mapping, Optional as Nullable, TypeVar
45
46from pyTooling.Common import getFullyQualifiedName
47from pyTooling.Decorators import export
48from pyTooling.MetaClasses import ExtendedType
49
50
51__all__ = ["ElementType", "Predicate"]
52
53
54# WORKAROUND: Python <3.12
55# Obsolete with the 'type' statement for 'Predicate' below, which declares its type parameter itself.
56ElementType = TypeVar("ElementType")
57"""A type variable for the element a :data:`Predicate` decides on."""
58
59# WORKAROUND: Python <3.12
60# The 'type' statement (PEP 695) isn't supported by Python 3.11. Use it when Python 3.11 support gets dropped:
61# type Predicate[ElementType] = Callable[[ElementType], bool]
62Predicate = Callable[[ElementType], bool]
63"""
64A function deciding whether an element is selected.
65
66``Predicate[Vertex]`` is ``Callable[[Vertex], bool]``. Methods filtering what they iterate, reverse or remove take a
67predicate, e.g. :meth:`pyTooling.Graph.BaseGraph.IterateVertices`.
68"""
69
70
71@export
72class KeyValuePairsMixin(metaclass=ExtendedType, mixin=True):
73 """
74 Mixin-class adding arbitrary key-value-pairs to an element of a data model, accessed like a dictionary.
75
76 * :pycode:`element[key]` reads a value.
77 * :pycode:`element.get(key, default)` reads a value, or a default value, if the key doesn't exist.
78 * :pycode:`element[key] = value` creates or updates a pair.
79 * :pycode:`del element[key]` removes a pair.
80 * :pycode:`key in element` checks for a key.
81 * :pycode:`len(element)` counts the pairs.
82 * :pycode:`for key in element:` iterates the keys.
83 """
84
85 _dict: dict[Hashable, Any] #: A dictionary to store arbitrary key-value-pairs.
86
87 def __init__(self, keyValuePairs: Nullable[Mapping[Hashable, Any]] = None) -> None:
88 """
89 Initializes the key-value-pairs.
90
91 :param keyValuePairs: Optional, mapping (dictionary) of key-value-pairs. Default: ``None``.
92 :raises TypeError: If parameter 'keyValuePairs' is not a mapping.
93 """
94 if keyValuePairs is None:
95 self._dict = {}
96 return
97 elif not isinstance(keyValuePairs, Mapping):
98 ex = TypeError("Parameter 'keyValuePairs' is not a mapping ('dict', ...).")
99 ex.add_note(f"Got type '{getFullyQualifiedName(keyValuePairs)}'.")
100 raise ex
101
102 self._dict = dict(keyValuePairs)
103
104 def get(self, key: Hashable, default: Any = None) -> Any:
105 """
106 Read an attached attribute (key-value-pair) by key, or a default value, if the key doesn't exist.
107
108 This method is spelled the way :meth:`dict.get` is, because that is the behaviour it offers.
109
110 :param key: The key to look for.
111 :param default: Optional, the value returned if the key isn't an attached attribute. Default: ``None``.
112 :returns: The value associated to the given key, otherwise the default value.
113 """
114 return self._dict.get(key, default)
115
116 def __getitem__(self, key: Hashable) -> Any:
117 """
118 Read an attached attribute (key-value-pair) by key.
119
120 :param key: The key to look for.
121 :returns: The value associated to the given key.
122 :raises KeyError: If key doesn't exist in the attached attributes.
123 """
124 return self._dict[key]
125
126 def __setitem__(self, key: Hashable, value: Any) -> None:
127 """
128 Create or update an attached attribute (key-value-pair) by key.
129
130 If a key doesn't exist yet, a new key-value-pair is created.
131
132 :param key: The key to create or update.
133 :param value: The value to associate to the given key.
134 """
135 self._dict[key] = value
136
137 def __delitem__(self, key: Hashable) -> None:
138 """
139 Remove an attached attribute (key-value-pair) by key.
140
141 :param key: The key to remove.
142 :raises KeyError: If key doesn't exist in the attached attributes.
143 """
144 del self._dict[key]
145
146 def __contains__(self, key: Hashable) -> bool:
147 """
148 Check if the key is an attached attribute (key-value-pair).
149
150 :param key: The key to check.
151 :returns: ``True``, if the key is an attached attribute.
152 """
153 return key in self._dict
154
155 def __len__(self) -> int:
156 """
157 Return the number of attached attributes (key-value-pairs).
158
159 :returns: Number of attached attributes.
160 """
161 return len(self._dict)
162
163 def __iter__(self) -> Iterator[Hashable]:
164 """
165 Iterate the keys of the attached attributes (key-value-pairs).
166
167 :returns: An iterator over the keys, in the order they were added.
168 """
169 return iter(self._dict)