jcmsuite 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 might be problematic. Click here for more details.

Files changed (119) hide show
  1. jcmsuite/__init__.py +22 -0
  2. jcmsuite/_build_info.py +4 -0
  3. jcmsuite/context/__init__.py +44 -0
  4. jcmsuite/context/interface_metadata.py +158 -0
  5. jcmsuite/context/models.py +213 -0
  6. jcmsuite/context/scope.py +210 -0
  7. jcmsuite/context/solver_context.py +569 -0
  8. jcmsuite/context/subprocess_tools.py +172 -0
  9. jcmsuite/contract.py +47 -0
  10. jcmsuite/daemon/__init__.py +19 -0
  11. jcmsuite/daemon/handler.py +925 -0
  12. jcmsuite/daemon/internal/__init__.py +4 -0
  13. jcmsuite/daemon/internal/bundle_protocol.py +64 -0
  14. jcmsuite/daemon/internal/handler_helpers.py +368 -0
  15. jcmsuite/daemon/internal/handler_resource_jobs.py +227 -0
  16. jcmsuite/daemon/internal/handler_wait.py +564 -0
  17. jcmsuite/daemon/models.py +349 -0
  18. jcmsuite/daemon/namespaces.py +250 -0
  19. jcmsuite/daemon/protocol.py +801 -0
  20. jcmsuite/daemon/resources.py +407 -0
  21. jcmsuite/daemon/scope.py +53 -0
  22. jcmsuite/daemon/transport.py +223 -0
  23. jcmsuite/editing/__init__.py +10 -0
  24. jcmsuite/editing/editor.py +274 -0
  25. jcmsuite/exceptions/__init__.py +32 -0
  26. jcmsuite/exceptions/errors.py +173 -0
  27. jcmsuite/geo/__init__.py +10 -0
  28. jcmsuite/geo/mesh.py +302 -0
  29. jcmsuite/info/__init__.py +10 -0
  30. jcmsuite/info/runtime_info.py +45 -0
  31. jcmsuite/internal/__init__.py +2 -0
  32. jcmsuite/internal/diagnostics.py +74 -0
  33. jcmsuite/internal/progress.py +80 -0
  34. jcmsuite/loaders/__init__.py +18 -0
  35. jcmsuite/loaders/blob_header.py +315 -0
  36. jcmsuite/loaders/cartesian_field_reader.py +249 -0
  37. jcmsuite/loaders/cartesian_fields.py +324 -0
  38. jcmsuite/loaders/nested_mapping.py +69 -0
  39. jcmsuite/loaders/powerflux.py +136 -0
  40. jcmsuite/loaders/table.py +637 -0
  41. jcmsuite/logging/__init__.py +22 -0
  42. jcmsuite/logging/runtime.py +210 -0
  43. jcmsuite/results/__init__.py +126 -0
  44. jcmsuite/results/artifacts.py +806 -0
  45. jcmsuite/results/discovery.py +82 -0
  46. jcmsuite/results/field_exports.py +1062 -0
  47. jcmsuite/results/field_payloads.py +453 -0
  48. jcmsuite/results/internal/__init__.py +4 -0
  49. jcmsuite/results/internal/export/__init__.py +4 -0
  50. jcmsuite/results/internal/export/common.py +56 -0
  51. jcmsuite/results/internal/export/pandas/__init__.py +4 -0
  52. jcmsuite/results/internal/export/pandas/common.py +165 -0
  53. jcmsuite/results/internal/export/pandas/payload.py +480 -0
  54. jcmsuite/results/internal/export/pandas/rows.py +484 -0
  55. jcmsuite/results/internal/export/preview.py +178 -0
  56. jcmsuite/results/internal/export/xarray/__init__.py +4 -0
  57. jcmsuite/results/internal/export/xarray/export.py +688 -0
  58. jcmsuite/results/internal/export/xarray/grouped.py +608 -0
  59. jcmsuite/results/internal/export/xarray/headers.py +290 -0
  60. jcmsuite/results/internal/export/xarray/runtime.py +99 -0
  61. jcmsuite/results/internal/export/xarray/shared.py +246 -0
  62. jcmsuite/results/internal/export/xarray/tabular.py +304 -0
  63. jcmsuite/results/internal/export/xarray/types.py +28 -0
  64. jcmsuite/results/internal/models/__init__.py +4 -0
  65. jcmsuite/results/internal/models/batch.py +1081 -0
  66. jcmsuite/results/internal/models/batch_postprocess.py +1728 -0
  67. jcmsuite/results/internal/models/bundle.py +343 -0
  68. jcmsuite/results/internal/models/core.py +556 -0
  69. jcmsuite/results/internal/models/submission.py +1157 -0
  70. jcmsuite/results/internal/resultbag/__init__.py +4 -0
  71. jcmsuite/results/internal/resultbag/access.py +489 -0
  72. jcmsuite/results/internal/resultbag/iteration.py +199 -0
  73. jcmsuite/results/internal/resultbag/query.py +226 -0
  74. jcmsuite/results/internal/resultbag/raw.py +407 -0
  75. jcmsuite/results/internal/resultbag/source_files.py +142 -0
  76. jcmsuite/results/internal/resultbag/store.py +881 -0
  77. jcmsuite/results/internal/resultbag/utils.py +258 -0
  78. jcmsuite/results/models.py +76 -0
  79. jcmsuite/results/opening.py +55 -0
  80. jcmsuite/results/pandas_export.py +325 -0
  81. jcmsuite/results/payloads.py +478 -0
  82. jcmsuite/results/postprocess.py +97 -0
  83. jcmsuite/results/postprocess_payloads.py +757 -0
  84. jcmsuite/results/postprocess_record.py +418 -0
  85. jcmsuite/results/resultbag.py +279 -0
  86. jcmsuite/results/resultbag_management.py +433 -0
  87. jcmsuite/results/structured_derivatives.py +387 -0
  88. jcmsuite/solve/__init__.py +10 -0
  89. jcmsuite/solve/daemon_bundle_staging.py +100 -0
  90. jcmsuite/solve/daemon_bundle_wait.py +89 -0
  91. jcmsuite/solve/orchestration.py +1576 -0
  92. jcmsuite/solve/orchestration_execution.py +180 -0
  93. jcmsuite/solve/orchestration_routing.py +128 -0
  94. jcmsuite/solve/orchestration_support.py +323 -0
  95. jcmsuite/solve/path_resolution.py +98 -0
  96. jcmsuite/solve/progress.py +20 -0
  97. jcmsuite/solve/solver.py +709 -0
  98. jcmsuite/solve/staging.py +264 -0
  99. jcmsuite/solve/types.py +25 -0
  100. jcmsuite/solve/working_dirs.py +227 -0
  101. jcmsuite/templates/__init__.py +11 -0
  102. jcmsuite/templates/converter.py +71 -0
  103. jcmsuite/templates/formatting.py +335 -0
  104. jcmsuite/templates/formatting_cli.py +47 -0
  105. jcmsuite/templates/rendering.py +666 -0
  106. jcmsuite/torch/__init__.py +25 -0
  107. jcmsuite/torch/autograd.py +488 -0
  108. jcmsuite/torch/coordinate_policy.py +82 -0
  109. jcmsuite/torch/core.py +312 -0
  110. jcmsuite/torch/results/__init__.py +51 -0
  111. jcmsuite/torch/types.py +84 -0
  112. jcmsuite/torch/validation.py +208 -0
  113. jcmsuite/torch/wrappers.py +4332 -0
  114. jcmsuite/view/__init__.py +10 -0
  115. jcmsuite/view/viewer.py +122 -0
  116. jcmsuite-7.4.2.dist-info/METADATA +180 -0
  117. jcmsuite-7.4.2.dist-info/RECORD +119 -0
  118. jcmsuite-7.4.2.dist-info/WHEEL +4 -0
  119. jcmsuite-7.4.2.dist-info/entry_points.txt +3 -0
