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

framework/__main__.py

@@ -37,7 +37,12 @@ def _parser() -> argparse.ArgumentParser:
     create.add_argument(
         "--interactive",
         action="store_true",
-        help="prompt for missing answers, initialize git, and register the project",
+        help=(
+            "with --name, ask for the type when --type is missing (the project is "
+            "registered and gets a git repository either way, unless your defaults turn "
+            "git off); with --from-layers, initialize git and register the project "
+            "instead of running headless"
+        ),
     )
 
     bootstrap = commands.add_parser("bootstrap", help="prepare a cloned project")

framework/_assets/hooks/pre-commit

@@ -12,23 +12,31 @@ set -u
 
 cd "$(git rev-parse --show-toplevel)" || exit 1
 
+# Each runner returns 127 when its runtime or the framework package is
+# missing, so the next runtime gets a turn and the message below can say why
+
 run_r() {
   command -v Rscript >/dev/null 2>&1 || return 127
+  # framework 1.x from CRAN has no shared hook entry point
+  probe='ok <- requireNamespace("framework", quietly = TRUE) && exists(".hook_run", envir = asNamespace("framework"))'
+  Rscript -e "$probe; quit(status = if (ok) 0 else 127)" >/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
+    set -- .venv/bin/python
   elif [ -x .venv/Scripts/python.exe ]; then
-    .venv/Scripts/python.exe -m framework hook pre-commit
+    set -- .venv/Scripts/python.exe
   elif [ -f uv.lock ] && command -v uv >/dev/null 2>&1; then
-    uv run --frozen python -m framework hook pre-commit
+    set -- uv run --frozen python
   elif command -v python3 >/dev/null 2>&1; then
-    python3 -m framework hook pre-commit
+    set -- python3
   else
     return 127
   fi
+  "$@" -c 'import framework' >/dev/null 2>&1 || return 127
+  "$@" -m framework hook pre-commit
 }
 
 has_rproj() {
@@ -52,8 +60,8 @@ if [ "$status" -eq 127 ] && { [ -f pyproject.toml ] || [ -f uv.lock ] || [ -d .v
 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
+  echo "Framework hook: found neither R with framework 2.0 or later nor Python with framework-py." >&2
+  echo "Install one of them, or run 'git commit --no-verify' if you are sure this commit is safe." >&2
   exit 1
 fi
 exit "$status"

framework/_assets/schema/docs-reference.v1.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://framework.pub/schema/docs-reference.v1.json",
+  "title": "Framework docs reference",
+  "description": "The generated function or command reference for one product's docs site (docs/site/reference.json). Text fields hold CommonMark with GFM tables.",
+  "type": "object",
+  "required": ["schema", "product", "version", "categories", "entries"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "docs-reference.v1" },
+    "product": { "enum": ["r", "py", "cli"] },
+    "version": { "type": "string", "minLength": 1, "description": "The release this reference was built from, such as 2.0.0 or 0.1.0.dev1." },
+    "categories": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/category" }
+    },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/entry" }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$",
+      "description": "URL-safe and unique within the product: /reference/{id}."
+    },
+    "markdown": { "type": "string" },
+    "category": {
+      "type": "object",
+      "required": ["id", "title", "position"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "description": "One line, shown under the title in the Reference dropdown." },
+        "position": { "type": "integer" },
+        "common": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Entry names listed first, under a Common heading."
+        }
+      }
+    },
+    "titled": {
+      "type": "object",
+      "required": ["title", "content"],
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "content": { "$ref": "#/$defs/markdown" }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "required": ["id", "name", "kind", "category", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "#/$defs/id" },
+        "name": { "type": "string", "minLength": 1, "description": "As users write it: data_read, AuditResult, or \"project bootstrap\"." },
+        "kind": { "enum": ["function", "class", "command"] },
+        "category": { "type": "string", "description": "A category id." },
+        "title": { "type": "string", "description": "A short heading. Defaults to name." },
+        "summary": { "type": "string", "minLength": 1, "description": "One line, used in lists and search results." },
+        "usage": { "type": "string", "description": "The signature or command line, shown as code." },
+        "description": { "$ref": "#/$defs/markdown", "description": "A paragraph or two (roxygen @description, a docstring's opening paragraphs)." },
+        "details": { "$ref": "#/$defs/markdown", "description": "The long body (roxygen @details)." },
+        "parameters": {
+          "type": "array",
+          "description": "Arguments, flags, or a class's fields, in signature order.",
+          "items": {
+            "type": "object",
+            "required": ["name", "description"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string", "minLength": 1, "description": "x, *, --path, or -p, --path." },
+              "type": { "type": "string" },
+              "default": { "type": "string", "description": "As code, such as NULL, None, or \".\"." },
+              "required": { "type": "boolean" },
+              "env": { "type": "string", "description": "An environment variable that sets it (commands)." },
+              "description": { "$ref": "#/$defs/markdown" }
+            }
+          }
+        },
+        "returns": { "$ref": "#/$defs/markdown" },
+        "note": { "$ref": "#/$defs/markdown" },
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["title", "content"],
+            "additionalProperties": false,
+            "properties": {
+              "title": { "type": "string", "minLength": 1 },
+              "content": { "$ref": "#/$defs/markdown" },
+              "subsections": { "type": "array", "items": { "$ref": "#/$defs/titled" } }
+            }
+          }
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["code"],
+            "additionalProperties": false,
+            "properties": {
+              "title": { "type": "string" },
+              "code": { "type": "string", "minLength": 1 },
+              "runnable": { "type": "boolean", "default": true, "description": "False for R's \\dontrun and for examples that need a server or credentials." }
+            }
+          }
+        },
+        "see_also": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "type": "string", "minLength": 1, "description": "An entry name in this product, or a link target such as py:ref:data_read." },
+              {
+                "type": "object",
+                "required": ["title", "url"],
+                "additionalProperties": false,
+                "properties": {
+                  "title": { "type": "string", "minLength": 1 },
+                  "url": { "type": "string", "pattern": "^https://" }
+                }
+              }
+            ]
+          }
+        },
+        "aliases": { "type": "array", "items": { "type": "string" } },
+        "lifecycle": { "enum": ["stable", "deprecated", "experimental"], "default": "stable" },
+        "replaced_by": { "type": "string", "description": "The entry name to use instead, for deprecated entries." },
+        "since": { "type": "string", "description": "The version that added it." }
+      }
+    }
+  }
+}

