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

framework/_assets/schema/spec.v1.json

@@ -0,0 +1,604 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://framework.pub/schema/spec/v1.json",
+  "title": "Framework project spec (resolved)",
+  "description": "A complete project spec, produced by spec_resolve() and accepted by project_create().",
+  "type": "object",
+  "properties": {
+    "spec_version": {
+      "const": 1
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "project",
+        "project_sensitive",
+        "course",
+        "presentation",
+        "bare"
+      ]
+    },
+    "language": {
+      "type": "string",
+      "enum": [
+        "r",
+        "python",
+        "stata"
+      ],
+      "description": "Primary language. The R package builds r, the Python package builds python, and fw builds stata (scaffolding only). A layers file with no language means r."
+    },
+    "author": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "email": {
+          "type": "string"
+        },
+        "affiliation": {
+          "type": "string"
+        },
+        "orcid": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        },
+        "affiliations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
+              "department": {
+                "type": "string"
+              },
+              "city": {
+                "type": "string"
+              },
+              "country": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "name"
+            ]
+          }
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "email",
+        "affiliation"
+      ]
+    },
+    "directories": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$"
+      },
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9_]*$"
+      }
+    },
+    "extra_directories": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/extra_directory"
+      },
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9_]*$"
+      }
+    },
+    "render_dirs": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$"
+      },
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9_]*$"
+      }
+    },
+    "packages": {
+      "type": "object",
+      "properties": {
+        "use_renv": {
+          "type": "boolean"
+        },
+        "default_packages": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/package"
+          },
+          "description": "Package name -> spec. JSON object key order is not kept (Postgres JSONB sorts keys).",
+          "propertyNames": {
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+          }
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "default_packages"
+      ]
+    },
+    "git": {
+      "type": "object",
+      "properties": {
+        "use_git": {
+          "type": "boolean"
+        },
+        "hooks": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "boolean"
+          },
+          "propertyNames": {
+            "pattern": "^[a-z][a-z0-9_]*$"
+          }
+        },
+        "gitignore_content": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "use_git",
+        "hooks",
+        "gitignore_content"
+      ]
+    },
+    "ai": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "assistants": {
+          "type": "object",
+          "propertyNames": {
+            "enum": [
+              "claude",
+              "codex",
+              "copilot"
+            ]
+          },
+          "additionalProperties": {
+            "type": "boolean"
+          },
+          "description": "Assistant -> true to include. In a layer, false or null removes it."
+        },
+        "agents_md": {
+          "type": "string",
+          "enum": [
+            "stub",
+            "none"
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "enabled",
+        "assistants",
+        "agents_md"
+      ]
+    },
+    "scaffold": {
+      "type": "object",
+      "properties": {
+        "seed_on_scaffold": {
+          "type": "boolean"
+        },
+        "seed": {
+          "type": "string"
+        },
+        "set_theme_on_scaffold": {
+          "type": "boolean"
+        },
+        "ggplot_theme": {
+          "type": "string"
+        },
+        "source_all_functions": {
+          "type": "boolean"
+        },
+        "notebook_format": {
+          "type": "string",
+          "enum": [
+            "quarto",
+            "rmarkdown",
+            "jupyter"
+          ]
+        },
+        "ide": {
+          "type": "string",
+          "enum": [
+            "vscode",
+            "positron",
+            "rstudio",
+            "both",
+            "none"
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "seed_on_scaffold",
+        "seed"
+      ]
+    },
+    "quarto": {
+      "type": "object",
+      "description": "Passed through to _quarto.yml generation"
+    },
+    "connections": {
+      "type": "object",
+      "properties": {
+        "default_database": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "default_storage_bucket": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "databases": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/connection"
+          },
+          "propertyNames": {
+            "pattern": "^[a-z][a-z0-9_]*$"
+          }
+        },
+        "storage_buckets": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/connection"
+          },
+          "propertyNames": {
+            "pattern": "^[a-z][a-z0-9_]*$"
+          }
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "databases",
+        "storage_buckets"
+      ]
+    },
+    "security": {
+      "type": "object",
+      "properties": {
+        "sensitive": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "sensitive"
+      ]
+    },
+    "env": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Variables written to .env. Secret-looking names must be empty.",
+      "propertyNames": {
+        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+      }
+    },
+    "data_hooks": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^[^:]+\\.(R|py)::[A-Za-z_.][A-Za-z0-9._]*$"
+      },
+      "description": "Directory key -> 'path/to/file.R::function'",
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9_]*$"
+      }
+    },
+    "files": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/file"
+      },
+      "propertyNames": {
+        "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$"
+      }
+    },
+    "skills": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/skill"
+      },
+      "propertyNames": {
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      }
+    },
+    "source": {
+      "type": "object",
+      "properties": {
+        "origin": {
+          "type": "string",
+          "enum": [
+            "cloud",
+            "cli",
+            "r",
+            "python"
+          ]
+        },
+        "fragments": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "base",
+                  "facet",
+                  "blueprint"
+                ]
+              },
+              "key": {
+                "type": "string"
+              },
+              "version": {
+                "type": "integer"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "kind",
+              "key"
+            ]
+          }
+        },
+        "blueprint": {
+          "type": "object",
+          "properties": {
+            "key": {
+              "type": "string"
+            },
+            "version": {
+              "type": "integer"
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "key"
+          ]
+        },
+        "study_plan": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "version": {
+              "type": "integer"
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "id"
+          ]
+        },
+        "framework_version": {
+          "type": "string",
+          "description": "Version of the R or Python package that created the project"
+        },
+        "fw_version": {
+          "type": "string",
+          "description": "Version of fw that created the project (Stata scaffolding)"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "origin"
+      ]
+    }
+  },
+  "additionalProperties": false,
+  "required": [
+    "spec_version",
+    "name",
+    "type",
+    "language",
+    "author",
+    "directories",
+    "extra_directories",
+    "git",
+    "ai",
+    "security",
+    "env",
+    "data_hooks",
+    "files",
+    "skills"
+  ],
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "language": {
+            "enum": [
+              "r",
+              "python"
+            ]
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "render_dirs",
+          "packages",
+          "scaffold",
+          "connections"
+        ]
+      }
+    }
+  ],
+  "definitions": {
+    "package": {
+      "type": "object",
+      "properties": {
+        "source": {
+          "type": "string",
+          "enum": [
+            "cran",
+            "github",
+            "bioc",
+            "pypi"
+          ]
+        },
+        "version": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "repo": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "ref": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "auto_attach": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "source",
+        "auto_attach"
+      ]
+    },
+    "extra_directory": {
+      "type": "object",
+      "properties": {
+        "label": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "path"
+      ]
+    },
+    "file": {
+      "type": "object",
+      "properties": {
+        "content": {
+          "type": "string"
+        },
+        "template": {
+          "type": "boolean",
+          "description": "Replace {{project_name}}, {{author}}, {{author_email}}, {{affiliation}}, and {{date}}"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "content"
+      ]
+    },
+    "skill": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "package": {
+              "const": true
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "package"
+          ]
+        },
+        {
+          "type": "object",
+          "properties": {
+            "content": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Full SKILL.md text, including frontmatter"
+            },
+            "files": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              },
+              "propertyNames": {
+                "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$"
+              }
+            }
+          },
+          "additionalProperties": false,
+          "required": [
+            "content"
+          ]
+        }
+      ]
+    },
+    "connection": {
+      "type": "object",
+      "properties": {
+        "driver": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true,
+      "required": [
+        "driver"
+      ]
+    }
+  }
+}

