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.
- framework/__init__.py +5 -0
- framework/__main__.py +64 -5
- framework/_agents_md.py +210 -0
- framework/_assets/adopt/rules.json +161 -0
- framework/_assets/features/jupyter.json +39 -0
- framework/_assets/features/quarto.json +18 -0
- framework/_assets/features/quarto_manuscript.json +35 -0
- framework/_assets/features/quarto_slides.json +29 -0
- framework/_assets/features/renv.json +20 -0
- framework/_assets/features/targets.json +34 -0
- framework/_assets/features/uv.json +17 -0
- framework/_assets/schema/layer.v1.json +45 -7
- framework/_assets/schema/layers.v1.json +49 -7
- framework/_assets/schema/spec.v1.json +38 -7
- framework/_assets/sets/packages/tidyverse-analysis.json +42 -0
- framework/_assets/sets/skills/framework.json +25 -0
- framework/_assets/sets/skills/ggplot2.json +26 -0
- framework/_assets/workflows/jupyter.json +14 -0
- framework/_assets/workflows/quarto.json +14 -0
- framework/_assets/workflows/scripts.json +18 -0
- framework/_defaults_cache.py +47 -0
- framework/_pages.py +228 -0
- framework/_paths.py +19 -9
- framework/_private.py +69 -0
- framework/adopt.py +365 -0
- framework/ai.py +13 -20
- framework/cloud.py +139 -14
- framework/create.py +395 -18
- framework/features.py +195 -0
- framework/hooks.py +69 -7
- framework/notebooks.py +9 -1
- framework/outputs.py +6 -1
- framework/quarto.py +77 -25
- framework/scaffold.py +50 -3
- framework/spec/check.py +31 -7
- framework/spec/merge.py +1 -0
- framework/spec/resolve.py +80 -6
- framework/storage.py +96 -50
- framework/templates/defaults.yml +0 -1
- framework/templates/skills/framework-outputs/SKILL.md +5 -5
- framework/templates/skills/framework-sensitive-data/SKILL.md +3 -2
- {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/METADATA +1 -1
- framework_py-0.1.0.dev4.dist-info/RECORD +84 -0
- framework_py-0.1.0.dev2.dist-info/RECORD +0 -64
- {framework_py-0.1.0.dev2.dist-info → framework_py-0.1.0.dev4.dist-info}/WHEEL +0 -0
- {framework_py-0.1.0.dev2.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
|
-
"
|
|
19
|
-
"
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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
|
-
"
|
|
341
|
-
"
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
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
|
-
"
|
|
19
|
-
"
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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/_pages.py
ADDED
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
"""Publishing to GitHub Pages: ``publish(..., to="github")``.
|
|
2
|
+
|
|
3
|
+
Framework Cloud's "Publish with GitHub Pages" commits a workflow that deploys
|
|
4
|
+
the repository's ``published/`` folder from the default branch. This side
|
|
5
|
+
copies a document into ``published/<slug>/``, commits only that folder, and
|
|
6
|
+
pushes. Documents never pass through the cloud. R and fw behave the same way.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import re
|
|
12
|
+
import shutil
|
|
13
|
+
import subprocess
|
|
14
|
+
import sys
|
|
15
|
+
import tempfile
|
|
16
|
+
import warnings
|
|
17
|
+
from dataclasses import dataclass
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
|
|
20
|
+
from framework._log import inform
|
|
21
|
+
from framework.errors import FrameworkError, FrameworkWarning
|
|
22
|
+
|
|
23
|
+
PUBLIC_NOTICE = "GitHub Pages sites are public, even when the repository is private."
|
|
24
|
+
_SLUG = re.compile(r"^[a-z0-9][a-z0-9._-]*$")
|
|
25
|
+
_REMOTE = re.compile(r"github\.com[:/]+([^/]+)/([^/]+?)(?:\.git)?/?$")
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass(frozen=True)
|
|
29
|
+
class _Remote:
|
|
30
|
+
name: str
|
|
31
|
+
owner: str
|
|
32
|
+
repo: str
|
|
33
|
+
has_upstream: bool
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _git(top: Path, *args: str) -> subprocess.CompletedProcess[str]:
|
|
37
|
+
return subprocess.run(
|
|
38
|
+
["git", "-C", str(top), *args], capture_output=True, text=True, check=False
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def github_remote(url: str) -> tuple[str, str] | None:
|
|
43
|
+
"""The owner and repository of a GitHub remote URL (https, ssh, or scp-style)."""
|
|
44
|
+
match = _REMOTE.search(url.strip())
|
|
45
|
+
return (match[1], match[2]) if match else None
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def pages_base(owner: str, repo: str) -> str:
|
|
49
|
+
"""The URL GitHub gives a repository's Pages site."""
|
|
50
|
+
host = f"{owner.lower()}.github.io"
|
|
51
|
+
if repo.lower() == host:
|
|
52
|
+
return f"https://{host}/"
|
|
53
|
+
return f"https://{host}/{repo}/"
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def pages_slug(source: Path) -> str:
|
|
57
|
+
"""The file name lowercased, with each run of other characters as "-".
|
|
58
|
+
|
|
59
|
+
GitHub Pages URLs are case-sensitive. "Final Report (v2).html" becomes
|
|
60
|
+
"final-report-v2".
|
|
61
|
+
"""
|
|
62
|
+
name = source.name if source.is_dir() else source.stem
|
|
63
|
+
return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _remote(top: Path) -> _Remote | None:
|
|
67
|
+
"""The branch's upstream remote, then origin, then any GitHub remote."""
|
|
68
|
+
upstream = _git(top, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}")
|
|
69
|
+
upstream_name = upstream.stdout.strip().split("/")[0] if upstream.returncode == 0 else None
|
|
70
|
+
listed = _git(top, "remote")
|
|
71
|
+
names = listed.stdout.split() if listed.returncode == 0 else []
|
|
72
|
+
candidates = [n for n in (upstream_name, "origin", *names) if n is not None]
|
|
73
|
+
for name in dict.fromkeys(candidates):
|
|
74
|
+
if name not in names:
|
|
75
|
+
continue
|
|
76
|
+
url = _git(top, "remote", "get-url", name)
|
|
77
|
+
found = github_remote(url.stdout) if url.returncode == 0 else None
|
|
78
|
+
if found is not None:
|
|
79
|
+
return _Remote(name, found[0], found[1], name == upstream_name)
|
|
80
|
+
return None
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _stage(source: Path, stage: Path, self_contained: bool) -> None:
|
|
84
|
+
"""Copy ``source`` into ``stage`` as a folder whose front page is index.html."""
|
|
85
|
+
suffix = source.suffix.lower()
|
|
86
|
+
if source.is_dir():
|
|
87
|
+
if not (source / "index.html").is_file():
|
|
88
|
+
raise FrameworkError(
|
|
89
|
+
f"A folder published to GitHub Pages needs an index.html at its top: {source}"
|
|
90
|
+
)
|
|
91
|
+
shutil.copytree(source, stage, dirs_exist_ok=True)
|
|
92
|
+
return
|
|
93
|
+
if suffix in (".html", ".htm"):
|
|
94
|
+
shutil.copy2(source, stage / source.name)
|
|
95
|
+
assets = source.with_name(f"{source.stem}_files")
|
|
96
|
+
if assets.is_dir():
|
|
97
|
+
# The supporting folder keeps its name, so relative links still resolve
|
|
98
|
+
shutil.copytree(assets, stage / assets.name)
|
|
99
|
+
elif suffix in (".qmd", ".ipynb"):
|
|
100
|
+
quarto = shutil.which("quarto")
|
|
101
|
+
if quarto is None:
|
|
102
|
+
raise FrameworkError("Rendering requires the quarto command on your PATH.")
|
|
103
|
+
command = [quarto, "render", str(source.resolve()), "--output-dir", str(stage)]
|
|
104
|
+
command += ["--to", "html", *(["--embed-resources"] if self_contained else [])]
|
|
105
|
+
inform(f"Rendering {source.name}...")
|
|
106
|
+
result = subprocess.run(command, capture_output=True, text=True, check=False)
|
|
107
|
+
if result.returncode != 0:
|
|
108
|
+
raise FrameworkError(f"Quarto render failed:\n{result.stdout}{result.stderr}")
|
|
109
|
+
else:
|
|
110
|
+
raise FrameworkError(
|
|
111
|
+
"GitHub Pages publishing takes rendered HTML, a render folder, or a .qmd or "
|
|
112
|
+
f".ipynb to render. Got: {suffix or source.name}"
|
|
113
|
+
)
|
|
114
|
+
if not (stage / "index.html").is_file():
|
|
115
|
+
main = stage / f"{source.stem}.html"
|
|
116
|
+
if not main.is_file():
|
|
117
|
+
pages = sorted(stage.glob("*.htm*"))
|
|
118
|
+
if len(pages) != 1:
|
|
119
|
+
raise FrameworkError(f"No single HTML page found to publish from {source}")
|
|
120
|
+
main = pages[0]
|
|
121
|
+
main.rename(stage / "index.html")
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _cloud_pages_url(root: Path) -> tuple[bool, str | None, str | None]:
|
|
125
|
+
"""Whether the cloud answered, its Pages URL (None when Pages is off), and the server.
|
|
126
|
+
|
|
127
|
+
One call to ``/api/v1/me`` with the project token. Not known when there is
|
|
128
|
+
no project token or the call fails.
|
|
129
|
+
"""
|
|
130
|
+
from framework.cloud import CloudError, api, cloud_server, project_token
|
|
131
|
+
|
|
132
|
+
token = project_token(root)
|
|
133
|
+
if token is None:
|
|
134
|
+
return False, None, None
|
|
135
|
+
try:
|
|
136
|
+
server = cloud_server(scope="project", project_dir=root).url
|
|
137
|
+
me = api("/api/v1/me", token, server)
|
|
138
|
+
except CloudError:
|
|
139
|
+
return False, None, None
|
|
140
|
+
if not isinstance(me, dict) or me.get("kind") != "project":
|
|
141
|
+
return False, None, None
|
|
142
|
+
pages = me.get("pages_url")
|
|
143
|
+
return True, pages if isinstance(pages, str) and pages else None, server
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def _confirm() -> None:
|
|
147
|
+
# Shown on every run, even when Framework's messages are off
|
|
148
|
+
print(PUBLIC_NOTICE, file=sys.stderr)
|
|
149
|
+
if sys.stdin.isatty():
|
|
150
|
+
answer = input("Publish it? [y/N] ").strip().lower()
|
|
151
|
+
if answer not in ("y", "yes"):
|
|
152
|
+
raise FrameworkError("Cancelled: nothing was published.")
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def github_publish(source: Path, slug: str | None = None, self_contained: bool = True) -> str:
|
|
156
|
+
"""Copy ``source`` to ``published/<slug>/``, commit only that folder, and push."""
|
|
157
|
+
from framework.project import find_settings_file
|
|
158
|
+
|
|
159
|
+
if slug is None:
|
|
160
|
+
slug = pages_slug(source)
|
|
161
|
+
if not _SLUG.match(slug):
|
|
162
|
+
raise FrameworkError(
|
|
163
|
+
"slug must start with a lowercase letter or digit and use only lowercase letters, "
|
|
164
|
+
"digits, '.', '_', and '-' (GitHub Pages URLs are case-sensitive)."
|
|
165
|
+
)
|
|
166
|
+
settings_file = find_settings_file()
|
|
167
|
+
root = settings_file.parent if settings_file is not None else Path.cwd()
|
|
168
|
+
shown = _git(root, "rev-parse", "--show-toplevel")
|
|
169
|
+
if shown.returncode != 0:
|
|
170
|
+
raise FrameworkError(
|
|
171
|
+
"This project isn't a git repository. Create the project on GitHub first."
|
|
172
|
+
)
|
|
173
|
+
top = Path(shown.stdout.strip())
|
|
174
|
+
remote = _remote(top)
|
|
175
|
+
if remote is None:
|
|
176
|
+
raise FrameworkError(
|
|
177
|
+
"This project has no GitHub remote. Create the project on GitHub first, then "
|
|
178
|
+
"publish again."
|
|
179
|
+
)
|
|
180
|
+
_confirm()
|
|
181
|
+
|
|
182
|
+
# published/ sits at the top of the repository, where the workflow deploys from
|
|
183
|
+
rel = f"published/{slug}"
|
|
184
|
+
with tempfile.TemporaryDirectory(prefix="fw_pages_") as temp:
|
|
185
|
+
_stage(source, Path(temp), self_contained)
|
|
186
|
+
target = top / rel
|
|
187
|
+
if target.exists():
|
|
188
|
+
shutil.rmtree(target)
|
|
189
|
+
shutil.copytree(temp, target)
|
|
190
|
+
|
|
191
|
+
# Commit only this folder; anything else the user staged stays staged
|
|
192
|
+
_git(top, "add", "-A", "--", rel)
|
|
193
|
+
if _git(top, "diff", "--cached", "--quiet", "--", rel).returncode == 0:
|
|
194
|
+
inform(f"No change in {rel}; nothing committed or pushed.")
|
|
195
|
+
else:
|
|
196
|
+
commit = _git(top, "commit", "-m", f"Publish {slug}", "--", rel)
|
|
197
|
+
if commit.returncode != 0:
|
|
198
|
+
raise FrameworkError(f"git commit failed:\n{commit.stdout}{commit.stderr}")
|
|
199
|
+
branch = _git(top, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
|
|
200
|
+
default = _git(top, "symbolic-ref", "--short", f"refs/remotes/{remote.name}/HEAD")
|
|
201
|
+
if default.returncode == 0:
|
|
202
|
+
default_branch = default.stdout.strip().split("/", 1)[-1]
|
|
203
|
+
if branch != default_branch:
|
|
204
|
+
warnings.warn(
|
|
205
|
+
f"You're on '{branch}'. GitHub Pages deploys only from the default branch "
|
|
206
|
+
f"('{default_branch}'), so this won't appear until it's merged there.",
|
|
207
|
+
FrameworkWarning,
|
|
208
|
+
stacklevel=3,
|
|
209
|
+
)
|
|
210
|
+
push = (
|
|
211
|
+
_git(top, "push")
|
|
212
|
+
if remote.has_upstream
|
|
213
|
+
else _git(top, "push", "-u", remote.name, "HEAD")
|
|
214
|
+
)
|
|
215
|
+
if push.returncode != 0:
|
|
216
|
+
raise FrameworkError(f"Committed, but git push failed:\n{push.stdout}{push.stderr}")
|
|
217
|
+
|
|
218
|
+
known, pages_url, server = _cloud_pages_url(root)
|
|
219
|
+
if known and pages_url is None:
|
|
220
|
+
warnings.warn(
|
|
221
|
+
f"GitHub Pages is off for this project. Turn it on under Projects at {server}.",
|
|
222
|
+
FrameworkWarning,
|
|
223
|
+
stacklevel=3,
|
|
224
|
+
)
|
|
225
|
+
base = pages_url or pages_base(remote.owner, remote.repo)
|
|
226
|
+
url = f"{base.rstrip('/')}/{slug}/"
|
|
227
|
+
inform(f"Published to {url}")
|
|
228
|
+
return url
|