framework-py 0.1.0.dev32__py3-none-any.whl → 0.1.0.dev34__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.
framework/__init__.py CHANGED
@@ -62,6 +62,7 @@ from framework.create import (
62
62
  project_create,
63
63
  project_create_from_layers,
64
64
  )
65
+ from framework.dags import dagitty, publish_dag
65
66
  from framework.data import data_add, data_read, data_save
66
67
  from framework.data_registry import pull_data_registry, push_data_registry
67
68
  from framework.display import TableDisplay, show_table
@@ -194,6 +195,7 @@ __all__ = [
194
195
  "config_sync",
195
196
  "configure_global",
196
197
  "connections_list",
198
+ "dagitty",
197
199
  "data_add",
198
200
  "data_info",
199
201
  "data_list",
@@ -248,6 +250,7 @@ __all__ = [
248
250
  "project_root",
249
251
  "project_unregister",
250
252
  "publish",
253
+ "publish_dag",
251
254
  "publish_data",
252
255
  "publish_dir",
253
256
  "publish_list",
framework/_artifacts.py CHANGED
@@ -1298,6 +1298,10 @@ def structured(source: Any) -> dict[str, Any] | None:
1298
1298
 
1299
1299
 
1300
1300
  def _structured(source: Any) -> dict[str, Any] | None:
1301
+ if _has_class(source, "networkx", "Graph"):
1302
+ from framework import dags
1303
+
1304
+ return dags.structured(source)
1301
1305
  frame = as_frame(source)
1302
1306
  if frame is not None:
1303
1307
  return _table_document(source, frame)
framework/catalog.py CHANGED
@@ -57,7 +57,8 @@ class DataInfo:
57
57
  private: Whether the file is in a private folder: one whose name
58
58
  contains private, confidential, or sensitive, at any depth below
59
59
  the project root.
60
- description: Shown when the data is read.
60
+ description: Optional description of the dataset, printed by ``data_read()``
61
+ when ``scaffold.print_description_on_read`` is ``true``.
61
62
  name: The catalog name, when the file was found by name.
62
63
  extra: Any other fields of the catalog entry.
63
64
  columns: With ``data_info(..., columns=True)``: one row per column, with its
framework/dags.py ADDED
@@ -0,0 +1,492 @@
1
+ """Causal diagrams (DAGs) as DAGitty model text, published to Framework Cloud.
2
+
3
+ A DAG is a ``framework.artifact/v1`` document with ``kind: "dag"``. Its ``dagitty`` field
4
+ holds DAGitty model text, which R's dagitty and ggdag and dagitty.net read. Framework Cloud
5
+ validates the graph, lays it out, and draws it, so this module only writes the text and
6
+ collects the labels, code, and analysis that ride along.
7
+
8
+ A graph comes from a ``networkx.DiGraph`` (or a subclass, such as pgmpy's ``DAG``) or
9
+ from DAGitty text. networkx is never imported: graphs are recognized by class name.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ import math
16
+ import re
17
+ import tempfile
18
+ from collections.abc import Iterable, Mapping
19
+ from pathlib import Path
20
+ from typing import Any
21
+
22
+ from framework.errors import FrameworkError
23
+
24
+ SCHEMA = "framework.artifact/v1"
25
+ KIND = "dag"
26
+ ROLES = ("exposure", "outcome", "latent", "adjusted", "selected")
27
+ MAX_NAME = 100
28
+ # Names DAGitty can read without quotes. Graph-type words are quoted so they never read
29
+ # as a header.
30
+ _BARE = re.compile(r"[A-Za-z_][A-Za-z0-9_.]*")
31
+ _KEYWORDS = {"dag", "pdag", "mag", "pag", "graph", "digraph", "node", "edge"}
32
+ _EFFECTS = ("total", "direct")
33
+ _Y = ("up", "down")
34
+
35
+
36
+ # ---------------------------------------------------------------------------
37
+ # DAGitty text
38
+
39
+
40
+ def _quote(name: str) -> str:
41
+ """A node name as DAGitty reads it: bare when it can be, else double-quoted."""
42
+ if _BARE.fullmatch(name) and name.lower() not in _KEYWORDS:
43
+ return name
44
+ return '"' + name.replace("\\", "\\\\").replace('"', '\\"') + '"'
45
+
46
+
47
+ def _number(value: float) -> str:
48
+ return str(int(value)) if value.is_integer() and abs(value) < 1e15 else format(value, ".10g")
49
+
50
+
51
+ def _name(node: Any) -> str:
52
+ name = str(node)
53
+ if not name or name != name.strip() or len(name) > MAX_NAME:
54
+ raise FrameworkError(
55
+ f"DAG variable names are 1 to {MAX_NAME} characters without leading or trailing "
56
+ f"spaces: {name!r}."
57
+ )
58
+ if any(ord(char) < 32 or ord(char) == 127 for char in name):
59
+ raise FrameworkError(f"DAG variable names can't hold control characters: {name!r}.")
60
+ return name
61
+
62
+
63
+ def _roles(name: str, value: Any) -> list[str]:
64
+ """A node's ``role`` attribute: one role or a list of them."""
65
+ if value is None:
66
+ return []
67
+ values = [value] if isinstance(value, str) else value
68
+ if not isinstance(values, Iterable):
69
+ raise FrameworkError(f'The role of {name} must be a string or a list, such as "exposure".')
70
+ roles = set()
71
+ for role in values:
72
+ if role not in ROLES:
73
+ raise FrameworkError(
74
+ f"{name} has the role {role!r}. A role is one of {', '.join(ROLES)}."
75
+ )
76
+ roles.add(role)
77
+ return [role for role in ROLES if role in roles]
78
+
79
+
80
+ def _position(name: str, value: Any) -> tuple[float, float] | None:
81
+ if value is None:
82
+ return None
83
+ try:
84
+ x, y = (float(part) for part in value)
85
+ except (TypeError, ValueError):
86
+ raise FrameworkError(
87
+ f"The position of {name} must be two numbers, such as (1, 0)."
88
+ ) from None
89
+ if not (math.isfinite(x) and math.isfinite(y)):
90
+ raise FrameworkError(f"The position of {name} must be two finite numbers.")
91
+ return x, y
92
+
93
+
94
+ def _cycle(nodes: list[str], edges: list[tuple[str, str, str]]) -> list[str] | None:
95
+ """A directed cycle as a path that ends where it starts, or None."""
96
+ children: dict[str, list[str]] = {name: [] for name in nodes}
97
+ for start, end, kind in edges:
98
+ if kind == "->":
99
+ children[start].append(end)
100
+ state: dict[str, int] = {}
101
+ for root in nodes:
102
+ if state.get(root):
103
+ continue
104
+ path = [root]
105
+ state[root] = 1
106
+ stack = [iter(children[root])]
107
+ while stack:
108
+ child = next(stack[-1], None)
109
+ if child is None:
110
+ state[path.pop()] = 2
111
+ stack.pop()
112
+ elif state.get(child) == 1:
113
+ return [*path[path.index(child) :], child]
114
+ elif not state.get(child):
115
+ state[child] = 1
116
+ path.append(child)
117
+ stack.append(iter(children[child]))
118
+ return None
119
+
120
+
121
+ class _Graph:
122
+ """A graph's nodes, roles, positions, labels, and edges, checked to be a DAG."""
123
+
124
+ def __init__(
125
+ self, source: Any, pos: Mapping[Any, Any] | None = None, y: str | None = None
126
+ ) -> None:
127
+ if not _is_digraph(source):
128
+ if _is_graph(source):
129
+ raise FrameworkError(
130
+ "This networkx graph is undirected. A DAG needs a networkx.DiGraph."
131
+ )
132
+ raise FrameworkError(
133
+ "A DAG is a networkx.DiGraph or DAGitty text, such as "
134
+ 'publish_dag("dag { x -> y }").'
135
+ )
136
+ if pos is not None and not isinstance(pos, Mapping):
137
+ raise FrameworkError("pos must map node names to (x, y) positions.")
138
+ y = "up" if y is None else y
139
+ if y not in _Y:
140
+ raise FrameworkError('y must be "up", as networkx draws, or "down", as DAGitty reads.')
141
+ # DAGitty's y points down. networkx and matplotlib draw y pointing up.
142
+ self.flip = y == "up"
143
+ latents = {str(node) for node in (getattr(source, "latents", None) or ())}
144
+ self.names: list[str] = []
145
+ self.roles: dict[str, list[str]] = {}
146
+ self.positions: dict[str, tuple[float, float] | None] = {}
147
+ self.labels: dict[str, str] = {}
148
+ names: dict[Any, str] = {}
149
+ for node, attributes in source.nodes(data=True):
150
+ name = _name(node)
151
+ if name in self.roles:
152
+ raise FrameworkError(f"Two nodes are both named {name}.")
153
+ names[node] = name
154
+ self.names.append(name)
155
+ roles = _roles(name, attributes.get("role"))
156
+ if name in latents and "latent" not in roles:
157
+ roles = [role for role in ROLES if role in {*roles, "latent"}]
158
+ self.roles[name] = roles
159
+ given = pos.get(node, pos.get(name)) if pos is not None else None
160
+ if given is None:
161
+ given = attributes.get("pos")
162
+ self.positions[name] = _position(name, given)
163
+ label = attributes.get("label")
164
+ if label is not None and str(label).strip():
165
+ self.labels[name] = str(label)
166
+ if pos is not None:
167
+ unknown = [str(key) for key in pos if key not in names and str(key) not in self.roles]
168
+ if unknown:
169
+ raise FrameworkError(
170
+ f"pos names nodes the graph doesn't have: {', '.join(unknown)}."
171
+ )
172
+ self.edges: list[tuple[str, str, str]] = []
173
+ seen: set[tuple[str, str, str]] = set()
174
+ for start, end, attributes in source.edges(data=True):
175
+ a, b = names[start], names[end]
176
+ if a == b:
177
+ raise FrameworkError(f"{a} points to itself. A DAG has no loops.")
178
+ if attributes.get("bidirected"):
179
+ a, b = sorted((a, b))
180
+ edge = (a, b, "<->")
181
+ else:
182
+ edge = (a, b, "->")
183
+ if edge not in seen:
184
+ seen.add(edge)
185
+ self.edges.append(edge)
186
+ cycle = _cycle(self.names, self.edges)
187
+ if cycle is not None:
188
+ raise FrameworkError(
189
+ f"The graph has a cycle: {' -> '.join(cycle)}. A DAG has none. "
190
+ "Mark an edge that stands for a latent common cause with bidirected=True."
191
+ )
192
+
193
+ def text(self) -> str:
194
+ lines = ["dag {"]
195
+ for name in self.names:
196
+ attributes = list(self.roles[name])
197
+ position = self.positions[name]
198
+ if position is not None:
199
+ x, y = position[0], -position[1] if self.flip else position[1]
200
+ attributes.append(f'pos="{_number(x)},{_number(y)}"')
201
+ lines.append(_quote(name) + (f" [{','.join(attributes)}]" if attributes else ""))
202
+ lines += [f"{_quote(a)} {kind} {_quote(b)}" for a, b, kind in self.edges]
203
+ lines.append("}")
204
+ return "\n".join(lines)
205
+
206
+
207
+ def _classes(source: Any) -> list[tuple[str, str]]:
208
+ return [(cls.__module__.split(".")[0], cls.__name__) for cls in type(source).__mro__]
209
+
210
+
211
+ def _is_digraph(source: Any) -> bool:
212
+ return ("networkx", "DiGraph") in _classes(source)
213
+
214
+
215
+ def _is_graph(source: Any) -> bool:
216
+ return ("networkx", "Graph") in _classes(source)
217
+
218
+
219
+ def dagitty(graph: Any, *, pos: Mapping[Any, Any] | None = None, y: str | None = None) -> str:
220
+ """DAGitty model text for a networkx graph.
221
+
222
+ ::
223
+
224
+ import networkx as nx
225
+
226
+ g = nx.DiGraph()
227
+ g.add_node("smoking", role="exposure", label="Smoking status")
228
+ g.add_node("cancer", role="outcome")
229
+ g.add_edges_from([("age", "smoking"), ("age", "cancer"), ("smoking", "cancer")])
230
+ print(fw.dagitty(g))
231
+
232
+ The text opens with ``dag {``, lists every node with its roles and position, then
233
+ every edge. R's dagitty and ggdag and dagitty.net read it. A name that isn't a plain
234
+ identifier, such as ``parental SES``, is double-quoted.
235
+
236
+ The graph's node and edge attributes say what DAGitty needs:
237
+
238
+ - ``role``: ``"exposure"``, ``"outcome"``, ``"latent"``, ``"adjusted"``, or
239
+ ``"selected"``, or a list of them. A pgmpy ``DAG``'s ``latents`` are latent too.
240
+ - ``pos``: an ``(x, y)`` position, as ``nx.draw(G, pos)`` takes it: y points up.
241
+ DAGitty's y points down, so y is negated in the text, and the drawing on
242
+ Framework Cloud matches ``nx.draw()``. ``y="down"`` writes positions as they are.
243
+ - ``label``: the name to show. ``dagitty()`` leaves labels out; ``publish_dag()``
244
+ sends them.
245
+ - ``bidirected=True`` on an edge: ``a <-> b``, a latent common cause. The edge's
246
+ direction doesn't matter, and it isn't part of the cycle check.
247
+
248
+ Args:
249
+ graph: A ``networkx.DiGraph``, or a subclass such as pgmpy's ``DAG``.
250
+ pos: Positions by node, such as ``{"age": (0, 0), "smoking": (1, 1)}`` or a
251
+ networkx layout. They win over ``pos`` node attributes.
252
+ y: Which way y points in the positions: ``"up"``, as networkx and matplotlib
253
+ draw, or ``"down"``, as DAGitty reads. Default: ``"up"``.
254
+
255
+ Returns:
256
+ The DAGitty model text.
257
+
258
+ Raises:
259
+ FrameworkError: The graph is undirected or has a directed cycle, a node points to
260
+ itself, or a role or position isn't valid.
261
+ """
262
+ return _Graph(graph, pos, y).text()
263
+
264
+
265
+ # ---------------------------------------------------------------------------
266
+ # The document
267
+
268
+
269
+ def _code(code: str | None) -> dict[str, str] | None:
270
+ if code is None:
271
+ return None
272
+ if not isinstance(code, str):
273
+ raise FrameworkError("code must be the Python code that built the graph, as a string.")
274
+ text = code.strip("\n")
275
+ return {"language": "python", "text": text} if text.strip() else None
276
+
277
+
278
+ def _labels(labels: Mapping[Any, Any] | None) -> dict[str, str]:
279
+ if labels is None:
280
+ return {}
281
+ if not isinstance(labels, Mapping):
282
+ raise FrameworkError('labels must map node names to labels: {"ses": "Parental SES"}.')
283
+ return {str(name): str(label) for name, label in labels.items()}
284
+
285
+
286
+ def _set(value: Any, what: str) -> list[str]:
287
+ if isinstance(value, str) or not isinstance(value, Iterable):
288
+ raise FrameworkError(f"{what} must be a list of node names.")
289
+ return [str(name) for name in value]
290
+
291
+
292
+ def _analysis(analysis: Mapping[str, Any] | None) -> dict[str, Any] | None:
293
+ """The producer's analysis, checked for shape. Framework computes none of it."""
294
+ if analysis is None:
295
+ return None
296
+ if not isinstance(analysis, Mapping):
297
+ raise FrameworkError('analysis must be a dict, such as {"adjustment_sets": [["age"]]}.')
298
+ unknown = sorted(set(analysis) - {"effect", "adjustment_sets", "implications"})
299
+ if unknown:
300
+ raise FrameworkError(
301
+ f"analysis takes effect, adjustment_sets, and implications, not {', '.join(unknown)}."
302
+ )
303
+ out: dict[str, Any] = {}
304
+ effect = analysis.get("effect")
305
+ if effect is not None:
306
+ if effect not in _EFFECTS:
307
+ raise FrameworkError('analysis["effect"] must be "total" or "direct".')
308
+ out["effect"] = effect
309
+ if analysis.get("adjustment_sets") is not None:
310
+ sets = analysis["adjustment_sets"]
311
+ if isinstance(sets, str) or not isinstance(sets, Iterable):
312
+ raise FrameworkError(
313
+ 'analysis["adjustment_sets"] must be a list of sets of node names: '
314
+ "[[]] when no adjustment is needed, [] when no set works."
315
+ )
316
+ out["adjustment_sets"] = [_set(item, "Each adjustment set") for item in sets]
317
+ if analysis.get("implications") is not None:
318
+ implications = []
319
+ for item in analysis["implications"]:
320
+ if not isinstance(item, Mapping) or "x" not in item or "y" not in item:
321
+ raise FrameworkError(
322
+ 'Each implication is {"x": "a", "y": "b", "given": ["c"]}: x is '
323
+ "independent of y given the nodes in given."
324
+ )
325
+ implications.append(
326
+ {
327
+ "x": str(item["x"]),
328
+ "y": str(item["y"]),
329
+ "given": _set(item.get("given") or [], "given"),
330
+ }
331
+ )
332
+ out["implications"] = implications
333
+ return out or None
334
+
335
+
336
+ def _document(
337
+ graph: Any,
338
+ *,
339
+ labels: Mapping[Any, Any] | None = None,
340
+ code: str | None = None,
341
+ analysis: Mapping[str, Any] | None = None,
342
+ pos: Mapping[Any, Any] | None = None,
343
+ y: str | None = None,
344
+ ) -> dict[str, Any]:
345
+ """The ``dag`` document for a graph or DAGitty text."""
346
+ shown = _labels(labels)
347
+ if isinstance(graph, Path):
348
+ if not graph.is_file():
349
+ raise FrameworkError(f"DAGitty file not found: {graph}")
350
+ graph = graph.read_text(encoding="utf-8")
351
+ if isinstance(graph, str):
352
+ if pos is not None:
353
+ raise FrameworkError('pos is for networkx graphs. In DAGitty text, write pos="x,y".')
354
+ if y not in (None, "down"):
355
+ raise FrameworkError("DAGitty text is sent as written, with y pointing down.")
356
+ text = graph.strip()
357
+ if not text:
358
+ raise FrameworkError("The DAGitty text is empty.")
359
+ source: dict[str, Any] = {"language": "python"}
360
+ else:
361
+ parsed = _Graph(graph, pos, y)
362
+ unknown = sorted(set(shown) - set(parsed.names))
363
+ if unknown:
364
+ raise FrameworkError(
365
+ f"labels names nodes the graph doesn't have: {', '.join(unknown)}."
366
+ )
367
+ shown = {**parsed.labels, **shown}
368
+ text = parsed.text()
369
+ source = {
370
+ "language": "python",
371
+ "class": [
372
+ f"{cls.__module__}.{cls.__name__}"
373
+ for cls in type(graph).__mro__
374
+ if cls is not object
375
+ ],
376
+ }
377
+ document: dict[str, Any] = {"schema": SCHEMA, "kind": KIND, "source": source, "dagitty": text}
378
+ if shown:
379
+ document["labels"] = shown
380
+ written = _code(code)
381
+ if written is not None:
382
+ document["code"] = written
383
+ checked = _analysis(analysis)
384
+ if checked is not None:
385
+ document["analysis"] = checked
386
+ return document
387
+
388
+
389
+ def structured(graph: Any) -> dict[str, Any]:
390
+ """The document ``publish()`` sends for a networkx graph."""
391
+ return _document(graph)
392
+
393
+
394
+ # ---------------------------------------------------------------------------
395
+ # Publishing
396
+
397
+
398
+ def publish_dag(
399
+ graph: Any,
400
+ *,
401
+ labels: Mapping[Any, Any] | None = None,
402
+ code: str | None = None,
403
+ analysis: Mapping[str, Any] | None = None,
404
+ pos: Mapping[Any, Any] | None = None,
405
+ y: str | None = None,
406
+ slug: str | None = None,
407
+ title: str | None = None,
408
+ description: str | None = None,
409
+ visibility: str | None = None,
410
+ password: str | None = None,
411
+ collection: str | int | None = None,
412
+ share_unlisted: bool = False,
413
+ to: str | None = None,
414
+ include_private: bool = False,
415
+ ) -> str | list[str]:
416
+ """Publish a causal diagram (DAG) to Framework Cloud.
417
+
418
+ ::
419
+
420
+ g = nx.DiGraph()
421
+ g.add_node("education", role="exposure")
422
+ g.add_node("health", role="outcome")
423
+ g.add_edges_from([("income", "education"), ("income", "health"),
424
+ ("education", "health")])
425
+ fw.publish_dag(g, slug="education-health", code=CODE,
426
+ analysis={"adjustment_sets": [["income"]]})
427
+
428
+ fw.publish_dag("dag { smoking [exposure] cancer [outcome] smoking -> cancer }",
429
+ slug="smoking")
430
+
431
+ A ``networkx.DiGraph`` becomes DAGitty text as ``dagitty()`` writes it: roles,
432
+ positions, and labels come from node attributes, and ``bidirected=True`` on an edge
433
+ makes it ``<->``. Positions are read as ``nx.draw(G, pos)`` reads them, with y
434
+ pointing up, so the drawing on Framework Cloud matches. A string is DAGitty text,
435
+ sent as it is, with DAGitty's y pointing down; a ``Path`` names a ``.dagitty`` file.
436
+ ``publish(graph)`` publishes a networkx graph too, without code or analysis.
437
+
438
+ Framework Cloud checks the graph, lays it out, and draws it, with the DAGitty text
439
+ and the code to copy. A graph with a cycle, an undirected edge, more than 100 nodes,
440
+ or more than 400 edges is refused. Framework computes no adjustment sets or
441
+ implications. Pass what another tool found in ``analysis``.
442
+
443
+ Args:
444
+ graph: A ``networkx.DiGraph`` (or pgmpy ``DAG``), DAGitty text, or a ``Path`` to a
445
+ ``.dagitty`` file.
446
+ labels: Display labels by node name. They win over ``label`` node attributes.
447
+ code: The Python code that built the graph, shown with it.
448
+ analysis: What the producer computed: ``effect`` (``"total"`` or ``"direct"``),
449
+ ``adjustment_sets`` (a list of lists of names: ``[[]]`` when no adjustment is
450
+ needed, ``[]`` when no set works), and ``implications`` (``{"x", "y",
451
+ "given"}`` conditional independencies).
452
+ pos: Positions by node, such as ``{"age": (0, 0)}`` or a networkx layout. For
453
+ networkx graphs.
454
+ y: Which way y points in a graph's positions: ``"up"``, as networkx and
455
+ matplotlib draw, or ``"down"``, as DAGitty reads. Default: ``"up"``.
456
+ DAGitty text is always read with y pointing down.
457
+ slug: Artifact slug. Default: from ``title``, else ``dag``. Name each DAG, or a
458
+ second one publishes as a new version of the first.
459
+ title: Artifact title. Default: the slug.
460
+ description: Artifact description.
461
+ visibility: "public", "unlisted", or "private". Default: a new artifact is
462
+ unlisted and an existing one keeps its setting.
463
+ password: Password required to view the DAG.
464
+ collection: Project collection ID or slug.
465
+ share_unlisted: Allow collection readers to see an unlisted DAG.
466
+ to: A configured destination name, or "cloud".
467
+ include_private: Publish without asking about private folders.
468
+
469
+ Returns:
470
+ The artifact's URL.
471
+ """
472
+ from framework.publish_bundle import artifact_slug
473
+ from framework.storage import publish
474
+
475
+ document = _document(graph, labels=labels, code=code, analysis=analysis, pos=pos, y=y)
476
+ slug = slug or (artifact_slug(title) if title else None)
477
+ with tempfile.TemporaryDirectory(prefix="fw_dag_") as temp:
478
+ path = Path(temp) / "dag.json"
479
+ path.write_text(json.dumps(document, ensure_ascii=False, indent=2), encoding="utf-8")
480
+ return publish(
481
+ path,
482
+ kind=KIND,
483
+ slug=slug,
484
+ title=title,
485
+ description=description,
486
+ visibility=visibility,
487
+ password=password,
488
+ collection=collection,
489
+ share_unlisted=share_unlisted,
490
+ to=to,
491
+ include_private=include_private,
492
+ )
framework/data.py CHANGED
@@ -363,6 +363,12 @@ def data_read(
363
363
  later read. A changed locked file raises ``IntegrityError``. A changed
364
364
  unlocked file issues a ``DataChangedWarning``.
365
365
 
366
+ With ``print_description_on_read: true`` under ``scaffold:`` in
367
+ ``settings/scaffold.yml`` (or ``settings.yml``), ``data_read()`` prints a
368
+ catalog entry's ``description`` on each read as
369
+ ``Note: <name>: <description>``. Printing is off by default.
370
+ ``data_list()`` always shows descriptions.
371
+
366
372
  Args:
367
373
  path: A catalog name such as ``"inputs.raw.survey"``, or a file path. A relative
368
374
  path is looked for from the project root, then from the current folder.
@@ -429,13 +435,29 @@ def data_read(
429
435
  _check_integrity(path, info)
430
436
 
431
437
  data = read_file(info, delim, keep_attributes, r_args, kwargs)
432
- if info.description:
438
+ if info.description and _print_description_on_read():
433
439
  inform(f"Note: {path}: {info.description}")
434
440
  if info.private or is_private_data(info.path, _root_or_none()):
435
441
  note_private_read(path)
436
442
  return data
437
443
 
438
444
 
445
+ def _print_description_on_read() -> bool:
446
+ """Whether data_read() prints a catalog entry's description, as R does.
447
+
448
+ Off unless the project sets ``print_description_on_read: true`` under
449
+ ``scaffold:`` (settings/scaffold.yml), ``options:``, or the top level.
450
+ """
451
+ try:
452
+ config = settings_read()
453
+ except FrameworkError:
454
+ return False
455
+ for section in (config.get("scaffold"), config.get("options"), config):
456
+ if isinstance(section, dict) and section.get("print_description_on_read") is not None:
457
+ return section["print_description_on_read"] is True
458
+ return False
459
+
460
+
439
461
  def _catalog_entry(name: str) -> DataInfo | None:
440
462
  """The catalog entry ``name`` already has, or None."""
441
463
  try:
framework/storage.py CHANGED
@@ -469,7 +469,7 @@ def _publish_legacy(
469
469
  with tempfile.TemporaryDirectory(prefix="fw_artifact_") as temp:
470
470
  is_cloud = to != "github" and _target(connection, to) == "cloud"
471
471
  path = _artifact_file(source, Path(temp), cloud=is_cloud)
472
- if kind is None and is_cloud and path.name in ("table.json", "model.json"):
472
+ if kind is None and is_cloud and path.name in ("table.json", "model.json", "dag.json"):
473
473
  kind = path.stem
474
474
  return _publish_legacy(
475
475
  path,
@@ -567,6 +567,7 @@ def publish(
567
567
  (every row is kept), tests and models become structured summaries, and static
568
568
  plots become SVG. Model exports carry coefficients, importance, and fit
569
569
  statistics, never observations, residuals, posterior draws, or serialized models.
570
+ A ``networkx.DiGraph`` becomes a DAG (see ``publish_dag()``).
570
571
  Buckets receive CSV tables, PNG figures, and HTML model summaries; Styler tables,
571
572
  plotly figures, and altair charts keep their HTML or Vega-Lite form everywhere.
572
573
  dest: Where to put it in the bucket. Default: the source's name.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: framework-py
3
- Version: 0.1.0.dev32
3
+ Version: 0.1.0.dev34
4
4
  Summary: Structured data science projects: a data catalog, integrity tracking, caching, outputs, and AI guardrails
5
5
  Project-URL: Homepage, https://framework.pub
6
6
  Project-URL: Source, https://github.com/frameworktools/framework-py
@@ -1,7 +1,7 @@
1
- framework/__init__.py,sha256=9nN8wRdlk8AgmpRqSk-bLpxXgr6Go42UnRMWQ6szP-A,6898
1
+ framework/__init__.py,sha256=oNThlKgpfAON6v0upCbudEDfJeFxQ8EPw8v6ch79-PQ,6980
2
2
  framework/__main__.py,sha256=S0ChmRQnNa9W5_MPXhHnH61Kjr_pNthkeS41eJU1w0U,9093
3
3
  framework/_agents_md.py,sha256=yI_8YYF3D3zqNNZs5skzGQMLTgL9KH35L_Ben_vUY5I,15803
4
- framework/_artifacts.py,sha256=XjYOBQOQJuvztUyqwWsc3xc1qJ5o4O5XpCW49WN548k,55807
4
+ framework/_artifacts.py,sha256=Svc2m3vR4_g5FlT7U0EF5OtDQj89fGi6IJUevLS8Wjk,55930
5
5
  framework/_backups.py,sha256=ra1DhGcIbIXB0zqDFVFJ3yPEjmXpYKFX-fjV01b9Rtg,1958
6
6
  framework/_bayesian.py,sha256=Yx8deM_LWsfPPM8n3rX7b1R9L1qcdeaDU2aUIZZyhB4,23675
7
7
  framework/_csv.py,sha256=oAaLUChyUsHJsh0YuUDt0viC8SAImMgUseNKGk7kLXo,4855
@@ -26,13 +26,14 @@ framework/adopt.py,sha256=oOfpfwo8ehTMDthctihGHi11sEg8StQ3R_85Bq-oq8Y,33441
26
26
  framework/ai.py,sha256=QTPbzGSGneRngZd9l7D7nJIUCraG7CWgz-v7BLbLiRg,8840
27
27
  framework/bootstrap.py,sha256=1UaLpzui-wJ4D6-b8-YN2-e4eMPtavVKsmnj6scoWWQ,10606
28
28
  framework/cache.py,sha256=z8Zaem5Q7dsAghuX9CgK_j0vhX5dDlRw7fl9f-CF3eA,17440
29
- framework/catalog.py,sha256=sl4V1judSCVoa2LYLXeQdDhWdsONTC_5s2_fpyPylto,13202
29
+ framework/catalog.py,sha256=UNyMj7g_iTBcQnFq_uwRAL4tlNh1NUDunrTtX4BfOBg,13306
30
30
  framework/cloud.py,sha256=juhTsfhiinvxwnpScEJoIDjw_Ytdk6njCk26WhLmqFk,68171
31
31
  framework/config_home.py,sha256=iSb0VuENgNOSnsZ_v53xFqjRiGgrB7OzZbHbyDOqKzs,8265
32
32
  framework/connections.py,sha256=99JqrNAi2zBpNYyxLV6SYj-NAJjh56pYh9jaMSYOHCU,32742
33
33
  framework/console.py,sha256=zQ0LuFDcxe1W1kuc5E1bJ03h8d3cvwFoqDT8dAJQyN0,1267
34
34
  framework/create.py,sha256=KSODHvnRFrSha79LH-0e4o1y_3e1ZjbTrjCDzQbhbYk,54728
35
- framework/data.py,sha256=HpiRl5qTk1o9G-XXNDgsWhNOgXlyYegv8-8KDz-HyPA,40853
35
+ framework/dags.py,sha256=I00zMb10ZUGWUw3P9P1zOW14GxfO-pUtQ97Y5cZx9pY,20134
36
+ framework/data.py,sha256=jWWkUeLey_FxOafsFrwKhoJoVXb9NguNcjhsd_laDL0,41817
36
37
  framework/data_registry.py,sha256=QrFki_-zd7gF4afOesYPAn7xZEvnhYolhxtz_0bsaSA,22477
37
38
  framework/db.py,sha256=UYEUCvk4vGytBkmdNTUxRpYPtoFSDHwTpgpfWFw31aE,8522
38
39
  framework/display.py,sha256=0FuKUt67uf5h1WjD4bwzoruc2XAN4y_j3mz_f5FskhE,5334
@@ -56,7 +57,7 @@ framework/settings.py,sha256=Sb2YyE53aYLWPj423P-pQVCvRpLsiHydgZh2K0luTQQ,23893
56
57
  framework/skill_pull.py,sha256=BsprrVhv4khrXQJupAChLi_s0qJLmA0KBrfrTD6A_9k,75964
57
58
  framework/skill_sync.py,sha256=2xPcEIN_ftjX4QpA4ZkRzjFHS9rkoIHcnKPO59eKr8U,35813
58
59
  framework/snippets.py,sha256=J8j36YqHgG-HhWlhJ9RmJK-qwVGOOSOOd1pNakJyuVE,26481
59
- framework/storage.py,sha256=Haz8CBXrz2CCqGHOVgHKC3mUUwobnod2SanU759lK7c,56115
60
+ framework/storage.py,sha256=ohF5OT2EJoMYMJHuLJGhv3pnapxEsRnpjW3RH_xoBK0,56201
60
61
  framework/sync_all.py,sha256=hcp-EYI8OVV9l40S4S8Iu0-2k7CUbF6faBcrRD3Up3M,36757
61
62
  framework/upgrade.py,sha256=vMtL9_04LgJ4AHj6EXg5PmV3n699XvFNj820Auqa0hM,66546
62
63
  framework/_assets/init.sql,sha256=-aIiuIcCmBniGKq-CHdRtUiV9e_CLXoqxxd05snmgOE,1156
@@ -142,7 +143,7 @@ framework/templates/stubs/notebook-default.qmd,sha256=8Js1S2BcHYeQWmJS-kt31gBvIj
142
143
  framework/templates/stubs/notebook-minimal.qmd,sha256=2U2k8judffhrh_6m6r6OAbQBCYEtViAjeKRBqBYCJTM,178
143
144
  framework/templates/stubs/notebook-revealjs.qmd,sha256=_ztT_gHoudpB5DIjlbvtB5zQ8163DeV8xbWcT-HgJrI,409
144
145
  framework/templates/stubs/script-default.py,sha256=vbWqgW0_rHot17mQC3tYb92g_9L-cbTOeL3y99BRrSk,216
145
- framework_py-0.1.0.dev32.dist-info/METADATA,sha256=CpgnkL5A1C0o0M_ttMUnoUp9mONllnbc3Hjq33-mbns,5143
146
- framework_py-0.1.0.dev32.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
147
- framework_py-0.1.0.dev32.dist-info/licenses/LICENSE,sha256=giOOgSwALkZimC7uhLZQK8Untez641bLW1-2-Cjvmq0,1072
148
- framework_py-0.1.0.dev32.dist-info/RECORD,,
146
+ framework_py-0.1.0.dev34.dist-info/METADATA,sha256=gcsZlhWG0LmoOntREDlWlXad4fpHbJ0I7WZqSeN9ZIs,5143
147
+ framework_py-0.1.0.dev34.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
148
+ framework_py-0.1.0.dev34.dist-info/licenses/LICENSE,sha256=giOOgSwALkZimC7uhLZQK8Untez641bLW1-2-Cjvmq0,1072
149
+ framework_py-0.1.0.dev34.dist-info/RECORD,,