jcmsuite-data-tree 7.4.2__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.

Potentially problematic release.


This version of jcmsuite-data-tree might be problematic. Click here for more details.

@@ -0,0 +1,91 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Data-tree package exports for `jcmsuite`."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import importlib
9
+ from pathlib import Path
10
+ from types import ModuleType
11
+ from typing import TYPE_CHECKING, Final
12
+
13
+ from .data_branch import TreeDir
14
+ from .data_primitives import TreePrimitive
15
+ from .facade import create_dir_schema, create_tree_dir, serialize_tree_dir
16
+ from .system import FilePath
17
+ from .toolbox import (
18
+ AsciiVector,
19
+ NiL,
20
+ get_derived_nil,
21
+ getDerivedNiL,
22
+ is_nil,
23
+ isNiL,
24
+ typename,
25
+ )
26
+
27
+ if TYPE_CHECKING:
28
+ from . import data_branch as data_branch
29
+ from . import data_primitives as data_primitives
30
+ from . import data_tree_exceptions as data_tree_exceptions
31
+ from . import facade as facade
32
+ from . import parser as parser
33
+ from . import schema_primitives as schema_primitives
34
+ from . import schema_tree as schema_tree
35
+
36
+ _LAZY_SUBMODULES: Final[set[str]] = {
37
+ "data_branch",
38
+ "data_primitives",
39
+ "data_tree_exceptions",
40
+ "facade",
41
+ "parser",
42
+ "schema_primitives",
43
+ "schema_tree",
44
+ }
45
+
46
+
47
+ def package_root() -> Path:
48
+ """Return the filesystem root path of the data-tree package.
49
+
50
+ Returns
51
+ -------
52
+ Path
53
+ Absolute package directory path.
54
+ """
55
+
56
+ return Path(__file__).resolve().parent
57
+
58
+
59
+ def __getattr__(name: str) -> ModuleType:
60
+ """Lazily expose package submodules at the package root."""
61
+
62
+ if name in _LAZY_SUBMODULES:
63
+ module: ModuleType = importlib.import_module(f".{name}", __name__)
64
+ globals()[name] = module
65
+ return module
66
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
67
+
68
+
69
+ __all__: list[str] = [
70
+ "AsciiVector",
71
+ "FilePath",
72
+ "NiL",
73
+ "TreeDir",
74
+ "TreePrimitive",
75
+ "getDerivedNiL",
76
+ "get_derived_nil",
77
+ "isNiL",
78
+ "is_nil",
79
+ "package_root",
80
+ "typename",
81
+ "data_branch",
82
+ "data_primitives",
83
+ "data_tree_exceptions",
84
+ "facade",
85
+ "parser",
86
+ "schema_primitives",
87
+ "schema_tree",
88
+ "create_dir_schema",
89
+ "create_tree_dir",
90
+ "serialize_tree_dir",
91
+ ]
@@ -0,0 +1,4 @@
1
+ """Auto-generated build metadata embedded into release artifacts."""
2
+
3
+ BUILD_GIT_SHA: str = "8cfc72fd116f5f8585725a68c2ca43d9dedbfa9f"
4
+ BUILD_TIMESTAMP: str = "2026-10-22T12:11:53Z"
@@ -0,0 +1,10 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Internal runtime helpers for compatibility data-tree modules."""
5
+
6
+ from .tree_writer import write_tree_dir
7
+
8
+ __all__: list[str] = [
9
+ "write_tree_dir",
10
+ ]
@@ -0,0 +1,53 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Tree writer used by the data-tree modules."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from collections.abc import Mapping
9
+ from typing import cast
10
+
11
+ SINGLE_INDENT: str = " "
12
+
13
+
14
+ def write_tree_dir(tree_dir: object, *, indentation: int = 0) -> str:
15
+ """Serialize a tree directory.
16
+
17
+ Parameters
18
+ ----------
19
+ tree_dir : object
20
+ Tree node implementing ``GetPrimitives`` and ``GetDirs`` methods.
21
+ indentation : int, optional
22
+ Initial indentation level.
23
+
24
+ Returns
25
+ -------
26
+ str
27
+ Serialized tree text.
28
+ """
29
+
30
+ return_string: str = ""
31
+ primitive_data_map: Mapping[tuple[str, int], object] = cast(
32
+ Mapping[tuple[str, int], object],
33
+ tree_dir.GetPrimitives(), # type: ignore[attr-defined]
34
+ )
35
+ prim_iter: tuple[tuple[str, int], object]
36
+ for prim_iter in primitive_data_map.items():
37
+ return_string += "\n" + SINGLE_INDENT * indentation + str(prim_iter[0][0])
38
+ if prim_iter[0][1] > 0:
39
+ return_string += "(" + str(prim_iter[0][1]) + ")"
40
+ return_string += " = " + prim_iter[1].Write() # type: ignore[attr-defined]
41
+
42
+ branch_data_map: Mapping[tuple[str, int], object] = cast(
43
+ Mapping[tuple[str, int], object],
44
+ tree_dir.GetDirs(), # type: ignore[attr-defined]
45
+ )
46
+ branch_iter: tuple[tuple[str, int], object]
47
+ for branch_iter in branch_data_map.items():
48
+ branch_name: str = branch_iter[0][0]
49
+ return_string += "\n" + SINGLE_INDENT * indentation + branch_name + " {"
50
+ return_string += write_tree_dir(branch_iter[1], indentation=indentation + 2)
51
+ return_string += "\n" + SINGLE_INDENT * indentation + "}"
52
+
53
+ return return_string
@@ -0,0 +1,366 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Tree-directory storage and traversal helpers for parsed data trees."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import os
9
+ import weakref
10
+ from collections.abc import Callable
11
+ from typing import Protocol, cast
12
+
13
+ # import jcmwave.data_tree.data_primitives as data_primitives
14
+ from . import data_primitives, schema_tree
15
+ from .decorators import accepts
16
+ from .system import FilePath
17
+ from .toolbox import AsciiVector
18
+
19
+ TREE_PATH_TEMPLATE = AsciiVector(delimiter=":")
20
+
21
+
22
+ class FilePrimitiveLike(Protocol):
23
+ """Minimal file-primitive protocol used for path expansion."""
24
+
25
+ def GetValue(self) -> FilePath: ...
26
+
27
+
28
+ class TreeDir:
29
+ """Store tree directories, child directories, and primitive values."""
30
+
31
+ def __init__(
32
+ self,
33
+ dirName: str = "",
34
+ father: TreeDir | None = None,
35
+ branchDir: TreeDir | None = None,
36
+ ) -> None:
37
+ """Create a tree directory, optionally copying from a branch template."""
38
+
39
+ if branchDir is not None:
40
+ self.dirs: dict[tuple[str, int], TreeDir] = branchDir.dirs.copy()
41
+ self.primitives: dict[tuple[str, int], data_primitives.TreePrimitive] = {}
42
+ for vIter in branchDir.primitives.items():
43
+ self.primitives[vIter[0]] = vIter[1].Copy()
44
+ self.name: str = branchDir.GetName()
45
+ self.trunkDir: str = branchDir.trunkDir
46
+ self.sourceDir: FilePath = branchDir.sourceDir.Copy()
47
+ self.dummyDirs: list[str] = [x for x in branchDir.dummyDirs]
48
+ else:
49
+ self.dirs = {}
50
+ self.primitives = {}
51
+ self.name = dirName
52
+ self.trunkDir = ""
53
+ self.sourceDir = FilePath()
54
+ self.dummyDirs = [] # stack of strings
55
+ self.father: Callable[[], TreeDir | None]
56
+ if father is None:
57
+ self.father = lambda: None
58
+ else:
59
+ self.father = weakref.ref(father)
60
+ parent = self.father()
61
+ if parent is not None:
62
+ parent.AddTreeDir(self)
63
+ self.alias = ""
64
+
65
+ @staticmethod
66
+ def Create(
67
+ dirName: str = "",
68
+ father: TreeDir | None = None,
69
+ branchDir: TreeDir | None = None,
70
+ ) -> TreeDir:
71
+ """Create a new tree directory instance."""
72
+ return TreeDir(dirName, father, branchDir)
73
+
74
+ def Copy(self) -> TreeDir:
75
+ """Return a shallow structural copy of the directory tree node."""
76
+ cp = TreeDir()
77
+ cp.dirs = self.dirs.copy()
78
+ cp.primitives = {}
79
+ for vIter in self.primitives.items():
80
+ cp.primitives[vIter[0]] = vIter[1].Copy()
81
+ cp.name = self.name
82
+ cp.trunkDir = self.trunkDir
83
+ cp.sourceDir = self.sourceDir.Copy()
84
+ cp.alias = self.alias
85
+ cp.dummyDirs = [x for x in self.dummyDirs]
86
+ return cp
87
+
88
+ def GetName(self) -> str:
89
+ """Return the local directory name."""
90
+ return self.name
91
+
92
+ def GetFullName(self) -> str:
93
+ """Return the full colon-delimited path of this directory."""
94
+ path = TREE_PATH_TEMPLATE.Copy()
95
+ parent = self.GetFather()
96
+ if parent is not None:
97
+ path.PushBack(parent.GetFullName())
98
+ path.PushBack(self.GetName())
99
+ return path.Export()
100
+
101
+ def SetAlias(self, alias: str = "") -> None:
102
+ """Store an alternate display alias for this directory."""
103
+ self.alias = str(alias)
104
+
105
+ def Alias(self) -> str:
106
+ """Return the configured directory alias."""
107
+ return self.alias
108
+
109
+ def Get(
110
+ self, itemname: str = "", multipleindex: int = 0
111
+ ) -> data_primitives.TreePrimitive | None:
112
+ """Return a primitive by name and overload index."""
113
+ return self.GetPrimitive(itemname, multipleindex)
114
+
115
+ def TryGet(
116
+ self, fallback: object | None = None, itemname: str = "", multipleindex: int = 0
117
+ ) -> data_primitives.TreePrimitive | object | None:
118
+ """Return a primitive when present, otherwise the fallback value."""
119
+ if self.GetPrimitive(itemname, multipleindex) is None:
120
+ return fallback
121
+ else:
122
+ return self.GetPrimitive(itemname, multipleindex)
123
+
124
+ def GetPrimitive(
125
+ self, itemname: str, multipleindex: int = 0
126
+ ) -> data_primitives.TreePrimitive | None:
127
+ """Return one primitive entry by name and overload index."""
128
+ key = (itemname, multipleindex)
129
+ if key in self.primitives:
130
+ return self.primitives[key]
131
+ else:
132
+ return None
133
+
134
+ def GetPrimitives(self) -> dict[tuple[str, int], data_primitives.TreePrimitive]:
135
+ """Return a copy of the primitive mapping."""
136
+ return self.primitives.copy()
137
+
138
+ def GetDir(self, itemname: str, multipleindex: int = 0) -> TreeDir | None:
139
+ """Return one child directory by name and overload index."""
140
+ key = (itemname, multipleindex)
141
+ if key in self.dirs:
142
+ return self.dirs[key]
143
+ else:
144
+ return None
145
+
146
+ def GetDirs(self) -> dict[tuple[str, int], TreeDir]:
147
+ """Return a copy of the child-directory mapping."""
148
+ return self.dirs.copy()
149
+
150
+ def AddPrimitive(
151
+ self,
152
+ itemname: str = "",
153
+ newitem: data_primitives.TreePrimitive | None = None,
154
+ ) -> data_primitives.TreePrimitive | None:
155
+ """Append a primitive under the next available overload slot."""
156
+ if newitem is None:
157
+ return None
158
+ multipleindex = 0
159
+ key = (itemname, multipleindex)
160
+ while key in self.primitives:
161
+ multipleindex += 1
162
+ key = (itemname, multipleindex)
163
+ self.primitives[key] = newitem
164
+ return newitem
165
+
166
+ def SetPrimitive(
167
+ self,
168
+ itemname: str = "",
169
+ newitem: data_primitives.TreePrimitive | None = None,
170
+ multipleindex: int = 0,
171
+ ) -> data_primitives.TreePrimitive | None:
172
+ """Store a primitive at an explicit overload slot."""
173
+ if newitem is None:
174
+ return None
175
+ key = (itemname, multipleindex)
176
+ self.primitives[key] = newitem
177
+ return newitem
178
+
179
+ def AddTreeDir(self, newItem: TreeDir | None = None) -> TreeDir | None:
180
+ """Append a child directory under the next available overload slot."""
181
+ if newItem is None:
182
+ return None
183
+ itemname = newItem.GetName()
184
+ multipleindex = 0
185
+ key = (itemname, multipleindex)
186
+ while key in self.dirs:
187
+ multipleindex += 1
188
+ key = (itemname, multipleindex)
189
+ newItem.father = weakref.ref(self)
190
+ self.dirs[key] = newItem
191
+ return newItem
192
+
193
+ def Add(
194
+ self,
195
+ itemname: str | None = None,
196
+ item: data_primitives.TreePrimitive | TreeDir | None = None,
197
+ ) -> data_primitives.TreePrimitive | TreeDir | None:
198
+ """Add either a primitive or a child directory."""
199
+ # @TODO: check (this does not seem to work correctly)
200
+ if isinstance(item, data_primitives.TreePrimitive):
201
+ if not isinstance(itemname, str):
202
+ return None
203
+ return self.AddPrimitive(itemname, item)
204
+ elif isinstance(item, TreeDir):
205
+ return self.AddTreeDir(item)
206
+ else:
207
+ return None
208
+
209
+ def ReleaseDir(self, itemname: str = "", multipleindex: int = 0) -> TreeDir | None:
210
+ """Remove and return a child directory if present."""
211
+ key = (itemname, multipleindex)
212
+ return self.dirs.pop(key, None)
213
+
214
+ def ReleasePrimitive(
215
+ self, itemname: str = "", multipleindex: int = 0
216
+ ) -> data_primitives.TreePrimitive | None:
217
+ """Remove and return a primitive if present."""
218
+ key = (itemname, multipleindex)
219
+ return self.primitives.pop(key, None)
220
+
221
+ def GetFather(self) -> TreeDir | None:
222
+ """Return the parent directory, if any."""
223
+ return self.father()
224
+
225
+ def GetTrunkDir(self) -> TreeDir | None:
226
+ """Return the selected trunk child directory."""
227
+ return self.GetDir(self.trunkDir)
228
+
229
+ def SetTrunkDir(self, trunkDir: str = "") -> None:
230
+ """Select the named child directory as trunk directory."""
231
+ self.trunkDir = trunkDir
232
+
233
+ def FinalDir(self) -> TreeDir:
234
+ """Follow trunk-directory links until the final directory is reached."""
235
+ d = self
236
+ trunk_dir = d.GetTrunkDir()
237
+ while trunk_dir is not None:
238
+ d = trunk_dir
239
+ trunk_dir = d.GetTrunkDir()
240
+ return d
241
+
242
+ @accepts(object, FilePath, sourceFile=FilePath)
243
+ def SetSourceFile(self, sourceFile: FilePath) -> None:
244
+ """Record the source file associated with this directory."""
245
+ self.sourceDir = sourceFile
246
+
247
+ def GetSourceFile(self) -> FilePath:
248
+ """Return the source file associated with this directory."""
249
+ return self.sourceDir
250
+
251
+ @accepts(object, (str), dummyDir=(str))
252
+ def AddDummyDir(self, dummyDir: str) -> str:
253
+ """Register a placeholder child-directory name."""
254
+ if dummyDir not in self.dummyDirs:
255
+ self.dummyDirs.append(dummyDir)
256
+ return dummyDir
257
+
258
+ def DummyDirs(self) -> list[str]:
259
+ """Return the registered placeholder child-directory names."""
260
+ return [x for x in self.dummyDirs]
261
+
262
+ @staticmethod
263
+ def __ExpandFilePaths(treeDir: TreeDir, sourceDirPath: FilePath) -> None:
264
+ """Resolve file primitives in-place to absolute paths below the source directory.
265
+
266
+ Parameters
267
+ ----------
268
+ treeDir : None
269
+ Filesystem path supplied via `treeDir`.
270
+ sourceDirPath : None
271
+ Filesystem path supplied via `sourceDirPath`.
272
+
273
+ Returns
274
+ -------
275
+ None
276
+ No value is returned.
277
+
278
+ Notes
279
+ -----
280
+ Internal API: this helper is an implementation detail and may change
281
+ without notice.
282
+ """
283
+
284
+ sourceDirPathString = os.path.normpath(sourceDirPath.Export()) + os.sep
285
+ for primitive in treeDir.primitives.values():
286
+ if isinstance(primitive, data_primitives.FilePrimitive):
287
+ file_primitive = cast(FilePrimitiveLike, primitive)
288
+ relPath = file_primitive.GetValue()
289
+ relPathString = os.path.normpath(relPath.Export())
290
+ absPathString = os.path.abspath(sourceDirPathString + relPathString)
291
+ relPath.Import(absPathString)
292
+ for td in list(treeDir.dirs.values()):
293
+ TreeDir.__ExpandFilePaths(td, sourceDirPath)
294
+
295
+
296
+ class TreeAdaptor:
297
+ """Base adaptor interface for transforming tree directories."""
298
+
299
+ def __init__(self) -> None:
300
+ """Initialize the adaptor."""
301
+
302
+ pass
303
+
304
+ def Transform(self, treeDir: TreeDir) -> TreeDir:
305
+ """Transform a tree directory in adaptor-specific ways."""
306
+ raise Exception("Missing implementation.")
307
+
308
+
309
+ def Copy(
310
+ sourceTreeDir: TreeDir,
311
+ itemString: str,
312
+ targetTreeDir: TreeDir,
313
+ itemString_: str = "",
314
+ ) -> None:
315
+ """Copy one named primitive or directory from source to target."""
316
+ if len(itemString_) == 0:
317
+ itemString_ = itemString
318
+ source_primitive = sourceTreeDir.GetPrimitive(itemString)
319
+ if source_primitive is not None:
320
+ targetTreeDir.AddPrimitive(itemString_, source_primitive.Copy())
321
+ source_dir = sourceTreeDir.GetDir(itemString)
322
+ if source_dir is not None:
323
+ copied_dir = source_dir.Copy()
324
+ if itemString_ != itemString:
325
+ copied_dir.name = itemString_
326
+ targetTreeDir.AddTreeDir(copied_dir)
327
+ if sourceTreeDir.GetTrunkDir() == source_dir:
328
+ targetTreeDir.SetTrunkDir(itemString_)
329
+
330
+
331
+ def CD(currentTreeDir: TreeDir | None, itemString: str) -> tuple[TreeDir | None, bool]:
332
+ """Navigate to a child or parent directory and report success."""
333
+ if currentTreeDir is None:
334
+ dir_ = None
335
+ elif itemString == ".":
336
+ dir_ = currentTreeDir
337
+ elif itemString == "..":
338
+ dir_ = currentTreeDir.GetFather()
339
+ else:
340
+ dir_ = currentTreeDir.GetDir(itemString)
341
+ if dir_ is None:
342
+ success = False
343
+ else:
344
+ success = True
345
+ return dir_, success
346
+
347
+
348
+ def MKDir(currentTreeDir: TreeDir | None, itemString: str) -> TreeDir | None:
349
+ """Create a child directory below the current directory."""
350
+ if currentTreeDir is None:
351
+ return None
352
+ else:
353
+ return TreeDir.Create(father=currentTreeDir, dirName=itemString)
354
+
355
+
356
+ def GetFinalDir(
357
+ currentTreeDir: TreeDir,
358
+ prototypeDirSchema: schema_tree.DirSchema | None,
359
+ ) -> schema_tree.DirSchema | None:
360
+ """Follow trunk-directory links and matching schema choices to the end."""
361
+ trunk_dir = currentTreeDir.GetTrunkDir()
362
+ while prototypeDirSchema is not None and trunk_dir is not None:
363
+ currentTreeDir = trunk_dir
364
+ prototypeDirSchema = prototypeDirSchema.GetChoiceDir(currentTreeDir.GetName())
365
+ trunk_dir = currentTreeDir.GetTrunkDir()
366
+ return prototypeDirSchema