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

framework/quarto.py

@@ -0,0 +1,163 @@
+"""Generating ``_quarto.yml`` files for a project, as the R package does."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+from framework.errors import FrameworkError
+from framework.settings import settings_read
+
+_HTML_DEFAULTS: dict[str, Any] = {
+    "theme": "default",
+    "toc": True,
+    "toc_depth": 3,
+    "code_fold": False,
+    "code_tools": False,
+    "embed_resources": True,
+    "highlight_style": "github",
+}
+_REVEALJS_DEFAULTS: dict[str, Any] = {
+    "theme": "default",
+    "incremental": False,
+    "slide_number": True,
+    "transition": "slide",
+    "background_transition": "fade",
+    "controls": True,
+    "progress": True,
+    "center": True,
+    "highlight_style": "github",
+}
+
+
+def _value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def quarto_yml(
+    settings: dict[str, Any] | None,
+    format: str = "html",
+    project_root: bool = False,
+    output_dir: str | None = None,
+) -> str:
+    """The text of one ``_quarto.yml`` file."""
+    if format not in ("html", "revealjs"):
+        raise FrameworkError("Format must be 'html' or 'revealjs'")
+    defaults = _HTML_DEFAULTS if format == "html" else _REVEALJS_DEFAULTS
+    given = (settings or {}).get(format)
+    options = {**defaults, **(given if isinstance(given, dict) else {})}
+
+    lines = [
+        f"# Auto-generated by Framework on {date.today():%Y-%m-%d}",
+        "# This file is yours to customize - Framework will not modify it after creation",
+        "# To regenerate: run framework.quarto_regenerate() (WARNING: overwrites!)",
+        "",
+    ]
+    if project_root or output_dir:
+        lines.append("project:")
+        if project_root:
+            lines.append("  type: default")
+        if output_dir:
+            lines.append(f"  output-dir: {output_dir}")
+        lines.append("")
+    lines.append("format:")
+    lines.append(f"  {format}:")
+    for key in defaults:
+        if key == "format":
+            continue
+        lines.append(f"    {key.replace('_', '-')}: {_value(options[key])}")
+    return "\n".join(lines) + "\n"
+
+
+def render_format(dir_key: str, project_type: str | None = None) -> str:
+    """Slides render as revealjs, everything else as HTML."""
+    if re.search(r"slides?", dir_key, re.IGNORECASE):
+        return "revealjs"
+    if project_type == "presentation" and dir_key == "root":
+        return "revealjs"
+    return "html"
+
+
+def quarto_generate_all(
+    project_path: str | Path,
+    project_type: str,
+    render_dirs: dict[str, str] | None = None,
+    quarto_settings: dict[str, Any] | None = None,
+    directories: dict[str, str] | None = None,
+) -> list[Path]:
+    """Write the root ``_quarto.yml`` and one per render folder. Returns the files written."""
+    root = Path(project_path)
+    if not root.is_dir():
+        raise FrameworkError(f"Project path does not exist: {root}")
+    written = []
+    root_format = "revealjs" if project_type == "presentation" else "html"
+    root_file = root / "_quarto.yml"
+    root_file.write_text(
+        quarto_yml(quarto_settings, root_format, project_root=True), encoding="utf-8"
+    )
+    written.append(root_file)
+
+    for key, target in (render_dirs or {}).items():
+        if not target:
+            continue
+        source = (directories or {}).get(key, key)
+        if not source:
+            continue
+        source_path = root / source
+        source_path.mkdir(parents=True, exist_ok=True)
+        output_dir = Path(os.path.relpath(root / target, source_path)).as_posix()
+        path = source_path / "_quarto.yml"
+        path.write_text(
+            quarto_yml(quarto_settings, render_format(key, project_type), output_dir=output_dir),
+            encoding="utf-8",
+        )
+        written.append(path)
+    return written
+
+
+@dataclass
+class RegenerateResult:
+    regenerated: list[Path]
+    backed_up: list[str] = field(default_factory=list)
+    backup_location: Path | None = None
+
+
+def quarto_regenerate(project_path: str | Path, backup: bool = True) -> RegenerateResult:
+    """Rewrite every ``_quarto.yml`` from the project's settings, backing up the old ones."""
+    root = Path(project_path)
+    settings_file = next(
+        (root / name for name in ("settings.yml", "config.yml") if (root / name).is_file()), None
+    )
+    if settings_file is None:
+        raise FrameworkError("Project settings.yml/config.yml not found")
+    config = settings_read(settings_file)
+
+    backed_up: list[str] = []
+    location = None
+    if backup:
+        location = root / ".quarto_backups" / f"{datetime.now():%Y%m%d_%H%M%S}"
+        for existing in root.rglob("_quarto.yml"):
+            if ".quarto_backups" in existing.parts:
+                continue
+            relative = existing.relative_to(root)
+            target = location / relative
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(existing, target)
+            backed_up.append(relative.as_posix())
+
+    quarto = config.get("quarto") if isinstance(config.get("quarto"), dict) else None
+    written = quarto_generate_all(
+        root,
+        str(config.get("project_type") or "project"),
+        config.get("render_dirs") or {},
+        quarto,
+        config.get("directories") or {},
+    )
+    return RegenerateResult(written, backed_up, location)

