framework-py 0.1.0.dev2__py3-none-any.whl → 0.1.0.dev4__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.
Files changed (46) hide show
  1. framework/__init__.py +5 -0
  2. framework/__main__.py +64 -5
  3. framework/_agents_md.py +210 -0
  4. framework/_assets/adopt/rules.json +161 -0
  5. framework/_assets/features/jupyter.json +39 -0
  6. framework/_assets/features/quarto.json +18 -0
  7. framework/_assets/features/quarto_manuscript.json +35 -0
  8. framework/_assets/features/quarto_slides.json +29 -0
  9. framework/_assets/features/renv.json +20 -0
  10. framework/_assets/features/targets.json +34 -0
  11. framework/_assets/features/uv.json +17 -0
  12. framework/_assets/schema/layer.v1.json +45 -7
  13. framework/_assets/schema/layers.v1.json +49 -7
  14. framework/_assets/schema/spec.v1.json +38 -7
  15. framework/_assets/sets/packages/tidyverse-analysis.json +42 -0
  16. framework/_assets/sets/skills/framework.json +25 -0
  17. framework/_assets/sets/skills/ggplot2.json +26 -0
  18. framework/_assets/workflows/jupyter.json +14 -0
  19. framework/_assets/workflows/quarto.json +14 -0
  20. framework/_assets/workflows/scripts.json +18 -0
  21. framework/_defaults_cache.py +47 -0
  22. framework/_pages.py +228 -0
  23. framework/_paths.py +19 -9
  24. framework/_private.py +69 -0
  25. framework/adopt.py +365 -0
  26. framework/ai.py +13 -20
  27. framework/cloud.py +139 -14
  28. framework/create.py +395 -18
  29. framework/features.py +195 -0
  30. framework/hooks.py +69 -7
  31. framework/notebooks.py +9 -1
  32. framework/outputs.py +6 -1
  33. framework/quarto.py +77 -25
  34. framework/scaffold.py +50 -3
  35. framework/spec/check.py +31 -7
  36. framework/spec/merge.py +1 -0
  37. framework/spec/resolve.py +80 -6
  38. framework/storage.py +96 -50
  39. framework/templates/defaults.yml +0 -1
  40. framework/templates/skills/framework-outputs/SKILL.md +5 -5
  41. framework/templates/skills/framework-sensitive-data/SKILL.md +3 -2
  42. {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/METADATA +1 -1
  43. framework_py-0.1.0.dev4.dist-info/RECORD +84 -0
  44. framework_py-0.1.0.dev2.dist-info/RECORD +0 -64
  45. {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/WHEEL +0 -0
  46. {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/licenses/LICENSE +0 -0
framework/cloud.py CHANGED
@@ -30,7 +30,7 @@ import subprocess
30
30
  import sys
31
31
  import tempfile
32
32
  import zipfile
33
- from collections.abc import Mapping
33
+ from collections.abc import Mapping, Sequence
34
34
  from dataclasses import dataclass
35
35
  from datetime import UTC, datetime
36
36
  from pathlib import Path
@@ -41,6 +41,7 @@ import pandas as pd
41
41
 
42
42
  from framework import _secretservice, _wincred, _yaml, db, dotenv
43
43
  from framework._log import inform, show_messages
44
+ from framework._private import confirm_private_upload
44
45
  from framework.config_home import config_dir, ensure_config_dir, r_config_dir
45
46
  from framework.errors import FrameworkError, FrameworkWarning
46
47
  from framework.integrity import file_hash
@@ -300,12 +301,40 @@ def _client() -> httpx.Client:
300
301
  )
301
302
 
302
303
 
304
+ class CloudOfflineError(CloudError):
305
+ """The server couldn't be reached: a network error, a timeout, or a 5xx reply.
306
+
307
+ 401 and 403 are authentication errors, never offline.
308
+ """
309
+
310
+
311
+ class _MissingEndpointError(CloudError):
312
+ """HTTP 404 or 405: an older server without this endpoint."""
313
+
314
+
303
315
  def _error(response: httpx.Response, what: str) -> CloudError:
304
316
  try:
305
- message = response.json().get("message")
317
+ body = response.json()
306
318
  except Exception:
307
- message = None
308
- return CloudError(message or f"{what} failed (HTTP {response.status_code})")
319
+ body = None
320
+ body = body if isinstance(body, dict) else {}
321
+ message = body.get("message") or f"{what} failed (HTTP {response.status_code})"
322
+ # A 422 lists each problem by field
323
+ errors = body.get("errors")
324
+ if isinstance(errors, dict):
325
+ details = [
326
+ f" - {field}: {text}"
327
+ for field, texts in errors.items()
328
+ for text in (texts if isinstance(texts, list) else [texts])
329
+ if str(text) not in str(message)
330
+ ]
331
+ if details:
332
+ message = "\n".join([str(message), *details])
333
+ if response.status_code in (404, 405):
334
+ return _MissingEndpointError(str(message))
335
+ if response.status_code >= 500:
336
+ return CloudOfflineError(str(message))
337
+ return CloudError(str(message))
309
338
 
310
339
 
311
340
  def api(
@@ -316,6 +345,16 @@ def api(
316
345
  body: Mapping[str, Any] | None = None,
317
346
  ) -> Any:
318
347
  """Call the cloud API and return the decoded JSON."""
348
+ return _request(path, token, url, method, body).json()
349
+
350
+
351
+ def _request(
352
+ path: str,
353
+ token: str,
354
+ url: str,
355
+ method: str = "GET",
356
+ body: Mapping[str, Any] | None = None,
357
+ ) -> httpx.Response:
319
358
  try:
320
359
  with _client() as client:
321
360
  response = client.request(
@@ -325,10 +364,26 @@ def api(
325
364
  headers={"Authorization": f"Bearer {token}"},
326
365
  )
327
366
  except httpx.HTTPError as error:
328
- raise CloudError(f"Could not reach {host(url)}: {error}") from error
367
+ raise CloudOfflineError(f"Could not reach {host(url)}: {error}") from error
329
368
  if response.is_error:
330
369
  raise _error(response, "Cloud request")
331
- return response.json()
370
+ return response
371
+
372
+
373
+ def resolve_choices(
374
+ body: Mapping[str, Any], token: str, url: str
375
+ ) -> tuple[dict[str, Any], str | None]:
376
+ """Resolve project choices on the cloud: the envelope and the defaults revision.
377
+
378
+ Each Framework-Notice header is shown as a message.
379
+ """
380
+ response = _request("/api/v2/resolve", token, url, method="POST", body=body)
381
+ for notice in response.headers.get_list("Framework-Notice"):
382
+ inform(notice)
383
+ envelope = response.json()
384
+ if not isinstance(envelope, dict):
385
+ raise CloudError("The server returned an unexpected project definition.")
386
+ return envelope, response.headers.get("Framework-Defaults-Revision")
332
387
 
333
388
 
334
389
  # Logging in ---------------------------------------------------------------------------
@@ -803,14 +858,23 @@ def cloud_publish(
803
858
  self_contained: bool = True,
804
859
  slug: str | bool | None = None,
805
860
  title: str | None = None,
861
+ include_private: bool = False,
806
862
  ) -> str:
807
863
  """Publish rendered HTML (or a .qmd or .ipynb to render) to the project's cloud server.
808
864
 
809
865
  Accepts a self-contained ``.html``, an ``.html`` with a sibling
810
866
  ``<name>_files/`` folder, a render output folder, or a ``.qmd`` or ``.ipynb``. Each
811
867
  publish adds a version. ``slug`` names the document and turns on its
812
- readable URL (``True`` uses the derived name, ``False`` turns it off).
868
+ readable URL (``True`` uses the derived name, ``False`` turns it off). A source with
869
+ "private" in its path needs confirmation, or ``include_private=True``.
813
870
  """
871
+ sources = [source]
872
+ if source.is_dir():
873
+ sources = sorted(p for p in source.rglob("*") if p.is_file())
874
+ elif source.with_name(f"{source.stem}_files").is_dir():
875
+ assets = source.with_name(f"{source.stem}_files")
876
+ sources += sorted(p for p in assets.rglob("*") if p.is_file())
877
+ confirm_private_upload(sources, include_private)
814
878
  token = _require_project_token()
815
879
  with tempfile.TemporaryDirectory(prefix="fw_publish_") as temp:
816
880
  stage = Path(temp)
@@ -913,7 +977,12 @@ def cloud_publish(
913
977
 
914
978
 
915
979
  def write_project_token(project_dir: Path, token: str, url: str) -> list[str]:
916
- """Add the project's key and server to its ``.env`` (never to the settings)."""
980
+ """Add the project's key and server to its ``.env`` (never to the settings).
981
+
982
+ Git is made to ignore ``.env`` first, so the token can't be committed.
983
+ """
984
+ from framework.create import keep_env_out_of_git
985
+
917
986
  env = project_dir / ".env"
918
987
  present = dotenv.read(env)
919
988
  missing = {
@@ -921,6 +990,7 @@ def write_project_token(project_dir: Path, token: str, url: str) -> list[str]:
921
990
  }
922
991
  if not missing:
923
992
  return []
993
+ keep_env_out_of_git(project_dir)
924
994
  text = env.read_text(encoding="utf-8") if env.exists() else ""
925
995
  if text and not text.endswith("\n"):
926
996
  text += "\n"
@@ -933,20 +1003,75 @@ def write_project_token(project_dir: Path, token: str, url: str) -> list[str]:
933
1003
  return list(missing)
934
1004
 
935
1005
 
936
- def register_project(project_dir: Path, name: str, type: str) -> Any:
937
- """Register a new local project on the cloud when logged in. Never fails creation."""
1006
+ def registration_body(
1007
+ name: str,
1008
+ type: str,
1009
+ spec: Mapping[str, Any],
1010
+ package_sets: Sequence[str] = (),
1011
+ skill_sets: Sequence[str] = (),
1012
+ ) -> dict[str, Any]:
1013
+ """The choices a project built offline was made from, for ``/api/v2/projects``.
1014
+
1015
+ Each of Framework's five types is a structure of the same name.
1016
+ """
1017
+ ai = spec.get("ai") or {}
1018
+ body: dict[str, Any] = {
1019
+ "name": name,
1020
+ "language": "python",
1021
+ "structure": f"framework/{type}",
1022
+ "tools": dict(spec.get("tools") or {}),
1023
+ "settings": {
1024
+ "sensitive": (spec.get("security") or {}).get("sensitive") is True,
1025
+ "git": (spec.get("git") or {}).get("use_git") is not False,
1026
+ "ai": {
1027
+ "enabled": ai.get("enabled") is True,
1028
+ "assistants": dict(ai.get("assistants") or {}),
1029
+ },
1030
+ },
1031
+ }
1032
+ if package_sets:
1033
+ body["package_sets"] = [s if "/" in s else f"framework/{s}" for s in package_sets]
1034
+ if skill_sets:
1035
+ body["skill_sets"] = [s if "/" in s else f"framework/{s}" for s in skill_sets]
1036
+ return body
1037
+
1038
+
1039
+ def register_project(
1040
+ project_dir: Path,
1041
+ name: str,
1042
+ type: str,
1043
+ spec: Mapping[str, Any] | None = None,
1044
+ package_sets: Sequence[str] = (),
1045
+ skill_sets: Sequence[str] = (),
1046
+ ) -> Any:
1047
+ """Register a new local project on the cloud when logged in. Never fails creation.
1048
+
1049
+ The cloud records the structure, tools, sets, and settings the project
1050
+ was built from. A server without ``/api/v2/projects`` gets the older
1051
+ registration.
1052
+ """
938
1053
  server = cloud_server().url
939
1054
  token = cloud_token(server)
940
1055
  if token is None:
941
1056
  return None
942
- body = {"name": name, "project_type": type, "language": "python"}
943
1057
  try:
944
- result = api("/api/v1/projects", token, server, method="POST", body=body)
1058
+ if spec is not None:
1059
+ body = registration_body(name, type, spec, package_sets, skill_sets)
1060
+ try:
1061
+ result = api("/api/v2/projects", token, server, method="POST", body=body)
1062
+ slug, project_token = result.get("slug"), result.get("token")
1063
+ except _MissingEndpointError:
1064
+ spec = None
1065
+ if spec is None:
1066
+ body = {"name": name, "project_type": type, "language": "python"}
1067
+ result = api("/api/v1/projects", token, server, method="POST", body=body)
1068
+ slug, project_token = result["project"]["slug"], result["pull_token"]
945
1069
  except CloudError as error:
946
1070
  inform(f"Cloud project registration skipped: {error}")
947
1071
  return None
948
- inform(f"[ok] Registered on {host(server)}: {result['project']['slug']}")
949
- write_project_token(project_dir, result["pull_token"], server)
1072
+ inform(f"[ok] Registered on {host(server)}: {slug}")
1073
+ if project_token:
1074
+ write_project_token(project_dir, str(project_token), server)
950
1075
  return result
951
1076
 
952
1077