framework/_paths.py

@@ -2,11 +2,21 @@
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 from typing import Any
 
 from framework.project import project_root
 
+# A folder named like private, confidential, or sensitive (outputs_private and
+# private_raw count too), as the git security audit and R's audit match them.
+PRIVATE_SEGMENT = re.compile(r"(^|/)[^/]*(private|confidential|sensitive)[^/]*(/|$)", re.IGNORECASE)
+
+
+def has_private_segment(path: str | Path) -> bool:
+    """Whether a folder path, with ``/`` separators, has a private segment."""
+    return bool(PRIVATE_SEGMENT.search(Path(path).as_posix()))
+
 
 def relative_to_root(path: Path, root: Path) -> str:
     """``path`` relative to the project root when it is inside it, else absolute."""

framework/ai.py

@@ -179,13 +179,16 @@ def ai_skills_update(project_path: str | Path = ".") -> list[str]:
     come from ``.framework/spec.json``, or from the settings for projects
     without one.
 
+    Args:
+        project_path: The project's root directory. Default: the current directory.
+
     Returns:
         The skill folders written.
     """
     from framework._log import inform, show_messages
 
     show_messages()
-    root = Path(project_path)
+    root = Path(project_path).expanduser()
     spec = _installed_spec(root)
     folders, _ = assistant_targets(spec)
     updated = []

framework/bootstrap.py

@@ -29,7 +29,7 @@ from typing import Any
 from framework import db, dotenv
 from framework._log import inform, show_messages
 from framework._paths import in_root
-from framework.create import ensure_secrets_ignored
+from framework.create import FILE_LIKE, ensure_secrets_ignored
 from framework.errors import FrameworkError
 from framework.hooks import git_hooks_install
 from framework.project import _settings_in
@@ -111,7 +111,13 @@ def _folders(config: dict[str, Any]) -> list[str]:
     folders: list[str] = []
     directories = config.get("directories")
     if isinstance(directories, dict):
-        folders += [value for value in directories.values() if isinstance(value, str) and value]
+        # Entries that name a file, such as presentation.qmd, are skipped, as
+        # project creation skips them. R's bootstrap() creates them as folders.
+        folders += [
+            value
+            for value in directories.values()
+            if isinstance(value, str) and value and not FILE_LIKE.search(value)
+        ]
     extra = config.get("extra_directories")
     if isinstance(extra, list):
         folders += [

framework/cache.py

@@ -210,7 +210,19 @@ def _lookup(name: str, file: str | Path | None) -> Any:
 
 
 def cache_get(name: str, file: str | Path | None = None, default: Any = None) -> Any:
-    """A cached value, or ``default`` when it is missing, expired, or unreadable."""
+    """A cached value, or ``default`` when it is missing, expired, or unreadable.
+
+    An expired value is removed. A value saved by R (``.rds``) or one whose file hash no longer
+    matches its record counts as missing.
+
+    Args:
+        name: The cache name.
+        file: Read the value from this file instead of the cache folder.
+        default: The value to return when the cache has no usable value.
+
+    Returns:
+        The cached value, or ``default``.
+    """
     value = _lookup(name, file)
     return default if value is _MISSING else value
 
@@ -298,7 +310,13 @@ def cache_remember(
 
 
 def cache_forget(name: str, file: str | Path | None = None) -> None:
-    """Remove a cached value and its record, whichever language saved it."""
+    """Remove a cached value and its record, whichever language saved it.
+
+    Args:
+        name: The cache name.
+        file: Remove this file instead of the files in the cache folder and the one in the
+            cache record.
+    """
     _remove(name, file)
 
 

framework/catalog.py

@@ -3,7 +3,10 @@
 The catalog is the ``data`` section of the settings. An entry is either a
 path string or a mapping with ``path`` and optional ``type``, ``delimiter``,
 ``locked``, ``description``, and other fields. Nested mappings without a
-``path`` group entries, and their keys form the dot-notation name.
+``path`` group entries, and their keys form the dot-notation name. A key may
+itself contain dots, so ``inputs.raw.survey`` is found as nested YAML, as
+``raw.survey:`` under ``inputs:``, or as ``inputs.raw.survey:`` directly under
+``data:``.
 """
 
 from __future__ import annotations