framework/scaffold.py

@@ -0,0 +1,269 @@
+"""Starting work in a project: ``scaffold()``, ``status()``, and ``project_info()``."""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import runpy
+import shutil
+import subprocess
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from framework import db, dotenv
+from framework._log import inform, show_messages
+from framework._paths import in_root
+from framework.errors import ProjectNotFoundError, SettingsError
+from framework.project import find_settings_file
+from framework.settings import settings_read
+
+_DEFAULT_SEED = 123
+
+
+def _section(config: dict[str, Any], name: str) -> dict[str, Any]:
+    value = config.get(name)
+    return value if isinstance(value, dict) else {}
+
+
+def _first(config: dict[str, Any], key: str) -> Any:
+    """A scaffold option from ``scaffold:``, then ``options:``, then the top level."""
+    for section in (_section(config, "scaffold"), _section(config, "options"), config):
+        if section.get(key) is not None:
+            return section[key]
+    return None
+
+
+def _load_dotenv(config: dict[str, Any], root: Path) -> None:
+    location = config.get("dotenv_location")
+    if location is None:
+        return
+    path = in_root(str(location), root)
+    if path.is_dir():
+        path = path / ".env"
+    if not path.is_file():
+        raise SettingsError(f"Dotenv file not found at '{path}'")
+    dotenv.load(path)
+
+
+def _mark_scaffolded(root: Path) -> dict[str, str]:
+    """Record the first and latest scaffold times in framework.db, as R does."""
+    stamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    history: dict[str, str] = {}
+    raw = db.get_meta("scaffold_history", root)
+    if raw:
+        try:
+            history = json.loads(raw)
+        except json.JSONDecodeError:
+            history = {}
+    updated = {"first": history.get("first") or stamp, "last": stamp}
+    db.set_meta("scaffold_history", json.dumps(updated, separators=(",", ":")), root)
+    return updated
+
+
+def _as_int(value: Any) -> int | None:
+    try:
+        return int(str(value).strip())
+    except ValueError:
+        return None
+
+
+def _set_seed(config: dict[str, Any]) -> int | None:
+    """Seed ``random`` and NumPy with R's rules.
+
+    An explicit ``seed_on_scaffold: false`` skips seeding even when
+    ``FW_SEED`` is set. Without a project setting, ``FW_SEED`` turns seeding
+    on. The project's seed wins over ``FW_SEED``, and the fallback is 123.
+    """
+    scaffold, options = _section(config, "scaffold"), _section(config, "options")
+    enabled = next(
+        (
+            s["seed_on_scaffold"]
+            for s in (scaffold, options, config)
+            if s.get("seed_on_scaffold") is not None
+        ),
+        None,
+    )
+    project_seed = next(
+        (_as_int(s["seed"]) for s in (scaffold, config, options) if s.get("seed") is not None),
+        None,
+    )
+    global_seed = _as_int(os.environ.get("FW_SEED", "x"))
+    if enabled is False or (enabled is None and global_seed is None):
+        return None
+    value = project_seed if project_seed is not None else global_seed
+    if value is None:
+        value = _DEFAULT_SEED
+    random.seed(value)
+    try:
+        import numpy as np
+
+        np.random.seed(value)
+    except ImportError:  # pragma: no cover (numpy comes with pandas)
+        pass
+    inform(f"Random seed set to {value}.")
+    return value
+
+
+def _add_function_folders(config: dict[str, Any], root: Path) -> list[Path]:
+    """Put the project's function folders on the import path."""
+    options = _section(config, "options")
+    if options.get("source_all_functions") is False:
+        return []
+    folders = options.get("functions_dir") or _section(config, "directories").get("functions")
+    if folders is None:
+        folders = "functions"
+    added = []
+    for folder in folders if isinstance(folders, list) else [folders]:
+        path = in_root(str(folder), root).resolve()
+        if path.is_dir() and str(path) not in sys.path:
+            sys.path.insert(0, str(path))
+            added.append(path)
+            inform(f"Added {folder} to the import path")
+    return added
+
+
+def scaffold(settings_file: str | Path | None = None) -> Path:
+    """Prepare the current Python session for work in the project.
+
+    Call it at the top of every notebook and script. It:
+
+    - finds the project root and loads its ``.env`` and settings,
+    - creates framework.db if needed and records the scaffold time,
+    - sets the random seed when ``seed_on_scaffold`` is on (or ``FW_SEED`` is set),
+    - puts the project's ``functions`` folder on the import path, and
+    - runs ``scaffold.py`` from the project root, if there is one.
+
+    The working directory is not changed: Framework resolves project paths
+    from the root wherever the notebook runs.
+
+    Returns:
+        The project root.
+    """
+    show_messages()
+    path = Path(settings_file) if settings_file is not None else find_settings_file()
+    if path is None or not path.is_file():
+        raise ProjectNotFoundError(
+            "Could not locate a Framework project: no settings.yml or config.yml in "
+            f"{Path.cwd()} or its parent folders. Create one with framework.new()."
+        )
+    root = path.resolve().parent
+    config = settings_read(path)
+    _load_dotenv(config, root)
+    db.ensure_db(root)
+    _mark_scaffolded(root)
+    _set_seed(config)
+    _add_function_folders(config, root)
+
+    script = root / "scaffold.py"
+    if script.is_file():
+        runpy.run_path(str(script), run_name="__scaffold__")
+    return root
+
+
+def _git(*args: str) -> str | None:
+    if shutil.which("git") is None:
+        return None
+    result = subprocess.run(["git", *args], capture_output=True, text=True, check=False)
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def status() -> None:
+    """Print an overview of the project: settings, git, AI files, and folders."""
+    from framework import __version__
+
+    settings_file = find_settings_file()
+    if settings_file is None:
+        raise ProjectNotFoundError(
+            "Not in a Framework project directory (settings.yml or config.yml not found)"
+        )
+    root = settings_file.parent
+    config = settings_read(settings_file)
+    lines = ["Framework project status", "", "Framework:", f"  Version: {__version__}", ""]
+
+    lines.append("Project:")
+    if config.get("project_type"):
+        lines.append(f"  Type: {config['project_type']}")
+    author = _section(config, "author").get("name")
+    if author:
+        lines.append(f"  Author: {author}")
+    lines.append("")
+
+    lines.append("Git:")
+    if shutil.which("git") is None:
+        lines.append("  Git not installed")
+    elif _git("-C", str(root), "rev-parse", "--git-dir") is None:
+        lines.append("  Not a git repository")
+    elif _git("-C", str(root), "rev-parse", "HEAD") is None:
+        lines.append("  No commits yet")
+    else:
+        lines.append(f"  Branch: {_git('-C', str(root), 'branch', '--show-current')}")
+        lines.append(f"  Commits: {_git('-C', str(root), 'rev-list', '--count', 'HEAD')}")
+        changes = (_git("-C", str(root), "status", "--porcelain") or "").splitlines()
+        lines.append(
+            f"  Uncommitted changes: {len(changes)}" if changes else "  Working tree clean"
+        )
+    lines.append("")
+
+    ai_files = [
+        name
+        for name in ("AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md")
+        if (root / name).is_file()
+    ]
+    lines.append("AI Assistants:")
+    lines.append(
+        f"  Files: {', '.join(ai_files)}" if ai_files else "  No AI instruction files found"
+    )
+    lines.append("")
+
+    lines.append("Package Management:")
+    if (root / "uv.lock").is_file():
+        lines.append("  uv: uv.lock present")
+    elif (root / "pyproject.toml").is_file():
+        lines.append("  pyproject.toml present (no lock file)")
+    else:
+        lines.append("  No pyproject.toml")
+    lines.append("")
+
+    directories = _section(config, "directories")
+    if directories:
+        lines.append("Directories:")
+        for key, value in directories.items():
+            if isinstance(value, str):
+                mark = "ok" if in_root(value, root).is_dir() else "x "
+                lines.append(f"  {mark} {key} -> {value}")
+    print("\n".join(lines))
+
+
+def project_info(verbose: bool = False) -> pd.DataFrame:
+    """The project's configured folders and whether each exists yet.
+
+    Folders that do not exist are created the first time something is saved
+    there. With ``verbose``, the project name and type are printed too.
+
+    Returns:
+        A DataFrame with columns key, path, and exists. Its ``attrs`` hold the
+        project ``name`` and ``type``.
+    """
+    settings_file = find_settings_file()
+    if settings_file is None:
+        raise ProjectNotFoundError(
+            "No project configuration found. Are you in a Framework project?"
+        )
+    root = settings_file.parent
+    config = settings_read(settings_file)
+    rows = [
+        {"key": key, "path": value, "exists": in_root(value, root).is_dir()}
+        for key, value in _section(config, "directories").items()
+        if isinstance(value, str)
+    ]
+    frame = pd.DataFrame(rows, columns=["key", "path", "exists"])
+    frame.attrs["name"] = config.get("project_name") or root.name
+    frame.attrs["type"] = config.get("project_type") or "project"
+    if verbose:
+        print(f"Project: {frame.attrs['name']}\nType: {frame.attrs['type']}")
+    return frame