@@ -0,0 +1,4 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Internal Resultbag storage and query helpers."""
@@ -0,0 +1,489 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Typed read access and promotion for persistent Resultbags."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import json
9
+ import pickle
10
+ import sqlite3
11
+ from collections.abc import Iterator, Mapping, Sequence
12
+ from dataclasses import dataclass
13
+ from typing import Protocol, cast
14
+
15
+ from ....exceptions import InvalidConfigurationError
16
+ from .utils import (
17
+ _decanonicalize_key_value,
18
+ _FilterSpec,
19
+ )
20
+
21
+
22
+ @dataclass(frozen=True, slots=True)
23
+ class ResultbagEntry:
24
+ """Normalized stored entry used by the public read boundary."""
25
+
26
+ keys: dict[str, object]
27
+ suffix_pattern: str | None
28
+ result: object | None
29
+ log: object | None
30
+ legacy: bool = False
31
+
32
+
33
+ class ResultbagKeys(tuple[dict[str, object], ...]):
34
+ """Immutable collection of project keys."""
35
+
36
+
37
+ class _ResultbagAccessOwner(Protocol):
38
+ _connection: sqlite3.Connection
39
+
40
+
41
+ def _split_storage_keys(keys_json: str) -> tuple[dict[str, object], str | None]:
42
+ """Decode stored keys and remove the historical cache discriminator."""
43
+
44
+ raw_keys: object = json.loads(keys_json)
45
+ if not isinstance(raw_keys, dict):
46
+ raise InvalidConfigurationError("Stored Resultbag keys are not a mapping.")
47
+ decoded: object = _decanonicalize_key_value(raw_keys)
48
+ if not isinstance(decoded, dict):
49
+ raise InvalidConfigurationError("Stored Resultbag keys are not a mapping.")
50
+ storage_keys: dict[str, object] = {
51
+ str(key): value for key, value in decoded.items()
52
+ }
53
+ suffix_value: object = storage_keys.pop("__suffix_pattern__", None)
54
+ suffix_pattern: str | None = None if suffix_value is None else str(suffix_value)
55
+ return storage_keys, suffix_pattern
56
+
57
+
58
+ def iter_storage_entries(owner: _ResultbagAccessOwner) -> Iterator[ResultbagEntry]:
59
+ """Read all stored result entries without relying on SQLite insertion order."""
60
+
61
+ stored_entries: list[ResultbagEntry] = []
62
+ cursor: sqlite3.Cursor = owner._connection.cursor()
63
+ cursor.execute(
64
+ "SELECT keys_json, result_blob, log_blob, payload_format FROM entries"
65
+ )
66
+ row: tuple[str, bytes, bytes, int]
67
+ for row in cursor.fetchall():
68
+ keys, suffix_pattern = _split_storage_keys(row[0])
69
+ stored_entries.append(
70
+ ResultbagEntry(
71
+ keys=keys,
72
+ suffix_pattern=suffix_pattern,
73
+ result=None if row[3] != 1 else pickle.loads(row[1]),
74
+ log=pickle.loads(row[2]),
75
+ legacy=row[3] != 1,
76
+ )
77
+ )
78
+ for entry in stored_entries:
79
+ yield entry
80
+
81
+ stored_ids: set[tuple[str, str | None]] = {
82
+ (json.dumps(entry.keys, sort_keys=True, default=str), entry.suffix_pattern)
83
+ for entry in stored_entries
84
+ }
85
+ cursor.execute(
86
+ "SELECT keys_json, attempt_index, payload_blob FROM attempt_logs "
87
+ "ORDER BY attempt_index ASC"
88
+ )
89
+ final_attempts: dict[
90
+ tuple[str, str | None], tuple[dict[str, object], str | None, object]
91
+ ] = {}
92
+ attempt_row: tuple[str, int, bytes]
93
+ for attempt_row in cursor.fetchall():
94
+ keys, suffix_pattern = _split_storage_keys(attempt_row[0])
95
+ identity = (json.dumps(keys, sort_keys=True, default=str), suffix_pattern)
96
+ final_attempts[identity] = (keys, suffix_pattern, pickle.loads(attempt_row[2]))
97
+ for identity, (keys, suffix_pattern, payload) in final_attempts.items():
98
+ if identity not in stored_ids:
99
+ yield ResultbagEntry(
100
+ keys=keys,
101
+ suffix_pattern=suffix_pattern,
102
+ result=None,
103
+ log=payload,
104
+ )
105
+
106
+
107
+ class ResultbagReadable(Protocol):
108
+ """Shared public read operations for Resultbag and its views."""
109
+
110
+ def _access_entries(self) -> Iterator[ResultbagEntry]: ...
111
+
112
+ def filter(
113
+ self,
114
+ key: str | None = None,
115
+ filter_value: object | None = None,
116
+ /,
117
+ **criteria: object,
118
+ ) -> ResultbagView: ...
119
+
120
+
121
+ class ResultbagView:
122
+ """Provide read-only access to selected Resultbag entries.
123
+
124
+ The Resultbag loads each entry only when an operation needs the entry.
125
+ Obtain a view from `Resultbag.filter(...)`; do not construct this class
126
+ directly.
127
+ """
128
+
129
+ def __init__(self, source: ResultbagReadable, specs: Sequence[_FilterSpec]) -> None:
130
+ self._source: ResultbagReadable = source
131
+ self._specs: tuple[_FilterSpec, ...] = tuple(specs)
132
+
133
+ def _access_entries(self) -> Iterator[ResultbagEntry]:
134
+ entry: ResultbagEntry
135
+ for entry in self._source._access_entries():
136
+ if all(spec.matches(entry.keys) for spec in self._specs):
137
+ yield entry
138
+
139
+ @property
140
+ def keys(self) -> ResultbagKeys:
141
+ """Return the project keys for the selected Resultbag entries.
142
+
143
+ Returns
144
+ -------
145
+ ResultbagKeys
146
+ project keys in a stable order. The collection cannot be changed.
147
+ """
148
+
149
+ unique: dict[str, dict[str, object]] = {}
150
+ for entry in self._access_entries():
151
+ identity: str = json.dumps(entry.keys, sort_keys=True, default=str)
152
+ unique[identity] = dict(entry.keys)
153
+ return ResultbagKeys(unique[key] for key in unique)
154
+
155
+ @property
156
+ def suffixes(self) -> tuple[str | None, ...]:
157
+ """Return the suffix patterns for the selected Resultbag entries.
158
+
159
+ The result is in a stable order. `None` identifies entries that have no
160
+ suffix pattern.
161
+
162
+ Returns
163
+ -------
164
+ tuple[str | None, ...]
165
+ Available suffix patterns.
166
+ """
167
+
168
+ values: set[str | None] = {
169
+ entry.suffix_pattern for entry in self._access_entries()
170
+ }
171
+ return tuple(sorted(values, key=lambda value: (value is not None, value or "")))
172
+
173
+ def filter(
174
+ self,
175
+ key: str | None = None,
176
+ filter_value: object | None = None,
177
+ /,
178
+ **criteria: object,
179
+ ) -> ResultbagView:
180
+ """Narrow the selection by adding project key filters.
181
+
182
+ Parameters
183
+ ----------
184
+ key : str | None, optional
185
+ project key name for a positional filter.
186
+ filter_value : object | None, optional
187
+ Value for a positional filter. Use a plain value for an exact
188
+ match. Use `between(lower, upper)` to include both limits.
189
+ **criteria : object
190
+ project key filters. An entry must match all filters.
191
+
192
+ Returns
193
+ -------
194
+ ResultbagView
195
+ Read-only access to entries that match all old and new filters.
196
+
197
+ Raises
198
+ ------
199
+ InvalidConfigurationError
200
+ If no filter is supplied, a positional filter is incomplete, a
201
+ project key name is empty or duplicated, or bounds cannot be
202
+ compared with a stored value.
203
+ """
204
+
205
+ from .utils import _build_filter_specs
206
+
207
+ specs: tuple[_FilterSpec, ...] = _build_filter_specs(
208
+ key, filter_value, criteria
209
+ )
210
+ return ResultbagView(self, specs)
211
+
212
+ def get_results(
213
+ self,
214
+ keys: Mapping[str, object] | Sequence[Mapping[str, object]] | None = None,
215
+ *,
216
+ suffix_pattern: str | None = None,
217
+ ) -> object:
218
+ """Load the selected Resultbag entries as solve results.
219
+
220
+ Parameters
221
+ ----------
222
+ keys : Mapping[str, object] | Sequence[Mapping[str, object]] | None, optional
223
+ One set or a sequence of project keys to load. `None` loads all
224
+ entries in this view.
225
+ suffix_pattern : str | None, optional
226
+ Suffix pattern to select. `None` selects entries that have no suffix
227
+ pattern.
228
+
229
+ Returns
230
+ -------
231
+ SolveResult | BatchSolveResult | BundledSolveResult | BundledBatchSolveResult
232
+ Solve result shape for the selected entries.
233
+
234
+ Raises
235
+ ------
236
+ InvalidConfigurationError
237
+ If no entry matches, the selection is ambiguous, an empty sequence
238
+ of project keys is supplied, or stored result shapes are not
239
+ compatible.
240
+
241
+ Notes
242
+ -----
243
+ If a sequence of project keys is supplied, the selected entries follow
244
+ that sequence and receive new batch positions that start at zero.
245
+ Duplicate project keys are included once at their first requested
246
+ position. With no selection, entries retain Resultbag storage order.
247
+ Only load results from a Resultbag file that you trust. This method uses
248
+ Python pickle to load stored objects.
249
+ """
250
+
251
+ from ...models import (
252
+ BatchSolveEntry,
253
+ BatchSolveFailure,
254
+ BatchSolveResult,
255
+ BundledBatchSolveEntry,
256
+ BundledBatchSolveResult,
257
+ BundledSolveResult,
258
+ SolveResult,
259
+ )
260
+ from .raw import promote_raw_result, raw_result_project_count
261
+
262
+ candidates: list[ResultbagEntry] = [
263
+ entry
264
+ for entry in self._access_entries()
265
+ if entry.suffix_pattern == suffix_pattern
266
+ ]
267
+ if keys is not None:
268
+ requested: list[Mapping[str, object]]
269
+ if isinstance(keys, Mapping):
270
+ requested = [keys]
271
+ else:
272
+ requested = list(keys)
273
+ if not requested:
274
+ raise InvalidConfigurationError(
275
+ "get_results requires at least one key."
276
+ )
277
+ entries_by_id: dict[str, ResultbagEntry] = {
278
+ json.dumps(entry.keys, sort_keys=True, default=str): entry
279
+ for entry in candidates
280
+ }
281
+ ordered_candidates: list[ResultbagEntry] = []
282
+ seen_ids: set[str] = set()
283
+ for requested_keys in requested:
284
+ requested_id: str = json.dumps(
285
+ dict(requested_keys), sort_keys=True, default=str
286
+ )
287
+ if requested_id in seen_ids:
288
+ continue
289
+ candidate: ResultbagEntry | None = entries_by_id.get(requested_id)
290
+ if candidate is not None:
291
+ ordered_candidates.append(candidate)
292
+ seen_ids.add(requested_id)
293
+ candidates = ordered_candidates
294
+ if not candidates:
295
+ raise InvalidConfigurationError("No Resultbag entries match the selection.")
296
+ if any(entry.legacy for entry in candidates):
297
+ raise InvalidConfigurationError(
298
+ "Resultbag entry uses an unsupported legacy result format. "
299
+ "Reset the Resultbag before storing new results."
300
+ )
301
+ if isinstance(keys, Mapping) and len(candidates) > 1:
302
+ raise InvalidConfigurationError("The Resultbag key selection is ambiguous.")
303
+ if len(candidates) == 1 and candidates[0].result is not None:
304
+ return promote_raw_result(
305
+ candidates[0].result,
306
+ keys=candidates[0].keys,
307
+ log=candidates[0].log,
308
+ )
309
+
310
+ if all(
311
+ entry.result is None
312
+ or (
313
+ isinstance(entry.result, Mapping)
314
+ and raw_result_project_count(entry.result) == 1
315
+ )
316
+ for entry in candidates
317
+ ):
318
+ promoted_entries: list[SolveResult | None] = [
319
+ (
320
+ None
321
+ if entry.result is None
322
+ else cast(
323
+ SolveResult,
324
+ promote_raw_result(
325
+ entry.result,
326
+ keys=entry.keys,
327
+ log=entry.log,
328
+ ),
329
+ )
330
+ )
331
+ for entry in candidates
332
+ ]
333
+ if not all(
334
+ result is None or isinstance(result, SolveResult)
335
+ for result in promoted_entries
336
+ ):
337
+ raise InvalidConfigurationError(
338
+ "Resultbag entries contain incompatible solve shapes."
339
+ )
340
+ return BatchSolveResult(
341
+ entries=tuple(
342
+ BatchSolveEntry(
343
+ index=index,
344
+ keys=dict(entry.keys),
345
+ result=promoted_entries[index],
346
+ failure=(
347
+ None
348
+ if entry.result is not None
349
+ else BatchSolveFailure(
350
+ index=index,
351
+ keys=dict(entry.keys),
352
+ exception_type=RuntimeError,
353
+ message=str(entry.log),
354
+ )
355
+ ),
356
+ )
357
+ for index, entry in enumerate(candidates)
358
+ )
359
+ )
360
+ if all(
361
+ entry.result is None
362
+ or (
363
+ isinstance(entry.result, Mapping)
364
+ and raw_result_project_count(entry.result) > 1
365
+ )
366
+ for entry in candidates
367
+ ):
368
+ bundle_entries = tuple(
369
+ (
370
+ index,
371
+ entry,
372
+ (
373
+ None
374
+ if entry.result is None
375
+ else cast(
376
+ BundledSolveResult,
377
+ promote_raw_result(
378
+ entry.result,
379
+ keys=entry.keys,
380
+ log=entry.log,
381
+ ),
382
+ )
383
+ ),
384
+ )
385
+ for index, entry in enumerate(candidates)
386
+ )
387
+ successful_bundles = [
388
+ item[2] for item in bundle_entries if item[2] is not None
389
+ ]
390
+ if not successful_bundles:
391
+ raise InvalidConfigurationError(
392
+ "Bundled Resultbag failures have no project axis."
393
+ )
394
+ project_files = successful_bundles[0].project_files
395
+ if any(item.project_files != project_files for item in successful_bundles):
396
+ raise InvalidConfigurationError(
397
+ "Resultbag bundle project axes do not match."
398
+ )
399
+ from ...models import BundledBatchSolveEntry
400
+
401
+ return BundledBatchSolveResult(
402
+ entries=tuple(
403
+ BundledBatchSolveEntry(
404
+ index=index,
405
+ keys=dict(entry.keys),
406
+ result=result,
407
+ failure=(
408
+ None
409
+ if result is not None
410
+ else BatchSolveFailure(
411
+ index=index,
412
+ keys=dict(entry.keys),
413
+ exception_type=RuntimeError,
414
+ message=str(entry.log),
415
+ )
416
+ ),
417
+ project_files=project_files,
418
+ )
419
+ for index, entry, result in bundle_entries
420
+ )
421
+ )
422
+ raise InvalidConfigurationError(
423
+ "Resultbag entries contain incompatible solve shapes."
424
+ )
425
+
426
+
427
+ class ResultbagAccessMixin:
428
+ """Mixin that exposes Resultbag's shared read boundary."""
429
+
430
+ def _access_entries(self) -> Iterator[ResultbagEntry]:
431
+ yield from self._iter_access_entries()
432
+
433
+ def _iter_access_entries(self) -> Iterator[ResultbagEntry]:
434
+ yield from iter_storage_entries(cast(_ResultbagAccessOwner, self))
435
+
436
+ @property
437
+ def suffixes(self) -> tuple[str | None, ...]:
438
+ """Return the suffix patterns stored in the Resultbag.
439
+
440
+ The result is in a stable order. `None` identifies entries that have no
441
+ suffix pattern.
442
+
443
+ Returns
444
+ -------
445
+ tuple[str | None, ...]
446
+ Stored suffix patterns.
447
+ """
448
+
449
+ return ResultbagView(cast(ResultbagReadable, self), ()).suffixes
450
+
451
+ def get_results(
452
+ self,
453
+ keys: Mapping[str, object] | Sequence[Mapping[str, object]] | None = None,
454
+ *,
455
+ suffix_pattern: str | None = None,
456
+ ) -> object:
457
+ """Load Resultbag entries as solve results.
458
+
459
+ Parameters
460
+ ----------
461
+ keys : Mapping[str, object] | Sequence[Mapping[str, object]] | None, optional
462
+ One set or a sequence of project keys to load. `None` loads all
463
+ entries in the Resultbag.
464
+ suffix_pattern : str | None, optional
465
+ Suffix pattern to select. `None` selects entries that have no suffix
466
+ pattern.
467
+
468
+ Returns
469
+ -------
470
+ SolveResult | BatchSolveResult | BundledSolveResult | BundledBatchSolveResult
471
+ Solve result shape for the selected entries.
472
+
473
+ Raises
474
+ ------
475
+ InvalidConfigurationError
476
+ If no entry matches, the selection is ambiguous, an empty sequence
477
+ of project keys is supplied, or stored result shapes are not
478
+ compatible.
479
+
480
+ Notes
481
+ -----
482
+ Multiple entries are sorted by project keys before the method assigns
483
+ new batch positions. Only load results from a Resultbag file that you
484
+ trust. This method uses Python pickle to load stored objects.
485
+ """
486
+
487
+ return ResultbagView(cast(ResultbagReadable, self), ()).get_results(
488
+ keys, suffix_pattern=suffix_pattern
489
+ )
@@ -0,0 +1,199 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Iteration, dataframe export, and filtered query helpers for Resultbag."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import json
9
+ import pickle
10
+ import sqlite3
11
+ from collections.abc import Iterator
12
+ from typing import TYPE_CHECKING, Protocol, cast
13
+
14
+ from ....exceptions import InvalidConfigurationError
15
+ from .access import ResultbagEntry, ResultbagKeys
16
+ from .utils import (
17
+ FilterInput,
18
+ _build_filter_specs,
19
+ _canonicalize_key_value,
20
+ _decanonicalize_key_value,
21
+ _FilterSpec,
22
+ )
23
+
24
+ if TYPE_CHECKING:
25
+ from .query import ResultbagQuery
26
+
27
+
28
+ class ResultbagIterationMixin:
29
+ """Iteration/query helper methods for Resultbag internals."""
30
+
31
+ def _iter_tags_and_keys(self) -> Iterator[tuple[str, dict[str, object]]]:
32
+ """Iterate over tags and keys.
33
+
34
+ Parameters
35
+ ----------
36
+ None
37
+ This helper uses internal state only.
38
+
39
+ Returns
40
+ -------
41
+ Iterator[tuple[str, dict[str, object]]]
42
+ Normalized mapping output.
43
+
44
+ Notes
45
+ -----
46
+ Internal API: this helper is an implementation detail and may change
47
+ without notice.
48
+ """
49
+
50
+ owner: _ResultbagConnectionProtocol = cast(_ResultbagConnectionProtocol, self)
51
+ cursor: sqlite3.Cursor = owner._connection.cursor()
52
+ cursor.execute("SELECT tag, keys_json FROM entries ORDER BY rowid ASC")
53
+ row: tuple[str, str]
54
+ for row in cursor.fetchall():
55
+ tag: str = row[0]
56
+ keys_obj: object = cast(object, json.loads(row[1]))
57
+ if not isinstance(keys_obj, dict):
58
+ continue
59
+ decoded_keys: object = _decanonicalize_key_value(keys_obj)
60
+ if not isinstance(decoded_keys, dict):
61
+ continue
62
+ keys_dict: dict[str, object] = {
63
+ str(key): value
64
+ for key, value in decoded_keys.items()
65
+ if key != "__suffix_pattern__"
66
+ }
67
+ yield tag, keys_dict
68
+
69
+ @property
70
+ def keys(self) -> ResultbagKeys:
71
+ """Return the project keys without loading the stored results.
72
+
73
+ Returns
74
+ -------
75
+ ResultbagKeys
76
+ project keys in a stable order. The collection cannot be changed.
77
+ """
78
+
79
+ access_iterator: object = getattr(self, "_iter_access_entries", None)
80
+ if callable(access_iterator):
81
+ unique_keys: dict[str, dict[str, object]] = {}
82
+ entry: ResultbagEntry
83
+ for entry in cast(Iterator[ResultbagEntry], access_iterator()):
84
+ identity: str = json.dumps(
85
+ _canonicalize_key_value(entry.keys),
86
+ sort_keys=True,
87
+ default=str,
88
+ )
89
+ unique_keys[identity] = dict(entry.keys)
90
+ return ResultbagKeys(unique_keys[key] for key in unique_keys)
91
+
92
+ return ResultbagKeys(
93
+ keys_dict for _tag, keys_dict in self._iter_tags_and_keys()
94
+ )
95
+
96
+ def items(self) -> Iterator[tuple[dict[str, object], object]]:
97
+ """Return each set of project keys with its stored result.
98
+
99
+ Returns
100
+ -------
101
+ Iterator[tuple[dict[str, object], object]]
102
+ Pairs in the order in which the Resultbag entries were stored.
103
+
104
+ Notes
105
+ -----
106
+ Only iterate over a Resultbag file that you trust. This method uses
107
+ Python pickle to load each stored result.
108
+ """
109
+
110
+ owner: _ResultbagConnectionProtocol = cast(_ResultbagConnectionProtocol, self)
111
+ cursor: sqlite3.Cursor = owner._connection.cursor()
112
+ cursor.execute("PRAGMA table_info(entries)")
113
+ columns: set[str] = {str(column[1]) for column in cursor.fetchall()}
114
+ has_payload_format: bool = "payload_format" in columns
115
+ if has_payload_format:
116
+ cursor.execute(
117
+ "SELECT keys_json, result_blob, payload_format "
118
+ "FROM entries ORDER BY rowid ASC"
119
+ )
120
+ else:
121
+ cursor.execute(
122
+ "SELECT keys_json, result_blob FROM entries ORDER BY rowid ASC"
123
+ )
124
+ row: tuple[str, bytes] | tuple[str, bytes, int]
125
+ for row in cursor.fetchall():
126
+ keys_obj: object = cast(object, json.loads(row[0]))
127
+ if not isinstance(keys_obj, dict):
128
+ continue
129
+ decoded_keys: object = _decanonicalize_key_value(keys_obj)
130
+ if not isinstance(decoded_keys, dict):
131
+ continue
132
+ keys_dict = {
133
+ str(key): value
134
+ for key, value in decoded_keys.items()
135
+ if key != "__suffix_pattern__"
136
+ }
137
+ payload_format: int = 1
138
+ if has_payload_format:
139
+ row_with_format: tuple[str, bytes, int] = cast(
140
+ tuple[str, bytes, int], row
141
+ )
142
+ payload_format = row_with_format[2]
143
+ if payload_format != 1:
144
+ raise InvalidConfigurationError(
145
+ "Resultbag entry uses an unsupported legacy result format. "
146
+ "Reset the Resultbag before iterating results."
147
+ )
148
+ result_payload: object = cast(object, pickle.loads(row[1]))
149
+ yield keys_dict, result_payload
150
+
151
+ def filter(
152
+ self,
153
+ key: str | None = None,
154
+ filter_value: FilterInput | None = None,
155
+ /,
156
+ **criteria: FilterInput,
157
+ ) -> "ResultbagQuery":
158
+ """Select Resultbag entries by their project keys.
159
+
160
+ Parameters
161
+ ----------
162
+ key : str | None, optional
163
+ project key name for a positional filter.
164
+ filter_value : object | None, optional
165
+ Value for a positional filter. Use a plain value for an exact
166
+ match. Use `between(lower, upper)` to include both limits.
167
+ **criteria : object
168
+ project key filters. An entry must match all filters. Plain values,
169
+ including tuples, require an exact match. Use
170
+ `between(lower, upper)` to include both limits.
171
+
172
+ Returns
173
+ -------
174
+ ResultbagQuery
175
+ Read-only access to the matching Resultbag entries.
176
+
177
+ Raises
178
+ ------
179
+ InvalidConfigurationError
180
+ If no filter is supplied, a positional filter is incomplete, a
181
+ project key name is empty or duplicated, or bounds cannot be
182
+ compared with a stored value.
183
+ """
184
+
185
+ specs: tuple[_FilterSpec, ...] = _build_filter_specs(
186
+ key,
187
+ filter_value,
188
+ criteria,
189
+ )
190
+ from .query import ResultbagLike, ResultbagQuery
191
+
192
+ owner_query: ResultbagLike = cast(ResultbagLike, self)
193
+ return ResultbagQuery(owner_query, specs)
194
+
195
+
196
+ class _ResultbagConnectionProtocol(Protocol):
197
+ """Protocol for Resultbag SQLite connection ownership."""
198
+
199
+ _connection: sqlite3.Connection