@@ -15,6 +18,7 @@ from typing import Any
 
 import pandas as pd
 
+from framework._paths import has_private_segment
 from framework.errors import DataNotFoundError
 from framework.project import find_settings_file
 from framework.settings import settings_read
@@ -48,7 +52,9 @@ class DataInfo:
         delimiter: For delimited text: comma, tab, semicolon, or space. None
             means it is guessed from the extension.
         locked: Whether the file's hash is checked against framework.db on read.
-        private: Whether the file is in a folder named ``private``.
+        private: Whether the file is in a private folder: one whose name
+            contains private, confidential, or sensitive, at any depth below
+            the project root.
         description: Shown when the data is read.
         name: The catalog name, when the file was found by name.
         extra: Any other fields of the catalog entry.
@@ -77,15 +83,33 @@ def _is_absolute(path: str) -> bool:
     return Path(path).is_absolute() or bool(re.match(r"^[A-Za-z]:[/\\]", path))
 
 
-def _build(path: str, base: Path, entry: dict[str, Any] | None, name: str | None) -> DataInfo:
-    full = Path(path) if _is_absolute(path) else base / path
+def _in_private_folder(path: Path, root: Path | None) -> bool:
+    """Whether any folder above ``path``, below the project root, is private.
+
+    R checks only the immediate folder, so it misses ``inputs/private/raw``.
+    """
+    folder = path.parent
+    if root is not None and folder.is_relative_to(root.resolve()):
+        folder = folder.relative_to(root.resolve())
+    return has_private_segment(folder)
+
+
+def _build(
+    path: str,
+    base: Path,
+    entry: dict[str, Any] | None,
+    name: str | None,
+    root: Path | None = None,
+) -> DataInfo:
+    expanded = Path(path).expanduser()
+    full = expanded if _is_absolute(str(expanded)) else base / expanded
     full = full.resolve()
     file_type, delimiter = type_from_extension(full)
     fields: dict[str, Any] = {
         "type": file_type,
         "delimiter": delimiter,
         "locked": False,
-        "private": full.parent.name == "private",
+        "private": _in_private_folder(full, root),
         "description": None,
     }
     extra: dict[str, Any] = {}
@@ -122,13 +146,35 @@ def catalog_names(data: Any, prefix: str = "") -> list[str]:
     return names
 
 
-def _lookup(name: str, data: Any) -> Any:
-    current = data
-    for part in name.split("."):
-        if not isinstance(current, dict) or current.get(part) is None:
+def catalog_locate(name: str, data: Any) -> tuple[dict[str, Any], str] | None:
+    """The mapping that holds a catalog name's value, and its key there.
+
+    Keys may contain dots, so each run of name parts is tried as one key:
+    nested keys first, then ``raw.survey:``-style mixed keys, then a flat
+    ``inputs.raw.survey:`` key.
+    """
+    parts = name.split(".")
+
+    def search(node: Any, start: int) -> tuple[dict[str, Any], str] | None:
+        if not isinstance(node, dict):
             return None