framework/scratch.py

@@ -0,0 +1,108 @@
+"""Scratch files: quick captures of objects for a look outside Python."""
+
+from __future__ import annotations
+
+import pickle
+from datetime import datetime
+from pathlib import Path
+from typing import Any, TypeVar, cast
+
+import pandas as pd
+
+from framework import _yaml
+from framework._log import inform
+from framework._paths import in_root
+from framework.errors import FrameworkError
+from framework.project import project_root
+from framework.settings import settings_read
+
+T = TypeVar("T")
+
+_FORMATS = {"text": ".txt", "csv": ".csv", "tsv": ".tsv", "pickle": ".pkl"}
+_FROM_EXTENSION = {".txt": "text", ".csv": "csv", ".tsv": "tsv", ".pkl": "pickle"}
+
+
+def scratch_dir() -> Path:
+    """The scratch folder: ``directories.scratch`` in the settings."""
+    config = settings_read()
+    directories = config.get("directories") or {}
+    options = config.get("options") or {}
+    data_options = options.get("data") if isinstance(options, dict) else None
+    folder = (
+        (directories.get("scratch") if isinstance(directories, dict) else None)
+        or (data_options.get("scratch_dir") if isinstance(data_options, dict) else None)
+        or "outputs/private/scratch"
+    )
+    return in_root(folder, project_root())
+
+
+def _text(value: Any) -> str:
+    if isinstance(value, list | tuple | set) and all(
+        not isinstance(item, dict | list | tuple | set) for item in value
+    ):
+        return "".join(f"{item}\n" for item in value)
+    if isinstance(value, dict | list | tuple):
+        return f"# {type(value).__name__} with {len(value)} items\n" + _yaml.dump(value)
+    return f"{value}\n"
+
+
+def scratch_capture(
+    x: T,
+    name: str | None = None,
+    to: str | None = None,
+    location: str | Path | None = None,
+    n: int | None = None,
+) -> T:
+    """Write an object to the scratch folder and return it unchanged.
+
+    Args:
+        x: The object. DataFrames are written as TSV by default, anything
+            else as text.
+        name: File name. An extension (.txt, .csv, .tsv, .pkl) sets the format.
+            Default: ``capture_<timestamp>``.
+        to: ``"text"``, ``"csv"``, ``"tsv"``, or ``"pickle"``.
+        location: Folder to write to. Default: the scratch folder.
+        n: For a DataFrame, write only the first ``n`` rows.
+    """
+    folder = Path(location) if location is not None else scratch_dir()
+    folder.mkdir(parents=True, exist_ok=True)
+    if name is None:
+        name = f"capture_{datetime.now():%Y%m%d_%H%M%S}"
+    suffix = Path(name).suffix
+    if suffix in _FROM_EXTENSION:
+        to = _FROM_EXTENSION[suffix]
+        name = Path(name).stem
+    is_frame = isinstance(x, pd.DataFrame)
+    to = to or ("tsv" if is_frame else "text")
+    if to not in _FORMATS:
+        raise FrameworkError(f"'to' must be one of: {', '.join(_FORMATS)}")
+
+    path = folder / f"{name}{_FORMATS[to]}"
+    if to == "pickle":
+        with path.open("wb") as handle:
+            pickle.dump(x, handle)
+    elif is_frame:
+        if to == "text":
+            raise FrameworkError("DataFrames can be saved as 'csv', 'tsv', or 'pickle'")
+        frame = cast(pd.DataFrame, x)
+        if n is not None:
+            frame = frame.head(n)
+        frame.to_csv(path, sep="," if to == "csv" else "\t", index=False, lineterminator="\n")
+    elif to == "text":
+        path.write_text(_text(x), encoding="utf-8")
+    else:
+        raise FrameworkError("Only DataFrames can be saved as 'csv' or 'tsv'")
+    inform(f"Captured to {path}")
+    return x
+
+
+def scratch_clean() -> None:
+    """Delete the files in the scratch folder. Subfolders are left alone, as in R."""
+    folder = scratch_dir()
+    if not folder.is_dir():
+        inform(f"Scratch directory does not exist: {folder}")
+        return
+    for path in folder.iterdir():
+        if path.is_file() or path.is_symlink():
+            path.unlink()
+    inform(f"Scratch directory cleaned: {folder}")