framework-py 0.1.0.dev3__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 (40) 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/_paths.py +19 -9
  23. framework/adopt.py +365 -0
  24. framework/ai.py +13 -20
  25. framework/cloud.py +128 -13
  26. framework/create.py +395 -18
  27. framework/features.py +195 -0
  28. framework/hooks.py +69 -7
  29. framework/notebooks.py +9 -1
  30. framework/outputs.py +6 -1
  31. framework/quarto.py +77 -25
  32. framework/scaffold.py +50 -3
  33. framework/spec/check.py +31 -7
  34. framework/spec/merge.py +1 -0
  35. framework/spec/resolve.py +80 -6
  36. framework/templates/defaults.yml +0 -1
  37. {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/METADATA +1 -1
  38. {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/RECORD +40 -22
  39. {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/WHEEL +0 -0
  40. {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev4.dist-info}/licenses/LICENSE +0 -0
@@ -0,0 +1,17 @@
1
+ {
2
+ "id": "uv",
3
+ "name": "uv",
4
+ "description": "Manages the project's Python environment with uv: pyproject.toml and uv.lock.",
5
+ "category": "reproducibility",
6
+ "language": [
7
+ "python"
8
+ ],
9
+ "requires": [],
10
+ "conflicts": [],
11
+ "layer": {
12
+ "tools": {
13
+ "uv": true
14
+ }
15
+ },
16
+ "language_layers": {}
17
+ }
@@ -13,14 +13,38 @@
13
13
  "minLength": 1
14
14
  },
15
15
  "type": {
16
+ "type": "string",
17
+ "pattern": "^[a-z][a-z0-9_]*$",
18
+ "description": "A label for the blueprint the project came from. Framework's own are project, project_sensitive, course, presentation, and bare. Behavior follows settings, tools, and core_files, not this label."
19
+ },
20
+ "core_files": {
21
+ "type": "boolean",
22
+ "description": "Whether the structure writes Framework's core files (starter scripts and .env). false for bare structures. Missing means true."
23
+ },
24
+ "settings_layout": {
16
25
  "type": "string",
17
26
  "enum": [
18
- "project",
19
- "project_sensitive",
20
- "course",
21
- "presentation",
22
- "bare"
23
- ]
27
+ "split",
28
+ "flat"
29
+ ],
30
+ "description": "split: connections, packages, and data in settings/*.yml. flat: everything in settings.yml. Missing means split for Framework's project and project_sensitive structures and flat for the rest."
31
+ },
32
+ "tools": {
33
+ "type": "object",
34
+ "additionalProperties": {
35
+ "anyOf": [
36
+ {
37
+ "type": "boolean"
38
+ },
39
+ {
40
+ "type": "null"
41
+ }
42
+ ]
43
+ },
44
+ "description": "Tool id -> on. Missing means off. Framework's tools are defined in inst/features/<id>.json. In a layer, later layers override earlier ones key by key.",
45
+ "propertyNames": {
46
+ "pattern": "^[a-z][a-z0-9_]*$"
47
+ }
24
48
  },
25
49
  "language": {
26
50
  "type": "string",
@@ -238,9 +262,19 @@
238
262
  "enum": [
239
263
  "quarto",
240
264
  "rmarkdown",
241
- "jupyter"
265
+ "jupyter",
266
+ "script"
242
267
  ]
243
268
  },
269
+ "workflow": {
270
+ "type": "string",
271
+ "enum": [
272
+ "quarto",
273
+ "jupyter",
274
+ "scripts"
275
+ ],
276
+ "description": "How notebooks are written. quarto allows notebook_format quarto (or rmarkdown in R), jupyter allows jupyter, and scripts allows script."
277
+ },
244
278
  "ide": {
245
279
  "type": "string",
246
280
  "enum": [
@@ -451,6 +485,10 @@
451
485
  },
452
486
  "additionalProperties": false
453
487
  },
488
+ "adopted": {
489
+ "type": "boolean",
490
+ "description": "True when adopt() made an existing folder a project, mapping its folders in place"
491
+ },
454
492
  "framework_version": {
455
493
  "type": "string",
456
494
  "description": "Version of the R or Python package that created the project"
@@ -164,6 +164,10 @@
164
164
  "id"
165
165
  ]
166
166
  },
167
+ "adopted": {
168
+ "type": "boolean",
169
+ "description": "True when adopt() made an existing folder a project, mapping its folders in place"
170
+ },
167
171
  "framework_version": {
168
172
  "type": "string",
169
173
  "description": "Version of the R or Python package that created the project"
@@ -335,14 +339,38 @@
335
339
  "minLength": 1
336
340
  },
