framework-py 0.1.0.dev6__py3-none-any.whl → 0.1.0.dev8__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 (68) hide show
  1. framework/__init__.py +6 -0
  2. framework/__main__.py +9 -4
  3. framework/_assets/hooks/pre-commit +10 -0
  4. framework/_assets/schema/docs-reference.v1.json +1 -1
  5. framework/_assets/schema/layer.v1.json +35 -0
  6. framework/_assets/schema/layers.v1.json +35 -0
  7. framework/_assets/schema/spec.v1.json +31 -0
  8. framework/_assets/sets/packages/bayes-r.json +51 -0
  9. framework/_assets/sets/packages/causal-inference-r.json +34 -0
  10. framework/_assets/sets/packages/fastapi-python.json +34 -0
  11. framework/_assets/sets/packages/large-data-r.json +30 -0
  12. framework/_assets/sets/packages/plumber-r.json +30 -0
  13. framework/_assets/sets/packages/polars-python.json +26 -0
  14. framework/_assets/sets/packages/python-bayes.json +26 -0
  15. framework/_assets/sets/packages/python-data-analysis.json +34 -0
  16. framework/_assets/sets/packages/python-database.json +26 -0
  17. framework/_assets/sets/packages/python-ml.json +22 -0
  18. framework/_assets/sets/packages/python-spatial.json +22 -0
  19. framework/_assets/sets/packages/python-viz.json +22 -0
  20. framework/_assets/sets/packages/regression-r.json +42 -0
  21. framework/_assets/sets/packages/shiny-python.json +30 -0
  22. framework/_assets/sets/packages/shiny-r.json +34 -0
  23. framework/_assets/sets/packages/spatial-r.json +26 -0
  24. framework/_assets/sets/packages/survey-r.json +22 -0
  25. framework/_assets/sets/packages/survival-r.json +30 -0
  26. framework/_assets/sets/packages/tables-r.json +30 -0
  27. framework/_assets/sets/packages/text-r.json +22 -0
  28. framework/_assets/sets/packages/tidy-core.json +26 -0
  29. framework/_assets/sets/packages/tidy-database.json +38 -0
  30. framework/_assets/sets/packages/tidy-omop.json +58 -0
  31. framework/_assets/sets/packages/tidymodels.json +22 -0
  32. framework/_assets/sets/packages/tidyverse-extended.json +70 -0
  33. framework/_keychain.py +79 -0
  34. framework/_log.py +9 -1
  35. framework/_pages.py +98 -14
  36. framework/_paths.py +19 -0
  37. framework/adopt.py +3 -2
  38. framework/ai.py +22 -4
  39. framework/bootstrap.py +49 -9
  40. framework/cache.py +28 -7
  41. framework/catalog.py +30 -6
  42. framework/cloud.py +227 -65
  43. framework/config_home.py +25 -3
  44. framework/connections.py +94 -11
  45. framework/create.py +54 -10
  46. framework/data.py +105 -53
  47. framework/db.py +11 -1
  48. framework/dotenv.py +57 -6
  49. framework/hooks.py +58 -14
  50. framework/notebooks.py +56 -26
  51. framework/outputs.py +51 -15
  52. framework/packages.py +130 -8
  53. framework/publish_bundle.py +589 -0
  54. framework/scaffold.py +21 -3
  55. framework/security.py +47 -18
  56. framework/settings.py +91 -22
  57. framework/skill_sync.py +3 -3
  58. framework/spec/check.py +31 -1
  59. framework/spec/resolve.py +1 -0
  60. framework/storage.py +420 -37
  61. framework/templates/defaults.yml +1 -1
  62. framework/templates/gitignore/course +2 -5
  63. framework/templates/reader.html +12 -0
  64. {framework_py-0.1.0.dev6.dist-info → framework_py-0.1.0.dev8.dist-info}/METADATA +1 -1
  65. framework_py-0.1.0.dev8.dist-info/RECORD +119 -0
  66. framework_py-0.1.0.dev6.dist-info/RECORD +0 -91
  67. {framework_py-0.1.0.dev6.dist-info → framework_py-0.1.0.dev8.dist-info}/WHEEL +0 -0
  68. {framework_py-0.1.0.dev6.dist-info → framework_py-0.1.0.dev8.dist-info}/licenses/LICENSE +0 -0
