framework-py 0.1.0.dev0__py3-none-any.whl

framework/__init__.py

@@ -0,0 +1,250 @@
+"""Framework: structured data science projects.
+
+Import it as ``import framework as fw``. The functions here match the R
+package's names, so the same documentation and skills apply in both
+languages.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from framework._time import now
+from framework.ai import ai_skills_update
+from framework.bootstrap import BootstrapResult, bootstrap
+from framework.cache import (
+    cache,
+    cache_flush,
+    cache_forget,
+    cache_get,
+    cache_list,
+    cache_remember,
+)
+from framework.catalog import DataInfo, data_info, data_list
+from framework.cloud import (
+    CloudError,
+    cloud_login,
+    cloud_logout,
+    cloud_settings,
+    cloud_status,
+    cloud_sync,
+    data_verify,
+    ledger_list,
+    ledger_push,
+)
+from framework.config_home import (
+    config_dir,
+    config_sync,
+    global_settings,
+    project_list,
+    project_register,
+    project_unregister,
+)
+from framework.connections import (
+    Connection,
+    connections_list,
+    db_connect,
+    db_drivers_status,
+    db_execute,
+    db_list,
+    db_query,
+    db_transaction,
+)
+from framework.console import CapturedOutput, capture_output
+from framework.create import (
+    new,
+    project_add_directory,
+    project_create,
+    project_create_from_layers,
+)
+from framework.data import data_add, data_read, data_save
+from framework.errors import (
+    CacheWarning,
+    DataChangedWarning,
+    DataNotFoundError,
+    FrameworkError,
+    FrameworkWarning,
+    IntegrityError,
+    ProjectNotFoundError,
+    SettingsError,
+    UnsupportedFormatError,
+)
+from framework.global_config import (
+    configure_global,
+    framework_template_path,
+    load_settings_catalog,
+    read_framework_template,
+    reset_framework_template,
+    write_framework_template,
+)
+from framework.hooks import (
+    git_hooks_disable,
+    git_hooks_enable,
+    git_hooks_install,
+    git_hooks_list,
+    git_hooks_uninstall,
+)
+from framework.notebooks import (
+    make_notebook,
+    make_presentation,
+    make_qmd,
+    make_revealjs,
+    make_script,
+    stubs_list,
+    stubs_path,
+    stubs_publish,
+)
+from framework.outputs import (
+    result_list,
+    save_figure,
+    save_model,
+    save_notebook,
+    save_report,
+    save_table,
+)
+from framework.packages import (
+    PackagesStatus,
+    package_add,
+    packages_install,
+    packages_list,
+    packages_restore,
+    packages_snapshot,
+    packages_status,
+    packages_update,
+)
+from framework.project import project_root
+from framework.quarto import quarto_generate_all, quarto_regenerate
+from framework.scaffold import project_info, scaffold, status
+from framework.scratch import scratch_capture, scratch_clean
+from framework.security import AuditResult, git_security_audit
+from framework.settings import settings, settings_read, settings_write
+from framework.spec.check import spec_check
+from framework.spec.merge import SpecError
+from framework.spec.resolve import ResolvedSpec, spec_resolve
+from framework.storage import (
+    publish,
+    publish_data,
+    publish_dir,
+    publish_list,
+    publish_notebook,
+    storage_test,
+)
+
+try:
+    __version__ = version("framework-py")
+except PackageNotFoundError:  # pragma: no cover (running from a source tree)
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AuditResult",
+    "BootstrapResult",
+    "CacheWarning",
+    "CapturedOutput",
+    "CloudError",
+    "Connection",
+    "DataChangedWarning",
+    "DataInfo",
+    "DataNotFoundError",
+    "FrameworkError",
+    "FrameworkWarning",
+    "IntegrityError",
+    "PackagesStatus",
+    "ProjectNotFoundError",
+    "ResolvedSpec",
+    "SettingsError",
+    "SpecError",
+    "UnsupportedFormatError",
+    "__version__",
+    "ai_skills_update",
+    "bootstrap",
+    "cache",
+    "cache_flush",
+    "cache_forget",
+    "cache_get",
+    "cache_list",
+    "cache_remember",
+    "capture_output",
+    "cloud_login",
+    "cloud_logout",
+    "cloud_settings",
+    "cloud_status",
+    "cloud_sync",
+    "config_dir",
+    "config_sync",
+    "configure_global",
+    "connections_list",
+    "data_add",
+    "data_info",
+    "data_list",
+    "data_read",
+    "data_save",
+    "data_verify",
+    "db_connect",
+    "db_drivers_status",
+    "db_execute",
+    "db_list",
+    "db_query",
+    "db_transaction",
+    "framework_template_path",
+    "git_hooks_disable",
+    "git_hooks_enable",
+    "git_hooks_install",
+    "git_hooks_list",
+    "git_hooks_uninstall",
+    "git_security_audit",
+    "global_settings",
+    "ledger_list",
+    "ledger_push",
+    "load_settings_catalog",
+    "make_notebook",
+    "make_presentation",
+    "make_qmd",
+    "make_revealjs",
+    "make_script",
+    "new",
+    "now",
+    "package_add",
+    "packages_install",
+    "packages_list",
+    "packages_restore",
+    "packages_snapshot",
+    "packages_status",
+    "packages_update",
+    "project_add_directory",
+    "project_create",
+    "project_create_from_layers",
+    "project_info",
+    "project_list",
+    "project_register",
+    "project_root",
+    "project_unregister",
+    "publish",
+    "publish_data",
+    "publish_dir",
+    "publish_list",
+    "publish_notebook",
+    "quarto_generate_all",
+    "quarto_regenerate",
+    "read_framework_template",
+    "reset_framework_template",
+    "result_list",
+    "save_figure",
+    "save_model",
+    "save_notebook",
+    "save_report",
+    "save_table",
+    "scaffold",
+    "scratch_capture",
+    "scratch_clean",
+    "settings",
+    "settings_read",
+    "settings_write",
+    "spec_check",
+    "spec_resolve",
+    "status",
+    "storage_test",
+    "stubs_list",
+    "stubs_path",
+    "stubs_publish",
+    "write_framework_template",
+]

framework/__main__.py

@@ -0,0 +1,89 @@
+"""Command-line entry points: ``python -m framework``.
+
+    python -m framework create --from-layers FILE --path DIR [--interactive]
+    python -m framework create --name NAME --path DIR [--type TYPE] [--interactive]
+    python -m framework bootstrap [--path DIR] [--interactive] [--no-packages]
+    python -m framework hook pre-commit
+
+Exit codes: 0 on success, 1 on failure (the message is on stderr), and 2 for
+a usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from framework.errors import FrameworkError
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="python -m framework", description="Framework for Python")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    create = commands.add_parser("create", help="create a Python project")
+    source = create.add_mutually_exclusive_group(required=True)
+    source.add_argument(
+        "--from-layers", metavar="FILE", help="a layers file (framework.pub format)"
+    )
+    source.add_argument("--name", help="project name; your defaults apply, as with framework.new()")
+    create.add_argument("--path", required=True, help="the project folder to create")
+    create.add_argument(
+        "--type",
+        choices=["project", "project_sensitive", "course", "presentation", "bare"],
+        help="project type, with --name (default: bare, or asked with --interactive)",
+    )
+    create.add_argument(
+        "--interactive",
+        action="store_true",
+        help="prompt for missing answers, initialize git, and register the project",
+    )
+
+    bootstrap = commands.add_parser("bootstrap", help="prepare a cloned project")
+    bootstrap.add_argument("--path", default=".", help="the project folder (default: .)")
+    bootstrap.add_argument("--interactive", action="store_true", help="ask for empty .env values")
+    bootstrap.add_argument(
+        "--no-packages", action="store_true", help="skip installing packages with uv"
+    )
+
+    hook = commands.add_parser("hook", help="run a git hook's checks (called by the hook)")
+    hook.add_argument("name", choices=["pre-commit"])
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if args.command == "hook":
+        from framework.hooks import hook_run
+
+        return hook_run(args.name)
+    if args.command == "create" and args.from_layers and args.type:
+        parser.error("--type can only be used with --name")
+    try:
+        if args.command == "bootstrap":
+            from framework.bootstrap import bootstrap
+
+            path = bootstrap(
+                args.path, interactive=args.interactive, packages=not args.no_packages
+            ).root
+        elif args.from_layers:
+            from framework.create import project_create_from_layers
+
+            path = project_create_from_layers(
+                args.from_layers, args.path, interactive=args.interactive
+            )
+        else:
+            from framework.create import new
+
+            path = new(args.name, args.path, args.type, interactive=args.interactive)
+    except FrameworkError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return 1
+    print(path)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

