jcmsuite-data-tree 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,369 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Schema-directory storage and lookup helpers for data-tree definitions."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import jcmsuite_data_tree.schema_primitives as schema_primitives
9
+
10
+ from .toolbox import AsciiVector
11
+
12
+ TREE_PATH_TEMPLATE = AsciiVector(delimiter=":")
13
+
14
+
15
+ class DirSchema:
16
+ """Describe one schema directory and the items allowed beneath it."""
17
+
18
+ def __init__(self, name: str = "", aliasNames: set[str] | None = None) -> None:
19
+ """Initialize a schema directory definition."""
20
+
21
+ self._name = str(name)
22
+ self._aliasNames: set[str] = set(aliasNames or set()).copy()
23
+ self._dirs: dict[str, DirSchema] = {}
24
+ self._primitives: dict[tuple[str, int], schema_primitives.PrimitiveSchema] = {}
25
+ self._choiceDirs: dict[str, DirSchema] = {}
26
+ self._adaptors: dict[str, SchemaAdaptor] = {}
27
+ self._thisAdaptors: set[SchemaAdaptor] = set()
28
+ self._defaultChoiceDir: str = ""
29
+ self._aliases: dict[str, str] = {}
30
+ self._multipleItems: set[str] = set()
31
+ self._dummyDirs: set[str] = set()
32
+ self._hiddenItems: set[str] = set()
33
+ self._obsoleteItems: set[str] = set()
34
+ self._optionalItems: set[str] = set()
35
+ self._exclusions: dict[str, set[str]] = {}
36
+ self._inclusions: dict[str, set[str]] = {}
37
+ self._shortCut: schema_primitives.PrimitiveSchema | None = None
38
+ self._father: DirSchema | None = None
39
+ self._decoration: dict[str, object] = {}
40
+
41
+ @staticmethod
42
+ def Create(
43
+ father: DirSchema | None = None,
44
+ name: str | None = None,
45
+ aliasNames: set[str] | tuple[str, ...] | None = None,
46
+ ) -> DirSchema:
47
+ """Create a schema directory and optionally attach it to a parent."""
48
+ if name is None:
49
+ raise AttributeError("DirSchema::Create(...): zero-pointer name.")
50
+ if aliasNames is None:
51
+ aliasNames = set()
52
+ newItem = DirSchema(name, set(aliasNames))
53
+ if father is not None:
54
+ newItem._father = father
55
+ father.AddChoiceDir(newItem, False)
56
+ return newItem
57
+
58
+ def GetName(self) -> str:
59
+ """Return the local schema directory name."""
60
+ return self._name
61
+
62
+ def GetAliasNames(self) -> set[str]:
63
+ """Return alias names accepted for this directory."""
64
+ return self._aliasNames.copy()
65
+
66
+ def GetFullName(self) -> AsciiVector:
67
+ """Return the full schema path as an ASCII vector."""
68
+ path: AsciiVector
69
+ if self._father is None:
70
+ path = TREE_PATH_TEMPLATE.Copy()
71
+ else:
72
+ path = self._father.GetFullName()
73
+ path.PushBack(self.GetName())
74
+ return path
75
+
76
+ def GetPrimitive(
77
+ self, itemName: str, iOverload: int = 0
78
+ ) -> schema_primitives.PrimitiveSchema | None:
79
+ """Return one primitive schema overload by name and index."""
80
+ if (itemName, iOverload) in self._primitives:
81
+ return self._primitives[(itemName, iOverload)]
82
+ else:
83
+ return None
84
+
85
+ def GetPrimitiveOverloads(
86
+ self, itemName: str
87
+ ) -> list[schema_primitives.PrimitiveSchema]:
88
+ """Return all primitive schema overloads registered for a name."""
89
+ overloads: list[schema_primitives.PrimitiveSchema] = []
90
+ while True:
91
+ p = self.GetPrimitive(itemName, len(overloads))
92
+ if p is None:
93
+ break
94
+ overloads.append(p)
95
+ return overloads
96
+
97
+ def GetDir(self, itemName: str) -> DirSchema | None:
98
+ """Return a concrete child directory by name or alias."""
99
+ trueName = self.GetTrueName(itemName)
100
+ if trueName in self._dirs:
101
+ return self._dirs[trueName]
102
+ elif itemName in self._dirs:
103
+ return self._dirs[itemName]
104
+ else:
105
+ return None
106
+
107
+ def GetChoiceDir(self, itemName: str) -> DirSchema | None:
108
+ """Return a choice directory by name or alias."""
109
+ trueName = self.GetTrueName(itemName)
110
+ if itemName in self._choiceDirs:
111
+ return self._choiceDirs[itemName]
112
+ elif trueName in self._choiceDirs:
113
+ return self._choiceDirs[trueName]
114
+ else:
115
+ return None
116
+
117
+ def DefaultChoiceDir(self) -> DirSchema | None:
118
+ """Return the default choice directory, if configured."""
119
+ return self.GetChoiceDir(self._defaultChoiceDir)
120
+
121
+ def GetFather(self) -> DirSchema | None:
122
+ """Return the parent schema directory."""
123
+ return self._father
124
+
125
+ def SetFather(self, father: DirSchema | None) -> None:
126
+ """Set the parent schema directory."""
127
+ self._father = father
128
+
129
+ def GetChoiceDirs(self) -> list[str]:
130
+ """Return the registered choice-directory names."""
131
+ return [x for x in self._choiceDirs]
132
+
133
+ def GetDirs(self) -> dict[str, DirSchema]:
134
+ """Return a copy of the concrete child-directory mapping."""
135
+ return self._dirs.copy()
136
+
137
+ def GetThisAdaptors(self) -> set[SchemaAdaptor]:
138
+ """Return adaptors attached directly to this schema."""
139
+ return self._thisAdaptors
140
+
141
+ def GetPrimitives(self) -> dict[tuple[str, int], schema_primitives.PrimitiveSchema]:
142
+ """Return a copy of the primitive-schema mapping."""
143
+ return self._primitives.copy()
144
+
145
+ def AddPrimitive(
146
+ self, itemName: str, newItem: schema_primitives.PrimitiveSchema
147
+ ) -> None:
148
+ """Append a primitive schema under the next overload slot."""
149
+ # self.__AssureNonExistence(itemName)
150
+ iOverload = 0
151
+ while (itemName, iOverload) in self._primitives:
152
+ iOverload += 1
153
+ self._primitives[(itemName, iOverload)] = newItem
154
+
155
+ def AddDirSchema(self, newItem: DirSchema) -> None:
156
+ """Register a concrete child schema directory."""
157
+ itemName = newItem.GetName()
158
+ # self.__AssureNonExistence(itemName)
159
+ newItem.SetFather(self)
160
+ adaptors = newItem.GetThisAdaptors()
161
+ aliasNames = newItem.GetAliasNames()
162
+ self._dirs[itemName] = newItem
163
+ for ada in adaptors:
164
+ self.AddSchemaAdaptor(ada)
165
+ for alias in aliasNames:
166
+ self.SetAlias(itemName, alias)
167
+
168
+ def AddSchemaAdaptor(self, schemaAdaptor: SchemaAdaptor) -> None:
169
+ """Register an adaptor for one schema directory name."""
170
+ # self.__AssureNonExistence(schemaAdaptor.schema.GetName())
171
+ if schemaAdaptor.schema is None:
172
+ raise ValueError("SchemaAdaptor schema must be set before registration.")
173
+ self._adaptors[schemaAdaptor.schema.GetName()] = schemaAdaptor
174
+
175
+ def AddChoiceDir(self, choiceDir: DirSchema, setDefault: bool = False) -> None:
176
+ """Register a selectable child directory."""
177
+ itemName = choiceDir.GetName()
178
+ # self.__AssureNonExistence(itemName)
179
+ choiceDir.SetFather(self)
180
+ self._choiceDirs[itemName] = choiceDir
181
+ if setDefault:
182
+ self._defaultChoiceDir = itemName
183
+
184
+ def Add(
185
+ self,
186
+ newItem: schema_primitives.PrimitiveSchema | DirSchema | SchemaAdaptor,
187
+ name: str | None = None,
188
+ ) -> None:
189
+ """Add a primitive, child schema, or adaptor."""
190
+ # @todo: untested, may not work
191
+ if isinstance(newItem, schema_primitives.PrimitiveSchema):
192
+ if not isinstance(name, str):
193
+ return None
194
+ self.AddPrimitive(name, newItem)
195
+ return None
196
+ elif isinstance(newItem, DirSchema):
197
+ self.AddDirSchema(newItem)
198
+ return None
199
+ elif isinstance(newItem, SchemaAdaptor):
200
+ self.AddSchemaAdaptor(newItem)
201
+ return None
202
+ else:
203
+ return None
204
+
205
+ def SetDefaultChoiceDir(self, dirName: str) -> None:
206
+ """Set the default choice-directory name."""
207
+ self._defaultChoiceDir = dirName
208
+
209
+ def GetTrueName(self, aliasName: str) -> str:
210
+ """Resolve an alias to its canonical item name."""
211
+ if aliasName in self._aliases:
212
+ return self._aliases[aliasName]
213
+ return aliasName
214
+
215
+ def AddDummyDir(self, dirName: str) -> None:
216
+ """Register a placeholder directory name."""
217
+ self._dummyDirs.add(dirName)
218
+
219
+ def IsDummyDir(self, dirName: str) -> bool:
220
+ """Return whether `dirName` is registered as a dummy directory."""
221
+ return dirName in self._dummyDirs
222
+
223
+ def TagMultiple(self, itemName: str) -> None:
224
+ """Mark an item as supporting multiple occurrences."""
225
+ self._multipleItems.add(itemName)
226
+
227
+ def IsMultiple(self, itemName: str) -> bool:
228
+ """Return whether an item supports multiple occurrences."""
229
+ return itemName in self._multipleItems
230
+
231
+ def TagHidden(self, itemName: str) -> None:
232
+ """Mark an item as hidden."""
233
+ self._hiddenItems.add(itemName)
234
+
235
+ def IsHidden(self, itemName: str) -> bool:
236
+ """Return whether an item is marked hidden."""
237
+ return itemName in self._hiddenItems
238
+
239
+ def TagObsolete(self, itemName: str) -> None:
240
+ """Mark an item as obsolete."""
241
+ self._obsoleteItems.add(itemName)
242
+
243
+ def IsObsolete(self, itemName: str) -> bool:
244
+ """Return whether an item is marked obsolete."""
245
+ return itemName in self._obsoleteItems
246
+
247
+ def TagOptional(self, itemName: str) -> None:
248
+ """Mark an item as optional."""
249
+ self._optionalItems.add(itemName)
250
+
251
+ def IsOptional(self, itemName: str) -> bool:
252
+ """Return whether an item is optional."""
253
+ return itemName in self._optionalItems
254
+
255
+ def SetExclusion(self, itemName: str, excludedItemName: str) -> None:
256
+ """Declare that `itemName` excludes `excludedItemName`."""
257
+ if itemName not in self._exclusions:
258
+ self._exclusions[itemName] = set()
259
+ self._exclusions[itemName].add(excludedItemName)
260
+
261
+ def SetMutualExclusion(self, itemName1: str, itemName2: str) -> None:
262
+ """Declare that two items exclude each other."""
263
+ self.SetExclusion(itemName1, itemName2)
264
+ self.SetExclusion(itemName2, itemName1)
265
+
266
+ def GetExclusions(self, itemName: str) -> set[str]:
267
+ """Return the items excluded by `itemName`."""
268
+ if itemName not in self._exclusions:
269
+ return set()
270
+ return self._exclusions[itemName]
271
+
272
+ def SetInclusion(self, itemName: str, includedItemName: str) -> None:
273
+ """Declare that `itemName` requires `includedItemName`."""
274
+ if itemName not in self._inclusions:
275
+ self._inclusions[itemName] = set()
276
+ self._inclusions[itemName].add(includedItemName)
277
+
278
+ def SetMutualInclusion(self, itemName1: str, itemName2: str) -> None:
279
+ """Declare that two items require each other."""
280
+ self.SetInclusion(itemName1, itemName2)
281
+ self.SetInclusion(itemName2, itemName1)
282
+
283
+ def GetInclusions(self, itemName: str) -> set[str]:
284
+ """Return the items required by `itemName`."""
285
+ if itemName not in self._inclusions:
286
+ return set()
287
+ return self._inclusions[itemName]
288
+
289
+ def SetAlias(self, itemName: str, alias: str) -> None:
290
+ """Register an alias for an existing schema item."""
291
+ trueName = self.GetTrueName(itemName)
292
+ if (
293
+ self.GetDir(trueName) is not None
294
+ or self.GetChoiceDir(trueName) is not None
295
+ or self.GetPrimitive(trueName) is not None
296
+ ):
297
+ self._aliases[alias] = trueName
298
+
299
+ def GetShortCut(self) -> schema_primitives.PrimitiveSchema | None:
300
+ """Return the shortcut primitive for this directory, if any."""
301
+ return self._shortCut
302
+
303
+ def SetShortCut(self, shortCut: schema_primitives.PrimitiveSchema | None) -> None:
304
+ """Set the shortcut primitive for this directory."""
305
+ self._shortCut = shortCut
306
+
307
+ def GetAdaptor(self, itemName: str) -> SchemaAdaptor | None:
308
+ """Return the adaptor registered for `itemName`, if any."""
309
+ if itemName in self._adaptors:
310
+ return self._adaptors[itemName]
311
+ else:
312
+ return None
313
+
314
+ def __AssureNonExistence(self, itemName: str) -> None:
315
+ """Validate that a schema item name is not already registered.
316
+
317
+ Parameters
318
+ ----------
319
+ itemName : None
320
+ Value passed via ``itemName``.
321
+
322
+ Returns
323
+ -------
324
+ None
325
+ No value is returned.
326
+
327
+ Notes
328
+ -----
329
+ Internal API: this helper is an implementation detail and may change
330
+ without notice.
331
+ """
332
+
333
+ trueName = self.GetTrueName(itemName)
334
+ if (
335
+ (trueName, 0) in self._primitives
336
+ or trueName in self._dirs
337
+ or trueName in self._adaptors
338
+ ):
339
+ raise ValueError("Schema::Add(...): Item already exists.")
340
+
341
+ def GetDecoration(self) -> dict[str, object]:
342
+ """Return the decoration metadata mapping."""
343
+ return self._decoration
344
+
345
+
346
+ class SchemaAdaptor:
347
+ """Base adaptor object applied to schema directories."""
348
+
349
+ def __init__(self) -> None:
350
+ """Initialize the adaptor with empty schema bindings."""
351
+
352
+ self.schema: DirSchema | None = None
353
+ self.treeAdaptors: dict[AsciiVector, object] = {}
354
+
355
+
356
+ def PrintPrototypeDirContent(
357
+ fileObj: object,
358
+ dirRoot: DirSchema | None,
359
+ showHiddenEntries: bool = False,
360
+ indentation: int = 0,
361
+ ) -> None:
362
+ """Write one schema subtree to a file-like object."""
363
+ if dirRoot is None:
364
+ return
365
+
366
+
367
+ def GetInputSchema() -> None:
368
+ """Return the optional global input schema placeholder."""
369
+ pass
@@ -0,0 +1,102 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Filesystem primitives used by the data-tree modules."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import os
9
+
10
+ from .toolbox import AsciiVector
11
+
12
+
13
+ class FilePath(AsciiVector):
14
+ """Legacy file-path helper with delimiter-aware import/export behavior."""
15
+
16
+ def __init__(self, data: str = ".", universal: bool = False) -> None:
17
+ """Initialize a path from a string representation."""
18
+
19
+ self._delimiter: str = os.sep
20
+ self._data: list[str] = []
21
+ delimiters: set[str] = {self._delimiter}
22
+ if universal:
23
+ delimiters.add("\\")
24
+ delimiters.add("/")
25
+ self.Import(data, delimiters)
26
+ self._data = [part for part in self._data if len(part) > 0]
27
+ self._is_absolute: bool = (
28
+ len(data) > 0
29
+ and len(data.strip()) > 0
30
+ and data.strip()[0] == self._delimiter
31
+ )
32
+
33
+ def Copy(self) -> FilePath:
34
+ """Return a copy of the path."""
35
+ copy_value: FilePath = FilePath(data=self.Path())
36
+ return copy_value
37
+
38
+ def File(self) -> str:
39
+ """Return the file name component."""
40
+ return self.FileName()
41
+
42
+ def Dir(self) -> str:
43
+ """Return the directory component."""
44
+ return self.DirName()
45
+
46
+ def Path(self) -> str:
47
+ """Return the full path string."""
48
+ return self.Export()
49
+
50
+ def FileName(self) -> str:
51
+ """Return the last path component."""
52
+ return self.At(-1)
53
+
54
+ def DirName(self) -> str:
55
+ """Return the parent directory string."""
56
+ return self.ExportParent() + self._delimiter
57
+
58
+ def BaseName(self) -> str:
59
+ """Return the file name without its first suffix."""
60
+ return self.At(-1).split(".")[0]
61
+
62
+ def CompleteSuffix(self) -> str:
63
+ """Return the complete suffix string after the first dot."""
64
+ return ".".join(self.At(-1).split(".")[1:])
65
+
66
+ def IsAbsolute(self) -> bool:
67
+ """Return whether the path is absolute."""
68
+ return self._is_absolute
69
+
70
+ def SetAbsolute(self) -> None:
71
+ """Mark the path as absolute."""
72
+ self._is_absolute = True
73
+
74
+ def SetRelative(self) -> None:
75
+ """Mark the path as relative."""
76
+ self._is_absolute = False
77
+
78
+ def Export(self) -> str:
79
+ """Return the full path string with absolute prefix when needed."""
80
+ exported: str = self._delimiter.join(self._data)
81
+ if self._is_absolute:
82
+ exported = self._delimiter + exported
83
+ return exported
84
+
85
+ def ExportParent(self) -> str:
86
+ """Return the parent path string with absolute prefix when needed."""
87
+ exported: str = self._delimiter.join(self._data[:-1])
88
+ if self._is_absolute:
89
+ exported = self._delimiter + exported
90
+ return exported
91
+
92
+ def __eq__(self, other: object) -> bool:
93
+ """Return whether two file paths represent the same location shape."""
94
+
95
+ if isinstance(other, FilePath) and self._is_absolute != other._is_absolute:
96
+ return False
97
+ return AsciiVector.__eq__(self, other)
98
+
99
+ def __ne__(self, other: object) -> bool:
100
+ """Return whether two file paths differ."""
101
+
102
+ return not self.__eq__(other)