-        current = current[part]
-    return current
+        for end in range(start + 1, len(parts) + 1):
+            key = ".".join(parts[start:end])
+            if node.get(key) is None:
+                continue
+            if end == len(parts):
+                return node, key
+            found = search(node[key], end)
+            if found is not None:
+                return found
+        return None
+
+    return search(data, 0)
+
+
+def _lookup(name: str, data: Any) -> Any:
+    found = catalog_locate(name, data)
+    return None if found is None else found[0][found[1]]
 
 
 def _not_found(name: str, data: Any) -> DataNotFoundError:
@@ -153,24 +199,30 @@ def data_info(path: str) -> DataInfo:
     relative to the current folder (anything with a slash), or an absolute
     path. Catalog paths are relative to the project root.
 
+    Args:
+        path: A dot-notation catalog name, a relative path containing a slash, or an absolute
+            path.
+
+    Returns:
+        The file's path, type, and catalog fields.
+
     Raises:
-        DataNotFoundError: The name is not in the catalog.
+        DataNotFoundError: The name is not in the catalog, or its entry has no path.
     """
-    if _is_absolute(path):
-        return _build(path, Path.cwd(), None, None)
-    if "/" in path or "\\" in path:
-        return _build(path, Path.cwd(), None, None)
-
     settings_file = find_settings_file()
-    base = settings_file.parent if settings_file else Path.cwd()
+    root = settings_file.parent if settings_file else None
+    if _is_absolute(path) or "/" in path or "\\" in path:
+        return _build(path, Path.cwd(), None, None, root)
+
+    base = root or Path.cwd()
     data = settings_read(settings_file).get("data")
     entry = _lookup(path, data)
     if entry is None:
         raise _not_found(path, data)
     if isinstance(entry, str):
-        return _build(entry, base, None, path)
+        return _build(entry, base, None, path, root)
     if isinstance(entry, dict) and isinstance(entry.get("path"), str):
-        return _build(entry["path"], base, entry, path)
+        return _build(entry["path"], base, entry, path, root)
     raise DataNotFoundError(f"Catalog entry '{path}' has no path")
 
 

framework/cloud.py

@@ -413,7 +413,19 @@ def cloud_login(
 
 
 def cloud_logout(url: str | None = None) -> list[str]:
-    """Remove this machine's stored token for a server. Returns what was removed."""
+    """Remove this machine's stored token for a server. Returns what was removed.
+
+    Both the keyring entry and the token file are removed. For the default server, the legacy
+    keyring entry and ``~/.secrets/framework/token`` are removed too.
+
+    Args:
+        url: The server. Default: ``FW_CLOUD_URL``, then your saved default, then
+            https://framework.pub.
+
+    Returns:
+        A description of each keyring entry and the path of each file removed. The list is
+        empty when no token was stored.
+    """
     show_messages()
     server = cloud_server(url).url
     removed = []
@@ -436,7 +448,19 @@ def cloud_logout(url: str | None = None) -> list[str]:
 
 
 def cloud_status(url: str | None = None) -> bool:
-    """Report the server in use and whether this machine is connected to it."""
+    """Report the server in use and whether this machine is connected to it.
+
+    The server, where that setting came from, and the account are printed. When the project
+    publishes to a different server, that server is printed too.
+
+    Args:
+        url: The server. Default: ``FW_CLOUD_URL``, then your saved default, then
+            https://framework.pub.
+
+    Returns:
+        True when a token is stored and the server accepts it. False when no token is stored,
+        the server is unreachable, or the token is invalid.
+    """
     show_messages()
     server = cloud_server(url)
     inform(f"Server: {server.url} (from {server.source})")
@@ -488,6 +512,18 @@ def cloud_sync(direction: str = "auto") -> int:
     sends your local mirror, and ``"auto"`` picks the side that changed and
     stops when both did. The mirror is ``cloud-settings.yml`` in
     ``config_dir()``.
