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,418 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Single-result postprocess record façade."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import warnings
9
+ from collections.abc import Mapping
10
+ from dataclasses import dataclass, field
11
+ from typing import TYPE_CHECKING, cast
12
+
13
+ from ..exceptions import InvalidConfigurationError, UnsupportedExportError
14
+ from ..loaders import convert_to_powerflux
15
+ from .field_exports import FieldExportPayload
16
+ from .internal.export.common import materialize_rows, rows_to_dataframe
17
+ from .internal.export.pandas.payload import (
18
+ flatten_payload,
19
+ postprocess_payload_to_long_rows,
20
+ )
21
+ from .payloads import (
22
+ DictionaryExportMixin,
23
+ PostprocessRecordPayload,
24
+ Source,
25
+ TableCollectionPayload,
26
+ TablePayload,
27
+ XarrayExportMixin,
28
+ )
29
+ from .postprocess_payloads import (
30
+ _StructuredRecordPayload,
31
+ classify_payload,
32
+ format_postprocess_payload_preview,
33
+ is_field_export_mapping,
34
+ payload_mapping,
35
+ )
36
+
37
+ if TYPE_CHECKING:
38
+ import pandas as pd
39
+
40
+ from .artifacts import PostprocessHeader
41
+ from .internal.export.xarray.types import XarrayDataTree
42
+ from .postprocess_payloads import (
43
+ TableCollectionDerivativeCollection,
44
+ TableDerivativeCollection,
45
+ )
46
+ from .structured_derivatives import StructuredDerivativeCollection
47
+
48
+
49
+ @dataclass(slots=True, frozen=True, repr=False)
50
+ class PostprocessRecord(DictionaryExportMixin):
51
+ """Store and export one postprocess result."""
52
+
53
+ source_file: Source
54
+ _raw: object | None = field(repr=False)
55
+ title: str | None
56
+ payload: PostprocessRecordPayload | None = field(default=None, repr=False)
57
+ available: bool = True
58
+ failure_message: str | None = None
59
+
60
+ def __repr__(self) -> str:
61
+ status: str = (
62
+ "available"
63
+ if self.available
64
+ else (
65
+ "unavailable"
66
+ if self.failure_message is None
67
+ else f"unavailable: {self.failure_message}"
68
+ )
69
+ )
70
+ lines: list[str] = [
71
+ "PostprocessRecord(",
72
+ f" source_file: {self.source_file}",
73
+ f" title: {self.title if self.title is not None else '<untitled>'}",
74
+ f" status: {status}",
75
+ ]
76
+ if self.available and self.payload is not None:
77
+ lines.append(" preview:")
78
+ lines.extend(
79
+ f" {line}"
80
+ for line in format_postprocess_payload_preview(
81
+ self.payload
82
+ ).splitlines()
83
+ )
84
+ return "\n".join((*lines, ")"))
85
+
86
+ def __post_init__(self) -> None:
87
+ if self.payload is None:
88
+ typed_payload: PostprocessRecordPayload | None = classify_payload(
89
+ raw=self._raw, source=self.source_file, title=self.title
90
+ )
91
+ if typed_payload is not None:
92
+ object.__setattr__(self, "payload", typed_payload)
93
+
94
+ @property
95
+ def is_empty(self) -> bool:
96
+ return self._raw is None or not self.available
97
+
98
+ def _require_available(self) -> None:
99
+ if self.available:
100
+ return
101
+ record_label: str = (
102
+ str(self.source_file)
103
+ if self.title is None
104
+ else f"{self.title} ({self.source_file})"
105
+ )
106
+ warnings.warn(
107
+ (
108
+ f"Accessing unavailable postprocess output {record_label}"
109
+ if self.failure_message is None
110
+ else (
111
+ f"Accessing unavailable postprocess output {record_label}: "
112
+ f"{self.failure_message}"
113
+ )
114
+ ),
115
+ stacklevel=2,
116
+ )
117
+ message: str = (
118
+ "Postprocess output is unavailable and cannot be accessed."
119
+ if self.failure_message is None
120
+ else f"Postprocess output is unavailable and cannot be accessed: {self.failure_message}"
121
+ )
122
+ raise InvalidConfigurationError(message)
123
+
124
+ def __setstate__(self, state: object) -> None:
125
+ values: dict[str, object] = {
126
+ "source_file": None,
127
+ "_raw": None,
128
+ "title": None,
129
+ "payload": None,
130
+ "available": True,
131
+ "failure_message": None,
132
+ }
133
+ if isinstance(state, dict):
134
+ for name, value in state.items():
135
+ if name in values:
136
+ values[name] = value
137
+ elif isinstance(state, (tuple, list)):
138
+ state_values: tuple[object, ...] = tuple(state)
139
+ names: tuple[str, ...] = (
140
+ "source_file",
141
+ "_raw",
142
+ "title",
143
+ "available",
144
+ "failure_message",
145
+ )
146
+ for index, name in enumerate(names):
147
+ if index < len(state_values):
148
+ values[name] = state_values[index]
149
+ else:
150
+ raise TypeError(
151
+ f"Unsupported pickled state for PostprocessRecord: {type(state)!r}"
152
+ )
153
+ for name, value in values.items():
154
+ object.__setattr__(self, name, value)
155
+ if values["payload"] is None:
156
+ restored: PostprocessRecordPayload | None = classify_payload(
157
+ raw=values["_raw"],
158
+ source=cast(Source, values["source_file"]),
159
+ title=cast(str | None, values["title"]),
160
+ )
161
+ if restored is not None:
162
+ object.__setattr__(self, "payload", restored)
163
+
164
+ def _unsupported(self, operation: str) -> UnsupportedExportError:
165
+ payload_name: str = (
166
+ type(self.payload).__name__
167
+ if self.payload is not None
168
+ else type(self._raw).__name__
169
+ )
170
+ return UnsupportedExportError(
171
+ f"{operation} is not supported for `{payload_name}`."
172
+ )
173
+
174
+ def to_dict(self) -> Mapping[object, object]:
175
+ """Return the postprocess data as a dictionary.
176
+
177
+ Returns
178
+ -------
179
+ Mapping[object, object]
180
+ Postprocess data as a dictionary that keeps the original field names.
181
+ """
182
+
183
+ self._require_available()
184
+ if self.payload is None:
185
+ raise self._unsupported("to_dict")
186
+ return cast(DictionaryExportMixin, self.payload).to_dict()
187
+
188
+ @property
189
+ def header(self) -> "PostprocessHeader | None":
190
+ """Return the optional header associated with this postprocess result.
191
+
192
+ Returns
193
+ -------
194
+ PostprocessHeader | None
195
+ Header data when the result contains a header. Otherwise, `None`.
196
+ """
197
+
198
+ self._require_available()
199
+ raw_mapping: Mapping[object, object] | None = payload_mapping(self._raw)
200
+ if raw_mapping is None or not isinstance(raw_mapping.get("header"), Mapping):
201
+ return None
202
+ from .artifacts import PostprocessHeader
203
+
204
+ return PostprocessHeader(
205
+ table=cast(Mapping[object, object], raw_mapping["header"])
206
+ )
207
+
208
+ def is_field_export(self) -> bool:
209
+ """Return whether this record contains a Cartesian field export.
210
+
211
+ Returns
212
+ -------
213
+ bool
214
+ `True` when the record contains field data. Otherwise, `False`.
215
+ """
216
+
217
+ return is_field_export_mapping(payload_mapping(self._raw), self.title)
218
+
219
+ @property
220
+ def fields(self) -> FieldExportPayload:
221
+ """Return the field-export interface for this record.
222
+
223
+ Returns
224
+ -------
225
+ FieldExportPayload
226
+ Field data and field-navigation operations.
227
+
228
+ Raises
229
+ ------
230
+ UnsupportedExportError
231
+ If the record does not contain field data.
232
+ """
233
+
234
+ self._require_available()
235
+ if not isinstance(self.payload, FieldExportPayload):
236
+ raise self._unsupported("fields")
237
+ return self.payload
238
+
239
+ @property
240
+ def derivatives(
241
+ self,
242
+ ) -> "TableDerivativeCollection | TableCollectionDerivativeCollection | StructuredDerivativeCollection":
243
+ """Return parameter-derivative navigation for numeric postprocess data.
244
+
245
+ Returns
246
+ -------
247
+ TableDerivativeCollection | TableCollectionDerivativeCollection | StructuredDerivativeCollection
248
+ Name-based selection for canonical table or structured payloads.
249
+ """
250
+
251
+ self._require_available()
252
+ if isinstance(self.payload, TablePayload):
253
+ return self.payload.derivatives
254
+ if isinstance(self.payload, TableCollectionPayload):
255
+ return self.payload.derivatives
256
+ if not isinstance(self.payload, _StructuredRecordPayload):
257
+ raise AttributeError("derivatives")
258
+ values: Mapping[object, object] = self.payload._value_mapping()
259
+ # Preserve established dynamic access for a user quantity named
260
+ # `derivatives` instead of shadowing it with the navigation view.
261
+ if "derivatives" in values:
262
+ raise AttributeError("derivatives")
263
+ from .structured_derivatives import (
264
+ StructuredDerivativeCollection,
265
+ _base_values,
266
+ _has_selected_numeric,
267
+ _parameter_branches,
268
+ )
269
+
270
+ base: Mapping[object, object] = _base_values(values)
271
+ branches: Mapping[str, Mapping[object, object]] = _parameter_branches(values)
272
+ return StructuredDerivativeCollection(
273
+ _branches={
274
+ name: branch
275
+ for name, branch in branches.items()
276
+ if _has_selected_numeric(branch, base)
277
+ },
278
+ _source=self.source_file,
279
+ _title=self.title,
280
+ _root=values,
281
+ )
282
+
283
+ def to_df(self, orient: str | None = None) -> "pd.DataFrame":
284
+ """Return tabular postprocess data as a pandas `DataFrame`.
285
+
286
+ Parameters
287
+ ----------
288
+ orient : {None, "wide", "long"}, optional
289
+ Select the table layout. Structured and table-collection payloads
290
+ support only the long layout.
291
+
292
+ Raises
293
+ ------
294
+ InvalidConfigurationError
295
+ If the record is unavailable or does not contain tabular data.
296
+ UnsupportedExportError
297
+ If the payload does not support the requested layout.
298
+
299
+ Returns
300
+ -------
301
+ pandas.DataFrame
302
+ Postprocess data in the selected layout.
303
+ """
304
+
305
+ if orient not in {None, "wide", "long"}:
306
+ raise ValueError("orient must be None, 'wide', or 'long'")
307
+ self._require_available()
308
+ if isinstance(self.payload, TableCollectionPayload):
309
+ if orient == "wide":
310
+ raise self._unsupported("to_df")
311
+ return self.payload.to_df(orient=orient)
312
+ if self.is_field_export():
313
+ raise self._unsupported("to_df")
314
+ if isinstance(self.payload, _StructuredRecordPayload):
315
+ if orient == "wide":
316
+ raise self._unsupported("to_df")
317
+ rows: list[dict[str, object]] = [
318
+ {"path": path, "value": value}
319
+ for path, value in flatten_payload(
320
+ self.payload._value_mapping(), path_prefix=""
321
+ )
322
+ ]
323
+ return rows_to_dataframe(
324
+ materialize_rows(
325
+ rows,
326
+ prefix={
327
+ "postprocess_title": self.title,
328
+ "source_file": str(self.source_file),
329
+ },
330
+ )
331
+ )
332
+ if not isinstance(self.payload, TablePayload):
333
+ raise self._unsupported("to_df")
334
+ if orient in (None, "wide"):
335
+ return self.payload.to_df(orient=orient)
336
+ values: dict[object, object] = dict(self.payload.to_dict())
337
+ values.pop("title", None)
338
+ values.pop("header", None)
339
+ table_rows: list[dict[str, object]] | None = postprocess_payload_to_long_rows(
340
+ values
341
+ )
342
+ if table_rows is None:
343
+ raise InvalidConfigurationError("Postprocess payload is not tabular.")
344
+ return rows_to_dataframe(
345
+ materialize_rows(
346
+ table_rows,
347
+ prefix={
348
+ "postprocess_title": self.title,
349
+ "source_file": str(self.source_file),
350
+ },
351
+ )
352
+ )
353
+
354
+ def to_xarray(self) -> "XarrayDataTree":
355
+ """Return postprocess data as an xarray `DataTree`.
356
+
357
+ Returns
358
+ -------
359
+ xarray.DataTree
360
+ Postprocess data in an xarray tree.
361
+ """
362
+
363
+ self._require_available()
364
+ if self.is_field_export():
365
+ return self.fields.to_xarray()
366
+ if isinstance(self.payload, TableCollectionPayload):
367
+ return self.payload.to_xarray()
368
+ if self.payload is None:
369
+ if self._raw is None:
370
+ raise InvalidConfigurationError(
371
+ "Postprocess payload is unavailable and cannot be exported via to_xarray()."
372
+ )
373
+ raise self._unsupported("to_xarray")
374
+ return cast(XarrayExportMixin, self.payload).to_xarray()
375
+
376
+ def to_powerflux(self) -> PostprocessRecord:
377
+ """Return a new record with field data converted to power flux.
378
+
379
+ Returns
380
+ -------
381
+ PostprocessRecord
382
+ New record containing converted postprocess data.
383
+
384
+ Raises
385
+ ------
386
+ InvalidConfigurationError
387
+ If the postprocess data is not stored as named values.
388
+ """
389
+
390
+ self._require_available()
391
+ raw_mapping: Mapping[object, object] | None = payload_mapping(self._raw)
392
+ if raw_mapping is None:
393
+ raise InvalidConfigurationError(
394
+ "Postprocess payload is not mapping-like and cannot be converted to power flux."
395
+ )
396
+ converted: dict[str, object] = convert_to_powerflux(
397
+ cast(Mapping[str, object], raw_mapping)
398
+ )
399
+ title_object: object | None = converted.get("title")
400
+ return PostprocessRecord(
401
+ source_file=self.source_file,
402
+ _raw=converted,
403
+ title=title_object if isinstance(title_object, str) else self.title,
404
+ )
405
+
406
+ def __getattr__(self, name: str) -> object:
407
+ self._require_available()
408
+ values: Mapping[object, object] = self.to_dict()
409
+ if name in values:
410
+ return values[name]
411
+ raise AttributeError(f"Postprocess mapping has no key {name!r}.")
412
+
413
+ def _field_payload_mapping(self, *, error_message: str) -> Mapping[object, object]:
414
+ self._require_available()
415
+ values: Mapping[object, object] | None = payload_mapping(self._raw)
416
+ if values is None:
417
+ raise InvalidConfigurationError(error_message)
418
+ return values
@@ -0,0 +1,279 @@
1
+ # SPDX-License-Identifier: MIT
2
+ # Copyright (c) 2001-2026 JCMwave GmbH
3
+
4
+ """Persistent Resultbag storage for solve/result workflows."""
5
+
6
+ from __future__ import annotations
7
+
8
+ import sqlite3
9
+ from collections.abc import Iterator, Mapping, Sequence
10
+ from pathlib import Path
11
+
12
+ from .internal.resultbag.access import ResultbagEntry, ResultbagKeys, ResultbagView
13
+ from .internal.resultbag.query import ResultbagQuery
14
+ from .internal.resultbag.store import _ResultbagStore
15
+ from .internal.resultbag.utils import FilterInput, between
16
+ from .resultbag_management import ResultbagManagement
17
+
18
+
19
+ class Resultbag:
20
+ """Store and query solve results in a persistent Resultbag.
21
+
22
+ .. warning::
23
+ Open Resultbag files only from trusted sources. Loading stored results
24
+ or logs uses Python pickle and can execute code from the file.
25
+
26
+ Parameters
27
+ ----------
28
+ filepath : str | Path
29
+ Resultbag storage path. When the path has no suffix, `.jcmrb` is
30
+ appended automatically.
31
+ keys : Mapping[str, object] | Sequence[str] | None, optional
32
+ project keys or a sequence of project key names that defines the
33
+ stored fields. When you reopen a Resultbag, `None` preserves its
34
+ existing fields. If stored data exists, call
35
+ `resultbag.management.reset()` before you change the fields.
36
+
37
+ Notes
38
+ -----
39
+ Use one Resultbag for one logical project and one set of source files.
40
+ Source-file checks determine whether stored results can be reused.
41
+ """
42
+
43
+ management: ResultbagManagement
44
+ """Provide advanced Resultbag maintenance and solve integration.
45
+
46
+ Use this namespace to add, inspect, remove, or reset stored entries, manage
47
+ attempt logs, and connect daemon submissions to Resultbag storage. These
48
+ operations access persisted data directly. Use `Resultbag.get_results(...)`
49
+ for normal result selection and the current typed result interfaces.
50
+ """
51
+
52
+ def __init__(
53
+ self,
54
+ filepath: str | Path,
55
+ keys: Mapping[str, object] | Sequence[str] | None = None,
56
+ ) -> None:
57
+ """Open or create a Resultbag.
58
+
59
+ Parameters
60
+ ----------
61
+ filepath : str | Path
62
+ Resultbag storage path. When the path has no suffix, `.jcmrb` is
63
+ appended automatically.
64
+ keys : Mapping[str, object] | Sequence[str] | None, optional
65
+ project keys or a sequence of project key names that defines the
66
+ stored fields. When you reopen a Resultbag, `None` preserves its
67
+ existing fields. If stored data exists, call
68
+ `resultbag.management.reset()` before you change the fields.
69
+
70
+ Raises
71
+ ------
72
+ InvalidConfigurationError
73
+ If the parent directory does not exist, or if stored data exists
74
+ and the requested project key fields differ.
75
+ """
76
+
77
+ self._store: _ResultbagStore = _ResultbagStore(filepath, keys)
78
+ self.management: ResultbagManagement = ResultbagManagement(self._store)
79
+
80
+ @property
81
+ def _filepath(self) -> Path:
82
+ """Expose the normalized path for existing internal diagnostics."""
83
+
84
+ return self._store._filepath
85
+
86
+ @property
87
+ def _connection(self) -> sqlite3.Connection:
88
+ """Expose the connection for existing internal diagnostics."""
89
+
90
+ return self._store._connection
91
+
92
+ @property
93
+ def _closed(self) -> bool:
94
+ """Expose closure state for existing internal diagnostics."""
95
+
96
+ return self._store._closed
97
+
98
+ @classmethod
99
+ def _close_open_instances_for_exit(cls) -> None:
100
+ """Close still-open Resultbag stores during process teardown."""
101
+
102
+ _ResultbagStore._close_open_instances_for_exit()
103
+
104
+ def close(self) -> None:
105
+ """Close the Resultbag file.
106
+
107
+ Repeated calls have no effect.
108
+ """
109
+
110
+ self._store.close()
111
+
112
+ def __enter__(self) -> Resultbag:
113
+ """Return this Resultbag for context-managed usage.
114
+
115
+ Returns
116
+ -------
117
+ Resultbag
118
+ This Resultbag instance.
119
+ """
120
+
121
+ return self
122
+
123
+ def __exit__(
124
+ self,
125
+ exc_type: type[BaseException] | None,
126
+ exc: BaseException | None,
127
+ tb: object | None,
128
+ ) -> None:
129
+ """Close the Resultbag when the context-managed block exits.
130
+
131
+ Parameters
132
+ ----------
133
+ exc_type : type[BaseException] | None
134
+ Exception type raised in the managed block, if any.
135
+ exc : BaseException | None
136
+ Exception instance raised in the managed block, if any.
137
+ tb : object | None
138
+ Traceback object associated with `exc`, if any.
139
+ """
140
+
141
+ del exc_type, exc, tb
142
+ self.close()
143
+
144
+ @property
145
+ def keys(self) -> ResultbagKeys:
146
+ """Return stored project keys without loading result payloads.
147
+
148
+ Returns
149
+ -------
150
+ ResultbagKeys
151
+ project keys in stable order. The collection cannot be changed.
152
+ """
153
+
154
+ return self._store.keys
155
+
156
+ @property
157
+ def suffixes(self) -> tuple[str | None, ...]:
158
+ """Return stored suffix patterns in stable order.
159
+
160
+ Returns
161
+ -------
162
+ tuple[str | None, ...]
163
+ Available suffix patterns. `None` identifies entries without a
164
+ suffix pattern.
165
+ """
166
+
167
+ return self._store.suffixes
168
+
169
+ def items(self) -> Iterator[tuple[dict[str, object], object]]:
170
+ """Iterate over stored project keys and result payloads.
171
+
172
+ Returns
173
+ -------
174
+ Iterator[tuple[dict[str, object], object]]
175
+ project keys and stored raw result pairs in storage order.
176
+
177
+ Notes
178
+ -----
179
+ Only iterate over a Resultbag file that you trust. This method loads
180
+ serialized raw result data.
181
+ """
182
+
183
+ yield from self._store.items()
184
+
185
+ def filter(
186
+ self,
187
+ key: str | None = None,
188
+ filter_value: FilterInput | None = None,
189
+ /,
190
+ **criteria: FilterInput,
191
+ ) -> ResultbagQuery:
192
+ """Return a read-only view filtered by project keys.
193
+
194
+ Parameters
195
+ ----------
196
+ key : str | None, optional
197
+ project key name for a positional filter.
198
+ filter_value : FilterInput | None, optional
199
+ Exact value or an inclusive range created by `between(...)`.
200
+ **criteria : FilterInput
201
+ project key filters. An entry must match all filters.
202
+
203
+ Returns
204
+ -------
205
+ ResultbagQuery
206
+ Read-only access to matching Resultbag entries.
207
+
208
+ Raises
209
+ ------
210
+ InvalidConfigurationError
211
+ If the filter is incomplete, empty, duplicated, or cannot compare
212
+ its bounds with a stored value.
213
+ """
214
+
215
+ return self._store.filter(key, filter_value, **criteria)
216
+
217
+ def get_results(
218
+ self,
219
+ keys: Mapping[str, object] | Sequence[Mapping[str, object]] | None = None,
220
+ *,
221
+ suffix_pattern: str | None = None,
222
+ ) -> object:
223
+ """Load selected entries as their supported solve result shape.
224
+
225
+ Parameters
226
+ ----------
227
+ keys : Mapping[str, object] | Sequence[Mapping[str, object]] | None, optional
228
+ One set or a sequence of project keys to load. `None` loads all
229
+ entries in the Resultbag.
230
+ suffix_pattern : str | None, optional
231
+ Suffix pattern to select. `None` selects entries without a suffix
232
+ pattern.
233
+
234
+ Returns
235
+ -------
236
+ SolveResult | BatchSolveResult | BundledSolveResult | BundledBatchSolveResult
237
+ Solve result shape for the selected entries.
238
+
239
+ Raises
240
+ ------
241
+ InvalidConfigurationError
242
+ If no entry matches, the selection is ambiguous, the supplied
243
+ project keys are empty, or stored result shapes are incompatible.
244
+
245
+ Notes
246
+ -----
247
+ When project keys are provided, batch positions follow their supplied
248
+ sequence. With no selection, entries retain Resultbag storage order.
249
+ Only load results from a Resultbag file that you trust.
250
+ This method uses Python pickle to load stored results.
251
+ """
252
+
253
+ return self._store.get_results(keys, suffix_pattern=suffix_pattern)
254
+
255
+ def has_results(self) -> bool:
256
+ """Return whether at least one stored result exists.
257
+
258
+ Returns
259
+ -------
260
+ bool
261
+ `True` when the Resultbag contains a stored result. Otherwise,
262
+ `False`.
263
+ """
264
+
265
+ return self._store.has_results()
266
+
267
+ def _iter_access_entries(self) -> Iterator[ResultbagEntry]:
268
+ """Provide the internal read seam used by filtered views."""
269
+
270
+ yield from self._store._iter_access_entries()
271
+
272
+
273
+ __all__ = [
274
+ "FilterInput",
275
+ "Resultbag",
276
+ "ResultbagQuery",
277
+ "ResultbagView",
278
+ "between",
279
+ ]