@@ -0,0 +1,34 @@
1
+ {
2
+ "id": "shiny-r",
3
+ "name": "Shiny app in R",
4
+ "description": "shiny with bslib and bsicons for the layout, and DT and plotly for tables and charts.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "shiny": {
12
+ "source": "cran",
13
+ "auto_attach": false
14
+ },
15
+ "bslib": {
16
+ "source": "cran",
17
+ "auto_attach": false
18
+ },
19
+ "bsicons": {
20
+ "source": "cran",
21
+ "auto_attach": false
22
+ },
23
+ "DT": {
24
+ "source": "cran",
25
+ "auto_attach": false
26
+ },
27
+ "plotly": {
28
+ "source": "cran",
29
+ "auto_attach": false
30
+ }
31
+ }
32
+ }
33
+ }
34
+ }
@@ -0,0 +1,26 @@
1
+ {
2
+ "id": "spatial-r",
3
+ "name": "Spatial data in R",
4
+ "description": "sf for vector data, terra for rasters, and tmap for maps.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "sf": {
12
+ "source": "cran",
13
+ "auto_attach": false
14
+ },
15
+ "terra": {
16
+ "source": "cran",
17
+ "auto_attach": false
18
+ },
19
+ "tmap": {
20
+ "source": "cran",
21
+ "auto_attach": false
22
+ }
23
+ }
24
+ }
25
+ }
26
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "id": "survey-r",
3
+ "name": "Survey data",
4
+ "description": "survey for weighted designs, and srvyr to use them with dplyr.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "survey": {
12
+ "source": "cran",
13
+ "auto_attach": false
14
+ },
15
+ "srvyr": {
16
+ "source": "cran",
17
+ "auto_attach": false
18
+ }
19
+ }
20
+ }
21
+ }
22
+ }
@@ -0,0 +1,30 @@
1
+ {
2
+ "id": "survival-r",
3
+ "name": "Survival analysis",
4
+ "description": "survival for the models, ggsurvfit for curves, and gtsummary and broom for tables.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "survival": {
12
+ "source": "cran",
13
+ "auto_attach": false
14
+ },
15
+ "ggsurvfit": {
16
+ "source": "cran",
17
+ "auto_attach": false
18
+ },
19
+ "gtsummary": {
20
+ "source": "cran",
21
+ "auto_attach": false
22
+ },
23
+ "broom": {
24
+ "source": "cran",
25
+ "auto_attach": false
26
+ }
27
+ }
28
+ }
29
+ }
30
+ }
@@ -0,0 +1,30 @@
1
+ {
2
+ "id": "tables-r",
3
+ "name": "Tables for reports",
4
+ "description": "gt, gtsummary, modelsummary, and flextable for tables in Quarto documents, Word, and the web.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "gt": {
12
+ "source": "cran",
13
+ "auto_attach": false
14
+ },
15
+ "gtsummary": {
16
+ "source": "cran",
17
+ "auto_attach": false
18
+ },
19
+ "modelsummary": {
20
+ "source": "cran",
21
+ "auto_attach": false
22
+ },
23
+ "flextable": {
24
+ "source": "cran",
25
+ "auto_attach": false
26
+ }
27
+ }
28
+ }
29
+ }
30
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "id": "text-r",
3
+ "name": "Text analysis in R",
4
+ "description": "tidytext and quanteda for text as data.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "tidytext": {
12
+ "source": "cran",
13
+ "auto_attach": false
14
+ },
15
+ "quanteda": {
16
+ "source": "cran",
17
+ "auto_attach": false
18
+ }
19
+ }
20
+ }
21
+ }
22
+ }
@@ -0,0 +1,26 @@
1
+ {
2
+ "id": "tidy-core",
3
+ "name": "Tidy basics",
4
+ "description": "dplyr, tidyr, and ggplot2: the smallest tidy set.",
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
+ }
24
+ }
25
+ }
26
+ }
@@ -0,0 +1,38 @@
1
+ {
2
+ "id": "tidy-database",
3
+ "name": "Tidy databases",
4
+ "description": "DBI and dbplyr for SQL from dplyr, with drivers for DuckDB, SQLite, PostgreSQL, and ODBC.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "DBI": {
12
+ "source": "cran",
13
+ "auto_attach": false
14
+ },
15
+ "dbplyr": {
16
+ "source": "cran",
17
+ "auto_attach": false
18
+ },
19
+ "duckdb": {
20
+ "source": "cran",
21
+ "auto_attach": false
22
+ },
23
+ "RSQLite": {
24
+ "source": "cran",
25
+ "auto_attach": false
26
+ },
27
+ "RPostgres": {
28
+ "source": "cran",
29
+ "auto_attach": false
30
+ },
31
+ "odbc": {
32
+ "source": "cran",
33
+ "auto_attach": false
34
+ }
35
+ }
36
+ }
37
+ }
38
+ }
@@ -0,0 +1,58 @@
1
+ {
2
+ "id": "tidy-omop",
3
+ "name": "Tidy OMOP",
4
+ "description": "The DARWIN EU packages for OMOP CDM data: CDMConnector and omopgenerics to connect, CodelistGenerator and CohortConstructor for cohorts, PatientProfiles, IncidencePrevalence, CohortCharacteristics, and DrugUtilisation for studies, visOmopResults for results, and omock for test data.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "DBI": {
12
+ "source": "cran",
13
+ "auto_attach": false
14
+ },
15
+ "CDMConnector": {
16
+ "source": "cran",
17
+ "auto_attach": false
18
+ },
19
+ "omopgenerics": {
20
+ "source": "cran",
21
+ "auto_attach": false
22
+ },
23
+ "CodelistGenerator": {
24
+ "source": "cran",
25
+ "auto_attach": false
26
+ },
27
+ "CohortConstructor": {
28
+ "source": "cran",
29
+ "auto_attach": false
30
+ },
31
+ "PatientProfiles": {
32
+ "source": "cran",
33
+ "auto_attach": false
34
+ },
35
+ "IncidencePrevalence": {
36
+ "source": "cran",
37
+ "auto_attach": false
38
+ },
39
+ "CohortCharacteristics": {
40
+ "source": "cran",
41
+ "auto_attach": false
42
+ },
43
+ "DrugUtilisation": {
44
+ "source": "cran",
45
+ "auto_attach": false
46
+ },
47
+ "visOmopResults": {
48
+ "source": "cran",
49
+ "auto_attach": false
50
+ },
51
+ "omock": {
52
+ "source": "cran",
53
+ "auto_attach": false
54
+ }
55
+ }
56
+ }
57
+ }
58
+ }
@@ -0,0 +1,22 @@
1
+ {
2
+ "id": "tidymodels",
3
+ "name": "Tidymodels",
4
+ "description": "tidymodels for machine learning with recipes, resampling, and tuning, and vip for variable importance.",
5
+ "language": [
6
+ "r"
7
+ ],
8
+ "layer": {
9
+ "packages": {
10
+ "default_packages": {
11
+ "tidymodels": {
12
+ "source": "cran",
13
+ "auto_attach": false
14
+ },
15
+ "vip": {
16
+ "source": "cran",
17
+ "auto_attach": false
18
+ }
19
+ }
20
+ }
21
+ }
22
+ }
@@ -0,0 +1,70 @@
1
+ {
2
+ "id": "tidyverse-extended",
3
+ "name": "Tidyverse extended",
4
+ "description": "The tidyverse analysis set plus readers for CSV, Excel, Stata, and SPSS files, janitor, glue, scales, and patchwork.",
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
+ "readr": {
40
+ "source": "cran",
41
+ "auto_attach": false
42
+ },
43
+ "readxl": {
44
+ "source": "cran",
45
+ "auto_attach": false
46
+ },
47
+ "haven": {
48
+ "source": "cran",
49
+ "auto_attach": false
50
+ },
51
+ "janitor": {
52
+ "source": "cran",
53
+ "auto_attach": false
54
+ },
55
+ "glue": {
56
+ "source": "cran",
57
+ "auto_attach": false
58
+ },
59
+ "scales": {
60
+ "source": "cran",
61
+ "auto_attach": false
62
+ },
63
+ "patchwork": {
64
+ "source": "cran",
65
+ "auto_attach": false
66
+ }
67
+ }
68
+ }
69
+ }
70
+ }
framework/_keychain.py ADDED
@@ -0,0 +1,79 @@
1
+ """macOS Keychain entries through ``/usr/bin/security``, as ``fw`` reads and writes them.
2
+
3
+ ``fw`` writes each token with ``security`` and reads it through go-keyring,
4
+ which also runs ``security``. Those items trust only ``/usr/bin/security``,
5
+ so reading them in this process through the Security framework (what
6
+ Python's keyring package does) shows an "allow access" dialog, and a run
7
+ without a screen waits forever. Running the same command avoids the dialog.
8
+
9
+ Setting ``PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring`` turns these
10
+ entries off, as it turns off the keyring package. Tests rely on it.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import base64
16
+ import os
17
+ import subprocess
18
+
19
+ SECURITY = "/usr/bin/security"
20
+ NOT_FOUND = 44
21
+ _GO_KEYRING = "go-keyring-base64:"
22
+
23
+
24
+ def disabled() -> bool:
25
+ return os.environ.get("PYTHON_KEYRING_BACKEND", "") == "keyring.backends.null.Keyring"
26
+
27
+
28
+ def _run(args: list[str], stdin: str | None = None) -> subprocess.CompletedProcess[str]:
29
+ return subprocess.run(
30
+ [SECURITY, *args], input=stdin, capture_output=True, text=True, check=False
31
+ )
32
+
33
+
34
+ def decode(output: str) -> str | None:
35
+ """A password as ``security -w`` prints it, decoding go-keyring's base64 form."""
36
+ value = output.rstrip("\n")
37
+ if value.startswith(_GO_KEYRING):
38
+ value = base64.b64decode(value[len(_GO_KEYRING) :]).decode("utf-8")
39
+ return value or None
40
+
41
+
42
+ def get(service: str, account: str) -> str | None:
43
+ """The password, or None when the item is missing or the keychain can't be read."""
44
+ if disabled():
45
+ return None
46
+ try:
47
+ result = _run(["find-generic-password", "-s", service, "-a", account, "-w"])
48
+ except OSError:
49
+ return None
50
+ if result.returncode != 0:
51
+ return None
52
+ return decode(result.stdout)
53
+
54
+
55
+ def set(service: str, account: str, password: str) -> bool:
56
+ """Add or update an item. The command goes on stdin, so the password is never in argv."""
57
+ if disabled():
58
+ return False
59
+ # The command is quoted for security's own parser, which has no escapes
60
+ if any(c in value for value in (service, account, password) for c in "'\\\n\r"):
61
+ return False
62
+ command = f"add-generic-password -U -s '{service}' -a '{account}' -w '{password}'\n"
63
+ try:
64
+ _run(["-i"], stdin=command)
65
+ except OSError:
66
+ return False
67
+ # security -i exits 0 even when a command fails, so read the item back
68
+ return get(service, account) == password
69
+
70
+
71
+ def delete(service: str, account: str) -> bool:
72
+ """Remove an item. False when it was missing or could not be removed."""
73
+ if disabled():
74
+ return False
75
+ try:
76
+ result = _run(["delete-generic-password", "-s", service, "-a", account])
77
+ except OSError:
78
+ return False
79
+ return result.returncode == 0
framework/_log.py CHANGED
@@ -18,11 +18,19 @@ def inform(message: str) -> None:
18
18
  logger.info(message)
