framework-py 0.1.0.dev22__py3-none-any.whl → 0.1.0.dev24__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/adopt.py CHANGED
@@ -520,7 +520,7 @@ def adopt(
520
520
  The project folder.
521
521
 
522
522
  Raises:
523
- FrameworkError: When the folder doesn't exist or is already a Framework project,
523
+ FrameworkError: When the folder does not exist or is already a Framework project,
524
524
  when its files say another language and ``force`` is False, when the
525
525
  arguments disagree, or when the review needs a terminal and ``yes`` is False.
526
526
  """
@@ -743,7 +743,7 @@ def structure_import(
743
743
 
744
744
  Raises:
745
745
  CloudError: When you are not logged in, or the server rejects the layout or
746
- doesn't support structures.
746
+ does not support structures.
747
747
  FrameworkError: When the review needs a terminal and ``yes`` is False, or when
748
748
  you cancel it.
749
749
  """
framework/cache.py CHANGED
@@ -26,7 +26,7 @@ import pandas as pd
26
26
  from framework import _depends, db
27
27
  from framework._log import inform
28
28
  from framework._paths import in_root, relative_to_root
29
- from framework.errors import CacheWarning, FrameworkError
29
+ from framework.errors import CacheWarning, FrameworkError, IntegrityError
30
30
  from framework.integrity import file_hash
31
31
  from framework.project import project_root
32
32
  from framework.settings import settings_read
@@ -149,6 +149,12 @@ def _store(
149
149
  path = (
150
150
  Path(file) if file is not None else cache_dir() / f"{name}{_FORMATS[0 if is_frame else 1]}"
151
151
  )
152
+ # A cache file never replaces locked data
153
+ from framework.data import locked_data_at, locked_message
154
+
155
+ held = locked_data_at(path)
156
+ if held is not None:
157
+ raise IntegrityError(locked_message("cache()", held, "Store the cache in another file."))
152
158
  if not path.parent.is_dir():
153
159
  path.parent.mkdir(parents=True, exist_ok=True)
154
160
  inform(f"Creating cache directory: {path.parent}")
framework/cloud.py CHANGED
@@ -7,13 +7,21 @@ and documents you publish.
7
7
 
8
8
  The server is resolved per call, as in R:
9
9
 
10
- - User calls (login, settings, sync, ``new(key=...)``): the ``url``
11
- argument, then ``FW_CLOUD_URL``, then the server saved by
12
- ``cloud_login()``, then https://framework.pub.
10
+ - User calls (settings, sync, ``new(key=...)``): the ``url`` argument, then
11
+ ``FW_CLOUD_URL``, then the server saved by the last login (``cloud_login()``,
12
+ ``fw login``, or R's ``cloud_login()``).
13
13
  - Project calls (publishing, the ledger): the ``url`` argument, then
14
14
  ``FW_CLOUD_URL`` in the project's ``.env``, then the environment variable,
15
- then https://framework.pub. A project token is only valid on the server
16
- that issued it, so these calls never use the login default.
15
+ then the saved login. A project token is only valid on the server that
16
+ issued it. A project whose ``.env`` has ``FW_PROJECT_TOKEN`` but no
17
+ ``FW_CLOUD_URL`` never uses the saved login: these calls raise
18
+ ``ProjectServerMissingError``. When saved logins name different servers,
19
+ they stop instead of guessing.
20
+ - Every call that writes a new ``FW_PROJECT_TOKEN`` also writes
21
+ ``FW_CLOUD_URL``, the server that issued it.
22
+ - With nothing set, calls raise ``NoServerError``. Only ``cloud_login()``
23
+ falls back to https://framework.pub, which its notice names before
24
+ connecting. Using the public cloud is always the user's choice.
17
25
 
18
26
  Plain ``http`` is accepted only for localhost.
19
27
  """
@@ -69,6 +77,30 @@ class CloudError(FrameworkError):
69
77
  status: int | None = None
70
78
 
71
79
 
80
+ class NoServerError(CloudError):
81
+ """Nothing names a server: no ``url``, no ``FW_CLOUD_URL``, and no saved login."""
82
+
83
+
84
+ class AmbiguousServerError(CloudError):
85
+ """A project call found logins to several servers and nothing naming the project's."""
86
+
87
+
88
+ class ProjectServerMissingError(CloudError):
89
+ """A project's ``.env`` has ``FW_PROJECT_TOKEN`` but no ``FW_CLOUD_URL``.
90
+
91
+ The token is only valid on the server that issued it, so project calls stop
92
+ instead of using the saved login. Not a ``NoServerError``, so code that
93
+ treats "no server" as "not signed in" still surfaces it.
94
+ """
95
+
96
+
97
+ PROJECT_SERVER_MISSING = (
98
+ "This project's .env has FW_PROJECT_TOKEN but no FW_CLOUD_URL, so it does not say which "
99
+ "Framework Cloud server issued the token. Add FW_CLOUD_URL=<server> to .env, or pass "
100
+ 'url="<server>".'
101
+ )
102
+
103
+
72
104
  def _version() -> str:
73
105
  from framework import __version__
74
106
 
@@ -121,14 +153,14 @@ def is_default(url: str) -> bool:
121
153
  return host(url) == host(DEFAULT_URL)
122
154
 
123
155
 
124
- def _saved_url() -> str | None:
125
- """The default server a login saved, from the newer of fw's and R's cloud.yml.
156
+ def _saved_urls() -> list[str]:
157
+ """Every server a login saved in fw's and R's cloud.yml, the most recent first.
126
158
 
127
- The most recently written file wins, so the last login in any tool counts.
128
- On a tie fw's folder comes first. fw and R use the same rule.
159
+ URLs are normalized and duplicates dropped. The most recently written file
160
+ comes first, so the last login in any tool counts. On a tie fw's folder
161
+ comes first. fw and R use the same rule.
129
162
  """
130
- best: str | None = None
131
- best_time = -1
163
+ found: list[tuple[int, str]] = []
132
164
  for folder in dict.fromkeys((config_dir(), r_config_dir())):
133
165
  path = folder / "cloud.yml"
134
166
  if not path.is_file():
@@ -136,10 +168,9 @@ def _saved_url() -> str | None:
136
168
  data = _yaml.read(path)
137
169
  server = data.get("server") if isinstance(data, dict) else None
138
170
  if isinstance(server, str) and server:
139
- written = path.stat().st_mtime_ns
140
- if written > best_time:
141
- best, best_time = server, written
142
- return best
171
+ found.append((path.stat().st_mtime_ns, normalize_url(server)))
172
+ found.sort(key=lambda item: -item[0])
173
+ return list(dict.fromkeys(url for _, url in found))
143
174
 
144
175
 
145
176
  def _project_dir(project_dir: str | Path | None) -> Path | None:
@@ -163,16 +194,47 @@ class Server:
163
194
  def cloud_server(
164
195
  url: str | None = None, scope: str = "user", project_dir: str | Path | None = None
165
196
  ) -> Server:
166
- """Which server a call uses, and where that setting came from."""
197
+ """Which server a call uses, and where that setting came from.
198
+
199
+ ``scope`` is ``"user"``, ``"project"``, or ``"login"``. Raises
200
+ ``NoServerError`` when nothing names a server, except for ``"login"``,
201
+ which falls back to https://framework.pub. A project whose ``.env`` has
202
+ ``FW_PROJECT_TOKEN`` but no ``FW_CLOUD_URL`` never uses the saved login:
203
+ without the ``url`` argument or the ``FW_CLOUD_URL`` environment variable,
204
+ project calls raise ``ProjectServerMissingError``.
205
+ """
167
206
  candidates: list[tuple[str | None, str]] = [(url, "the url argument")]
168
207
  if scope == "project":
169
208
  candidates.append((_project_env("FW_CLOUD_URL", project_dir), "the project's .env"))
170
209
  candidates.append((os.environ.get("FW_CLOUD_URL"), "the FW_CLOUD_URL environment variable"))
171
- if scope == "user":
172
- candidates.append((_saved_url(), "your cloud_login() default"))
173
- candidates.append((DEFAULT_URL, "the built-in default"))
174
- value, source = next((v, s) for v, s in candidates if v)
175
- return Server(normalize_url(str(value)), source)
210
+ for value, source in candidates:
211
+ if value:
212
+ return Server(normalize_url(str(value)), source)
213
+ if scope == "project" and _project_env("FW_PROJECT_TOKEN", project_dir):
214
+ raise ProjectServerMissingError(PROJECT_SERVER_MISSING)
215
+
216
+ saved = _saved_urls()
217
+ if len(saved) == 1 or (saved and scope != "project"):
218
+ return Server(saved[0], "your cloud_login() default")
219
+ if saved:
220
+ hosts = " and ".join(host(u) for u in saved)
221
+ raise AmbiguousServerError(
222
+ "This project does not say which Framework Cloud server it uses: its .env has no "
223
+ f"FW_CLOUD_URL, and you are logged in to {hosts}. Add FW_CLOUD_URL=<server> to the "
224
+ "project's .env, or set FW_CLOUD_URL."
225
+ )
226
+ if scope == "login":
227
+ return Server(DEFAULT_URL, "the cloud_login() default")
228
+ where = (
229
+ "This project's .env has no FW_CLOUD_URL and you have not logged in. "
230
+ "Add FW_CLOUD_URL=<server> to .env, or log in"
231
+ if scope == "project"
232
+ else "Log in"
233
+ )
234
+ raise NoServerError(
235
+ f"No Framework Cloud server is chosen. {where} with fw.cloud_login() (framework.pub) "
236
+ 'or fw.cloud_login(url="<server>"), or set FW_CLOUD_URL.'
237
+ )
176
238
 
177
239
 
178
240
  # Tokens ---------------------------------------------------------------------------
@@ -546,7 +608,7 @@ def cloud_login(
546
608
  Args:
547
609
  token: A personal token. Omit it to approve this computer in the browser.
548
610
  url: The server. Default: ``FW_CLOUD_URL``, then your saved default,
549
- then https://framework.pub.
611
+ then https://framework.pub, which the notice names before connecting.
550
612
  verify: Check the token with the server first.
551
613
  consent: ``True`` to confirm a pasted token without a prompt (scripts,
552
614
  CI). Approving in the browser is the confirmation for browser login.
@@ -556,7 +618,7 @@ def cloud_login(
556
618
  Where the token was stored: ``"keyring"`` or a file path.
557
619
  """
558
620
  show_messages()
559
- server = cloud_server(url).url
621
+ server = cloud_server(url, scope="login").url
560
622
  name = host(server)
561
623
  if token is None:
562
624
  print(consent_notice(server), file=sys.stderr)
@@ -624,7 +686,7 @@ def _revoke(server: str, token: str) -> None:
624
686
  def cloud_logout(url: str | None = None) -> list[str]:
625
687
  """Revoke and remove this machine's stored token for a server. Returns what was removed.
626
688
 
627
- Each stored token is revoked on the server first. If the server can't be reached, the
689
+ Each stored token is revoked on the server first. If the server cannot be reached, the
628
690
  local copy is still removed, and you can revoke the token on the server's tokens page.
629
691
  The keyring entry, the token file, and the file ``FW_TOKEN_FILE`` names are removed. For
630
692
  the default server, the legacy keyring entry and ``~/.secrets/framework/token`` are removed
@@ -632,8 +694,7 @@ def cloud_logout(url: str | None = None) -> list[str]:
632
694
  until you unset it.
633
695
 
634
696
  Args:
635
- url: The server. Default: ``FW_CLOUD_URL``, then your saved default, then
636
- https://framework.pub.
697
+ url: The server. Default: ``FW_CLOUD_URL``, then your saved default.
637
698
 
638
699
  Returns:
639
700
  A description of each keyring entry and the path of each file removed. The list is
@@ -677,19 +738,28 @@ def cloud_status(url: str | None = None) -> bool:
677
738
  publishes to a different server, that server is printed too.
678
739
 
679
740
  Args:
680
- url: The server. Default: ``FW_CLOUD_URL``, then your saved default, then
681
- https://framework.pub.
741
+ url: The server. Default: ``FW_CLOUD_URL``, then your saved default.
682
742
 
683
743
  Returns:
684
744
  True when a token is stored and the server accepts it. False when no token is stored,
685
745
  the server is unreachable, or the token is invalid.
686
746
  """
687
747
  show_messages()
688
- server = cloud_server(url)
748
+ try:
749
+ server = cloud_server(url)
750
+ except NoServerError as error:
751
+ inform(str(error))
752
+ return False
689
753
  inform(f"Server: {server.url} (from {server.source})")
690
754
  if project_token() is not None:
691
- project = cloud_server(scope="project")
692
- if project.url != server.url:
755
+ try:
756
+ project: Server | None = cloud_server(scope="project")
757
+ except ProjectServerMissingError as error:
758
+ inform(str(error))
759
+ project = None
760
+ except CloudError:
761
+ project = None
762
+ if project is not None and project.url != server.url:
693
763
  inform(f"This project publishes to {project.url} (from {project.source})")
694
764
  token = cloud_token(server.url)
695
765
  if token is None:
@@ -837,15 +907,20 @@ def _ledger_live() -> bool:
837
907
  def ledger_push_quietly(name: str, digest: str, file_path: Path | None = None) -> Any:
838
908
  """Send one digest to the project's ledger after ``data_save()``, in live mode only.
839
909
 
840
- No project token or an unreachable server means "local only", never a
841
- failed save. framework.db stays the record either way.
910
+ No project token, a project that doesn't name its server, or an unreachable
911
+ server means "local only", never a failed save. framework.db stays the record
912
+ either way.
842
913
  """
843
914
  if not _ledger_live():
844
915
  return None
845
916
  token = project_token()
846
917
  if token is None:
847
918
  return None
848
- url = cloud_server(scope="project").url
919
+ try:
920
+ url = cloud_server(scope="project").url
921
+ except ProjectServerMissingError as error:
922
+ inform(f"Ledger push skipped: {error}")
923
+ return None
849
924
  body = {
850
925
  "name": name,
851
926
  "algo": "sha256",
@@ -1237,28 +1312,27 @@ def cloud_publish(
1237
1312
  def write_project_token(project_dir: Path, token: str, url: str) -> list[str]:
1238
1313
  """Add the project's key and server to its ``.env`` (never to the settings).
1239
1314
 
1240
- Git is made to ignore ``.env`` first, so the token can't be committed.
1315
+ ``FW_PROJECT_TOKEN`` and ``FW_CLOUD_URL`` are written together, so the project
1316
+ always names the server that issued its token. An empty or different
1317
+ ``FW_CLOUD_URL`` is replaced. A project that already has a token keeps it, and
1318
+ its ``.env`` is left as it is. Git is made to ignore ``.env`` first, so the
1319
+ token can't be committed. Returns the keys written.
1241
1320
  """
1242
1321
  from framework.create import keep_env_out_of_git
1243
1322
 
1244
1323
  env = project_dir / ".env"
1245
- present = dotenv.read(env)
1246
- missing = {
1247
- k: v for k, v in (("FW_PROJECT_TOKEN", token), ("FW_CLOUD_URL", url)) if k not in present
1248
- }
1249
- if not missing:
1324
+ if dotenv.value(env, "FW_PROJECT_TOKEN"):
1250
1325
  return []
1326
+ server = normalize_url(url)
1251
1327
  keep_env_out_of_git(project_dir)
1252
- text = env.read_text(encoding="utf-8") if env.exists() else ""
1253
- if text and not text.endswith("\n"):
1254
- text += "\n"
1255
- if text:
1256
- text += "\n"
1257
- text += "# Framework Cloud project key and server (created by framework.new)\n"
1258
- text += "".join(f"{key}={value}\n" for key, value in missing.items())
1259
- env.write_text(text, encoding="utf-8")
1260
- inform(f" Added: {' and '.join(missing)} to .env")
1261
- return list(missing)
1328
+ written = dotenv.set_values(
1329
+ env,
1330
+ {"FW_PROJECT_TOKEN": token, "FW_CLOUD_URL": server},
1331
+ header="Framework Cloud project key and server (created by framework.new)",
1332
+ )
1333
+ if written:
1334
+ inform(f" Wrote {' and '.join(written)} to .env")
1335
+ return written
1262
1336
 
1263
1337
 
1264
1338
  def registration_body(
@@ -1308,7 +1382,10 @@ def register_project(
1308
1382
  was built from. A server without ``/api/v1/projects`` gets the older
1309
1383
  registration.
1310
1384
  """
1311
- server = cloud_server().url
1385
+ try:
1386
+ server = cloud_server().url
1387
+ except NoServerError:
1388
+ return None
1312
1389
  token = cloud_token(server)
1313
1390
  if token is None:
1314
1391
  return None
@@ -1463,12 +1540,13 @@ def cloud_register(
1463
1540
  tools, and none of your defaults. An adopted project is marked as
1464
1541
  adopted.
1465
1542
  2. Writes the project token and server to ``.env`` (``FW_PROJECT_TOKEN``,
1466
- ``FW_CLOUD_URL``), making sure git ignores ``.env`` first.
1543
+ ``FW_CLOUD_URL``), making sure git ignores ``.env`` first. An empty or
1544
+ different ``FW_CLOUD_URL`` is replaced with the server that issued the token.
1467
1545
 
1468
1546
  A project that already has a token in ``.env`` is left as it is. When you
1469
1547
  already have a project with the slug, an interactive session offers to
1470
1548
  link this folder to that project instead, and nothing is created. A slug
1471
- held by a project in your Trash can't be reused. A self-hosted server from
1549
+ held by a project in your Trash cannot be reused. A self-hosted server from
1472
1550
  before the spec API builds the project from your defaults; the spec is
1473
1551
  then sent separately (``PUT /api/v1/project/spec``). This is
1474
1552
  ``fw project link --create``.
framework/connections.py CHANGED
@@ -439,7 +439,7 @@ def db_query(
439
439
  this query and closed afterward.
440
440
  params: Values for the query's placeholders, as a sequence or a mapping.
441
441
  read_only: Open the connection read-only for this query (True), as
442
- ``db_connect()`` does. Default: the connection's setting, which False can't
442
+ ``db_connect()`` does. Default: the connection's setting, which False cannot
443
443
  override when it is ``read_only: true``. A read-only DuckDB
444
444
  file can be open in several processes at once, so ``read_only=True`` lets a
445
445
  notebook query a database another job holds open read-only too.
framework/create.py CHANGED
@@ -774,11 +774,12 @@ def new_project(
774
774
  url: With ``key``: the Framework Cloud server that issued the token. No login is
775
775
  needed. The server is saved as ``FW_CLOUD_URL`` in the project's ``.env``.
776
776
  Default: ``FW_CLOUD_URL``, then the server you last logged in to with
777
- [`cloud_login()`](ref:cloud_login), then https://framework.pub.
777
+ [`cloud_login()`](ref:cloud_login). With neither, ``new()`` raises
778
+ ``NoServerError`` rather than assume https://framework.pub.
778
779
  interactive: Whether to prompt. Default: whether stdin is a terminal.
779
780
  offline: Build from Framework's built-in defaults without contacting Framework Cloud.
780
781
  When you are logged in and pass no choices, ``new()`` resolves your defaults on
781
- the cloud and caches them. If the cloud can't be reached, it builds from that
782
+ the cloud and caches them. If the cloud cannot be reached, it builds from that
782
783
  cache and says so. With no cache it asks first, or, when not interactive, stops
783
784
  unless ``offline`` is True. It never falls back silently.
784
785
 
framework/data.py CHANGED
@@ -13,9 +13,12 @@ too.
13
13
  from __future__ import annotations
14
14
 
15
15
  import importlib.util
16
+ import os
16
17
  import re
18
+ import sys
17
19
  import warnings
18
20
  from collections.abc import Callable, Mapping, Sequence
21
+ from dataclasses import dataclass
19
22
  from pathlib import Path
20
23
  from typing import Any
21
24
 
@@ -26,7 +29,7 @@ from framework._identifiers import warn_identifiers
26
29
  from framework._log import inform
27
30
  from framework._paths import in_root, relative_to_root
28
31
  from framework._private import is_private_data, note_private_read
29
- from framework.catalog import DataInfo, catalog_locate, data_info
32
+ from framework.catalog import DataInfo, catalog_locate, catalog_names, data_info
30
33
  from framework.errors import (
31
34
  DataChangedWarning,
32
35
  DataNotFoundError,
@@ -516,16 +519,98 @@ def _in_settings_folder(folder: Path) -> bool:
516
519
  return False
517
520
 
518
521
 
522
+ @dataclass(frozen=True)
523
+ class LockedData:
524
+ """Locked data a write would change: its name, its file, and where the lock is."""
525
+
526
+ name: str
527
+ file: Path
528
+ source: str # "catalog" or "record"
529
+
530
+
531
+ def _same_file(a: Path, b: Path) -> bool:
532
+ """Whether two paths name the same file. Case is ignored on macOS and Windows."""
533
+ left, right = os.path.normpath(a.resolve()), os.path.normpath(b.resolve())
534
+ if sys.platform in ("darwin", "win32"):
535
+ return left.lower() == right.lower()
536
+ return left == right
537
+
538
+
539
+ def locked_data_at(file_path: str | Path, name: str | None = None) -> LockedData | None:
540
+ """The locked data a write to ``file_path`` would change, or None, as in R.
541
+
542
+ Locked data is a catalog entry with ``locked: true``, or a framework.db record saved
543
+ locked (``data_save()`` to a path has no catalog entry). An entry counts when its file
544
+ exists and is ``file_path``, or when its name is ``name``, since a save by name
545
+ repoints the entry. A catalog entry's flag wins over its record, so ``locked: false``
546
+ in the settings unlocks it.
547
+ """
548
+ try:
549
+ root = project_root()
550
+ data = settings_read().get("data")
551
+ except FrameworkError:
552
+ return None
553
+ target = Path(file_path)
554
+
555
+ def hit(entry_name: str, entry_path: Any) -> Path | None:
556
+ if not isinstance(entry_path, str) or not entry_path:
557
+ return None
558
+ file = Path(entry_path) if Path(entry_path).is_absolute() else root / entry_path
559
+ if file.is_file() and (entry_name == name or _same_file(file, target)):
560
+ return file
561
+ return None
562
+
563
+ names = catalog_names(data)
564
+ for entry_name in names:
565
+ located = catalog_locate(entry_name, data)
566
+ entry = located[0][located[1]] if located else None
567
+ if isinstance(entry, dict) and entry.get("locked") is True:
568
+ file = hit(entry_name, entry.get("path"))
569
+ if file is not None:
570
+ return LockedData(entry_name, file, "catalog")
571
+ for record_name, record_path in db.locked_data_records(root):
572
+ if record_name in names:
573
+ continue
574
+ file = hit(record_name, record_path)
575
+ if file is not None:
576
+ return LockedData(record_name, file, "record")
577
+ return None
578
+
579
+
580
+ def locked_message(caller: str, held: LockedData, advice: str) -> str:
581
+ """The error for a write that would change locked data."""
582
+ where = (
583
+ "locked: true in the data catalog" if held.source == "catalog" else "saved with locked=True"
584
+ )
585
+ try:
586
+ shown = relative_to_root(held.file, project_root())
587
+ except FrameworkError:
588
+ shown = str(held.file)
589
+ return (
590
+ f"{caller} does not overwrite locked data.\n"
591
+ f" dataset: {held.name} ({where})\n"
592
+ f" file: {shown}\n"
593
+ f"{advice}"
594
+ )
595
+
596
+
519
597
  def data_save(
520
598
  data: pd.DataFrame,
521
599
  path: str,
522
600
  type: str | None = None,
523
601
  delimiter: str = "comma",
524
- locked: bool = True,
602
+ locked: bool | None = None,
525
603
  force: bool = False,
604
+ unlock: bool = False,
526
605
  ) -> pd.DataFrame:
527
606
  """Save a DataFrame and record its hash.
528
607
 
608
+ Data is saved unlocked unless you lock it. Locked data protects inputs:
609
+ ``data_read()`` raises when a locked file changed. So ``data_save()`` never changes a
610
+ locked file unless asked. Save under another name, or pass ``unlock=True`` to replace
611
+ it; the new file is then unlocked, and later saves replace it. Pass
612
+ ``unlock=True, locked=True`` to replace it and keep it locked.
613
+
529
614
  Args:
530
615
  data: The data to save.
531
616
  path: A catalog name such as ``"inputs.intermediate.cleaned"`` or a
@@ -540,17 +625,26 @@ def data_save(
540
625
  type: ``"parquet"`` or ``"csv"``. Default: from the file extension,
541
626
  or Parquet for a catalog name.
542
627
  delimiter: Delimiter for CSV files: comma, tab, semicolon, or space.
543
- locked: Whether later reads must find the file unchanged. Default: True, as in R.
544
- Saving again over locked data with different contents replaces it, as R does,
545
- with a ``DataChangedWarning``. The same contents save silently.
628
+ locked: Whether later reads must find the file unchanged. Default: unlocked, as
629
+ in R, so a pipeline can save the data again. Pass ``locked=True`` to lock data
630
+ you mean to keep as it is. Left out, a save keeps a lock the data already
631
+ has, unless ``unlock=True``.
546
632
  force: Create any missing folder. Without it, a missing folder is created
547
633
  only when it is a folder named in the settings (``directories``,
548
634
  ``extra_directories``, ``render_dirs``) or inside one, such as
549
635
  ``inputs/private/intermediate`` in a fresh checkout; any other missing
550
636
  folder is an error.
637
+ unlock: Replace locked data and save it unlocked, unless ``locked=True``.
638
+ Without it, ``data_save()`` raises ``IntegrityError`` before writing when the
639
+ save would change locked data: a catalog entry with ``locked: true``, or a
640
+ file saved earlier with ``locked=True``. Saving the same contents again needs
641
+ no ``unlock``.
551
642
 
552
643
  Returns:
553
644
  ``data``, so the call can end a pipeline.
645
+
646
+ Raises:
647
+ IntegrityError: The save would change locked data and ``unlock`` is False.
554
648
  """
555
649
  if not isinstance(data, pd.DataFrame):
556
650
  raise FrameworkError("data_save() needs a pandas DataFrame")
@@ -577,12 +671,43 @@ def data_save(
577
671
  folder.mkdir(parents=True, exist_ok=True)
578
672
  inform(f"Created directory: {folder}")
579
673
 
580
- if file_type == "csv":
581
- # In readr's form (1 not 1.0, TRUE, NA, "\n" line endings), so R reads the same
582
- # values and the same data hashes the same in both languages
583
- _csv.write_csv(data, target, sep=_separator(delimiter))
584
- else:
585
- data.to_parquet(target, index=False)
674
+ def write(destination: Path) -> None:
675
+ if file_type == "csv":
676
+ # In readr's form (1 not 1.0, TRUE, NA, "\n" line endings), so R reads the same
677
+ # values and the same data hashes the same in both languages
678
+ _csv.write_csv(data, destination, sep=_separator(delimiter))
679
+ else:
680
+ data.to_parquet(destination, index=False)
681
+
682
+ # Locked data stays unchanged unless unlock=True: reads raise when a locked file
683
+ # changed. The new contents go to a temporary file first, so a refused save leaves
684
+ # the locked file as it was. The same contents pass.
685
+ held = locked_data_at(target, name=name)
686
+ if held is not None:
687
+ same = False
688
+ if _same_file(held.file, target):
689
+ temporary = folder / f".fw-save-{os.getpid()}{target.suffix}"
690
+ try:
691
+ write(temporary)
692
+ same = file_hash(temporary) == file_hash(target)
693
+ finally:
694
+ temporary.unlink(missing_ok=True)
695
+ if not same and not unlock:
696
+ raise IntegrityError(
697
+ locked_message(
698
+ "data_save()",
699
+ held,
700
+ "Save the data under another name, or pass unlock=True to replace it.\n"
701
+ "The new file is then unlocked. Add locked=True to keep it locked.",
702
+ )
703
+ )
704
+ if not same:
705
+ inform(f"Replacing locked data '{held.name}' (unlock=True).")
706
+ # Without ``locked``, locked data saved with the same contents stays locked, and
707
+ # unlock=True saves it unlocked. Everything else is saved unlocked.
708
+ if locked is None:
709
+ locked = held is not None and not unlock
710
+ write(target)
586
711
  root = project_root()
587
712
  relative = relative_to_root(target, root)
588
713
  inform(f"Data saved to: {relative}")
@@ -592,17 +717,6 @@ def data_save(
592
717
  key = name or relative
593
718
 
594
719
  digest = file_hash(target)
595
- previous = db.get_data_record(key, root)
596
- if previous is not None and previous.locked and previous.hash and previous.hash != digest:
597
- # As in R, the save goes ahead: data_save() is how locked data is rebuilt. It
598
- # says so, since the lock means reads expect the file unchanged.
599
- warnings.warn(
600
- f"data_save() replaced locked data '{key}' with different contents.\n"
601
- f"Previous hash: {previous.hash[:12]}\nCurrent hash: {digest[:12]}\n"
602
- "Pass locked=False for data a pipeline rebuilds.",
603
- DataChangedWarning,
604
- stacklevel=2,
605
- )
606
720
  db.set_data_record(
607
721
  key,
608
722
  path=relative,
@@ -714,7 +828,7 @@ def data_add(
714
828
  name: str | None = None,
715
829
  type: str | None = None,
716
830
  delimiter: str = "comma",
717
- locked: bool = True,
831
+ locked: bool | None = None,
718
832
  update_config: bool = True,
719
833
  ) -> dict[str, Any]:
720
834
  """Add an existing file to the data catalog and record its hash.
@@ -727,7 +841,8 @@ def data_add(
727
841
  ``inputs.private.raw.<file>`` in ``inputs_private_raw``), else the file name.
728
842
  type: File type. Default: from the extension.
729
843
  delimiter: Delimiter for CSV files.
730
- locked: Whether later reads must find the file unchanged.
844
+ locked: Whether later reads must find the file unchanged. Default: unlocked.
845
+ Left out, a file already locked in the catalog or framework.db stays locked.
731
846
  update_config: Write the entry to the settings, not just framework.db.
732
847
 
733
848
  Returns:
@@ -750,6 +865,11 @@ def data_add(
750
865
  if name is None:
751
866
  name = _derive_name(path, settings_read(), root)
752
867
 
868
+ # Left out, ``locked`` keeps a lock the file already has, so registering locked
869
+ # data again doesn't unlock it
870
+ if locked is None:
871
+ locked = locked_data_at(path, name=name) is not None
872
+
753
873
  relative = relative_to_root(path, root)
754
874
  stored_delimiter = delimiter if type == "csv" else None
755
875
  db.set_data_record(
@@ -461,7 +461,7 @@ def pull_data_registry(
461
461
  project's framework.db. Applying writes the new entries into the settings' data section
462
462
  (inline, or in its split file such as ``settings/data.yml``), keeping the file's comments.
463
463
  Local entries are never removed, and an entry whose local definition differs keeps it
464
- unless ``overwrite=True``. Fields Framework Cloud doesn't keep stay as they are. The
464
+ unless ``overwrite=True``. Fields Framework Cloud does not store remain unchanged. The
465
465
  revision pulled is kept in ``.framework/data.lock.json`` for ``push_data_registry()``.
466
466
  ``pull_all()`` pulls it with the packages and skills.
467
467
 
@@ -544,7 +544,7 @@ def push_data_registry(
544
544
 
545
545
  Args:
546
546
  project_path: The project's root directory. Default: the current directory.
547
- remove: Remove entries from Cloud's registry that this project doesn't have.
547
+ remove: Remove entries from Cloud's registry that this project does not have.
548
548
  force: Push even when Cloud's registry changed since the last pull.
549
549
  confirm: True pushes without asking; False cancels. None asks in a console.
550
550
  dry_run: List the changes and send nothing.
framework/db.py CHANGED
@@ -190,6 +190,15 @@ def set_data_record(
190
190
  )
191
191
 
192
192
 
193
+ def locked_data_records(root: str | Path | None = None) -> list[tuple[str, str]]:
194
+ """Name and path of each ``data`` row marked locked; none without framework.db."""
195
+ if not db_path(root).is_file():
196
+ return []
197
+ with connect(root) as connection:
198
+ rows = connection.execute("SELECT name, path FROM data WHERE locked").fetchall()
199
+ return [(row["name"], row["path"]) for row in rows if row["path"]]
200
+
201
+
193
202
  def update_data_hash(name: str, hash: str, root: str | Path | None = None) -> None:
194
203
  """Record a new hash for a data file, as R's ``.update_data_with_hash()`` does."""
195
204
  now = timestamp()
framework/dotenv.py CHANGED
@@ -112,19 +112,60 @@ def value(path: str | Path, key: str) -> str | None:
112
112
  return found or None
113
113
 
114
114
 
115
- def add_missing(path: str | Path, values: Mapping[str, str]) -> list[str]:
116
- """Append ``KEY=value`` lines for keys the file does not already define.
115
+ def _defines(line: str, key: str) -> bool:
116
+ if line.startswith("#") or not line.strip():
117
+ return False
118
+ match = _LINE.match(line)
119
+ return match is not None and match["key"] == key
117
120
 
118
- Returns the keys that were added. Existing lines are never changed.
121
+
122
+ def _placeholder(line: str, key: str) -> bool:
123
+ """A commented ``# KEY=`` line, as in a starter ``.env``."""
124
+ return re.match(rf"^#\s*(?:export\s+)?{re.escape(key)}=", line) is not None
125
+
126
+
127
+ def set_values(path: str | Path, values: Mapping[str, str], header: str | None = None) -> list[str]:
128
+ """Set ``KEY=value`` lines, keeping every other line as it is.
129
+
130
+ A key the file defines has its line replaced in place. Otherwise a commented
131
+ ``# KEY=`` placeholder is filled, or the line goes after the key set just
132
+ before it. Keys with no place go at the end, under ``header`` when given.
133
+ Returns the keys whose value changed.
119
134
  """
120
135
  file = Path(path)
121
136
  text = file.read_text(encoding="utf-8") if file.exists() else ""
122
137
  present = parse(text)
123
- added = [key for key in values if key not in present]
124
- if not added:
138
+ lines = text.splitlines()
139
+ changed: list[str] = []
140
+ appended: list[str] = []
141
+ previous: int | None = None
142
+ for key, new in values.items():
143
+ line = f"{key}={new}"
144
+ if key in present and present[key] == new:
145
+ previous = max(i for i, old in enumerate(lines) if _defines(old, key))
146
+ continue
147
+ changed.append(key)
148
+ defining = [i for i, old in enumerate(lines) if _defines(old, key)]
149
+ filled = next((i for i, old in enumerate(lines) if _placeholder(old, key)), None)
150
+ if defining:
151
+ for i in defining:
152
+ lines[i] = line
153
+ previous = defining[-1]
154
+ elif filled is not None:
155
+ lines[filled] = line
156
+ previous = filled
157
+ elif previous is not None:
158
+ lines.insert(previous + 1, line)
159
+ previous += 1
160
+ else:
161
+ appended.append(line)
162
+ if not changed:
125
163
  return []
126
- if text and not text.endswith("\n"):
127
- text += "\n"
128
- text += "".join(f"{key}={values[key]}\n" for key in added)
129
- file.write_text(text, encoding="utf-8")
130
- return added
164
+ if appended:
165
+ if lines and lines[-1].strip():
166
+ lines.append("")
167
+ if header:
168
+ lines.append(f"# {header}")
169
+ lines += appended
170
+ file.write_text("\n".join(lines) + "\n", encoding="utf-8")
171
+ return changed
framework/errors.py CHANGED
@@ -24,7 +24,8 @@ class UnsupportedFormatError(FrameworkError):
24
24
 
25
25
 
26
26
  class IntegrityError(FrameworkError):
27
- """A locked data file no longer matches the hash recorded in framework.db."""
27
+ """A locked data file no longer matches the hash recorded in framework.db, or a save
28
+ would change locked data."""
28
29
 
29
30
 
30
31
  class FrameworkWarning(UserWarning):
@@ -33,7 +34,7 @@ class FrameworkWarning(UserWarning):
33
34
 
34
35
  class DataChangedWarning(FrameworkWarning):
35
36
  """A data file changed since Framework last recorded its hash: an unlocked file read
36
- after it changed, or locked data that ``data_save()`` replaced with new contents."""
37
+ after it changed."""
37
38
 
38
39
 
39
40
  class CacheWarning(FrameworkWarning):
framework/notebooks.py CHANGED
@@ -242,7 +242,7 @@ def make_notebook(
242
242
  overwrite: Replace an existing file.
243
243
  subdir: A subfolder of ``dir``.
244
244
  title: The title, used exactly as given. Default: made from ``name`` in sentence
245
- case, which keeps a name with capitals as typed but can't know that a
245
+ case, which keeps a name with capitals as typed but cannot infer whether a
246
246
  lowercase file name such as "bp-for-ldl" holds acronyms. Pass
247
247
  ``title="BP for LDL"`` for those.
248
248
 
framework/outputs.py CHANGED
@@ -24,7 +24,12 @@ from framework import _csv, db
24
24
  from framework._log import inform
25
25
  from framework._paths import output_directory, relative_to_root
26
26
  from framework._private import private_read_note, warn_public_save
27
- from framework.errors import FrameworkError, FrameworkWarning, UnsupportedFormatError
27
+ from framework.errors import (
28
+ FrameworkError,
29
+ FrameworkWarning,
30
+ IntegrityError,
31
+ UnsupportedFormatError,
32
+ )
28
33
  from framework.integrity import file_hash
29
34
  from framework.settings import settings_read
30
35
 
@@ -64,6 +69,15 @@ def _check_overwrite(path: Path, overwrite: bool) -> None:
64
69
  raise FrameworkError(f"File already exists: {path}. Use overwrite=True to replace.")
65
70
 
66
71
 
72
+ def _check_locked(caller: str, path: Path) -> None:
73
+ """An output never replaces locked data."""
74
+ from framework.data import locked_data_at, locked_message
75
+
76
+ held = locked_data_at(path)
77
+ if held is not None:
78
+ raise IntegrityError(locked_message(caller, held, "Save under another name."))
79
+
80
+
67
81
  def _result_name(path: Path) -> str:
68
82
  """The results key: the path from the project root, so same-named files stay apart."""
69
83
  from framework.project import find_settings_file
@@ -130,6 +144,7 @@ def save_table(
130
144
  raise FrameworkError(f"format must be one of {', '.join(_TABLE_FORMATS)}")
131
145
  path = _output_file("tables", public, f"{name}{_TABLE_FORMATS[format]}")
132
146
  _check_overwrite(path, overwrite)
147
+ _check_locked("save_table()", path)
133
148
  if format == "csv":
134
149
  if kwargs:
135
150
  # The same readr form, with the caller's pandas options on top
@@ -300,7 +315,7 @@ def save_figure(
300
315
  The saved file, or for a list of formats, the saved files in that order.
301
316
 
302
317
  Raises:
303
- FrameworkError: When a format is unknown, ``plot`` can't be saved, or a file
318
+ FrameworkError: When a format is unknown, ``plot`` cannot be saved, or a file
304
319
  exists and ``overwrite`` is False. Nothing is written then.
305
320
  UnsupportedFormatError: When no backend writes a format (emf).
306
321
  """
@@ -413,6 +428,7 @@ def save_model(model: Any, name: str, public: bool = False, overwrite: bool = Tr
413
428
  rows_warned = True
414
429
  path = _output_file("models", public, f"{name}.pkl")
415
430
  _check_overwrite(path, overwrite)
431
+ _check_locked("save_model()", path)
416
432
  # Pickle to a temporary file first, so a failed dump leaves any existing model intact
417
433
  descriptor, temp = tempfile.mkstemp(prefix=f".{path.stem}.", suffix=".tmp", dir=path.parent)
418
434
  try:
framework/skill_pull.py CHANGED
@@ -258,11 +258,13 @@ def pull_skills(
258
258
 
259
259
  Raises:
260
260
  ProjectNotFoundError: When the folder is not a Framework project.
261
+ ProjectServerMissingError: When ``.env`` has ``FW_PROJECT_TOKEN`` but no
262
+ ``FW_CLOUD_URL``.
261
263
  """
262
264
  from framework._agents_md import refresh_skills
263
265
  from framework._log import inform, show_messages
264
266
  from framework.ai import _installed_spec
265
- from framework.cloud import CloudError
267
+ from framework.cloud import CloudError, ProjectServerMissingError
266
268
  from framework.skill_sync import _lock
267
269
  from framework.spec.merge import SpecError
268
270
 
@@ -274,6 +276,8 @@ def pull_skills(
274
276
  try:
275
277
  wanted = _cloud_skills(root, notes)
276
278
  source = "cloud"
279
+ except ProjectServerMissingError:
280
+ raise
277
281
  except (CloudError, SpecError) as error:
278
282
  reason = str(error).rstrip(".") or type(error).__name__
279
283
  inform(
framework/storage.py CHANGED
@@ -1225,7 +1225,7 @@ def publish_list(
1225
1225
 
1226
1226
  Like ``publish()``, it follows ``to``, then ``publish.default``. For a folder
1227
1227
  destination it lists the published artifacts, one row per slug. GitHub and Cloud
1228
- destinations can't be listed here: Framework Cloud artifacts are on the server's
1228
+ destinations cannot be listed here: Framework Cloud artifacts are on the server's
1229
1229
  Artifacts page, ``<server>/published``.
1230
1230
 
1231
1231
  Args:
framework/sync_all.py CHANGED
@@ -313,11 +313,13 @@ def _partial(function: str, done: str, outcome: dict[str, Any]) -> str:
313
313
 
314
314
  def _setup(root: Path) -> tuple[str, str, dict[str, Any]]:
315
315
  """The project's server, token, and package list; errors change nothing."""
316
- from framework.cloud import CloudError, _request
316
+ from framework.cloud import CloudError, ProjectServerMissingError, _request
317
317
 
318
318
  try:
319
319
  server, token = _connection(root)
320
320
  setup = _request("/api/v1/projects/setup", token, server).json()
321
+ except ProjectServerMissingError:
322
+ raise
321
323
  except CloudError as error:
322
324
  raise _unreachable(error) from error
323
325
  return server, token, setup if isinstance(setup, dict) else {}
@@ -469,9 +471,9 @@ def pull_all(
469
471
  are kept unless ``overwrite=True`` (edited skills are backed up first).
470
472
 
471
473
  The revisions pulled are kept in ``.framework/setup.lock.json`` (packages) and
472
- ``.framework/data.lock.json`` (data registry) for ``push_all()``. When a part can't be
473
- read or applied, the others still are, and the error names which parts were applied
474
- and which weren't.
474
+ ``.framework/data.lock.json`` (data registry) for ``push_all()``. When a part cannot be
475
+ read or applied, the others still proceed, and the error names which parts were applied
476
+ and which were skipped.
475
477
 
476
478
  Args:
477
479
  project_path: The project's root directory. Default: the current directory.
@@ -683,8 +685,8 @@ def _skills_push_plan(root: Path, force: bool) -> dict[str, Any]:
683
685
  from framework.skill_pull import _push_apply, _push_edited, _push_plan, _warning
684
686
 
685
687
  edited = _push_edited(root)
686
- url = cloud_server().url
687
- if edited and cloud_token(url) is None:
688
+ # Only edited skills need a server; with none chosen, NoServerError says how to pick one
689
+ if edited and cloud_token(url := cloud_server().url) is None:
688
690
  names = ", ".join(Path(paths[0]).name for _, paths in edited)
689
691
  raise CloudError(
690
692
  f"Not signed in, so edited skills ({names}) can't be pushed. {login_hint(url)}"
@@ -767,7 +769,7 @@ def push_all(
767
769
  edited skills, and its data registry. Cloud previews each part first (as a dry run),
768
770
  and the changes are listed together, grouped by part (Packages, Skills, Data registry),
769
771
  with what each push affects: new setups, zips, and Update on GitHub use the package
770
- list and data registry, and a skill's new version is used wherever it's attached. Then
772
+ list and data registry, and a skill's new version is used wherever it is attached. Then
771
773
  asks "Push these changes?" once. framework-py and the unpinned workflow tool packages
772
774
  every project gets are not sent.
773
775
 
@@ -779,13 +781,13 @@ def push_all(
779
781
  packages and the data registry go with the project token. Only data definitions are
780
782
  sent, never data files or hashes.
781
783
 
782
- When a part can't be pushed, the others still are, and the error names which parts
783
- were pushed and which weren't. A push resolves the project again from its blueprint's
784
+ When a part cannot be pushed, the others still proceed, and the error names which parts
785
+ were pushed and which were skipped. A push resolves the project again from its blueprint's
784
786
  latest version.
785
787
 
786
788
  Args:
787
789
  project_path: The project's root directory. Default: the current directory.
788
- remove: Remove packages and data entries from Cloud that this project doesn't have.
790
+ remove: Remove packages and data entries from Cloud that this project does not have.
789
791
  force: Push even when a part changed on Cloud since the last pull.
790
792
  confirm: True pushes without asking; False cancels. None asks in a console.
791
793
  dry_run: List the changes and send nothing.
@@ -794,11 +796,11 @@ def push_all(
794
796
  A dict: ``packages`` and ``data_registry`` (each with ``revision`` and Cloud's
795
797
  ``changes``: ``added``, ``changed``, ``removed``, and ``kept``), ``skills`` (each
796
798
  skill's ``name``, ``status``, and ``path``), ``applied`` (the parts pushed),
797
- ``failed`` (a reason for each part that wasn't), ``dry_run``, and ``message``.
799
+ ``failed`` (a reason for each part that failed), ``dry_run``, and ``message``.
798
800
 
799
801
  Raises:
800
802
  CloudError: Without a project token, offline, or when the server has no setup
801
- endpoint (nothing changes then), and when a part couldn't be pushed.
803
+ endpoint (nothing changes then), and when a part could not be pushed.
802
804
  FrameworkError: Without a console and without ``confirm=True`` or ``dry_run=True``.
803
805
  """
804
806
  from framework._log import inform, show_messages
@@ -8,7 +8,8 @@
8
8
  "0cdf0d8c885825802fee7688344ed2d607ad40df5dae99c4905b275d861a3f0b",
9
9
  "223a88db5e55b0d7ef9d85a68dddd5d4515b7522217f08d0ff52ea91bc3e99dc",
10
10
  "75d663831d581fbb5d30d12068b44f521bbeb42022df1cdc3c9acae9267bff28",
11
- "8ddcbd6f43a011612fc928014c457012bea16921d8a91802451693f5777dceca"
11
+ "8ddcbd6f43a011612fc928014c457012bea16921d8a91802451693f5777dceca",
12
+ "d26fb86e46ab55008ec3d9fb1b69066db2dcd05edf4a15fe0f3ea98f2c7d51b2"
12
13
  ],
13
14
  "framework-databases": [
14
15
  "b151906ffa9a8c886de99a9dbefd8c975b45cade5af8f7d1654dac9ba2596f38"
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "skill_id": "framework:framework-data",
3
- "release": 3,
4
- "hash": "05c8d581592e4d82d7b74e232e48e7465317f6ce07e92befb5257e5eb30ff2c4"
3
+ "release": 4,
4
+ "hash": "f023459703635800f30e11b45921265326afd97b993faea815353fd4f6697857"
5
5
  }
@@ -36,11 +36,12 @@ Prefer `fw.data_save()` to `DataFrame.to_csv()` and `DataFrame.to_parquet()`
36
36
  for project data. It writes Parquet or CSV, which R can also read.
37
37
 
38
38
  ```python
39
- # Locked by default: a later read raises an error if the file changed
40
- fw.data_save(final, "inputs/final/analysis_ready.csv")
39
+ # Unlocked by default, so a pipeline can save it again
40
+ fw.data_save(clean, "inputs.intermediate.survey_clean")
41
41
 
42
- # Data a pipeline rebuilds on every run: unlocked, so a rebuild doesn't warn
43
- fw.data_save(clean, "inputs.intermediate.survey_clean", locked=False)
42
+ # Locked: a later read raises an error if the file changed, and a save with
43
+ # new contents raises unless it passes unlock=True
44
+ fw.data_save(final, "inputs/final/analysis_ready.csv", locked=True)
44
45
  ```
45
46
 
46
47
  ## Folders
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: framework-py
3
- Version: 0.1.0.dev22
3
+ Version: 0.1.0.dev24
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
@@ -50,19 +50,13 @@ Description-Content-Type: text/markdown
50
50
 
51
51
  # framework-py
52
52
 
53
- Framework for Python: structured data science projects with a data catalog,
54
- data integrity tracking, caching, saved outputs, and guardrails for AI coding
55
- assistants.
53
+ Framework for Python provides structured data science projects with a data catalog, integrity tracking, caching, saved outputs, and AI coding assistant guardrails.
56
54
 
57
- framework-py is the Python implementation of
58
- [Framework](https://framework.table1.org). It reads and writes the same
59
- project files as the R package (`settings.yml`, the data catalog, and
60
- `framework.db`), so either language can work with a project's data. It works
61
- without Framework Cloud and without the `fw` command-line tool.
55
+ `framework-py` is the Python implementation of [Framework](https://framework.pub) ([documentation](https://py.framework.pub)). It reads and writes the same project files as the R package (`settings.yml`, the data catalog, and `framework.db`), so either language can read and verify a project's data. It runs standalone without Framework Cloud or the `fw` CLI.
62
56
 
63
- Status: in development. The plan is in [docs/plan.md](docs/plan.md).
57
+ Status: in development. See [docs/plan.md](docs/plan.md) for the implementation plan.
64
58
 
65
- ## Install
59
+ ## Installation
66
60
 
67
61
  ```sh
68
62
  uv add framework-py
@@ -70,22 +64,19 @@ uv add framework-py
70
64
  pip install framework-py
71
65
  ```
72
66
 
73
- Optional extras add database drivers, S3 storage, and more file formats:
74
- `postgres`, `mysql`, `duckdb`, `sqlserver`, `s3`, `excel`, `spss`, `sas`
75
- (version 8 SAS transport files), and `rds` (R's `.rds` data frames).
67
+ Optional extras install database drivers, S3 storage, and additional file formats: `postgres`, `mysql`, `duckdb`, `sqlserver`, `s3`, `excel`, `spss`, `sas` (version 8 SAS transport files), and `rds` (R `.rds` data frames).
76
68
 
77
69
  ```sh
78
70
  uv add "framework-py[postgres,s3]"
79
71
  ```
80
72
 
81
- Releases are published from GitHub Actions with signed build provenance. To
82
- check that a downloaded wheel or sdist was built from this repository:
73
+ GitHub Actions builds releases with signed build provenance. Verify that a wheel or sdist came from this repository:
83
74
 
84
75
  ```sh
85
76
  gh attestation verify framework_py-<version>-py3-none-any.whl --repo frameworktools/framework-py
86
77
  ```
87
78
 
88
- ## Use
79
+ ## Quick start
89
80
 
90
81
  ```python
91
82
  import framework as fw
@@ -95,17 +86,15 @@ info = fw.data_info("inputs.raw.survey")
95
86
  fw.data_list()
96
87
  ```
97
88
 
98
- After cloning a project, prepare it with:
89
+ Prepare a cloned project:
99
90
 
100
91
  ```sh
101
92
  uv run python -m framework bootstrap
102
93
  ```
103
94
 
104
- ## Sync with Framework Cloud
95
+ ## Framework Cloud sync
105
96
 
106
- Pull or push everything that syncs with the project on Framework Cloud: its
107
- packages, skills, and data registry. Each call lists the changes by part and
108
- asks once.
97
+ Pull or push packages, skills, and the data registry for a linked Framework Cloud project. Each call lists changes by section and asks once before applying them.
109
98
 
110
99
  ```python
111
100
  fw.pull_all(dry_run=True)
@@ -113,8 +102,7 @@ fw.pull_all()
113
102
  fw.push_all()
114
103
  ```
115
104
 
116
- `pull_skills()` / `push_skills()` and `pull_data_registry()` /
117
- `push_data_registry()` sync one part.
105
+ `pull_skills()`, `push_skills()`, `pull_data_registry()`, and `push_data_registry()` sync individual sections.
118
106
 
119
107
  ## Skill sync
120
108
 
@@ -125,9 +113,7 @@ fw.skills_sync(".agents/skills/my-skill", dry_run=True)
125
113
  fw.skills_sync(".agents/skills/my-skill")
126
114
  ```
127
115
 
128
- Local edits create account versions. Edited Framework skills become private
129
- forks with an exact source version. Concurrent edits stop for reconciliation.
130
- [Skill sync guide](https://framework.pub/docs/skill-sync).
116
+ Local edits create account versions. Edited Framework skills become private forks pinned to an exact source version. Concurrent edits stop for reconciliation. See the [Skill sync guide](https://framework.pub/docs/skill-sync).
131
117
 
132
118
  ## Development
133
119
 
@@ -140,10 +126,6 @@ uv run python scripts/check_parity.py
140
126
  uv run python scripts/sync_assets.py --check
141
127
  ```
142
128
 
143
- Shared files (JSON Schemas, the `framework.db` schema, conformance fixtures,
144
- and the R export list) are copied from the R package with
145
- `scripts/sync_assets.py`. Change them in the R repository, then copy them
146
- again.
129
+ `scripts/sync_assets.py` copies shared files (JSON Schemas, the `framework.db` schema, conformance fixtures, and the R export list) from the R package. Edit shared assets in the R repository, then run `scripts/sync_assets.py` here.
147
130
 
148
- `parity.toml` maps every function the R package exports to its Python
149
- equivalent, or gives the reason there is none.
131
+ `parity.toml` maps every exported R function to its Python equivalent or records why none exists.
@@ -20,28 +20,28 @@ framework/_tabular.py,sha256=zaUB83lMCCJql24BKv6CYD8d1s-jjViS0H4lTxeBzzQ,15131
20
20
  framework/_time.py,sha256=mv-BS3NjOo0hr6bwYRhUBY-3sG6SJmzaboaMD62QcJw,306
21
21
  framework/_wincred.py,sha256=oJGS37Dcw_PZVmiAGRu4H_lhcOC5-FqGGYfxVUGPPmU,3891
22
22
  framework/_yaml.py,sha256=eYqL4BsjyavrnJGxh88YziZtTgtWDzfeVAtA_Ru78wc,6200
23
- framework/adopt.py,sha256=oZ0I_9KEVjkaL9fr36zYk3XPMy6CqtFcA0X_yHY0Z3s,33439
23
+ framework/adopt.py,sha256=oOfpfwo8ehTMDthctihGHi11sEg8StQ3R_85Bq-oq8Y,33441
24
24
  framework/ai.py,sha256=hqBNXngw7VyQBcSt7kB20Zpa6N_5WS1hNhDi2zWJw0U,9218
25
25
  framework/bootstrap.py,sha256=mYlD1BG9KaG9PAIHlw3l6677fJYwQdtih95W9Rqmnho,9687
26
- framework/cache.py,sha256=jJxWIs6kQ7naMenC96pCPtqDCYiCe9c1KSITufV75q4,17160
26
+ framework/cache.py,sha256=z8Zaem5Q7dsAghuX9CgK_j0vhX5dDlRw7fl9f-CF3eA,17440
27
27
  framework/catalog.py,sha256=sl4V1judSCVoa2LYLXeQdDhWdsONTC_5s2_fpyPylto,13202
28
- framework/cloud.py,sha256=U9oy1nrt_puGFPKvnC3CFqifzZEhHKhPxvY4iPtMAIc,64083
28
+ framework/cloud.py,sha256=6w1oIfgGPPLLC2ILUvAqPXhIMlU08XJXd-KsP85QDbY,67608
29
29
  framework/config_home.py,sha256=iSb0VuENgNOSnsZ_v53xFqjRiGgrB7OzZbHbyDOqKzs,8265
30
- framework/connections.py,sha256=VUtT1kU3Z1kMxcYGnEzaEwgCvjeU5E71PxJAt8Ppzyw,32741
30
+ framework/connections.py,sha256=99JqrNAi2zBpNYyxLV6SYj-NAJjh56pYh9jaMSYOHCU,32742
31
31
  framework/console.py,sha256=zQ0LuFDcxe1W1kuc5E1bJ03h8d3cvwFoqDT8dAJQyN0,1267
32
- framework/create.py,sha256=sEWX_a250Ai47708gvi1wF69nLi4rD2aPWRUR6GWsM4,52954
33
- framework/data.py,sha256=5EwVKFwXABIhbEuf2MsvS8v_yJJ27upG0itSYA6N5mo,31557
34
- framework/data_registry.py,sha256=EOR6eD2xH9BoCKtAjWjnu6XRofqG0v3DnpOkmeaPPWI,22496
35
- framework/db.py,sha256=Wruez2V352xA3gjk5RcUi_0zncFsDwTs9Gwa2hXBY3Y,8099
32
+ framework/create.py,sha256=3ykMUhMslVsjiE__9Scx5v_6CU2Ye36wWqlp17j_vGw,53030
33
+ framework/data.py,sha256=cAOxwmF_nowXIZPl6vW5-ZUyI_z16H1bRJM60gJgeoo,36522
34
+ framework/data_registry.py,sha256=2hbXsoY9IF5Zj6lkiTE2RO2c5j2Z2vXKm2iTN7FdsQk,22499
35
+ framework/db.py,sha256=UYEUCvk4vGytBkmdNTUxRpYPtoFSDHwTpgpfWFw31aE,8522
36
36
  framework/display.py,sha256=0FuKUt67uf5h1WjD4bwzoruc2XAN4y_j3mz_f5FskhE,5334
37
- framework/dotenv.py,sha256=6YQVR8d0CnHXHAYxvP3E4Am4Ei9mzqN2g63w_ft7qa0,4642
38
- framework/errors.py,sha256=M0bQwnaBH_DE5n5QgHp_0S-SEwMeUxh9Kbx7n2wrVzw,1201
37
+ framework/dotenv.py,sha256=BYSF6YE92jXO7dqnaR-857XtZNYOx7FTuxCcCeIZ_yw,6172
38
+ framework/errors.py,sha256=kOXK0D-7xpcal8XsVnGAV9Nga-3xXxUFq-gdMn--El4,1177
39
39
  framework/features.py,sha256=NlR-0Xa4_d_nEBX9MicVyWqE_5L1-sA-zF_pJeNWznw,7729
40
40
  framework/global_config.py,sha256=fYLaxN_6Wc2xrIASn77dWkvGR3uuX-111bvfFPB82A4,11036
41
41
  framework/hooks.py,sha256=7FbEWBeMaI0QG7lW1myc3KjVmHd92MqhNjuFoTv1OFQ,21204
42
42
  framework/integrity.py,sha256=2hXk95tlNGs6HVTFA0AqcPWQg2AiO6Hy0APMIXHpCTU,586
43
- framework/notebooks.py,sha256=nBPDgZOSPZzTHaYvvXgyC_P2KXo7Zv471h47cvYOirA,21008
44
- framework/outputs.py,sha256=8CcKKedgR8rrgIgQP96l5x-geEGOoCnGIW3Ywq19oYc,27200
43
+ framework/notebooks.py,sha256=mZoxYrjG1y2MYb34w7oCPwoQtuKV8MwRgStnxR-Q468,21013
44
+ framework/outputs.py,sha256=bwc5_cEWvhBAW6PiDVjAXSM08mj9kBrgYSsNMTQR9nA,27627
45
45
  framework/packages.py,sha256=_ZE_eXDbonl7sNW_mT8MZXbpAhnGYOmBEyAbyQ6qQKo,16100
46
46
  framework/project.py,sha256=1aMzfqLZVkxdImyG3ZQcI-ayfV7Rc3Lrqv1JCsY0GVI,5719
47
47
  framework/publish_bundle.py,sha256=0vOrLZXSbdV2Fl05smq-2-04Fsts0na3rB_Y0mCOcuY,28802
@@ -51,10 +51,10 @@ framework/scaffold.py,sha256=ku_rFPcOcV77ZxCJSG1tdxAqJhriuTuA6j2jOmjBaIs,15958
51
51
  framework/scratch.py,sha256=idxthUR5BIMX7FIGS7KzIuhOrO3-HKLbBsV8It3EEE4,3890
52
52
  framework/security.py,sha256=-x66bSIIE_xOzkTf5Ojt7xIECKuAIpKVJZ5TtIGrwys,51147
53
53
  framework/settings.py,sha256=Sb2YyE53aYLWPj423P-pQVCvRpLsiHydgZh2K0luTQQ,23893
54
- framework/skill_pull.py,sha256=E6N1kMLJAww_wt-kSSNWhcqu-KOsago1C8ClqQ-XHlY,21669
54
+ framework/skill_pull.py,sha256=vr_yxe446JhHbtI0hps19AnLN6S7BacSt2oxn7BIlos,21859
55
55
  framework/skill_sync.py,sha256=0gqaeVkiNaqGJxmrVrKrYaX8wI3DNFZUsJEgG63xcKc,23060
56
- framework/storage.py,sha256=Jt8_adVwWMQmASzSUb97gLEMWz2GlmDUJmPgoYSgOBU,55485
57
- framework/sync_all.py,sha256=lRtXNbirHh45EcHpZnYPIQ7v4ahzGSENlBLfbx0i5vE,34422
56
+ framework/storage.py,sha256=UnTL9buYwawFFGll4D0FRDqsVXjj_B2uYMELXntfq_M,55486
57
+ framework/sync_all.py,sha256=tmSnapf-JfaL1_8rMpnr3wqHvSGJamn7c8ja4GQFKHA,34610
58
58
  framework/upgrade.py,sha256=WtghpLR65YFH_JQFmo1JlH9lHdwsXQd-ZzzOTmyOL28,65593
59
59
  framework/_assets/init.sql,sha256=-aIiuIcCmBniGKq-CHdRtUiV9e_CLXoqxxd05snmgOE,1156
60
60
  framework/_assets/adopt/rules.json,sha256=Ao_8reCfxohbF27hzVBjXJeMUP2E9MzlLMqrLutv41o,7603
@@ -113,15 +113,15 @@ framework/spec/merge.py,sha256=gvauBNsFJYe_1J3sO9eF7PSt7mii8ONmnPe8qmyOaGg,6303
113
113
  framework/spec/resolve.py,sha256=gyAewGbMcdTbh4feUp6DEj_D9wPBDzRiDC8PTOpyp6Q,12590
114
114
  framework/templates/defaults.yml,sha256=OPNe85BXmZ1G8CN-RZ62Ku-_uLtx5yC7nqltBL224kE,3933
115
115
  framework/templates/reader.html,sha256=SBw3I3rRMdAyoBosMVuZ9Yp177P11CoxIAaG0OOuvQg,19772
116
- framework/templates/skill-history.json,sha256=8eC1kESNqjDmSzO49JGAYXXH8lZ-6e-iAKpsHrSgKf0,2044
116
+ framework/templates/skill-history.json,sha256=thmGpcHEK67UjWnRvWY0I3WA3Xu2oFbZKlMS_vZkeEw,2118
117
117
  framework/templates/gitignore/course,sha256=6SL07s0J71lPepEdAd5BFWBF6Q3WM-SbEXy8mS-uCwc,3085
118
118
  framework/templates/gitignore/presentation,sha256=T4iJwMjivw4MjZExBM427nSwJmJoCbutIsJW6QOAomU,2987
119
119
  framework/templates/gitignore/project,sha256=A8y6g1SgkOb2uGfPRuQqhtwUEU5ev5vrronkgZZmcVI,2866
120
120
  framework/templates/gitignore/sensitive,sha256=gkJwc2bYDtR3QFgGflvJlihpsb5rQkX4JQ7Frlxg0Bo,3794
121
121
  framework/templates/skills/framework-cache/.framework-skill.json,sha256=aGE7pPEXxDDgfCXbwpgxN_3XEvAJ3i0udvDswboOoNM,140
122
122
  framework/templates/skills/framework-cache/SKILL.md,sha256=HMFnPD5VooarzBo9HU-TCodK7AgKes6rz6kBSjgsUqs,768
123
- framework/templates/skills/framework-data/.framework-skill.json,sha256=JS6uObJBN-AFFv51CByODlUwwTk0OMqUX3WeO2OtB78,139
124
- framework/templates/skills/framework-data/SKILL.md,sha256=DN8NjIhYJYAv7naINE7S1getQN9drpnEkFsnXYYaPws,1816
123
+ framework/templates/skills/framework-data/.framework-skill.json,sha256=JlgWP9twOVFrQyw54trjTCJWd-ZnvdKo-CcG8eLPCGo,139
124
+ framework/templates/skills/framework-data/SKILL.md,sha256=0m-4bkarVQCOw9n7G2kGbbLc0F7fShX-Dz6pjyx9UbI,1850
125
125
  framework/templates/skills/framework-databases/.framework-skill.json,sha256=_xbitYo6BaH5P5auj_flabnt4WfIHCnhsm5PAmKJmi4,144
126
126
  framework/templates/skills/framework-databases/SKILL.md,sha256=sVGQb_qajIht6Zqdvv2Ml1tFyt5a-PfRZU2sm6JZbzg,768
127
127
  framework/templates/skills/framework-outputs/.framework-skill.json,sha256=l-guJxNb4E_ZW74LIT-aMWn278jPDdg1Lv6FvB1CpfI,142
@@ -139,7 +139,7 @@ framework/templates/stubs/notebook-default.qmd,sha256=8Js1S2BcHYeQWmJS-kt31gBvIj
139
139
  framework/templates/stubs/notebook-minimal.qmd,sha256=2U2k8judffhrh_6m6r6OAbQBCYEtViAjeKRBqBYCJTM,178
140
140
  framework/templates/stubs/notebook-revealjs.qmd,sha256=_ztT_gHoudpB5DIjlbvtB5zQ8163DeV8xbWcT-HgJrI,409
141
141
  framework/templates/stubs/script-default.py,sha256=vbWqgW0_rHot17mQC3tYb92g_9L-cbTOeL3y99BRrSk,216
142
- framework_py-0.1.0.dev22.dist-info/METADATA,sha256=vR67YetfenMQ0yvq9bNDuoQY-FOgV-ar6g-zRBbF76M,4647
143
- framework_py-0.1.0.dev22.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
144
- framework_py-0.1.0.dev22.dist-info/licenses/LICENSE,sha256=giOOgSwALkZimC7uhLZQK8Untez641bLW1-2-Cjvmq0,1072
145
- framework_py-0.1.0.dev22.dist-info/RECORD,,
142
+ framework_py-0.1.0.dev24.dist-info/METADATA,sha256=AO0jqjl_730e6cN5rB6qlmGY77wCb7wqn6ZOEK6jaEE,4682
143
+ framework_py-0.1.0.dev24.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
144
+ framework_py-0.1.0.dev24.dist-info/licenses/LICENSE,sha256=giOOgSwALkZimC7uhLZQK8Untez641bLW1-2-Cjvmq0,1072
145
+ framework_py-0.1.0.dev24.dist-info/RECORD,,