337
341
  "type": {
342
+ "type": "string",
343
+ "pattern": "^[a-z][a-z0-9_]*$",
344
+ "description": "A label for the blueprint the project came from. Framework's own are project, project_sensitive, course, presentation, and bare. Behavior follows settings, tools, and core_files, not this label."
345
+ },
346
+ "core_files": {
347
+ "type": "boolean",
348
+ "description": "Whether the structure writes Framework's core files (starter scripts and .env). false for bare structures. Missing means true."
349
+ },
350
+ "settings_layout": {
338
351
  "type": "string",
339
352
  "enum": [
340
- "project",
341
- "project_sensitive",
342
- "course",
343
- "presentation",
344
- "bare"
345
- ]
353
+ "split",
354
+ "flat"
355
+ ],
356
+ "description": "split: connections, packages, and data in settings/*.yml. flat: everything in settings.yml. Missing means split for Framework's project and project_sensitive structures and flat for the rest."
357
+ },
358
+ "tools": {
359
+ "type": "object",
360
+ "additionalProperties": {
361
+ "anyOf": [
362
+ {
363
+ "type": "boolean"
364
+ },
365
+ {
366
+ "type": "null"
367
+ }
368
+ ]
369
+ },
370
+ "description": "Tool id -> on. Missing means off. Framework's tools are defined in inst/features/<id>.json. In a layer, later layers override earlier ones key by key.",
371
+ "propertyNames": {
372
+ "pattern": "^[a-z][a-z0-9_]*$"
373
+ }
346
374
  },
347
375
  "language": {
348
376
  "type": "string",
@@ -560,9 +588,19 @@
560
588
  "enum": [
561
589
  "quarto",
562
590
  "rmarkdown",
563
- "jupyter"
591
+ "jupyter",
592
+ "script"
564
593
  ]
565
594
  },
595
+ "workflow": {
596
+ "type": "string",
597
+ "enum": [
598
+ "quarto",
599
+ "jupyter",
600
+ "scripts"
601
+ ],
602
+ "description": "How notebooks are written. quarto allows notebook_format quarto (or rmarkdown in R), jupyter allows jupyter, and scripts allows script."
603
+ },
566
604
  "ide": {
567
605
  "type": "string",
568
606
  "enum": [
@@ -773,6 +811,10 @@
773
811
  },
774
812
  "additionalProperties": false
775
813
  },
814
+ "adopted": {
815
+ "type": "boolean",
816
+ "description": "True when adopt() made an existing folder a project, mapping its folders in place"
817
+ },
776
818
  "framework_version": {
777
819
  "type": "string",
778
820
  "description": "Version of the R or Python package that created the project"
@@ -13,14 +13,31 @@
13
13
  "minLength": 1
14
14
  },
15
15
  "type": {
16
+ "type": "string",
17
+ "pattern": "^[a-z][a-z0-9_]*$",
18
+ "description": "A label for the blueprint the project came from. Framework's own are project, project_sensitive, course, presentation, and bare. Behavior follows settings, tools, and core_files, not this label."
19
+ },
20
+ "core_files": {
21
+ "type": "boolean",
22
+ "description": "Whether the structure writes Framework's core files (starter scripts and .env). false for bare structures. Missing means true."
23
+ },
24
+ "settings_layout": {
16
25
  "type": "string",
17
26
  "enum": [
18
- "project",
19
- "project_sensitive",
20
- "course",
21
- "presentation",
22
- "bare"
23
- ]
27
+ "split",
28
+ "flat"
29
+ ],
30
+ "description": "split: connections, packages, and data in settings/*.yml. flat: everything in settings.yml. Missing means split for Framework's project and project_sensitive structures and flat for the rest."
31
+ },
32
+ "tools": {
33
+ "type": "object",
34
+ "additionalProperties": {
35
+ "type": "boolean"
36
+ },
37
+ "description": "Tool id -> on. Missing means off. Framework's tools are defined in inst/features/<id>.json. In a layer, later layers override earlier ones key by key.",
38
+ "propertyNames": {
39
+ "pattern": "^[a-z][a-z0-9_]*$"
40
+ }
24
41
  },
25
42
  "language": {
26
43
  "type": "string",
@@ -217,9 +234,19 @@
217
234
  "enum": [
218
235
  "quarto",
219
236
  "rmarkdown",
220
- "jupyter"
237
+ "jupyter",
238
+ "script"
221
239
  ]
222
240
  },
