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.
- framework/__init__.py +4 -0
- framework/_assets/sets/packages/bayes-r.json +51 -0
- framework/_assets/sets/packages/causal-inference-r.json +34 -0
- framework/_assets/sets/packages/fastapi-python.json +34 -0
- framework/_assets/sets/packages/large-data-r.json +30 -0
- framework/_assets/sets/packages/plumber-r.json +30 -0
- framework/_assets/sets/packages/polars-python.json +26 -0
- framework/_assets/sets/packages/python-bayes.json +26 -0
- framework/_assets/sets/packages/python-database.json +26 -0
- framework/_assets/sets/packages/python-ml.json +22 -0
- framework/_assets/sets/packages/python-spatial.json +22 -0
- framework/_assets/sets/packages/python-viz.json +22 -0
- framework/_assets/sets/packages/regression-r.json +42 -0
- framework/_assets/sets/packages/shiny-python.json +30 -0
- framework/_assets/sets/packages/shiny-r.json +34 -0
- framework/_assets/sets/packages/spatial-r.json +26 -0
- framework/_assets/sets/packages/survey-r.json +22 -0
- framework/_assets/sets/packages/survival-r.json +30 -0
- framework/_assets/sets/packages/tables-r.json +30 -0
- framework/_assets/sets/packages/text-r.json +22 -0
- framework/_assets/sets/packages/tidy-core.json +26 -0
- framework/_assets/sets/packages/tidy-database.json +38 -0
- framework/_assets/sets/packages/tidy-omop.json +58 -0
- framework/_assets/sets/packages/tidymodels.json +22 -0
- framework/_assets/sets/packages/tidyverse-extended.json +70 -0
- framework/bootstrap.py +32 -6
- framework/cache.py +9 -5
- framework/catalog.py +8 -4
- framework/cloud.py +19 -13
- framework/config_home.py +18 -2
- framework/connections.py +45 -7
- framework/create.py +22 -1
- framework/data.py +87 -48
- framework/hooks.py +40 -3
- framework/notebooks.py +43 -21
- framework/packages.py +117 -0
- framework/publish_bundle.py +59 -2
- framework/scaffold.py +10 -2
- framework/security.py +24 -12
- framework/storage.py +142 -11
- framework/templates/defaults.yml +1 -1
- framework/templates/gitignore/course +2 -5
- {framework_py-0.1.0.dev7.dist-info → framework_py-0.1.0.dev8.dist-info}/METADATA +1 -1
- {framework_py-0.1.0.dev7.dist-info → framework_py-0.1.0.dev8.dist-info}/RECORD +46 -22
- {framework_py-0.1.0.dev7.dist-info → framework_py-0.1.0.dev8.dist-info}/WHEEL +0 -0
- {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 =
|
|
259
|
-
if direct
|
|
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,
|
|
298
|
-
"""The file to write, its type, and
|
|
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
|
|
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
|
-
|
|
331
|
+
path = f"{path}.{type}"
|
|
312
332
|
inform(f"Note: Added .{type} extension to path")
|
|
313
|
-
return
|
|
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"
|
|
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
|
|
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
|
|
334
|
-
#
|
|
335
|
-
for end in range(len(parts) - 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 '{
|
|
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,
|
|
349
|
-
return target, type,
|
|
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
|
-
``
|
|
369
|
-
|
|
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,
|
|
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
|
-
|
|
409
|
-
path=
|
|
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: {
|
|
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(
|
|
452
|
+
ledger_push_quietly(key, digest, target)
|
|
423
453
|
|
|
424
|
-
if
|
|
454
|
+
if name is not None:
|
|
425
455
|
try:
|
|
426
|
-
data_add(target, name=
|
|
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 '{
|
|
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
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
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
|
-
|
|
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
|
-
|
|
504
|
-
|
|
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
|
-
|
|
515
|
-
if
|
|
553
|
+
found = _existing_file(file_path)
|
|
554
|
+
if found is None:
|
|
516
555
|
raise DataNotFoundError(f"File not found: {file_path}")
|
|
517
|
-
path =
|
|
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
|
|
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
|
|
221
|
-
|
|
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
|
-
|
|
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
|
-
|
|
270
|
+
stem = re.sub(r"\.(qmd|ipynb|py)$", "", Path(name).name, flags=re.IGNORECASE)
|
|
254
271
|
values = {
|
|
255
|
-
"title":
|
|
256
|
-
"filename":
|
|
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
|
-
|
|
266
|
-
|
|
267
|
-
|
|
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
|
|
286
|
-
|
|
287
|
-
``
|
|
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
|
|
314
|
-
|
|
315
|
-
``
|
|
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
|
|
338
|
-
|
|
339
|
-
``
|
|
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
|
|
362
|
-
``
|
|
363
|
-
root. The folder is created when
|
|
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
|
|