19
19
 
20
20
 
21
+ class _CurrentStderr(logging.StreamHandler): # type: ignore[type-arg]
22
+ """Writes to whatever ``sys.stderr`` is now, so ``capture_output()`` sees messages."""
23
+
24
+ def emit(self, record: logging.LogRecord) -> None:
25
+ self.stream = sys.stderr
26
+ super().emit(record)
27
+
28
+
21
29
  def show_messages() -> None:
22
30
  """Print Framework's messages to stderr, once per process."""
23
31
  if any(getattr(handler, "_framework", False) for handler in logger.handlers):
24
32
  return
25
- handler = logging.StreamHandler(sys.stderr)
33
+ handler = _CurrentStderr(sys.stderr)
26
34
  handler.setFormatter(logging.Formatter("%(message)s"))
27
35
  handler._framework = True # type: ignore[attr-defined]
28
36
  logger.addHandler(handler)
framework/_pages.py CHANGED
@@ -18,6 +18,7 @@ from dataclasses import dataclass
18
18
  from pathlib import Path
19
19
 
20
20
  from framework._log import inform
21
+ from framework._paths import rendered_page
21
22
  from framework.errors import FrameworkError, FrameworkWarning
22
23
 
23
24
  PUBLIC_NOTICE = "GitHub Pages sites are public, even when the repository is private."