241
+ "workflow": {
242
+ "type": "string",
243
+ "enum": [
244
+ "quarto",
245
+ "jupyter",
246
+ "scripts"
247
+ ],
248
+ "description": "How notebooks are written. quarto allows notebook_format quarto (or rmarkdown in R), jupyter allows jupyter, and scripts allows script."
249
+ },
223
250
  "ide": {
224
251
  "type": "string",
225
252
  "enum": [
@@ -409,6 +436,10 @@
409
436
  "id"
410
437
  ]
411
438
  },
439
+ "adopted": {
440
+ "type": "boolean",
441
+ "description": "True when adopt() made an existing folder a project, mapping its folders in place"
442
+ },
412
443
  "framework_version": {
413
444
  "type": "string",
414
445
  "description": "Version of the R or Python package that created the project"
@@ -0,0 +1,42 @@
1
+ {
2
+ "id": "tidyverse-analysis",
3
+ "name": "Tidyverse analysis",
4
+ "description": "The tidyverse packages most analyses use, loaded by scaffold().",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "dplyr": {
12
+ "source": "cran",
13
+ "auto_attach": true
14
+ },
15
+ "tidyr": {
16
+ "source": "cran",
17
+ "auto_attach": true
18
+ },
19
+ "ggplot2": {
20
+ "source": "cran",
21
+ "auto_attach": true
22
+ },
23
+ "purrr": {
24
+ "source": "cran",
25
+ "auto_attach": true
26
+ },
27
+ "stringr": {
28
+ "source": "cran",
29
+ "auto_attach": true
30
+ },
31
+ "forcats": {
32
+ "source": "cran",
33
+ "auto_attach": true
34
+ },
35
+ "lubridate": {
36
+ "source": "cran",
37
+ "auto_attach": true
38
+ }
39
+ }
40
+ }
41
+ }
42
+ }
@@ -0,0 +1,25 @@
1
+ {
2
+ "id": "framework",
3
+ "name": "Framework basics",
4
+ "description": "How to work in a Framework project: notebooks and scripts, reading and saving data, packages, and outputs.",
5
+ "language": [
6
+ "r",
7
+ "python"
8
+ ],
9
+ "layer": {
10
+ "skills": {
11
+ "framework-workflow": {
12
+ "package": true
13
+ },
14
+ "framework-data": {
15
+ "package": true
16
+ },
17
+ "framework-packages": {
18
+ "package": true
19
+ },
20
+ "framework-outputs": {
21
+ "package": true
22
+ }
23
+ }
24
+ }
25
+ }
@@ -0,0 +1,26 @@
1
+ {
2
+ "id": "ggplot2",
3
+ "name": "Figures with ggplot2",
4
+ "description": "Exploratory and publication figures with ggplot2.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "skills": {
10
+ "ggplot2-exploring": {
11
+ "package": true
12
+ },
13
+ "ggplot2-publishing": {
14
+ "package": true
15
+ }
16
+ },
17
+ "packages": {
18
+ "default_packages": {
19
+ "ggplot2": {
20
+ "source": "cran",
21
+ "auto_attach": true
22
+ }
23
+ }
24
+ }
25
+ }
26
+ }
@@ -0,0 +1,14 @@
1
+ {
2
+ "id": "jupyter",
3
+ "name": "Jupyter",
4
+ "description": "Write notebooks in Jupyter (.ipynb) with the kernel for the project's language. Quarto stays available to render and publish them.",
5
+ "language": ["r", "python"],
6
+ "requires": ["jupyter", "quarto"],
7
+ "layer": {
8
+ "scaffold": {
9
+ "workflow": "jupyter",
10
+ "notebook_format": "jupyter"
11
+ }
12
+ },
13
+ "language_layers": {}
14
+ }
@@ -0,0 +1,14 @@
1
+ {
2
+ "id": "quarto",
3
+ "name": "Quarto",
4
+ "description": "Write notebooks as Quarto documents (.qmd), or R Markdown in R projects. Quarto renders them to HTML, PDF, and Word.",
5
+ "language": ["r", "python"],
6
+ "requires": ["quarto"],
7
+ "layer": {
8
+ "scaffold": {
9
+ "workflow": "quarto",
10
+ "notebook_format": "quarto"
11
+ }
12
+ },
13
+ "language_layers": {}
14
+ }
@@ -0,0 +1,18 @@
1
+ {
2
+ "id": "scripts",
3
+ "name": "Scripts only",
4
+ "description": "No notebooks. Analysis lives in scripts, and the blueprint supplies any starter scripts.",
5
+ "language": ["r", "python", "stata"],
6
+ "requires": [],
7
+ "layer": {
8
+ "tools": {
9
+ "quarto": false,
10
+ "jupyter": false
11
+ },
12
+ "scaffold": {
13
+ "workflow": "scripts",
14
+ "notebook_format": "script"
15
+ }
16
+ },
17
+ "language_layers": {}
18
+ }
@@ -0,0 +1,47 @@
1
+ """The cached Framework Cloud defaults, for creating projects offline.
2
+
3
+ After each successful resolve of your defaults, ``new()`` saves the envelope
4
+ here, one file per server and language, in the format R and ``fw`` share:
5
+
6
+ <config folder>/cache/defaults/<host[_port]>/<language>.json
7
+ {"fetched_at": "<RFC 3339>", "defaults_revision": "...", "envelope": {...}}
8
+
9
+ Each ":" in host[:port] becomes "_", because Windows doesn't allow ":" in
10
+ folder names.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import json
16
+ from datetime import UTC, datetime
17
+ from pathlib import Path
18
+ from typing import Any
19
+
20
+ from framework.config_home import config_dir
21
+
22
+
23
+ def cache_path(url: str, language: str) -> Path:
24
+ from framework.cloud import host
25
+
26
+ return config_dir() / "cache" / "defaults" / host(url).replace(":", "_") / f"{language}.json"
27
+
28
+
29
+ def write_cached_defaults(
30
+ url: str, language: str, envelope: dict[str, Any], revision: str | None
31
+ ) -> None:
32
+ path = cache_path(url, language)
33
+ path.parent.mkdir(parents=True, exist_ok=True)
34
+ fetched_at = datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
35
+ record = {"fetched_at": fetched_at, "defaults_revision": revision, "envelope": envelope}
36
+ path.write_text(json.dumps(record, indent=2) + "\n", encoding="utf-8")
37
+
38
+
39
+ def read_cached_defaults(url: str, language: str) -> dict[str, Any] | None:
40
+ """The cached record, or None when there is none or it can't be read."""
41
+ try:
42
+ record = json.loads(cache_path(url, language).read_text(encoding="utf-8"))
43
+ except (OSError, ValueError):
44
+ return None
45
+ if not isinstance(record, dict) or not isinstance(record.get("envelope"), dict):
46
+ return None
47
+ return record
framework/_paths.py CHANGED
@@ -41,15 +41,25 @@ def directory(config: dict[str, Any], key: str, default: str, root: Path | None
41
41
  return in_root(value if isinstance(value, str) and value else default, root)
42
42
 
43
43
 
44
- def output_directory(config: dict[str, Any], kind: str, public: bool) -> Path:
44
+ def output_directory(
45
+ config: dict[str, Any], kind: str, public: bool, root: Path | None = None
46
+ ) -> Path:
45
47
  """Where outputs of one kind (tables, figures, ...) go.
46
48
 
47
- Sensitive projects split outputs into public and private folders; other
48
- projects use one folder per kind. This follows R's ``save_*()`` functions.
49
+ A project with private and public output folders (sensitive data on, or
50
+ ``outputs_private_*`` or ``outputs_public_*`` directories) splits by
51
+ ``public``. Any other project has one folder per kind. This follows R's
52
+ ``save_*()`` functions.
49
53
  """
50
- if config.get("project_type") == "project_sensitive":
51
- key = f"outputs_{'public' if public else 'private'}_{kind}"
52
- else:
53
- key = f"outputs_{kind}"
54
- default = f"outputs/public/{kind}" if public else f"outputs/{kind}"
55
- return directory(config, key, default)
54
+ directories = config.get("directories")
55
+ directories = directories if isinstance(directories, dict) else {}
56
+ security = config.get("security")
57
+ split = (
58
+ (isinstance(security, dict) and security.get("sensitive") is True)
59
+ or f"outputs_private_{kind}" in directories
60
+ or f"outputs_public_{kind}" in directories
61
+ )
62
+ if not split:
63
+ return directory(config, f"outputs_{kind}", f"outputs/{kind}", root)
64
+ side = "public" if public else "private"
65
+ return directory(config, f"outputs_{side}_{kind}", f"outputs/{side}/{kind}", root)