framework/_assets/hooks/pre-commit

@@ -0,0 +1,59 @@
+#!/bin/sh
+# Framework pre-commit hook (shared by R, Python, and fw)
+# Managed by Framework. Configure it with git_hooks_*() in R or Python.
+#
+# The checks themselves live in the language packages, which read
+# git.hooks in settings.yml to decide what to run. This script only finds a
+# runtime. A project with no usable runtime fails the commit, because the
+# hook guards against committing restricted data. Bypass with
+# `git commit --no-verify` only when you know the commit is safe.
+
+set -u
+
+cd "$(git rev-parse --show-toplevel)" || exit 1
+
+run_r() {
+  command -v Rscript >/dev/null 2>&1 || return 127
+  Rscript -e 'quit(status = framework:::.hook_run("pre-commit"))'
+}
+
+run_python() {
+  if [ -x .venv/bin/python ]; then
+    .venv/bin/python -m framework hook pre-commit
+  elif [ -x .venv/Scripts/python.exe ]; then
+    .venv/Scripts/python.exe -m framework hook pre-commit
+  elif [ -f uv.lock ] && command -v uv >/dev/null 2>&1; then
+    uv run --frozen python -m framework hook pre-commit
+  elif command -v python3 >/dev/null 2>&1; then
+    python3 -m framework hook pre-commit
+  else
+    return 127
+  fi
+}
+
+has_rproj() {
+  for f in ./*.Rproj; do
+    [ -e "$f" ] && return 0
+  done
+  return 1
+}
+
+# fw's detection plus *.Rproj, which every R-built project has even without
+# renv. R markers are checked first; a project with both runs the first
+# runtime that is installed.
+status=127
+if [ -f renv.lock ] || [ -f .Rprofile ] || has_rproj; then
+  run_r
+  status=$?
+fi
+if [ "$status" -eq 127 ] && { [ -f pyproject.toml ] || [ -f uv.lock ] || [ -d .venv ]; }; then
+  run_python
+  status=$?
+fi
+
+if [ "$status" -eq 127 ]; then
+  echo "Framework hook: no R or Python runtime with framework installed was found." >&2
+  echo "Install one, or run 'git commit --no-verify' if you are sure this commit is safe." >&2
+  exit 1
+fi
+exit "$status"

framework/_assets/init.sql

@@ -0,0 +1,63 @@
+CREATE TABLE results (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT UNIQUE,
+  type TEXT,
+  public BOOLEAN,
+  blind BOOLEAN,
+  comment TEXT,
+  hash TEXT,
+  last_read_at DATETIME,
+  created_at DATETIME,
+  updated_at DATETIME,
+  deleted_at DATETIME
+);
+
+CREATE TABLE data (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT UNIQUE,
+  path TEXT,
+  type TEXT,
+  delimiter TEXT,
+  locked BOOLEAN,
+  encrypted BOOLEAN,
+  hash TEXT,
+  last_read_at DATETIME,
+  created_at DATETIME,
+  updated_at DATETIME,
+  deleted_at DATETIME
+);
+
+CREATE TABLE cache (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT UNIQUE,
+  file_path TEXT,
+  hash TEXT,
+  expire_at DATETIME,
+  last_read_at DATETIME,
+  created_at DATETIME,
+  updated_at DATETIME,
+  deleted_at DATETIME
+);
+
+CREATE TABLE connections (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT UNIQUE,
+  driver TEXT,
+  host TEXT,
+  port INTEGER,
+  database TEXT,
+  schema TEXT,
+  user TEXT,
+  password TEXT,
+  last_used_at DATETIME,
+  created_at DATETIME,
+  updated_at DATETIME,
+  deleted_at DATETIME
+);
+
+CREATE TABLE meta (
+  key TEXT PRIMARY KEY,
+  value TEXT,
+  created_at DATETIME,
+  updated_at DATETIME
+);