scistackplotdb 0.4.1__tar.gz → 0.4.3__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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scistackplotdb
3
- Version: 0.4.1
3
+ Version: 0.4.3
4
4
  Summary: scidb-backed plotting: load variables into long tables and plot them with scistackplot
5
5
  Author: SciStack Contributors
6
6
  License-Expression: MIT
@@ -17,11 +17,11 @@ Classifier: Programming Language :: Python :: 3.13
17
17
  Classifier: Topic :: Scientific/Engineering :: Visualization
18
18
  Classifier: Typing :: Typed
19
19
  Requires-Python: >=3.10
20
- Requires-Dist: sciduckdb==0.4.1
21
- Requires-Dist: scifor==0.4.1
22
- Requires-Dist: scistack-db==0.4.1
23
- Requires-Dist: scistacklog==0.4.1
24
- Requires-Dist: scistackplot==0.4.1
20
+ Requires-Dist: sciduckdb==0.4.3
21
+ Requires-Dist: scifor==0.4.3
22
+ Requires-Dist: scistack-db==0.4.3
23
+ Requires-Dist: scistacklog==0.4.3
24
+ Requires-Dist: scistackplot==0.4.3
25
25
  Provides-Extra: dev
26
26
  Requires-Dist: matplotlib>=3.6; extra == 'dev'
27
27
  Requires-Dist: pytest-cov>=4.0; extra == 'dev'
@@ -32,6 +32,8 @@ from __future__ import annotations
32
32
 
