jcmsuite-data-tree 7.4.2__tar.gz

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,61 @@
1
+ Metadata-Version: 2.4
2
+ Name: jcmsuite-data-tree
3
+ Version: 7.4.2
4
+ Summary: Compatibility and facade data-tree package for JCMsuite tooling.
5
+ License-Expression: MIT
6
+ Author: Matthias Plock
7
+ Author-email: matthias.plock@jcmwave.com
8
+ Requires-Python: >=3.13
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: Programming Language :: Python :: 3.13
12
+ Classifier: Programming Language :: Python :: 3.14
13
+ Project-URL: Documentation, https://docs.jcmwave.com/JCMsuite/html/
14
+ Project-URL: Homepage, https://www.jcmwave.com
15
+ Description-Content-Type: text/markdown
16
+
17
+ # jcmsuite-data-tree
18
+
19
+ Standalone data-tree and serialization helpers for JCMsuite tooling.
20
+
21
+ Use this package to work directly with tree structures, schemas, and serialized
22
+ data. It is a low-level support library, not the JCMsuite solver interface, and
23
+ it does not provide xarray DataTree result exports.
24
+
25
+ ## What It Provides
26
+
27
+ - `TreeDir` and `TreePrimitive` data-tree building blocks,
28
+ - facade helpers such as `create_tree_dir(...)` and `serialize_tree_dir(...)`,
29
+ - compatibility helpers used by tooling and protocol layers.
30
+
31
+ Python imports use `jcmsuite_data_tree`, for example:
32
+
33
+ ```python
34
+ from jcmsuite_data_tree import TreeDir, create_tree_dir, serialize_tree_dir
35
+ ```
36
+
37
+ ## Install
38
+
39
+ Requires Python 3.13 or later. The standalone tree helpers do not require a
40
+ JCMsuite solver installation.
41
+
42
+ ```bash
43
+ python -m pip install jcmsuite-data-tree
44
+ ```
45
+
46
+ ## Relationship To `jcmsuite`
47
+
48
+ Use this package when you need the low-level data-tree model or serialization
49
+ helpers directly. For solver, daemon, and result workflows, install the main
50
+ `jcmsuite` package instead.
51
+
52
+ ## Documentation and Support
53
+
54
+ See the [JCMsuite documentation](https://docs.jcmwave.com/JCMsuite/html/) for the
55
+ JCMsuite manuals and tutorials. For product and support information, visit
56
+ [JCMwave](https://www.jcmwave.com).
57
+
58
+ ## License
59
+
60
+ This Python package is licensed under the MIT License.
61
+
@@ -0,0 +1,44 @@
1
+ # jcmsuite-data-tree
2
+
3
+ Standalone data-tree and serialization helpers for JCMsuite tooling.
4
+
5
+ Use this package to work directly with tree structures, schemas, and serialized
6
+ data. It is a low-level support library, not the JCMsuite solver interface, and
7
+ it does not provide xarray DataTree result exports.
8
+
9
+ ## What It Provides
10
+
11
+ - `TreeDir` and `TreePrimitive` data-tree building blocks,
12
+ - facade helpers such as `create_tree_dir(...)` and `serialize_tree_dir(...)`,
13
+ - compatibility helpers used by tooling and protocol layers.
14
+
15
+ Python imports use `jcmsuite_data_tree`, for example:
16
+
17
+ ```python
18
+ from jcmsuite_data_tree import TreeDir, create_tree_dir, serialize_tree_dir
19
+ ```
20
+
21
+ ## Install
22
+
23
+ Requires Python 3.13 or later. The standalone tree helpers do not require a
24
+ JCMsuite solver installation.
25
+
26
+ ```bash
27
+ python -m pip install jcmsuite-data-tree
28
+ ```
29
+
30
+ ## Relationship To `jcmsuite`
31
+
32
+ Use this package when you need the low-level data-tree model or serialization
33
+ helpers directly. For solver, daemon, and result workflows, install the main
34
+ `jcmsuite` package instead.
35
+
36
+ ## Documentation and Support
37
+
38
+ See the [JCMsuite documentation](https://docs.jcmwave.com/JCMsuite/html/) for the
39
+ JCMsuite manuals and tutorials. For product and support information, visit
40
+ [JCMwave](https://www.jcmwave.com).
41
+
42
+ ## License
43
+
44
+ This Python package is licensed under the MIT License.
@@ -0,0 +1,30 @@
1
+ [project]
2
+ name = "jcmsuite-data-tree"
3
+ version = "7.4.2"
4
+ readme = "README.md"
5
+ license = "MIT"
6
+ description = "Compatibility and facade data-tree package for JCMsuite tooling."
7
+ authors = [
8
+ { name = "Matthias Plock", email = "matthias.plock@jcmwave.com" },
9
+ { name = "Lin Zschiedrich", email = "lin.zschiedrich@jcmwave.com" },
10
+ { name = "Martin Hammerschmidt", email = "martin.hammerschmidt@jcmwave.com" },
11
+ { name = "Philipp-Immanuel Schneider", email = "philipp-immanuel.schneider@jcmwave.com" },
12
+ ]
13
+ classifiers = [
14
+ "Development Status :: 4 - Beta",
15
+ "Intended Audience :: Science/Research",
16
+ "Programming Language :: Python :: 3.13",
17
+ "Programming Language :: Python :: 3.14",
18
+ ]
19
+ requires-python = ">=3.13"
20
+
21
+ [project.urls]
22
+ Homepage = "https://www.jcmwave.com"
23
+ Documentation = "https://docs.jcmwave.com/JCMsuite/html/"
24
+
25
+ [tool.poetry]
26
+ packages = [{ include = "jcmsuite_data_tree", from = "src" }]
27
+
28
+ [build-system]
29
+ requires = ["poetry-core"]
30
+ build-backend = "poetry.core.masonry.api"
@@ -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