framework-py 0.1.0.dev33__py3-none-any.whl → 0.1.0.dev35__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 +3 -0
- framework/_artifacts.py +4 -0
- framework/cloud.py +53 -1
- framework/dags.py +498 -0
- framework/snippets.py +25 -2
- framework/storage.py +45 -1
- {framework_py-0.1.0.dev33.dist-info → framework_py-0.1.0.dev35.dist-info}/METADATA +1 -1
- {framework_py-0.1.0.dev33.dist-info → framework_py-0.1.0.dev35.dist-info}/RECORD +10 -9
- {framework_py-0.1.0.dev33.dist-info → framework_py-0.1.0.dev35.dist-info}/WHEEL +0 -0
- {framework_py-0.1.0.dev33.dist-info → framework_py-0.1.0.dev35.dist-info}/licenses/LICENSE +0 -0
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/cloud.py
CHANGED
|
@@ -1139,6 +1139,54 @@ def _publish_collection(
|
|
|
1139
1139
|
return selected
|
|
1140
1140
|
|
|
1141
1141
|
|
|
1142
|
+
# What an artifact's embeds show, set per artifact on Framework Cloud. Every setting is on
|
|
1143
|
+
# by default; publishing changes only the settings it names.
|
|
1144
|
+
DISPLAY_KEYS = (
|
|
1145
|
+
"title",
|
|
1146
|
+
"description",
|
|
1147
|
+
"author",
|
|
1148
|
+
"details",
|
|
1149
|
+
"variable_tips",
|
|
1150
|
+
"column_summaries",
|
|
1151
|
+
"output",
|
|
1152
|
+
"links",
|
|
1153
|
+
"legend",
|
|
1154
|
+
"analysis",
|
|
1155
|
+
"dagitty",
|
|
1156
|
+
"code",
|
|
1157
|
+
"interactive",
|
|
1158
|
+
)
|
|
1159
|
+
|
|
1160
|
+
|
|
1161
|
+
def display_settings(display: Mapping[str, bool] | None) -> str | None:
|
|
1162
|
+
"""``display`` as the JSON text Framework Cloud takes, or None when it isn't given.
|
|
1163
|
+
|
|
1164
|
+
Raises:
|
|
1165
|
+
FrameworkError: ``display`` isn't a dict of known setting names to True or False.
|
|
1166
|
+
"""
|
|
1167
|
+
if display is None:
|
|
1168
|
+
return None
|
|
1169
|
+
keys = ", ".join(DISPLAY_KEYS)
|
|
1170
|
+
if not isinstance(display, Mapping):
|
|
1171
|
+
raise FrameworkError(
|
|
1172
|
+
f'display must be a dict of settings to True or False, such as {{"analysis": False}}. '
|
|
1173
|
+
f"Settings: {keys}."
|
|
1174
|
+
)
|
|
1175
|
+
unknown = [str(key) for key in display if key not in DISPLAY_KEYS]
|
|
1176
|
+
if unknown:
|
|
1177
|
+
raise FrameworkError(f"Unknown display setting: {', '.join(unknown)}. Settings: {keys}.")
|
|
1178
|
+
wrong = [str(key) for key, value in display.items() if not isinstance(value, bool)]
|
|
1179
|
+
if wrong:
|
|
1180
|
+
raise FrameworkError(f"display values must be True or False: {', '.join(wrong)}.")
|
|
1181
|
+
return json.dumps(dict(display), separators=(",", ":"))
|
|
1182
|
+
|
|
1183
|
+
|
|
1184
|
+
def display_ignored(display: Mapping[str, bool] | None, where: str) -> None:
|
|
1185
|
+
"""Say that ``display`` was left out, for a destination other than Framework Cloud."""
|
|
1186
|
+
if display is not None:
|
|
1187
|
+
inform(f"display applies on Framework Cloud only; {where} ignores it.")
|
|
1188
|
+
|
|
1189
|
+
|
|
1142
1190
|
def cloud_publish(
|
|
1143
1191
|
source: Path,
|
|
1144
1192
|
dest: str | None = None,
|
|
@@ -1152,6 +1200,7 @@ def cloud_publish(
|
|
|
1152
1200
|
visibility: str | None = None,
|
|
1153
1201
|
collection: str | int | None = None,
|
|
1154
1202
|
share_unlisted: bool = False,
|
|
1203
|
+
display: Mapping[str, bool] | None = None,
|
|
1155
1204
|
) -> str:
|
|
1156
1205
|
"""Publish a file, rendered HTML folder, or notebook to the project cloud server.
|
|
1157
1206
|
|
|
@@ -1162,8 +1211,10 @@ def cloud_publish(
|
|
|
1162
1211
|
``True`` turns the readable URL on with the derived name, and ``False`` turns it off.
|
|
1163
1212
|
Pass ``visibility="public"`` to make an artifact public. An explicit ``visibility``
|
|
1164
1213
|
always wins over ``True`` and ``False``. A source in a private folder needs
|
|
1165
|
-
confirmation, or ``include_private=True``.
|
|
1214
|
+
confirmation, or ``include_private=True``. ``display`` changes the embed settings it
|
|
1215
|
+
names (see ``DISPLAY_KEYS``) and leaves the others alone.
|
|
1166
1216
|
"""
|
|
1217
|
+
shown = display_settings(display)
|
|
1167
1218
|
sources = [source]
|
|
1168
1219
|
if source.is_dir():
|
|
1169
1220
|
sources = sorted(p for p in source.rglob("*") if p.is_file())
|
|
@@ -1246,6 +1297,7 @@ def cloud_publish(
|
|
|
1246
1297
|
("kind", kind),
|
|
1247
1298
|
("password", password),
|
|
1248
1299
|
("visibility", visibility),
|
|
1300
|
+
("display", shown),
|
|
1249
1301
|
):
|
|
1250
1302
|
if value is not None:
|
|
1251
1303
|
data[key] = value
|
framework/dags.py
ADDED
|
@@ -0,0 +1,498 @@
|
|
|
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
|
+
display: Mapping[str, bool] | None = None,
|
|
416
|
+
) -> str | list[str]:
|
|
417
|
+
"""Publish a causal diagram (DAG) to Framework Cloud.
|
|
418
|
+
|
|
419
|
+
::
|
|
420
|
+
|
|
421
|
+
g = nx.DiGraph()
|
|
422
|
+
g.add_node("education", role="exposure")
|
|
423
|
+
g.add_node("health", role="outcome")
|
|
424
|
+
g.add_edges_from([("income", "education"), ("income", "health"),
|
|
425
|
+
("education", "health")])
|
|
426
|
+
fw.publish_dag(g, slug="education-health", code=CODE,
|
|
427
|
+
analysis={"adjustment_sets": [["income"]]})
|
|
428
|
+
|
|
429
|
+
fw.publish_dag("dag { smoking [exposure] cancer [outcome] smoking -> cancer }",
|
|
430
|
+
slug="smoking")
|
|
431
|
+
|
|
432
|
+
A ``networkx.DiGraph`` becomes DAGitty text as ``dagitty()`` writes it: roles,
|
|
433
|
+
positions, and labels come from node attributes, and ``bidirected=True`` on an edge
|
|
434
|
+
makes it ``<->``. Positions are read as ``nx.draw(G, pos)`` reads them, with y
|
|
435
|
+
pointing up, so the drawing on Framework Cloud matches. A string is DAGitty text,
|
|
436
|
+
sent as it is, with DAGitty's y pointing down; a ``Path`` names a ``.dagitty`` file.
|
|
437
|
+
``publish(graph)`` publishes a networkx graph too, without code or analysis.
|
|
438
|
+
|
|
439
|
+
Framework Cloud checks the graph, lays it out, and draws it, with the DAGitty text
|
|
440
|
+
and the code to copy. A graph with a cycle, an undirected edge, more than 100 nodes,
|
|
441
|
+
or more than 400 edges is refused. Framework computes no adjustment sets or
|
|
442
|
+
implications. Pass what another tool found in ``analysis``.
|
|
443
|
+
|
|
444
|
+
Args:
|
|
445
|
+
graph: A ``networkx.DiGraph`` (or pgmpy ``DAG``), DAGitty text, or a ``Path`` to a
|
|
446
|
+
``.dagitty`` file.
|
|
447
|
+
labels: Display labels by node name. They win over ``label`` node attributes.
|
|
448
|
+
code: The Python code that built the graph, shown with it.
|
|
449
|
+
analysis: What the producer computed: ``effect`` (``"total"`` or ``"direct"``),
|
|
450
|
+
``adjustment_sets`` (a list of lists of names: ``[[]]`` when no adjustment is
|
|
451
|
+
needed, ``[]`` when no set works), and ``implications`` (``{"x", "y",
|
|
452
|
+
"given"}`` conditional independencies).
|
|
453
|
+
pos: Positions by node, such as ``{"age": (0, 0)}`` or a networkx layout. For
|
|
454
|
+
networkx graphs.
|
|
455
|
+
y: Which way y points in a graph's positions: ``"up"``, as networkx and
|
|
456
|
+
matplotlib draw, or ``"down"``, as DAGitty reads. Default: ``"up"``.
|
|
457
|
+
DAGitty text is always read with y pointing down.
|
|
458
|
+
slug: Artifact slug. Default: from ``title``, else ``dag``. Name each DAG, or a
|
|
459
|
+
second one publishes as a new version of the first.
|
|
460
|
+
title: Artifact title. Default: the slug.
|
|
461
|
+
description: Artifact description.
|
|
462
|
+
visibility: "public", "unlisted", or "private". Default: a new artifact is
|
|
463
|
+
unlisted and an existing one keeps its setting.
|
|
464
|
+
password: Password required to view the DAG.
|
|
465
|
+
collection: Project collection ID or slug.
|
|
466
|
+
share_unlisted: Allow collection readers to see an unlisted DAG.
|
|
467
|
+
to: A configured destination name, or "cloud".
|
|
468
|
+
include_private: Publish without asking about private folders.
|
|
469
|
+
display: What embeds of the DAG show, on Framework Cloud: ``legend``,
|
|
470
|
+
``analysis``, ``dagitty``, ``code``, ``title``, ``description``, and
|
|
471
|
+
``author``, such as ``{"code": False}``. True restores a default, and settings
|
|
472
|
+
left out keep their value.
|
|
473
|
+
|
|
474
|
+
Returns:
|
|
475
|
+
The artifact's URL.
|
|
476
|
+
"""
|
|
477
|
+
from framework.publish_bundle import artifact_slug
|
|
478
|
+
from framework.storage import publish
|
|
479
|
+
|
|
480
|
+
document = _document(graph, labels=labels, code=code, analysis=analysis, pos=pos, y=y)
|
|
481
|
+
slug = slug or (artifact_slug(title) if title else None)
|
|
482
|
+
with tempfile.TemporaryDirectory(prefix="fw_dag_") as temp:
|
|
483
|
+
path = Path(temp) / "dag.json"
|
|
484
|
+
path.write_text(json.dumps(document, ensure_ascii=False, indent=2), encoding="utf-8")
|
|
485
|
+
return publish(
|
|
486
|
+
path,
|
|
487
|
+
kind=KIND,
|
|
488
|
+
slug=slug,
|
|
489
|
+
title=title,
|
|
490
|
+
description=description,
|
|
491
|
+
visibility=visibility,
|
|
492
|
+
password=password,
|
|
493
|
+
collection=collection,
|
|
494
|
+
share_unlisted=share_unlisted,
|
|
495
|
+
to=to,
|
|
496
|
+
include_private=include_private,
|
|
497
|
+
display=display,
|
|
498
|
+
)
|
framework/snippets.py
CHANGED
|
@@ -276,6 +276,7 @@ _PUBLISH_OPTIONS = (
|
|
|
276
276
|
"share_unlisted",
|
|
277
277
|
"to",
|
|
278
278
|
"include_private",
|
|
279
|
+
"display",
|
|
279
280
|
)
|
|
280
281
|
|
|
281
282
|
|
|
@@ -301,6 +302,7 @@ def snippet(
|
|
|
301
302
|
share_unlisted: bool = False,
|
|
302
303
|
to: str | None = None,
|
|
303
304
|
include_private: bool = False,
|
|
305
|
+
display: dict[str, bool] | None = None,
|
|
304
306
|
) -> Iterator[None]:
|
|
305
307
|
"""Run a block and publish its code and printed output as a code snippet.
|
|
306
308
|
|
|
@@ -346,7 +348,14 @@ def snippet(
|
|
|
346
348
|
share_unlisted: Allow collection readers to see an unlisted snippet.
|
|
347
349
|
to: A configured destination name, or "cloud".
|
|
348
350
|
include_private: Publish without asking about private folders.
|
|
351
|
+
display: What embeds of the snippet show, on Framework Cloud: ``output``,
|
|
352
|
+
``links``, ``title``, ``description``, and ``author``, such as
|
|
353
|
+
``{"links": False}``. True restores a default, and settings left out keep
|
|
354
|
+
their value.
|
|
349
355
|
"""
|
|
356
|
+
from framework.cloud import display_settings
|
|
357
|
+
|
|
358
|
+
display_settings(display)
|
|
350
359
|
caller = sys._getframe(2)
|
|
351
360
|
filename = caller.f_code.co_filename
|
|
352
361
|
start = caller.f_lineno
|
|
@@ -395,6 +404,7 @@ def snippet(
|
|
|
395
404
|
"share_unlisted": share_unlisted,
|
|
396
405
|
"to": to,
|
|
397
406
|
"include_private": include_private,
|
|
407
|
+
"display": display,
|
|
398
408
|
}
|
|
399
409
|
if document is not None:
|
|
400
410
|
if error is None:
|
|
@@ -537,6 +547,7 @@ def _magic_parser() -> Any:
|
|
|
537
547
|
parser.add_argument("--share-unlisted", action="store_true")
|
|
538
548
|
parser.add_argument("--to")
|
|
539
549
|
parser.add_argument("--include-private", action="store_true")
|
|
550
|
+
parser.add_argument("--display", action="append", default=[])
|
|
540
551
|
return parser
|
|
541
552
|
|
|
542
553
|
|
|
@@ -551,7 +562,7 @@ def _magic_arguments(line: str) -> Any:
|
|
|
551
562
|
f"%%fw_snippet {line}: {error}. Usage: %%fw_snippet LABEL [--folded | --unfolded] "
|
|
552
563
|
"[--no-output] [--link notebook=URL] [--link model=SLUG] [--repository URL] "
|
|
553
564
|
"[--slug SLUG] [--title TITLE] [--visibility VISIBILITY] [--to DESTINATION] "
|
|
554
|
-
"[--no-publish]"
|
|
565
|
+
"[--display SETTING=on|off] [--no-publish]"
|
|
555
566
|
) from None
|
|
556
567
|
links: dict[str, str] = {}
|
|
557
568
|
for link in arguments.link:
|
|
@@ -560,6 +571,18 @@ def _magic_arguments(line: str) -> Any:
|
|
|
560
571
|
raise FrameworkError("--link takes REL=VALUE, as in --link notebook=https://...")
|
|
561
572
|
links[rel] = value
|
|
562
573
|
arguments.links = links
|
|
574
|
+
display: dict[str, bool] = {}
|
|
575
|
+
for setting in arguments.display:
|
|
576
|
+
name, separator, value = setting.partition("=")
|
|
577
|
+
if not separator or value not in ("on", "off"):
|
|
578
|
+
raise FrameworkError(
|
|
579
|
+
"--display takes SETTING=on or SETTING=off, as in --display links=off"
|
|
580
|
+
)
|
|
581
|
+
display[name] = value == "on"
|
|
582
|
+
arguments.display = display or None
|
|
583
|
+
from framework.cloud import display_settings
|
|
584
|
+
|
|
585
|
+
display_settings(arguments.display)
|
|
563
586
|
return arguments
|
|
564
587
|
|
|
565
588
|
|
|
@@ -721,7 +744,7 @@ def load_ipython_extension(shell: Any) -> None:
|
|
|
721
744
|
[--link notebook=URL] [--link model=SLUG] [--repository URL] [--file PATH]
|
|
722
745
|
[--slug SLUG] [--title TITLE] [--description TEXT] [--visibility VISIBILITY]
|
|
723
746
|
[--password PASSWORD] [--collection COLLECTION] [--share-unlisted]
|
|
724
|
-
[--to DESTINATION] [--include-private] [--no-publish]
|
|
747
|
+
[--to DESTINATION] [--include-private] [--display SETTING=on|off] [--no-publish]
|
|
725
748
|
"""
|
|
726
749
|
run_cell_snippet(shell, line, cell)
|
|
727
750
|
|
framework/storage.py
CHANGED
|
@@ -42,6 +42,7 @@ from framework._private import (
|
|
|
42
42
|
notebook_reasons,
|
|
43
43
|
sensitive_reasons,
|
|
44
44
|
)
|
|
45
|
+
from framework.cloud import display_ignored, display_settings
|
|
45
46
|
from framework.errors import FrameworkError
|
|
46
47
|
from framework.publish_bundle import doc_title
|
|
47
48
|
from framework.settings import settings_read
|
|
@@ -420,6 +421,7 @@ def _publish_legacy(
|
|
|
420
421
|
visibility: str | None = None,
|
|
421
422
|
collection: str | int | None = None,
|
|
422
423
|
share_unlisted: bool = False,
|
|
424
|
+
display: Mapping[str, bool] | None = None,
|
|
423
425
|
_on_s3: Callable[[Path, str | list[str]], None] | None = None,
|
|
424
426
|
) -> str | list[str]:
|
|
425
427
|
"""Upload a file or folder to the project's storage bucket.
|
|
@@ -458,6 +460,9 @@ def _publish_legacy(
|
|
|
458
460
|
``slug=True`` or ``False``.
|
|
459
461
|
collection: Existing project collection ID or slug; follows the latest artifact version.
|
|
460
462
|
share_unlisted: Explicitly allow collection readers to access an unlisted artifact.
|
|
463
|
+
display: What embeds show, on Framework Cloud: settings by name, such as
|
|
464
|
+
``{"analysis": False, "code": False}``. True restores a default, and settings
|
|
465
|
+
left out keep their value. Other destinations ignore it.
|
|
461
466
|
allow_private: Deprecated name for ``include_private``.
|
|
462
467
|
|
|
463
468
|
Returns:
|
|
@@ -469,7 +474,7 @@ def _publish_legacy(
|
|
|
469
474
|
with tempfile.TemporaryDirectory(prefix="fw_artifact_") as temp:
|
|
470
475
|
is_cloud = to != "github" and _target(connection, to) == "cloud"
|
|
471
476
|
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"):
|
|
477
|
+
if kind is None and is_cloud and path.name in ("table.json", "model.json", "dag.json"):
|
|
473
478
|
kind = path.stem
|
|
474
479
|
return _publish_legacy(
|
|
475
480
|
path,
|
|
@@ -488,6 +493,7 @@ def _publish_legacy(
|
|
|
488
493
|
visibility=visibility,
|
|
489
494
|
collection=collection,
|
|
490
495
|
share_unlisted=share_unlisted,
|
|
496
|
+
display=display,
|
|
491
497
|
_on_s3=_on_s3,
|
|
492
498
|
)
|
|
493
499
|
path = Path(source)
|
|
@@ -498,6 +504,7 @@ def _publish_legacy(
|
|
|
498
504
|
if to == "github":
|
|
499
505
|
if any(v is not None for v in (title, description, kind, password, visibility, collection)):
|
|
500
506
|
raise FrameworkError("Artifact metadata requires publishing to Framework Cloud.")
|
|
507
|
+
display_ignored(display, "GitHub Pages")
|
|
501
508
|
return _publish_github(to, path, dest, connection, slug, self_contained)
|
|
502
509
|
if _target(connection, to) == "cloud":
|
|
503
510
|
from framework.cloud import cloud_publish
|
|
@@ -515,10 +522,12 @@ def _publish_legacy(
|
|
|
515
522
|
visibility=visibility,
|
|
516
523
|
collection=collection,
|
|
517
524
|
share_unlisted=share_unlisted,
|
|
525
|
+
display=display,
|
|
518
526
|
)
|
|
519
527
|
if any(v is not None for v in (title, description, kind, password, visibility, collection)):
|
|
520
528
|
raise FrameworkError("Artifact metadata requires publishing to Framework Cloud.")
|
|
521
529
|
_slug_ignored(slug)
|
|
530
|
+
display_ignored(display, "a storage bucket")
|
|
522
531
|
bucket = resolve_bucket(connection)
|
|
523
532
|
dest = dest or path.name
|
|
524
533
|
if path.is_dir():
|
|
@@ -553,6 +562,7 @@ def publish(
|
|
|
553
562
|
collection: str | int | None = None,
|
|
554
563
|
share_unlisted: bool = False,
|
|
555
564
|
model: Any = None,
|
|
565
|
+
display: Mapping[str, bool] | None = None,
|
|
556
566
|
) -> str | list[str]:
|
|
557
567
|
"""Publish an artifact to a named destination or the project default.
|
|
558
568
|
|
|
@@ -567,6 +577,7 @@ def publish(
|
|
|
567
577
|
(every row is kept), tests and models become structured summaries, and static
|
|
568
578
|
plots become SVG. Model exports carry coefficients, importance, and fit
|
|
569
579
|
statistics, never observations, residuals, posterior draws, or serialized models.
|
|
580
|
+
A ``networkx.DiGraph`` becomes a DAG (see ``publish_dag()``).
|
|
570
581
|
Buckets receive CSV tables, PNG figures, and HTML model summaries; Styler tables,
|
|
571
582
|
plotly figures, and altair charts keep their HTML or Vega-Lite form everywhere.
|
|
572
583
|
dest: Where to put it in the bucket. Default: the source's name.
|
|
@@ -596,6 +607,9 @@ def publish(
|
|
|
596
607
|
model: The Bambi model whose ``fit()`` returned ``source``, an InferenceData:
|
|
597
608
|
``publish(idata, model=model)``. The model adds its family, formula, priors,
|
|
598
609
|
group-level effects, and variables to the posterior summaries.
|
|
610
|
+
display: What embeds show, on Framework Cloud: settings by name, such as
|
|
611
|
+
``{"analysis": False, "code": False}``. True restores a default, and settings
|
|
612
|
+
left out keep their value. Other destinations ignore it.
|
|
599
613
|
allow_private: Deprecated name for ``include_private``.
|
|
600
614
|
|
|
601
615
|
Returns:
|
|
@@ -611,6 +625,7 @@ def publish(
|
|
|
611
625
|
|
|
612
626
|
if share_unlisted and collection is None:
|
|
613
627
|
raise FrameworkError("share_unlisted requires a collection.")
|
|
628
|
+
display_settings(display)
|
|
614
629
|
selected = None if to == "bucket" else destination(to, connection)
|
|
615
630
|
if selected is not None:
|
|
616
631
|
visibility = visibility or selected.options.get("visibility")
|
|
@@ -677,6 +692,7 @@ def publish(
|
|
|
677
692
|
)
|
|
678
693
|
if isinstance(slug, bool):
|
|
679
694
|
raise FrameworkError("slug=True/False is not used with bundle destinations.")
|
|
695
|
+
display_ignored(display, f'the "{selected.name}" destination')
|
|
680
696
|
return publish_external(
|
|
681
697
|
source,
|
|
682
698
|
selected,
|
|
@@ -738,6 +754,7 @@ def publish(
|
|
|
738
754
|
visibility=visibility,
|
|
739
755
|
collection=collection,
|
|
740
756
|
share_unlisted=share_unlisted,
|
|
757
|
+
display=display,
|
|
741
758
|
_on_s3=record_legacy,
|
|
742
759
|
)
|
|
743
760
|
|
|
@@ -757,6 +774,7 @@ def publish_notebook(
|
|
|
757
774
|
share_unlisted: bool = False,
|
|
758
775
|
title: str | None = None,
|
|
759
776
|
description: str | None = None,
|
|
777
|
+
display: Mapping[str, bool] | None = None,
|
|
760
778
|
) -> str:
|
|
761
779
|
"""Render a Quarto notebook with the ``quarto`` command and upload the result.
|
|
762
780
|
|
|
@@ -797,6 +815,9 @@ def publish_notebook(
|
|
|
797
815
|
``title`` in the document's YAML front matter (for a Jupyter notebook, or a
|
|
798
816
|
level-1 heading opening its first markdown cell), else its file name.
|
|
799
817
|
description: A short description, on Framework Cloud and named destinations.
|
|
818
|
+
display: What embeds show, on Framework Cloud: settings by name, such as
|
|
819
|
+
``{"analysis": False, "code": False}``. True restores a default, and settings
|
|
820
|
+
left out keep their value. Other destinations ignore it.
|
|
800
821
|
|
|
801
822
|
Returns:
|
|
802
823
|
The public URL.
|
|
@@ -808,6 +829,7 @@ def publish_notebook(
|
|
|
808
829
|
"""
|
|
809
830
|
from framework.publish_bundle import destination
|
|
810
831
|
|
|
832
|
+
display_settings(display)
|
|
811
833
|
selected = None if to == "bucket" else destination(to, connection)
|
|
812
834
|
if selected is not None:
|
|
813
835
|
source_path = Path(file)
|
|
@@ -828,6 +850,7 @@ def publish_notebook(
|
|
|
828
850
|
share_unlisted=share_unlisted,
|
|
829
851
|
title=title,
|
|
830
852
|
description=description,
|
|
853
|
+
display=display,
|
|
831
854
|
)
|
|
832
855
|
assert isinstance(published, str)
|
|
833
856
|
return published
|
|
@@ -846,6 +869,7 @@ def publish_notebook(
|
|
|
846
869
|
raise FrameworkError(f'GitHub Pages publishes HTML only (got format="{format}").')
|
|
847
870
|
if title is not None or description is not None:
|
|
848
871
|
raise FrameworkError("Artifact metadata requires publishing to Framework Cloud.")
|
|
872
|
+
display_ignored(display, "GitHub Pages")
|
|
849
873
|
return _publish_github(to, source, dest, connection, slug, self_contained)
|
|
850
874
|
quarto = shutil.which("quarto")
|
|
851
875
|
if quarto is None:
|
|
@@ -867,12 +891,14 @@ def publish_notebook(
|
|
|
867
891
|
share_unlisted=share_unlisted,
|
|
868
892
|
title=title or doc_title(source),
|
|
869
893
|
description=description,
|
|
894
|
+
display=display,
|
|
870
895
|
)
|
|
871
896
|
if collection is not None:
|
|
872
897
|
raise FrameworkError("Collections require publishing to Framework Cloud.")
|
|
873
898
|
if title is not None or description is not None:
|
|
874
899
|
raise FrameworkError("Artifact metadata requires publishing to Framework Cloud.")
|
|
875
900
|
_slug_ignored(slug)
|
|
901
|
+
display_ignored(display, "a storage bucket")
|
|
876
902
|
bucket = resolve_bucket(connection)
|
|
877
903
|
self_contained = self_contained or not bucket.static_hosting
|
|
878
904
|
|
|
@@ -969,6 +995,7 @@ def publish_data(
|
|
|
969
995
|
allow_private: bool | None = None,
|
|
970
996
|
title: str | None = None,
|
|
971
997
|
description: str | None = None,
|
|
998
|
+
display: Mapping[str, bool] | None = None,
|
|
972
999
|
) -> str:
|
|
973
1000
|
"""Upload a DataFrame (as CSV, Parquet, or JSON) or a data file.
|
|
974
1001
|
|
|
@@ -999,6 +1026,9 @@ def publish_data(
|
|
|
999
1026
|
title: The published title, on Framework Cloud and named destinations. Default: the
|
|
1000
1027
|
slug.
|
|
1001
1028
|
description: A short description, on Framework Cloud and named destinations.
|
|
1029
|
+
display: What embeds show, on Framework Cloud: settings by name, such as
|
|
1030
|
+
``{"analysis": False, "code": False}``. True restores a default, and settings
|
|
1031
|
+
left out keep their value. Other destinations ignore it.
|
|
1002
1032
|
|
|
1003
1033
|
Returns:
|
|
1004
1034
|
The public URL (for a folder destination without a ``url``, its location).
|
|
@@ -1011,9 +1041,12 @@ def publish_data(
|
|
|
1011
1041
|
if format not in ("csv", "parquet", "json"):
|
|
1012
1042
|
raise FrameworkError("format must be csv, parquet, or json (rds is R-only)")
|
|
1013
1043
|
include = include_private_arg(include_private, allow_private)
|
|
1044
|
+
display_settings(display)
|
|
1014
1045
|
selected, bucket_name = _publish_route(to, connection)
|
|
1015
1046
|
if selected is None and (title is not None or description is not None):
|
|
1016
1047
|
raise FrameworkError("Artifact metadata requires publishing to Framework Cloud.")
|
|
1048
|
+
if selected is None:
|
|
1049
|
+
display_ignored(display, "a storage bucket")
|
|
1017
1050
|
if isinstance(data, pd.DataFrame):
|
|
1018
1051
|
confirm_private_upload([], include, sensitive_reasons("this DataFrame"))
|
|
1019
1052
|
if selected is not None and isinstance(data, pd.DataFrame):
|
|
@@ -1027,6 +1060,7 @@ def publish_data(
|
|
|
1027
1060
|
include_private=True,
|
|
1028
1061
|
title=title,
|
|
1029
1062
|
description=description,
|
|
1063
|
+
display=display,
|
|
1030
1064
|
)
|
|
1031
1065
|
assert isinstance(published, str)
|
|
1032
1066
|
return published
|
|
@@ -1064,6 +1098,7 @@ def publish_data(
|
|
|
1064
1098
|
include_private=True,
|
|
1065
1099
|
title=title,
|
|
1066
1100
|
description=description,
|
|
1101
|
+
display=display,
|
|
1067
1102
|
)
|
|
1068
1103
|
assert isinstance(published, str)
|
|
1069
1104
|
return published
|
|
@@ -1084,6 +1119,7 @@ def publish_dir(
|
|
|
1084
1119
|
allow_private: bool | None = None,
|
|
1085
1120
|
title: str | None = None,
|
|
1086
1121
|
description: str | None = None,
|
|
1122
|
+
display: Mapping[str, bool] | None = None,
|
|
1087
1123
|
) -> list[str]:
|
|
1088
1124
|
"""Upload the files in a folder. ``pattern`` is a regular expression on the paths.
|
|
1089
1125
|
|
|
@@ -1112,6 +1148,9 @@ def publish_dir(
|
|
|
1112
1148
|
title: The published title, on Framework Cloud and named destinations. Default: the
|
|
1113
1149
|
slug.
|
|
1114
1150
|
description: A short description, on Framework Cloud and named destinations.
|
|
1151
|
+
display: What embeds show, on Framework Cloud: settings by name, such as
|
|
1152
|
+
``{"analysis": False, "code": False}``. True restores a default, and settings
|
|
1153
|
+
left out keep their value. Other destinations ignore it.
|
|
1115
1154
|
|
|
1116
1155
|
Returns:
|
|
1117
1156
|
The public URL of each file uploaded. The list is empty when no file matched. For
|
|
@@ -1131,9 +1170,12 @@ def publish_dir(
|
|
|
1131
1170
|
inform("No files found to upload")
|
|
1132
1171
|
return []
|
|
1133
1172
|
confirm_private_upload(files, include)
|
|
1173
|
+
display_settings(display)
|
|
1134
1174
|
selected, bucket_name = _publish_route(to, connection)
|
|
1135
1175
|
if selected is None and (title is not None or description is not None):
|
|
1136
1176
|
raise FrameworkError("Artifact metadata requires publishing to Framework Cloud.")
|
|
1177
|
+
if selected is None:
|
|
1178
|
+
display_ignored(display, "a storage bucket")
|
|
1137
1179
|
dest = dest or folder.resolve().name
|
|
1138
1180
|
if selected is not None:
|
|
1139
1181
|
slug = _dir_slug(dest)
|
|
@@ -1146,6 +1188,7 @@ def publish_dir(
|
|
|
1146
1188
|
include_private=True,
|
|
1147
1189
|
title=title,
|
|
1148
1190
|
description=description,
|
|
1191
|
+
display=display,
|
|
1149
1192
|
)
|
|
1150
1193
|
else:
|
|
1151
1194
|
# Publish only the selected files, keeping their paths inside the folder
|
|
@@ -1162,6 +1205,7 @@ def publish_dir(
|
|
|
1162
1205
|
include_private=True,
|
|
1163
1206
|
title=title,
|
|
1164
1207
|
description=description,
|
|
1208
|
+
display=display,
|
|
1165
1209
|
)
|
|
1166
1210
|
return [published] if isinstance(published, str) else list(published)
|
|
1167
1211
|
bucket = resolve_bucket(bucket_name)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: framework-py
|
|
3
|
-
Version: 0.1.0.
|
|
3
|
+
Version: 0.1.0.dev35
|
|
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=
|
|
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=
|
|
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
|
|
@@ -27,11 +27,12 @@ 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
29
|
framework/catalog.py,sha256=UNyMj7g_iTBcQnFq_uwRAL4tlNh1NUDunrTtX4BfOBg,13306
|
|
30
|
-
framework/cloud.py,sha256=
|
|
30
|
+
framework/cloud.py,sha256=OHCe35nkBO-02Z0SJ5fnphBRxuexUr9MVi8q5IzbmoE,70056
|
|
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/dags.py,sha256=25LpVvdcZpYNMu4ouK0sysl90FcRXQrWwaYW1f400ho,20499
|
|
35
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
|
|
@@ -55,8 +56,8 @@ framework/security.py,sha256=-x66bSIIE_xOzkTf5Ojt7xIECKuAIpKVJZ5TtIGrwys,51147
|
|
|
55
56
|
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
|
-
framework/snippets.py,sha256=
|
|
59
|
-
framework/storage.py,sha256=
|
|
59
|
+
framework/snippets.py,sha256=Opung5npXX6L2tKwsW6j-77cRJ902Yc7g5SH8uR-fEM,27531
|
|
60
|
+
framework/storage.py,sha256=UkXrILWPetYArUgPOZrX71sF2tD_7k9ADpZr0fQcKsc,58526
|
|
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.
|
|
146
|
-
framework_py-0.1.0.
|
|
147
|
-
framework_py-0.1.0.
|
|
148
|
-
framework_py-0.1.0.
|
|
146
|
+
framework_py-0.1.0.dev35.dist-info/METADATA,sha256=Qvhe7y9thaIfvBd3JA-8pujg_RVLw5iYVQvgbraH_UQ,5143
|
|
147
|
+
framework_py-0.1.0.dev35.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
148
|
+
framework_py-0.1.0.dev35.dist-info/licenses/LICENSE,sha256=giOOgSwALkZimC7uhLZQK8Untez641bLW1-2-Cjvmq0,1072
|
|
149
|
+
framework_py-0.1.0.dev35.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|