33
33
  from .endpoint import (
34
34
  EndpointCode,
35
+ EndpointInput,
36
+ why_not_wireable,
35
37
  default_output_variable,
36
38
  default_path_template,
37
39
  generate_endpoint,
@@ -65,7 +67,6 @@ from .saved import (
65
67
  save_plot,
66
68
  saved_plot_history,
67
69
  )
68
- from .designs import DesignError, StoredDesign, apply_design, is_linked, link_design, load_design, save_design
69
70
  from .presets import (
70
71
  AppliedPreset,
71
72
  Preset,
@@ -92,13 +93,6 @@ from .variants import (
92
93
  )
93
94
 
94
95
  __all__ = [
95
- "DesignError",
96
- "StoredDesign",
97
- "apply_design",
98
- "is_linked",
99
- "link_design",
100
- "load_design",
101
- "save_design",
102
96
  "ScidbSource",
103
97
  # a wide variable's text fields as their own measure
104
98
  "TEXT_SUFFIX",
@@ -155,6 +149,8 @@ __all__ = [
155
149
  "joined_levels",
156
150
  "generate_endpoint",
157
151
  "EndpointCode",
152
+ "EndpointInput",
153
+ "why_not_wireable",
158
154
  "default_output_variable",
159
155
  "default_path_template",
160
156
  ]
@@ -15,15 +15,13 @@ import json
15
15
 
16
16
  from scistacklog import Log
17
17
 
18
- from . import designs, presets, saved
18
+ from . import presets, saved
19
19
 
20
20
  LAYER = "scistackplotdb"
21
21
 
22
22
  _STORES = {
23
23
  "saved_plots.json": saved.STORE,
24
24
  "presets.json": presets.STORE,
25
- # The shared design of a linked figure + table (designs.py).
26
- "designs.json": designs.STORE,
27
25
  }
28
26
 
29
27
 
@@ -45,6 +45,11 @@ class EndpointCode:
45
45
  iterate_keys: list[str] = field(default_factory=list)
46
46
  path_template: str = ""
47
47
  output_variable: str = ""
48
+ #: ``{param: EndpointInput}`` — what the call is fed (:func:`endpoint_inputs`,
49
+ #: the one owner the snippet and the canvas wiring both render from).
50
+ inputs: "dict[str, EndpointInput]" = field(default_factory=dict)
51
+ #: The ``as_table`` parameters of the call.
52
+ as_table: list[str] = field(default_factory=list)
48
53
 
49
54
  @property
50
55
  def source(self) -> str:
@@ -81,14 +86,18 @@ def generate_endpoint(
81
86
  template = path_template or default_path_template(name, iterate_keys)
82
87
 
83
88
  function_source = generate_plot_function(spec, table, function_name=name)
84
- foreach_source = _foreach_call(
89
+ inputs, table_inputs = endpoint_inputs(
85
90
  spec=spec,
86
91
  table=table,
87
- function_name=name,
88
92
  input_variable=input_variable,
89
93
  x_variable=x_variable,
90
- output_variable=output,
91
94
  path_template=template,
95
+ )
96
+ foreach_source = _foreach_call(
97
+ function_name=name,
98
+ inputs=inputs,
99
+ table_inputs=table_inputs,
100
+ output_variable=output,
92
101
  iterate_keys=iterate_keys,
93
102
  )
94
103
 
@@ -107,6 +116,8 @@ def generate_endpoint(
107
116
  iterate_keys=iterate_keys,
108
117
  path_template=template,
109
118
  output_variable=output,
119
+ inputs=inputs,
120
+ as_table=table_inputs,
110
121
  )
111
122
 
112
123
 
@@ -227,17 +238,50 @@ def _single_variant_expression(input_variable: str, spec, table=None) -> str:
227
238
  return row_expression(sets[0].variable or input_variable, sets[0], table)
228
239
 
229
240
 
230
- def _foreach_call(
241
+ @dataclass(frozen=True)
242
+ class EndpointInput:
243
+ """One ``for_each`` input of a generated endpoint.
244
+
245
+ ``expression`` is its source text in the generated call. The other fields
246
+ say what the CANVAS can express of it, and are filled only when it can:
247
+
248
+ * ``variable`` (+ ``column``): a plain variable load, optionally one
249
+ column (``Var["col"]``) — an edge from that variable node;
250
+ * ``template``: an output path (``PathOutput(template)``) — the node's
251
+ ``pathOutputs`` statement.
252
+
253
+ Anything else (a ``Variant(...)`` pin) has neither, and
254
+ :func:`why_not_wireable` names it.
255
+ """
256
+
257
+ expression: str
258
+ variable: str | None = None
259
+ column: str | None = None
260
+ template: str | None = None
261
+
262
+ @property
263
+ def wireable(self) -> bool:
264
+ return self.variable is not None or self.template is not None
265
+
266
+
267
+ def _bare(expression: str) -> str | None:
268
+ """The variable an expression loads when it is a bare variable name."""
269
+ return expression if expression.isidentifier() else None
270
+
271
+
272
+ def endpoint_inputs(
231
273
  *,
232
274
  spec: PlotSpec,
233
275
  table: LongTable | None = None,
234
- function_name: str,
235
276
  input_variable: str,
236
277
  x_variable: str | None,
237
- output_variable: str,
238
278
  path_template: str,
239
- iterate_keys: list[str],
240
- ) -> str:
279
+ ) -> "tuple[dict[str, EndpointInput], list[str]]":
280
+ """``({param: EndpointInput}, as_table params)`` — THE owner of what the
281
+ generated endpoint is fed. The ``for_each`` snippet (:func:`_foreach_call`)
282
+ and the canvas wiring (the GUI's ``endpoint_node_service``) are both
283
+ rendered from this one map, so they cannot disagree."""
284
+ inputs: dict[str, EndpointInput] = {}
241
285
  variant_inputs = variant_params(spec)
242
286
  if variant_inputs:
243
287
  # One input per named variant, each loaded through its own pin. See
@@ -245,20 +289,19 @@ def _foreach_call(
245
289
  # Zipped against `defined_sets`, not `spec.variant_sets`: unfilled rows
246
290
  # produce no input, so indexing the raw list would pair a parameter with
247
291
  # the wrong variant's selection.
248
- inputs = [
249
- f' "{generated.param}": '
250
- f"{row_expression(generated.variable, variant, table)},"
251
- for generated, variant in zip(
252
- variant_inputs, defined_sets(spec.variant_sets), strict=True
292
+ for generated, variant in zip(
293
+ variant_inputs, defined_sets(spec.variant_sets), strict=True
294
+ ):
295
+ inputs[generated.param] = EndpointInput(
296
+ row_expression(generated.variable, variant, table)
253
297
  )
254
- ]
255
298
  table_inputs = [generated.param for generated in variant_inputs]
256
299
  else:
257
300
  pinned = _single_variant_expression(input_variable, spec, table)
258
- inputs = [f' "df": {pinned},']
301
+ inputs["df"] = EndpointInput(pinned, variable=_bare(pinned))
259
302
  table_inputs = ["df"]
260
303
  if x_variable:
261
- inputs.append(f' "df_x": {x_variable},')
304
+ inputs["df_x"] = EndpointInput(x_variable, variable=_bare(x_variable))
262
305
  table_inputs.append("df_x")
263
306
  for group in spec.joined_factor_variables:
264
307
  # A grouping variable arrives as its own input and is merged onto the
@@ -276,6 +319,7 @@ def _foreach_call(
276
319
  if group.column is None
277
320
  else f"{group.variable}[{group.column!r}]"
278
321
  )
322
+ wire = {"variable": group.variable, "column": group.column}
279
323
  if group.selection:
280
324
  # The grouping's own variant pin, exported so the generated figure
281
325
  # is stratified by the same version of the sheet the preview used.
@@ -287,15 +331,46 @@ def _foreach_call(
287
331
  # VariantSet both provide — one translation from frame columns to
288
332
  # `Variant(...)` keywords, not two that can disagree.
289
333
  expression = variant_expression(expression, group)
290
- inputs.append(f' "{group_param(group)}": {expression},')
334
+ wire = {}
335
+ inputs[group_param(group)] = EndpointInput(expression, **wire)
291
336
  table_inputs.append(group_param(group))
292
- inputs.append(f' "filename": PathOutput("{path_template}"),')
337
+ inputs["filename"] = EndpointInput(
338
+ f'PathOutput("{path_template}")', template=path_template
339
+ )
340
+ return inputs, table_inputs
341
+
342
+
343
+ def why_not_wireable(inputs: "dict[str, EndpointInput]") -> str | None:
344
+ """Why the canvas cannot place a node fed by *inputs*, or ``None``.
345
+
346
+ v1 places plain variable loads (optionally one column) and output paths.
347
+ A ``Variant(...)`` pin — a saved plot frozen to an older code version, two
348
+ or more variant rows, a pinned grouping variable — has no edge form yet,
349
+ so the node is not placed and the reason is shown instead.
350
+ """
351
+ blocked = [f"{param} = {inp.expression}" for param, inp in inputs.items() if not inp.wireable]
352
+ if not blocked:
353
+ return None
354
+ return (
355
+ "the canvas cannot express a pinned variant load yet ("
356
+ + "; ".join(blocked)
357
+ + "). The function was written; wire it by hand or paste the for_each snippet."
358
+ )
359
+
293
360
 
361
+ def _foreach_call(
362
+ *,
363
+ function_name: str,
364
+ inputs: "dict[str, EndpointInput]",
365
+ table_inputs: list[str],
366
+ output_variable: str,
367
+ iterate_keys: list[str],
368
+ ) -> str:
294
369
  lines = [
295
370
  "for_each(",
296
371
  f" {function_name},",
297
372
  " inputs={",
298
- *inputs,
373
+ *(f' "{param}": {inp.expression},' for param, inp in inputs.items()),
299
374
  " },",
300
375
  f" outputs=[{output_variable}],",
301
376
  # A plot_ function receives the long-format table (schema keys as
@@ -98,6 +98,11 @@ class SavedPlot:
98
98
  #: index), stored verbatim. The frontend owns their meaning and reads them
99
99
  #: as leniently as the spec is read here.
100
100
  view: dict = field(default_factory=dict)
101
+ #: The table's test settings saved WITH the figure (one record per tab,
102
+ #: plan-stats-on-figure.md): a ``StatsSpec.to_dict()`` without its design
103
+ #: copy, stored verbatim and read by ``scistackstats.restore_stats_spec``
104
+ #: (this layer never imports statistics). None = saved without any.
105
+ stats: dict | None = None
101
106
  #: ``scistackplot.RestoreNote`` s from restoring the spec and, when a table
102
107
  #: was given, from reconciling it with today's data.
103
108
  notes: list = field(default_factory=list)
@@ -114,6 +119,7 @@ class SavedPlot:
114
119
  **self.info.to_dict(),
115
120
  "spec": self.spec.to_dict(),
116
121
  "view": dict(self.view),
122
+ "stats": dict(self.stats) if self.stats is not None else None,
117
123
  "notes": [note.to_dict() for note in self.notes],
118
124
  "stored_format": self.stored_format,
119
125
  "newer": [dict(entry) for entry in self.newer],
@@ -164,6 +170,7 @@ def save_plot(
164
170
  current_plot_id: str | None = None,
165
171
  table=None,
166
172
  table_for: Callable[[Any], Any] | None = None,
173
+ stats: dict | None = None,
167
174
  ) -> SavedPlotInfo:
168
175
  """Save *spec* under *name* for *variable*, returning the new version.
169
176
 
@@ -184,6 +191,9 @@ def save_plot(
184
191
  Saving onto any OTHER plot's name raises :class:`SavedPlotExists` so the
185
192
  caller can ask first.
186
193
 
194
+ *stats* is the table's test settings, stored opaquely beside the figure
195
+ (:attr:`SavedPlot.stats`); absent is fine.
196
+
187
197
  *spec* is a ``PlotSpec`` or its dict. A dict is read **strictly**: the
188
198
  panel always sends the current format, and a spec that does not parse is
189
199
  a bug to surface, not something to store.
@@ -201,6 +211,8 @@ def save_plot(
201
211
  view = {}
202
212
  if not isinstance(view, dict):
203
213
  raise SavedPlotError(f"view must be a table of settings, got {type(view).__name__}")
214
+ if stats is not None and not isinstance(stats, dict):
215
+ raise SavedPlotError(f"stats must be a table of settings, got {type(stats).__name__}")
204
216
 
205
217
  if table is None and table_for is not None:
206
218
  try:
@@ -230,6 +242,7 @@ def save_plot(
230
242
  "format": ENVELOPE_FORMAT,
231
243
  "spec": _strip_frozen(spec).to_dict(),
232
244
  "view": view,
245
+ "stats": stats,
233
246
  "saved_with": {"scistackplot": plot_version},
234
247
  FROZEN_KEY: frozen_code,
235
248
  }
@@ -361,6 +374,12 @@ def load_saved_plot(
361
374
  )
362
375
  view = {}
363
376
 
377
+ stats = envelope.get("stats")
378
+ if stats is not None and not isinstance(stats, dict):
379
+ Log.warn("[saved_plot] %s / %r: stored stats settings are not a table (%r); ignored",
380
+ info.variable, info.name, stats, layer=LAYER)
381
+ stats = None
382
+
364
383
  stored_format = envelope.get("format")
365
384
  Log.info(
366
385
  "[saved_plot] opened %s / %r version %d (envelope format %r, saved with %s): "
@@ -377,6 +396,7 @@ def load_saved_plot(
377
396
  info=info,
378
397
  spec=spec,
379
398
  view=view,
399
+ stats=stats,
380
400
  notes=notes,
381
401
  stored_format=stored_format,
382
402
  newer=newer,
@@ -675,6 +695,7 @@ def follow_latest_saved_plot(db, plot_id: str, *, table=None) -> SavedPlotInfo:
675
695
  overwrite=True,
676
696
  current_plot_id=plot_id,
677
697
  table=table,
698
+ stats=envelope.get("stats") if isinstance(envelope.get("stats"), dict) else None,
678
699
  )
679
700
  Log.info(
680
701
  "[saved_plot] %s / %r now follows latest code (version %d -> %d)",
@@ -30,6 +30,15 @@ from scistackplot.text.framesize import format_extent, frame_extent
30
30
  from scistackplot.sources import BaseSource, UnknownMeasureError
31
31
  from scistackplot.reduce.variants import VARIABLE_COLUMN
32
32
  from scistackplot.reduce.temporal import is_temporal_column
33
+ from scistackplot.model.where_check import (
34
+ LEVEL_ORDER,
35
+ LEVEL_YES,
36
+ MATCHING_FACTOR,
37
+ WhereCheck,
38
+ filter_factor_name,
39
+ matching_verdict,
40
+ verdict_level,
41
+ )
33
42
 
34
43
  from .hierarchy import join_frames, joinable, joined_levels
35
44
  from .load import (
@@ -589,6 +598,7 @@ class ScidbSource(BaseSource):
589
598
  *,
590
599
  x_measure: str | None = None,
591
600
  factor_variables: list[FactorVariable] | None = None,
601
+ where_check: WhereCheck | None = None,
592
602
  ) -> LongTable:
593
603
  """
594
604
  Build the long table for a plot's variables.
@@ -646,6 +656,11 @@ class ScidbSource(BaseSource):
646
656
  f"their own: they cannot stack with another variable or pair with "
647
657
  f"an x measure."
648
658
  )
659
+ if where_check and len(measures) > 1:
660
+ raise ValueError(
661
+ "A where= check looks at ONE variable's locations; "
662
+ f"got {measures}. Remove the variant rows that add other variables."
663
+ )
649
664
  if len(measures) > 1:
650
665
  return self._stacked_table(measures, factor_variables)
651
666
 
@@ -721,6 +736,11 @@ class ScidbSource(BaseSource):
721
736
  frame, group_depths = self._attach_groupings(
722
737
  frame, levels, factor_variables, own
723
738
  )
739
+ check_factors: list[str] = []
740
+ if where_check:
741
+ frame, check_factors = self._attach_where_check(
742
+ frame, levels, where_check, measures[0]
743
+ )
724
744
 
725
745
  # Variant columns first, and code versions lead within them (see
726
746
  # `attach_variants`). The variants are what a reader has to make a
@@ -732,6 +752,7 @@ class ScidbSource(BaseSource):
732
752
  # Keys: the attached factor names, in the order they were joined.
733
753
  factors.extend(group_depths)
734
754
  factors.extend(c for c in field_columns if c in frame.columns)
755
+ factors.extend(check_factors)
735
756
  factor_origins = {axis["column"]: axis for axis in variant_axes}
736
757
  factor_depths = dict(group_depths)
737
758
 
@@ -739,6 +760,9 @@ class ScidbSource(BaseSource):
739
760
  name: self._level_order(name, frame, is_field=name in field_columns)
740
761
  for name in factors
741
762
  }
763
+ for name in check_factors:
764
+ present = set(frame[name].unique())
765
+ level_order[name] = [lv for lv in LEVEL_ORDER if lv in present]
742
766
 
743
767
  table = LongTable.from_frame(
744
768
  frame,
@@ -771,6 +795,77 @@ class ScidbSource(BaseSource):
771
795
  table.absent = self._absent_locations(frame, levels)
772
796
  return table
773
797
 
798
+ def _attach_where_check(self, frame, levels: list[str], check: WhereCheck, target: str):
799
+ """The where= check's factor columns: ``Matching`` plus, for two or
800
+ more filters, one per filter.
801
+
802
+ The verdicts are scidb's (``filter_report``); this only joins them
803
+ onto the rows by schema key, as text on both sides (a key's spelling
804
+ differs between the frame and ``_schema``). A row at a location the
805
+ report does not know, or whose verdict is "no value", says so: it is
806
+ never dropped (the same promise as :data:`MISSING_LEVEL`).
807
+ Logs the counts the plan asks for under ``[where_check]``.
808
+ """
809
+ from scidb.model.filters import VERDICT_PREFIX, filter_report, is_blank_filter_dict
810
+ from scidb.model.variable import BaseVariable
811
+
812
+ rows = [f for f in check.filters if not is_blank_filter_dict(f.filter_dict())]
813
+ if not rows:
814
+ return frame, []
815
+ variable = base_variable(target)
816
+ target_class = BaseVariable._all_subclasses.get(variable)
817
+ if target_class is None:
818
+ raise ValueError(f"Cannot check where= on '{variable}': not a known variable.")
819
+ report, keys = filter_report(
820
+ self._db,
821
+ target_class,
822
+ [f.filter_dict() for f in rows],
823
+ BaseVariable._all_subclasses.get,
824
+ )
825
+ on = [k for k in levels if k in report.columns and k in frame.columns]
826
+ verdict_columns = [f"{VERDICT_PREFIX}{n}" for n in range(len(rows))]
827
+ right = report[[*on, *verdict_columns]].copy()
828
+ temp = {k: f"__where_key_{k}" for k in on}
829
+ for k in on:
830
+ right[temp[k]] = right[k].astype(object).map(lambda v: None if v is None else str(v))
831
+ right = right.drop(columns=on).drop_duplicates(subset=list(temp.values()))
832
+ left = frame.copy()
833
+ for k in on:
834
+ left[temp[k]] = left[k].astype(object).map(lambda v: None if v is None else str(v))
835
+ joined = left.merge(right, on=list(temp.values()), how="left")
836
+ joined = joined.drop(columns=list(temp.values()))
837
+ for col in verdict_columns:
838
+ joined[col] = joined[col].fillna("no value")
839
+
840
+ enabled_columns = [c for c, f in zip(verdict_columns, rows, strict=True) if f.enabled]
841
+ names = [MATCHING_FACTOR]
842
+ if len(rows) > 1:
843
+ names.extend(filter_factor_name(n) for n in range(len(rows)))
844
+ clash = [n for n in names if n in frame.columns]
845
+ if clash:
846
+ raise ValueError(
847
+ f"A where= check would add column(s) {clash}, which this table already has."
848
+ )
849
+ if enabled_columns:
850
+ joined[MATCHING_FACTOR] = [
851
+ matching_verdict(list(v)) for v in joined[enabled_columns].itertuples(index=False)
852
+ ]
853
+ else:
854
+ joined[MATCHING_FACTOR] = LEVEL_YES
855
+ if len(rows) > 1:
856
+ for column, name in zip(verdict_columns, names[1:], strict=True):
857
+ joined[name] = joined[column].map(verdict_level)
858
+ joined = joined.drop(columns=verdict_columns)
859
+ Log.info(
860
+ "[where_check] target=%s filters=%s rows=%d matching=%s",
861
+ variable,
862
+ keys,
863
+ len(joined),
864
+ joined[MATCHING_FACTOR].value_counts().to_dict(),
865
+ layer=LAYER,
866
+ )
867
+ return joined, names
868
+
774
869
  def _absent_locations(self, frame, levels: list[str]):
775
870
  """The variable's "No record" locations (`scidb.provenance.inventory.
776
871
  absent_locations`, the owner) as a frame of its schema-key columns:
@@ -1,148 +0,0 @@
1
- """
2
- The shared design of a linked figure and table: one owner
3
- (docs/claude/studio-unification.md, user decision 2026-11-01).
4
-
5
- A saved plot and the StatStudio tables linked to it used to each keep their
6
- own copy of the design, with "Sync to…" banners to copy one onto the other.
7
- Now the design of a linked pair lives in ONE row set here, keyed by the
8
- saved plot's ``plot_id``. Either studio writes it; both read it on open, and
9
- an edit in one reaches the other through the GUI's broadcast.
10
-
11
- What the design is, field by field, is still
12
- :data:`scistackplot.model.design.DESIGN_FIELDS`. This store keeps a whole
13
- ``PlotSpec`` dict (so it reads back through ``restore_spec``) but only its
14
- design fields are ever applied (:func:`apply_design`, through
15
- ``copy_design``). Display settings stay with each artifact.
16
-
17
- **A design exists only once something is linked.** :func:`link_design` is
18
- called when a StatStudio table is set up from a saved plot. An unlinked plot
19
- has no row here and its saved envelope stays the owner of its design.
20
-
21
- Rows are the shared ``VersionedStore`` (append-only, never deleted): the
22
- item's NAME is the plot id, so "the design of plot X" is a name lookup, and
23
- each change is a new version. A write that would not change the design
24
- (same ``design_fingerprint``) appends nothing.
25
- """
26
-
27
- from __future__ import annotations
28
-
29
- from dataclasses import dataclass
30
- from typing import Any
31
-
32
- from scistacklog import Log
33
-
34
- from scidb.store.versioned_store import VersionedStore
35
-
36
- LAYER = "scistackplotdb"
37
-
38
- TABLE = "_plot_design"
39
-
40
- ENVELOPE_FORMAT = 1
41
-
42
-
43
- class DesignError(ValueError):
44
- """A design that cannot be stored or read as asked."""
45
-
46
-
47
- STORE = VersionedStore(
48
- table=TABLE,
49
- id_column="design_id",
50
- scope_column=None,
51
- noun="shared design",
52
- tag="design",
53
- error=DesignError,
54
- owner="scistackplotdb",
55
- )
56
-
57
-
58
- @dataclass(frozen=True)
59
- class StoredDesign:
60
- plot_id: str
61
- design_id: str
62
- version: int
63
- #: The stored spec (a full PlotSpec; only its design fields apply).
64
- spec: Any
65
- fingerprint: str
66
-
67
-
68
- def _row_for(db, plot_id: str):
69
- if not plot_id:
70
- return None
71
- return STORE.visible_by_name(db, None, plot_id)
72
-
73
-
74
- def load_design(db, plot_id: str) -> StoredDesign | None:
75
- """The newest shared design of saved plot *plot_id*, or None when it is
76
- not linked to anything (or the row cannot be read)."""
77
- from scistackplot import restore_spec
78
- from scistackplot.model.design import design_fingerprint
79
-
80
- row = _row_for(db, plot_id)
81
- if row is None:
82
- return None
83
- _, text = STORE.load(db, row[0])
84
- envelope = STORE.parse_envelope(text, f"design of {plot_id[:8]}")
85
- raw = envelope.get("spec")
86
- if not isinstance(raw, dict):
87
- Log.warn("[design] %s: stored design has no spec; ignoring it", plot_id[:8], layer=LAYER)
88
- return None
89
- restored = restore_spec(raw, fallback_measure=(raw.get("measures") or [None])[0])
90
- for note in restored.notes:
91
- Log.info("[design] %s: restore note: %s", plot_id[:8], getattr(note, "message", note), layer=LAYER)
92
- spec = restored.spec
93
- return StoredDesign(plot_id, row[0], row[3], spec, design_fingerprint(spec))
94
-
95
-
96
- def is_linked(db, plot_id: str | None) -> bool:
97
- return bool(plot_id) and _row_for(db, plot_id) is not None
98
-
99
-
100
- def save_design(db, plot_id: str, spec) -> tuple[StoredDesign, bool]:
101
- """Write *spec*'s design as the shared design of *plot_id*.
102
-
103
- Returns ``(stored, changed)``. When the design fields are the same as
104
- the newest stored version, nothing is appended and ``changed`` is
105
- False, so a broadcast echo between two open studios stops here.
106
- """
107
- from scistackplot.model.design import design_fingerprint
108
-
109
- if not plot_id:
110
- raise DesignError("A shared design needs the saved plot it belongs to.")
111
- fingerprint = design_fingerprint(spec)
112
- current = load_design(db, plot_id)
113
- if current is not None and current.fingerprint == fingerprint:
114
- Log.debug("[design] %s: unchanged (fingerprint %s); nothing appended", plot_id[:8], fingerprint,
115
- layer=LAYER)
116
- return current, False
117
- envelope = {"format": ENVELOPE_FORMAT, "plot_id": plot_id, "spec": spec.to_dict()}
118
- row, is_new = STORE.save(db, None, plot_id, envelope, overwrite=True, current_id=None,
119
- on_clash=lambda r: DesignError(f"design clash for {plot_id}"))
120
- Log.info("[design] %s: %s version %d (fingerprint %s)", plot_id[:8],
121
- "linked, first" if is_new else "changed, new", row[3], fingerprint, layer=LAYER)
122
- return StoredDesign(plot_id, row[0], row[3], spec, fingerprint), True
123
-
124
-
125
- def link_design(db, plot_id: str, spec) -> StoredDesign:
126
- """Make *plot_id*'s design shared, starting from *spec* when nothing is
127
- stored yet. An already-linked plot keeps its stored design."""
128
- current = load_design(db, plot_id)
129
- if current is not None:
130
- Log.info("[design] %s: already linked (version %d)", plot_id[:8], current.version, layer=LAYER)
131
- return current
132
- stored, _ = save_design(db, plot_id, spec)
133
- return stored
134
-
135
-
136
- def apply_design(db, plot_id: str | None, spec) -> tuple[Any, list, int | None]:
137
- """*spec* with the shared design of *plot_id* copied onto it
138
- (``copy_design``: design fields only, display kept). Unchanged, with
139
- version None, when *plot_id* is not linked."""
140
- from scistackplot.model.design import copy_design
141
-
142
- stored = load_design(db, plot_id) if plot_id else None
143
- if stored is None:
144
- return spec, [], None
145
- merged, notes = copy_design(stored.spec, spec)
146
- Log.info("[design] %s: applied version %d onto a %s spec (%d note(s))", plot_id[:8], stored.version,
147
- getattr(spec.kind, "value", spec.kind), len(notes), layer=LAYER)
148
- return merged, notes, stored.version
File without changes