@@ -100,12 +101,19 @@ def _stage(source: Path, stage: Path, self_contained: bool) -> None:
100
101
  quarto = shutil.which("quarto")
101
102
  if quarto is None:
102
103
  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}")
104
+ with tempfile.TemporaryDirectory(prefix="fw_render_") as render:
105
+ out = Path(render)
106
+ command = [quarto, "render", str(source.resolve()), "--output-dir", str(out)]
107
+ command += ["--to", "html", *(["--embed-resources"] if self_contained else [])]
108
+ inform(f"Rendering {source.name}...")
109
+ result = subprocess.run(command, capture_output=True, text=True, check=False)
110
+ if result.returncode != 0:
111
+ raise FrameworkError(f"Quarto render failed:\n{result.stdout}{result.stderr}")
112
+ # A project's _quarto.yml keeps the notebook's folder under the output folder
113
+ page = rendered_page(out, source.stem)
114
+ if page is None:
115
+ raise FrameworkError(f"No single HTML page found to publish from {source}")
116
+ shutil.copytree(page.parent, stage, dirs_exist_ok=True)
109
117
  else:
110
118
  raise FrameworkError(
111
119
  "GitHub Pages publishing takes rendered HTML, a render folder, or a .qmd or "
@@ -152,7 +160,33 @@ def _confirm() -> None:
152
160
  raise FrameworkError("Cancelled: nothing was published.")
153
161
 
154
162
 
155
- def github_publish(source: Path, slug: str | None = None, self_contained: bool = True) -> str:
163
+ def _directory_bytes(folder: Path) -> int:
164
+ """All files in a site, including retained artifact versions."""
165
+ return sum(path.stat().st_size for path in folder.rglob("*") if path.is_file())
166
+
167
+
168
+ def _check_pages_budget(site: Path, incoming: Path, *, bundle: bool) -> None:
169
+ # Bundles are copied to both the current path and an immutable version folder.
170
+ # Keep existing files in the estimate, including every retained archive.
171
+ projected = _directory_bytes(site) + _directory_bytes(incoming) * (2 if bundle else 1)
172
+ if projected > 1_000_000_000:
173
+ raise FrameworkError("Publishing would exceed the 1 GB GitHub Pages site limit.")
174
+ if projected > 800_000_000:
175
+ warnings.warn(
176
+ "The GitHub Pages site is approaching its 1 GB limit.",
177
+ FrameworkWarning,
178
+ stacklevel=3,
179
+ )
180
+
181
+
182
+ def github_publish(
183
+ source: Path,
184
+ slug: str | None = None,
185
+ self_contained: bool = True,
186
+ *,
187
+ bundle: bool = False,
188
+ private: bool = False,
189
+ ) -> str:
156
190
  """Copy ``source`` to ``published/<slug>/``, commit only that folder, and push."""
157
191
  from framework.project import find_settings_file
158
192
 
@@ -177,23 +211,38 @@ def github_publish(source: Path, slug: str | None = None, self_contained: bool =
177
211
  "This project has no GitHub remote. Create the project on GitHub first, then "
178
212
  "publish again."
179
213
  )
180
- _confirm()
214
+ if not private:
215
+ _confirm()
181
216
 
182
217
  # published/ sits at the top of the repository, where the workflow deploys from
183
218
  rel = f"published/{slug}"
184
219
  with tempfile.TemporaryDirectory(prefix="fw_pages_") as temp:
185
220
  _stage(source, Path(temp), self_contained)
186
221
  target = top / rel
187
- if target.exists():
188
- shutil.rmtree(target)
189
- shutil.copytree(temp, target)
222
+ _check_pages_budget(top / "published", source if bundle else Path(temp), bundle=bundle)
223
+ if bundle:
224
+ import json
225
+
226
+ from framework.publish_bundle import folder_deliver
227
+
228
+ receipt = folder_deliver(source, top / "published")
229
+ (source.parent / "receipt.json").write_text(json.dumps(receipt), encoding="utf-8")
230
+ else:
231
+ if target.exists():
232
+ shutil.rmtree(target)
233
+ shutil.copytree(temp, target)
234
+
235
+ # Include the regenerated site index in the final check before staging or pushing.
236
+ if _directory_bytes(top / "published") > 1_000_000_000:
237
+ raise FrameworkError("Publishing would exceed the 1 GB GitHub Pages site limit.")
190
238
 
191
239
  # 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:
240
+ paths = [rel, "published/index.html", "published/index.json"] if bundle else [rel]
241
+ _git(top, "add", "-A", "--", *paths)
242
+ if _git(top, "diff", "--cached", "--quiet", "--", *paths).returncode == 0:
194
243
  inform(f"No change in {rel}; nothing committed or pushed.")
195
244
  else:
196
- commit = _git(top, "commit", "-m", f"Publish {slug}", "--", rel)
245
+ commit = _git(top, "commit", "-m", f"Publish {slug}", "--", *paths)
197
246
  if commit.returncode != 0:
198
247
  raise FrameworkError(f"git commit failed:\n{commit.stdout}{commit.stderr}")
199
248
  branch = _git(top, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
@@ -224,5 +273,40 @@ def github_publish(source: Path, slug: str | None = None, self_contained: bool =
224
273
  )
225
274
  base = pages_url or pages_base(remote.owner, remote.repo)
226
275
  url = f"{base.rstrip('/')}/{slug}/"
276
+ if bundle:
277
+ import json
278
+
279
+ receipt_path = source.parent / "receipt.json"
280
+ receipt = json.loads(receipt_path.read_text(encoding="utf-8"))
281
+ receipt.update(
282
+ driver="github",
283
+ url=url,
284
+ version_url=f"{url}v/{receipt['version']}/",
285
+ commit=_git(top, "rev-parse", "HEAD").stdout.strip(),
286
+ )
287
+ receipt_path.write_text(json.dumps(receipt), encoding="utf-8")
227
288
  inform(f"Published to {url}")
228
289
  return url
290
+
291
+
292
+ def private_pages() -> bool:
293
+ """Ask GitHub for the Pages access setting; repository privacy is insufficient."""
294
+ import json
295
+
296
+ from framework.project import project_root
297
+
298
+ top = project_root()
299
+ remote = _remote(top)
300
+ if remote is None:
301
+ return False
302
+ try:
303
+ result = subprocess.run(
304
+ ["gh", "api", f"repos/{remote.owner}/{remote.repo}/pages"],
305
+ capture_output=True,
306
+ text=True,
307
+ check=False,
308
+ cwd=top,
309
+ )
310
+ return result.returncode == 0 and json.loads(result.stdout).get("public") is False
311
+ except (OSError, ValueError):
312
+ return False
framework/_paths.py CHANGED
@@ -63,3 +63,22 @@ def output_directory(
63
63
  return directory(config, f"outputs_{kind}", f"outputs/{kind}", root)
64
64
  side = "public" if public else "private"
65
65
  return directory(config, f"outputs_{side}_{kind}", f"outputs/{side}/{kind}", root)
66
+
67
+
68
+ def rendered_page(out: Path, stem: str, extension: str = ".html") -> Path | None:
69
+ """The page ``quarto render --output-dir out`` wrote for a source named ``stem``.
70
+
71
+ Inside a Quarto project, such as any project ``new()`` makes, the output keeps the
72
+ source's folder under the output folder: ``notebooks/x.qmd`` becomes
73
+ ``out/notebooks/x.html``. The shallowest page named for the source wins. Otherwise
74
+ the one page outside ``_files`` folders is used. None when there is no single page.
75
+ """
76
+ named = sorted(out.rglob(f"{stem}{extension}"), key=lambda p: (len(p.parts), p))
77
+ if named:
78
+ return named[0]
79
+ pages = [
80
+ p
81
+ for p in sorted(out.rglob(f"*{extension}"))
82
+ if not any(part.endswith("_files") for part in p.relative_to(out).parts[:-1])
83
+ ]
84
+ return pages[0] if len(pages) == 1 else None