framework/_log.py

@@ -0,0 +1,29 @@
+"""Framework's progress messages.
+
+Messages go to the ``framework`` logger. A library stays quiet unless the
+caller configures logging. ``scaffold()`` and project creation call
+``show_messages()`` so interactive work shows them, as R's messages do.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+logger = logging.getLogger("framework")
+logger.addHandler(logging.NullHandler())
+
+
+def inform(message: str) -> None:
+    logger.info(message)
+
+
+def show_messages() -> None:
+    """Print Framework's messages to stderr, once per process."""
+    if any(getattr(handler, "_framework", False) for handler in logger.handlers):
+        return
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    handler._framework = True  # type: ignore[attr-defined]
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)

framework/_paths.py

@@ -0,0 +1,45 @@
+"""Resolving project folders from the settings."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from framework.project import project_root
+
+
+def relative_to_root(path: Path, root: Path) -> str:
+    """``path`` relative to the project root when it is inside it, else absolute."""
+    resolved = path.resolve()
+    try:
+        return resolved.relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return resolved.as_posix()
+
+
+def in_root(path: str | Path, root: Path) -> Path:
+    """A settings path, which is relative to the project root unless absolute."""
+    candidate = Path(path).expanduser()
+    return candidate if candidate.is_absolute() else root / candidate
+
+
+def directory(config: dict[str, Any], key: str, default: str, root: Path | None = None) -> Path:
+    """A folder from ``directories`` in the settings, or ``default``, under the root."""
+    root = root or project_root()
+    directories = config.get("directories")
+    value = directories.get(key) if isinstance(directories, dict) else None
+    return in_root(value if isinstance(value, str) and value else default, root)
+
+
+def output_directory(config: dict[str, Any], kind: str, public: bool) -> Path:
+    """Where outputs of one kind (tables, figures, ...) go.
+
+    Sensitive projects split outputs into public and private folders; other
+    projects use one folder per kind. This follows R's ``save_*()`` functions.
+    """
+    if config.get("project_type") == "project_sensitive":
+        key = f"outputs_{'public' if public else 'private'}_{kind}"
+    else:
+        key = f"outputs_{kind}"
+    default = f"outputs/public/{kind}" if public else f"outputs/{kind}"
+    return directory(config, key, default)