framework-py 0.1.0.dev7__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 (46) hide show
  1. framework/__init__.py +4 -0
  2. framework/_assets/sets/packages/bayes-r.json +51 -0
  3. framework/_assets/sets/packages/causal-inference-r.json +34 -0
  4. framework/_assets/sets/packages/fastapi-python.json +34 -0
  5. framework/_assets/sets/packages/large-data-r.json +30 -0
  6. framework/_assets/sets/packages/plumber-r.json +30 -0
  7. framework/_assets/sets/packages/polars-python.json +26 -0
  8. framework/_assets/sets/packages/python-bayes.json +26 -0
  9. framework/_assets/sets/packages/python-database.json +26 -0
  10. framework/_assets/sets/packages/python-ml.json +22 -0
  11. framework/_assets/sets/packages/python-spatial.json +22 -0
  12. framework/_assets/sets/packages/python-viz.json +22 -0
  13. framework/_assets/sets/packages/regression-r.json +42 -0
  14. framework/_assets/sets/packages/shiny-python.json +30 -0
  15. framework/_assets/sets/packages/shiny-r.json +34 -0
  16. framework/_assets/sets/packages/spatial-r.json +26 -0
  17. framework/_assets/sets/packages/survey-r.json +22 -0
  18. framework/_assets/sets/packages/survival-r.json +30 -0
  19. framework/_assets/sets/packages/tables-r.json +30 -0
  20. framework/_assets/sets/packages/text-r.json +22 -0
  21. framework/_assets/sets/packages/tidy-core.json +26 -0
  22. framework/_assets/sets/packages/tidy-database.json +38 -0
  23. framework/_assets/sets/packages/tidy-omop.json +58 -0
  24. framework/_assets/sets/packages/tidymodels.json +22 -0
  25. framework/_assets/sets/packages/tidyverse-extended.json +70 -0
  26. framework/bootstrap.py +32 -6
  27. framework/cache.py +9 -5
  28. framework/catalog.py +8 -4
  29. framework/cloud.py +19 -13
  30. framework/config_home.py +18 -2
  31. framework/connections.py +45 -7
  32. framework/create.py +22 -1
  33. framework/data.py +87 -48
  34. framework/hooks.py +40 -3
  35. framework/notebooks.py +43 -21
  36. framework/packages.py +117 -0
  37. framework/publish_bundle.py +59 -2
  38. framework/scaffold.py +10 -2
  39. framework/security.py +24 -12
  40. framework/storage.py +142 -11
  41. framework/templates/defaults.yml +1 -1
  42. framework/templates/gitignore/course +2 -5
  43. {framework_py-0.1.0.dev7.dist-info → framework_py-0.1.0.dev8.dist-info}/METADATA +1 -1
  44. {framework_py-0.1.0.dev7.dist-info → framework_py-0.1.0.dev8.dist-info}/RECORD +46 -22
  45. {framework_py-0.1.0.dev7.dist-info → framework_py-0.1.0.dev8.dist-info}/WHEEL +0 -0
  46. {framework_py-0.1.0.dev7.dist-info → framework_py-0.1.0.dev8.dist-info}/licenses/LICENSE +0 -0
framework/data.py CHANGED
@@ -231,6 +231,19 @@ def _check_integrity(name: str, info: DataInfo) -> None:
231
231
  )
232
232
 
233
233
 
234
+ def _existing_file(path: str | Path) -> Path | None:
235
+ """A file given by path: a relative path is looked for from the project root, then
236
+ from the current folder."""
237
+ candidate = Path(path).expanduser()
238
+ if candidate.is_absolute():
239
+ return candidate if candidate.is_file() else None
240
+ found = find_settings_file()
241
+ for base in ([found.parent] if found is not None else []) + [Path.cwd()]:
242
+ if (base / candidate).is_file():
243
+ return base / candidate
244
+ return None
245
+
246
+
234
247
  def data_read(
235
248
  path: str, delim: str | None = None, keep_attributes: bool = False, **kwargs: Any
236
249
  ) -> pd.DataFrame:
@@ -242,7 +255,8 @@ def data_read(
242
255
  unlocked file issues a ``DataChangedWarning``.
243
256
 
244
257
  Args:
245
- path: A catalog name such as ``"inputs.raw.survey"``, or a file path.
258
+ path: A catalog name such as ``"inputs.raw.survey"``, or a file path. A relative
259
+ path is looked for from the project root, then from the current folder.
246
260
  delim: Delimiter for delimited text: comma, tab, semicolon, or space.
247
261
  Default: the catalog's ``delimiter``, then the file extension.
248
262
  keep_attributes: Keep value labels from Stata and SPSS files as
@@ -255,8 +269,8 @@ def data_read(
255
269
  format Python cannot read.
256
270
  IntegrityError: A locked file changed since its hash was recorded.
257
271
  """
258
- direct = Path(path).expanduser()
259
- if direct.is_file():
272
+ direct = _existing_file(path)
273
+ if direct is not None:
260
274
  extension = direct.suffix.lower().lstrip(".")
261
275
  if extension not in _DIRECT_TYPES:
262
276
  raise UnsupportedFormatError(f"Unsupported file extension: {extension}")
@@ -294,35 +308,44 @@ def data_read(
294
308
  return data
295
309
 
296
310
 
297
- def _save_target(path: str, type: str | None) -> tuple[Path, str, bool]:
298
- """The file to write, its type, and whether ``path`` was a catalog name."""
311
+ def _save_target(path: str, type: str | None) -> tuple[Path, str, str | None]:
312
+ """The file to write, its type, and the catalog name (None when ``path`` is a file path).
313
+
314
+ A relative file path starts at the project root, as the catalog's paths do, so a
315
+ notebook in ``notebooks/`` writes where a script in the root would. A dot name that
316
+ ends in an extension, such as ``inputs.final.x.csv``, is the name ``inputs.final.x``
317
+ saved as that type.
318
+ """
299
319
  has_slash = "/" in path or "\\" in path
300
320
  extension = re.search(r"\.(csv|parquet|rds)$", path, re.IGNORECASE)
321
+ root = project_root()
301
322
 
302
- if has_slash or extension:
323
+ if has_slash:
303
324
  if type is None:
304
325
  if extension is None:
305
326
  raise FrameworkError(
306
327
  "Cannot auto-detect file type from path. Please specify 'type'."
307
328
  )
308
329
  type = extension.group(1).lower()
309
- target = Path(path)
310
330
  if not path.lower().endswith(f".{type}"):
311
- target = Path(f"{path}.{type}")
331
+ path = f"{path}.{type}"
312
332
  inform(f"Note: Added .{type} extension to path")
313
- return target, type, False
333
+ return in_root(path, root), type, None
334
+
335
+ if extension:
336
+ given = extension.group(1).lower()
337
+ if type is not None and type.lower() != given:
338
+ raise FrameworkError(f"'{path}' ends in .{given}, but type is '{type}'.")
339
+ type = given
340
+ path = path[: extension.start()]
314
341
 
315
342
  parts = path.split(".")
316
- if len(parts) == 1:
343
+ if len(parts) == 1 or not all(parts):
317
344
  suffix = type or "parquet"
318
345
  raise FrameworkError(
319
- f"Path '{path}' has no directory. Either:\n"
346
+ f"'{path}' has no directory. Either:\n"
320
347
  f" - Use dot notation: 'inputs.raw.{path}' or 'inputs.intermediate.{path}'\n"
321
- f" - Provide a full path: 'inputs/raw/{path}.{suffix}'"
322
- )
323
- if len(parts) < 3:
324
- raise FrameworkError(
325
- "Dot notation requires at least three parts (e.g., 'inputs.raw.filename')"
348
+ f" - Provide a path from the project root: 'inputs/raw/{path}.{suffix}'"
326
349
  )
327
350
 
328
351
  config = settings_read()
@@ -330,23 +353,23 @@ def _save_target(path: str, type: str | None) -> tuple[Path, str, bool]:
330
353
  if not isinstance(directories, dict):
331
354
  directories = {}
332
355
  # The longest run of leading parts that names a directory key selects the
333
- # folder, so inputs.private.raw.x uses inputs_private_raw. R joins only
334
- # the first two parts, so it cannot reach three-part keys.
335
- for end in range(len(parts) - 1, 1, -1):
356
+ # folder, so inputs.private.raw.x uses inputs_private_raw and data.x (a
357
+ # course's one-word key) uses data, as in R.
358
+ for end in range(len(parts) - 1, 0, -1):
336
359
  folder = directories.get("_".join(parts[:end]))
337
360
  if isinstance(folder, str) and folder:
338
361
  break
339
362
  else:
340
363
  available = ", ".join(k.replace("_", ".") for k in directories) or "none"
341
364
  raise FrameworkError(
342
- f"Unknown directory '{parts[0]}.{parts[1]}'. Use a configured directory.\n\n"
365
+ f"Unknown directory in '{path}'. Start the name with a configured directory.\n\n"
343
366
  f"Available directories:\n {available}\n\n"
344
367
  "Examples:\n data_save(df, 'inputs.raw.mydata')\n"
345
368
  " data_save(df, 'outputs.private.results')"
346
369
  )
347
370
  type = type or "parquet"
348
- target = in_root(folder, project_root()) / f"{'_'.join(parts[end:])}.{type}"
349
- return target, type, True
371
+ target = in_root(folder, root) / f"{'_'.join(parts[end:])}.{type}"
372
+ return target, type, path
350
373
 
351
374
 
352
375
  def data_save(
@@ -362,11 +385,14 @@ def data_save(
362
385
  Args:
363
386
  data: The data to save.
364
387
  path: A catalog name such as ``"inputs.intermediate.cleaned"`` or a
365
- file path ending in ``.csv`` or ``.parquet``. A name's leading
388
+ file path with a ``/``, ending in ``.csv`` or ``.parquet``. A name's leading
366
389
  parts select a folder from ``directories``: the longest run that
367
- names a key, such as ``inputs_intermediate`` or
368
- ``inputs_private_raw``. The rest becomes the file name. A name is
369
- also added to the data catalog, so ``data_read()`` finds it.
390
+ names a key, such as ``inputs_intermediate``, ``inputs_private_raw``, or a
391
+ course's ``data``. The rest becomes the file name. A name is also added to
392
+ the data catalog, so ``data_read()`` finds it. A name may end in
393
+ ``.csv`` or ``.parquet`` to choose the type: ``"inputs.final.x.csv"`` is
394
+ the name ``inputs.final.x`` saved as CSV. A relative file path starts at the
395
+ project root, wherever Python runs.
370
396
  type: ``"parquet"`` or ``"csv"``. Default: from the file extension,
371
397
  or Parquet for a catalog name.
372
398
  delimiter: Delimiter for CSV files: comma, tab, semicolon, or space.
@@ -378,7 +404,7 @@ def data_save(
378
404
  """
379
405
  if not isinstance(data, pd.DataFrame):
380
406
  raise FrameworkError("data_save() needs a pandas DataFrame")
381
- target, file_type, is_name = _save_target(path, type)
407
+ target, file_type, name = _save_target(path, type)
382
408
  if file_type == "rds":
383
409
  raise UnsupportedFormatError(
384
410
  ".rds files are R-only. Save as 'parquet' or 'csv' so both languages can read it."
@@ -400,33 +426,37 @@ def data_save(
400
426
  data.to_csv(target, sep=_separator(delimiter), index=False, lineterminator="\n")
401
427
  else:
402
428
  data.to_parquet(target, index=False)
403
- inform(f"Data saved to: {target}")
404
-
405
429
  root = project_root()
430
+ relative = relative_to_root(target, root)
431
+ inform(f"Data saved to: {relative}")
432
+ # A file path is recorded from the project root, however it was given, so an
433
+ # absolute path and the same path from the root share one record.
434
+ key = name or relative
435
+
406
436
  digest = file_hash(target)
407
437
  db.set_data_record(
408
- path,
409
- path=relative_to_root(target, root),
438
+ key,
439
+ path=relative,
410
440
  type=file_type,
411
441
  delimiter=delimiter if file_type == "csv" else None,
412
442
  locked=locked,
413
443
  hash=digest,
414
444
  root=root,
415
445
  )
416
- inform(f"Database updated: {path}")
446
+ inform(f"Database updated: {key}")
417
447
 
418
448
  # Mirror the digest to the project's cloud ledger in live mode only;
419
449
  # framework.db stays the record.
420
450
  from framework.cloud import ledger_push_quietly
421
451
 
422
- ledger_push_quietly(path, digest, target)
452
+ ledger_push_quietly(key, digest, target)
423
453
 
424
- if is_name:
454
+ if name is not None:
425
455
  try:
426
- data_add(target, name=path, type=file_type, delimiter=delimiter, locked=locked)
456
+ data_add(target, name=name, type=file_type, delimiter=delimiter, locked=locked)
427
457
  except FrameworkError as error:
428
458
  warnings.warn(
429
- f"File saved but could not update data catalog for '{path}': {error}",
459
+ f"File saved but could not update data catalog for '{name}': {error}",
430
460
  FrameworkWarning,
431
461
  stacklevel=2,
432
462
  )
@@ -434,14 +464,21 @@ def data_save(
434
464
 
435
465
 
436
466
  def _derive_name(file_path: Path, config: dict[str, Any], root: Path) -> str:
437
- directories = config.get("directories") or {}
438
- for key in ("inputs_raw", "inputs_intermediate", "inputs_final", "inputs_reference"):
439
- folder = directories.get(key) if isinstance(directories, dict) else None
440
- if not isinstance(folder, str):
467
+ """``<key>.<file name>`` for a file in a configured inputs directory, as in R.
468
+
469
+ The deepest matching directory wins, so a file in ``inputs_private_raw``
470
+ (``inputs/private/raw``) is ``inputs.private.raw.<file name>``.
471
+ """
472
+ directories = config.get("directories")
473
+ best: tuple[int, str] | None = None
474
+ for key, folder in (directories if isinstance(directories, dict) else {}).items():
475
+ if not re.match(r"^inputs(_|$)", str(key)) or not isinstance(folder, str) or not folder:
441
476
  continue
442
477
  base = in_root(folder, root).resolve()
443
- if file_path.is_relative_to(base):
444
- return f"{key.replace('_', '.')}.{file_path.stem}"
478
+ if file_path.is_relative_to(base) and (best is None or len(base.parts) > best[0]):
479
+ best = (len(base.parts), str(key))
480
+ if best is not None:
481
+ return f"{best[1].replace('_', '.')}.{file_path.stem}"
445
482
  inform(
446
483
  f"Note: Using '{file_path.stem}' as data name. Consider specifying a more descriptive name."
447
484
  )
@@ -499,9 +536,11 @@ def data_add(
499
536
  """Add an existing file to the data catalog and record its hash.
500
537
 
501
538
  Args:
502
- file_path: The file to add. It must exist.
503
- name: Catalog name. Default: from the folder (``inputs.raw.<file>``
504
- for a file in ``inputs_raw``), else the file name.
539
+ file_path: The file to add. It must exist. A relative path is looked for from
540
+ the project root, then from the current folder.
541
+ name: Catalog name. Default: from the deepest configured inputs folder
542
+ (``inputs.raw.<file>`` for a file in ``inputs_raw``, and
543
+ ``inputs.private.raw.<file>`` in ``inputs_private_raw``), else the file name.
505
544
  type: File type. Default: from the extension.
506
545
  delimiter: Delimiter for CSV files.
507
546
  locked: Whether later reads must find the file unchanged.
@@ -511,10 +550,10 @@ def data_add(
511
550
  The catalog entry. Its path is relative to the project root, so the
512
551
  project still works after it is moved or cloned.
513
552
  """
514
- path = Path(file_path).expanduser()
515
- if not path.is_file():
553
+ found = _existing_file(file_path)
554
+ if found is None:
516
555
  raise DataNotFoundError(f"File not found: {file_path}")
517
- path = path.resolve()
556
+ path = found.resolve()
518
557
  root = project_root()
519
558
  if type is None:
520
559
  extension = path.suffix.lower().lstrip(".")
framework/hooks.py CHANGED
@@ -124,17 +124,45 @@ def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
124
124
  )
125
125
 
126
126
 
127
+ def outer_repository(root: Path) -> Path | None:
128
+ """The top of the git repository holding ``root``, when that is a folder above it.
129
+
130
+ A project inside another project's repository has no hooks of its own: git runs the
131
+ outer repository's hooks, from the outer repository's top folder.
132
+ """
133
+ if shutil.which("git") is None:
134
+ return None
135
+ result = _git(root, "rev-parse", "--show-toplevel")
136
+ if result.returncode != 0 or not result.stdout.strip():
137
+ return None
138
+ top = Path(result.stdout.strip()).resolve()
139
+ return None if top == root.resolve() else top
140
+
141
+
127
142
  def _hook_path(root: Path) -> Path | None:
128
- """Where git looks for the pre-commit hook, or None outside a repository."""
143
+ """Where git looks for the project's pre-commit hook.
144
+
145
+ None outside a repository, or when the project sits inside a repository whose top is
146
+ a folder above it.
147
+ """
129
148
  if shutil.which("git") is None:
130
149
  return None
131
150
  result = _git(root, "rev-parse", "--git-path", "hooks/pre-commit")
132
- if result.returncode != 0:
151
+ if result.returncode != 0 or outer_repository(root) is not None:
133
152
  return None
134
153
  path = Path(result.stdout.strip())
135
154
  return path if path.is_absolute() else root / path
136
155
 
137
156
 
157
+ def _nested_error(root: Path, top: Path) -> FrameworkError:
158
+ return FrameworkError(
159
+ f"The project at {root} is inside the git repository at {top}, so its hooks would "
160
+ "be that repository's hooks and run from its top folder. Framework installs hooks "
161
+ "only for a project at the top of its own repository. Run git init in the project "
162
+ "to give it one."
163
+ )
164
+
165
+
138
166
  def _is_framework_hook(path: Path) -> bool:
139
167
  try:
140
168
  head = path.read_text(encoding="utf-8", errors="replace")[:500]
@@ -165,10 +193,15 @@ def git_hooks_install(
165
193
  enabled, or when another hook is kept.
166
194
 
167
195
  Raises:
168
- FrameworkError: When the settings file is not found.
196
+ FrameworkError: When the settings file is not found, or the project is inside a git
197
+ repository whose top is a folder above it. The hook would land in that
198
+ repository and run from its top folder, so install nothing there.
169
199
  """
170
200
  path = _settings_path(settings_file)
171
201
  root = path.parent
202
+ top = outer_repository(root)
203
+ if top is not None:
204
+ raise _nested_error(root, top)
172
205
  hook = _hook_path(root)
173
206
  if hook is None:
174
207
  _say(verbose, "✗ Not a git repository")
@@ -205,6 +238,10 @@ def git_hooks_uninstall(settings_file: str | Path | None = None, *, verbose: boo
205
238
  Whether a hook was removed.
206
239
  """
207
240
  root = _settings_path(settings_file).parent if settings_file else _root_or_cwd()
241
+ top = outer_repository(root)
242
+ if top is not None:
243
+ _say(verbose, f"No pre-commit hook of this project: it is inside the repository at {top}")
244
+ return False
208
245
  hook = _hook_path(root)
209
246
  if hook is None or not hook.exists():
210
247
  _say(verbose, "No pre-commit hook found")
framework/notebooks.py CHANGED
@@ -26,6 +26,7 @@ from typing import Any, Literal
26
26
  import pandas as pd
27
27
 
28
28
  from framework._log import inform, show_messages
29
+ from framework._paths import in_root
29
30
  from framework.config_home import global_settings
30
31
  from framework.errors import FrameworkError
31
32
  from framework.global_config import templates_dir
@@ -61,6 +62,21 @@ def _project() -> tuple[Path, dict[str, Any]]:
61
62
  return found.parent, {}
62
63
 
63
64
 
65
+ def notebook_title(name: str) -> str:
66
+ """The default title for a new notebook, as R makes it.
67
+
68
+ A name with spaces is already a title and is kept as typed ("My cool analysis"). A
69
+ file-style name has its ``-`` and ``_`` turned into spaces and each word capitalized:
70
+ "bp-summary" becomes "Bp Summary" and "01_load_data" becomes "01 Load Data".
71
+ """
72
+ if re.search(r"\s", name.strip()):
73
+ return name.strip()
74
+ words = [word for word in re.split(r"[-_\s]+", name) if word]
75
+ if not words:
76
+ return name
77
+ return " ".join(word[0].upper() + word[1:] for word in words)
78
+
79
+
64
80
  def slugify(text: str) -> str:
65
81
  """Lowercase letters, digits, and hyphens, as R names notebook files."""
66
82
  slug = re.sub(r"[^a-z0-9-]", "-", text.lower())
@@ -217,8 +233,8 @@ def make_notebook(
217
233
  type: ``"quarto"`` (the default), ``"jupyter"``, or ``"script"``.
218
234
  Without it, ``scaffold: notebook_format`` in the settings decides, so a
219
235
  Scripts-only project (``script``) gets a ``.py`` script.
220
- dir: The folder. Defaults to ``directories: notebooks`` in the
221
- settings, relative to the project root.
236
+ dir: The folder, relative to the project root unless absolute. Defaults to
237
+ ``directories: notebooks`` in the settings.
222
238
  stub: The stub to start from, such as ``"default"`` or ``"minimal"``.
223
239
  overwrite: Replace an existing file.
224
240
  subdir: A subfolder of ``dir``.
@@ -238,7 +254,8 @@ def make_notebook(
238
254
  else _default_dir(config, root, ("notebooks", "work"), "notebook_dir")
239
255
  )
240
256
  else:
241
- folder = Path(dir)
257
+ # Relative to the project root, as the settings' folders are, wherever Python runs
258
+ folder = in_root(dir, root)
242
259
  if subdir:
243
260
  folder = folder / subdir
244
261
  if not folder.exists():
@@ -250,10 +267,10 @@ def make_notebook(
250
267
 
251
268
  source = _find_stub(root, "script" if kind == "script" else "notebook", stub, ext)
252
269
  author = _author(config)
253
- title = re.sub(r"\.(qmd|ipynb|py)$", "", Path(name).name, flags=re.IGNORECASE)
270
+ stem = re.sub(r"\.(qmd|ipynb|py)$", "", Path(name).name, flags=re.IGNORECASE)
254
271
  values = {
255
- "title": title,
256
- "filename": title,
272
+ "title": notebook_title(stem),
273
+ "filename": stem,
257
274
  "date": f"{date.today():%Y-%m-%d}",
258
275
  "author": author.get("name") or "Your Name",
259
276
  "email": author.get("email", ""),
@@ -262,9 +279,10 @@ def make_notebook(
262
279
  content = _fill(source.read_text(encoding="utf-8"), ext, values, author)
263
280
  target.write_text(content, encoding="utf-8")
264
281
  label = {"quarto": "Quarto notebook", "jupyter": "Jupyter notebook", "script": "Python script"}
265
- inform(f"Created {label[kind]}: {target}")
266
- if stub != "default":
267
- inform(f" Using stub: {stub}")
282
+ what = "reveal.js presentation" if stub == "revealjs" else label[kind]
283
+ # The revealjs stub is implied by "presentation"; any other stub is named
284
+ note = f" (stub: {stub})" if stub not in ("default", "revealjs") else ""
285
+ inform(f"Created {what}: {target}{note}")
268
286
  return target
269
287
 
270
288
 
@@ -282,9 +300,10 @@ def make_qmd(
282
300
  name: The file name before slugifying, such as "Data Cleaning", which becomes
283
301
  ``data-cleaning.qmd``. Another extension wins, as in R: "x.ipynb" creates a
284
302
  Jupyter notebook and "x.py" a script.
285
- dir: The folder. Default: ``directories: notebooks`` or ``directories: work`` in the
286
- settings, then ``options: notebook_dir``, then an existing ``notebooks/`` or
287
- ``work/`` folder, then the project root. The folder is created when missing.
303
+ dir: The folder, relative to the project root unless absolute. Default:
304
+ ``directories: notebooks`` or ``directories: work`` in the settings, then
305
+ ``options: notebook_dir``, then an existing ``notebooks/`` or ``work/`` folder,
306
+ then the project root. The folder is created when missing.
288
307
  stub: The stub to start from, such as "default" or "minimal". The project's
289
308
  ``stubs/notebook-{stub}.qmd`` is used first, then your template, then Framework's.
290
309
  overwrite: Replace an existing file.
@@ -310,9 +329,10 @@ def make_revealjs(
310
329
  Args:
311
330
  name: The file name before slugifying, such as "Data Cleaning", which becomes
312
331
  ``data-cleaning.qmd``.
313
- dir: The folder. Default: ``directories: notebooks`` or ``directories: work`` in the
314
- settings, then ``options: notebook_dir``, then an existing ``notebooks/`` or
315
- ``work/`` folder, then the project root. The folder is created when missing.
332
+ dir: The folder, relative to the project root unless absolute. Default:
333
+ ``directories: notebooks`` or ``directories: work`` in the settings, then
334
+ ``options: notebook_dir``, then an existing ``notebooks/`` or ``work/`` folder,
335
+ then the project root. The folder is created when missing.
316
336
  overwrite: Replace an existing file.
317
337
  subdir: A subfolder of ``dir``.
318
338
 
@@ -334,9 +354,10 @@ def make_presentation(
334
354
  Args:
335
355
  name: The file name before slugifying, such as "Data Cleaning", which becomes
336
356
  ``data-cleaning.qmd``.
337
- dir: The folder. Default: ``directories: notebooks`` or ``directories: work`` in the
338
- settings, then ``options: notebook_dir``, then an existing ``notebooks/`` or
339
- ``work/`` folder, then the project root. The folder is created when missing.
357
+ dir: The folder, relative to the project root unless absolute. Default:
358
+ ``directories: notebooks`` or ``directories: work`` in the settings, then
359
+ ``options: notebook_dir``, then an existing ``notebooks/`` or ``work/`` folder,
360
+ then the project root. The folder is created when missing.
340
361
  overwrite: Replace an existing file.
341
362
  subdir: A subfolder of ``dir``.
342
363
 
@@ -358,9 +379,10 @@ def make_script(
358
379
  Args:
359
380
  name: The file name before slugifying, such as "Load Data", which becomes
360
381
  ``load-data.py``. A ``.py`` extension is added when missing.
361
- dir: The folder. Default: ``directories: scripts`` in the settings, then
362
- ``options: script_dir``, then an existing ``scripts/`` folder, then the project
363
- root. The folder is created when missing.
382
+ dir: The folder, relative to the project root unless absolute. Default:
383
+ ``directories: scripts`` in the settings, then ``options: script_dir``, then an
384
+ existing ``scripts/`` folder, then the project root. The folder is created when
385
+ missing.
364
386
  stub: The stub to start from, such as "default". The project's
365
387
  ``stubs/script-{stub}.py`` is used first, then your template, then Framework's.
366
388
  overwrite: Replace an existing file.
framework/packages.py CHANGED
@@ -17,6 +17,7 @@ import tomllib
17
17
  from dataclasses import dataclass, field
18
18
  from importlib.metadata import PackageNotFoundError, version
19
19
  from pathlib import Path
20
+ from typing import Any
20
21
 
21
22
  import pandas as pd
22
23
 
@@ -149,6 +150,122 @@ def package_add(requirement: str, *, install: bool = True, dev: bool = False) ->
149
150
  _check(_run([sys.executable, "-m", "pip", "install", requirement], root), "pip install")
150
151
 
151
152
 
153
+ def _package_set(set_id: str) -> dict[str, Any]:
154
+ """A package set for a Python project: built in, or an account's set from the cloud."""
155
+ from framework.features import _for_python, _sets
156
+
157
+ if "/" in set_id and not set_id.startswith("framework/"):
158
+ return _cloud_package_set(set_id)
159
+ set_id = set_id.removeprefix("framework/")
160
+ sets = _sets("packages")
161
+ available = ", ".join(i for i, d in sets.items() if _for_python(d))
162
+ definition = sets.get(set_id)
163
+ if definition is None:
164
+ raise FrameworkError(f"Unknown package set: {set_id}. Available: {available}")
165
+ if not _for_python(definition):
166
+ raise FrameworkError(
167
+ f"The {definition['name']} package set isn't available for Python projects. "
168
+ f"Available: {available}"
169
+ )
170
+ return definition
171
+
172
+
173
+ def _cloud_package_set(handle: str) -> dict[str, Any]:
174
+ """An account's package set, resolved by Framework Cloud as ``new()`` resolves chosen sets."""
175
+ from framework.cloud import _require_token, cloud_server, resolve_choices
176
+
177
+ server = cloud_server().url
178
+ token = _require_token(server)
179
+ body = {"language": "python", "package_sets": [handle]}
180
+ envelope, _ = resolve_choices(body, token, server)
181
+ for entry in envelope.get("layers") or []:
182
+ if isinstance(entry, dict) and entry.get("key") == handle:
183
+ return {"id": handle, "name": handle, "layer": entry.get("layer") or {}}
184
+ raise FrameworkError(f"The {handle} package set isn't available for Python projects.")
185
+
186
+
187
+ def package_set_add(set: str, *, install: bool = True) -> dict[str, list[str]]:
188
+ """Add a package set's packages to the project's dependencies, and install them.
189
+
190
+ Packages the project already lists are left as they are. The rest are added to
191
+ ``pyproject.toml`` as ``package_add()`` adds them. A GitHub package keeps its repository.
192
+ Sets also stack at creation with ``new(package_sets=[...])``.
193
+
194
+ Args:
195
+ set: A built-in package set for Python, such as ``"python-data-analysis"`` or
196
+ ``"fastapi-python"`` (see ``package_sets_list()``). When you are signed in to
197
+ Framework Cloud, a handle such as ``"@yourname/lab-tools"`` adds one of your
198
+ account's sets.
199
+ install: Install the added packages now. With uv, False only updates
200
+ ``pyproject.toml`` and ``uv.lock``.
201
+
202
+ Returns:
203
+ ``{"added": [...], "present": [...]}``: the packages added and those the project
204
+ already listed.
205
+
206
+ Raises:
207
+ FrameworkError: For an unknown set, a set for another language, or a failed install.
208
+ """
209
+ from framework.create import _dependency
210
+
211
+ show_messages()
212
+ root = project_root()
213
+ path = _pyproject(root)
214
+ definition = _package_set(set)
215
+ wanted = ((definition.get("layer") or {}).get("packages") or {}).get("default_packages") or {}
216
+ listed = {_normalize(_package_name(d)) for d in _dependencies(root)}
217
+ present = [name for name in wanted if _normalize(name) in listed]
218
+ added = [name for name in wanted if _normalize(name) not in listed]
219
+ requirements = [_dependency(name, wanted[name] or {}) for name in added]
220
+
221
+ if requirements:
222
+ uv = _uv()
223
+ if uv is not None:
224
+ args = [uv, "add", *requirements]
225
+ if not install:
226
+ args.append("--no-sync")
227
+ _check(_run(args, root), "uv add")
228
+ else:
229
+ for requirement in requirements:
230
+ _add_to_pyproject(path, requirement)
231
+ if install:
232
+ args = [sys.executable, "-m", "pip", "install", *requirements]
233
+ _check(_run(args, root), "pip install")
234
+ inform(f"✓ Added {len(added)} package(s) from {definition['name']}: {', '.join(added)}")
235
+ else:
236
+ inform(f"The project already lists every package in {definition['name']}.")
237
+ if present:
238
+ inform(f"Already listed: {', '.join(present)}")
239
+ return {"added": added, "present": present}
240
+
241
+
242
+ def package_sets_list() -> pd.DataFrame:
243
+ """Framework's built-in package sets for Python projects.
244
+
245
+ Add one to a project with ``package_set_add()``, or at creation with
246
+ ``new(package_sets=[...])``.
247
+
248
+ Returns:
249
+ One row per set with ``id``, ``name``, ``description``, and ``packages`` (a list of
250
+ package names).
251
+ """
252
+ from framework.features import _for_python, _sets
253
+
254
+ rows = [
255
+ {
256
+ "id": d["id"],
257
+ "name": d["name"],
258
+ "description": d["description"],
259
+ "packages": list(
260
+ ((d.get("layer") or {}).get("packages") or {}).get("default_packages") or {}
261
+ ),
262
+ }
263
+ for d in _sets("packages").values()
264
+ if _for_python(d)
265
+ ]
266
+ return pd.DataFrame(rows, columns=["id", "name", "description", "packages"])
267
+
268
+
152
269
  def packages_list() -> pd.DataFrame:
153
270
  """The project's dependencies from ``pyproject.toml``, with installed versions.
154
271