+
+    Args:
+        direction: One of "auto", "pull", or "push". Default: "auto". With "auto", a pull
+            happens when there is no local mirror or sync state yet.
+
+    Returns:
+        The settings revision after the sync.
+
+    Raises:
+        CloudError: When ``direction`` is not allowed, no token is stored, both sides changed
+            under "auto", a push has no local mirror or sync state, or the server rejects a
+            push.
     """
     show_messages()
     if direction not in ("auto", "pull", "push"):
@@ -662,7 +698,17 @@ def ledger_push() -> dict[str, int]:
 
 
 def ledger_list(name: str | None = None) -> pd.DataFrame:
-    """The project's cloud ledger, newest first."""
+    """The project's cloud ledger, newest first.
+
+    Args:
+        name: Only list entries for this catalog name. Default: every entry.
+
+    Returns:
+        A DataFrame with columns sequence, name, hash, size_bytes, and recorded_at.
+
+    Raises:
+        CloudError: When the project has no token, or the server request fails.
+    """
     columns = ["sequence", "name", "hash", "size_bytes", "recorded_at"]
     rows = [{key: entry.get(key) for key in columns} for entry in _ledger_entries(name)]
     return pd.DataFrame(rows, columns=columns)
@@ -672,6 +718,21 @@ def data_verify(name: str) -> bool:
     """Check a catalog file against framework.db and, if connected, the cloud ledger.
 
     Returns True when every record matches. A mismatch issues a warning.
+
+    The file's SHA-256 digest is compared with its framework.db record and, when the project
+    has a token, with the newest cloud ledger entry for the name. A missing record, an
+    unreachable ledger, or a name with no ledger entries is reported but does not count as a
+    mismatch.
+
+    Args:
+        name: A catalog name or file path, as accepted by ``data_info()``.
+
+    Returns:
+        True when every available record matches the file, otherwise False.
+
+    Raises:
+        DataNotFoundError: When the name is not in the catalog.
+        FrameworkError: When the file does not exist.
     """
     import warnings
 
@@ -743,10 +804,10 @@ def cloud_publish(
     slug: str | bool | None = None,
     title: str | None = None,
 ) -> str:
-    """Publish rendered HTML (or a .qmd to render) to the project's cloud server.
+    """Publish rendered HTML (or a .qmd or .ipynb to render) to the project's cloud server.
 
     Accepts a self-contained ``.html``, an ``.html`` with a sibling
-    ``<name>_files/`` folder, a render output folder, or a ``.qmd``. Each
+    ``<name>_files/`` folder, a render output folder, or a ``.qmd`` or ``.ipynb``. Each
     publish adds a version. ``slug`` names the document and turns on its
     readable URL (``True`` uses the derived name, ``False`` turns it off).
     """
@@ -766,7 +827,7 @@ def cloud_publish(
             if not pages:
                 raise CloudError(f"No HTML file found at the top of {source}")
             entrypoint = "index.html" if "index.html" in pages else pages[0]
-        elif suffix == ".qmd":
+        elif suffix in (".qmd", ".ipynb"):
             quarto = shutil.which("quarto")
             if quarto is None:
                 raise CloudError("Rendering requires the quarto command on your PATH.")
@@ -803,8 +864,8 @@ def cloud_publish(
                 html = source
         else:
             raise CloudError(
-                "Framework Cloud publishing takes rendered HTML, a render folder, or a .qmd "
-                f"to render. Got: {suffix or source.name}"
+                "Framework Cloud publishing takes rendered HTML, a render folder, or a .qmd or "
+                f".ipynb to render. Got: {suffix or source.name}"
             )
 
         readable = None if slug is None else slug is not False

framework/config_home.py

@@ -150,7 +150,16 @@ def _save_global_settings(settings: dict[str, Any]) -> None:
 
 
 def project_register(path: str | Path) -> int:
-    """Add a project to the registry in the global settings. Returns its id."""
+    """Add a project to the registry in the global settings. Returns its id.
+
+    Args:
+        path: The project folder. It is expanded and resolved to an absolute path before it is
+            stored.
+
+    Returns:
+        The project's id. A project already in the registry keeps its id and is not added
+        again.
+    """
     settings = global_settings()
     projects = settings.get("projects") or []
     resolved = str(Path(path).expanduser().resolve())
@@ -165,7 +174,15 @@ def project_register(path: str | Path) -> int:
 
 
 def project_unregister(project: int | str | Path) -> bool:
-    """Remove a project from the registry by id or path. Returns whether it was there."""
+    """Remove a project from the registry by id or path. Returns whether it was there.
+
+    Args:
+        project: The project's id as an integer, or its folder as a path or string. A string is
+            always read as a path, so pass ids as integers.
+
+    Returns:
+        True when a project was removed, False when none matched.
+    """
     settings = global_settings()
     projects = settings.get("projects") or []
     if isinstance(project, int):