devstuff 1.13.1__py3-none-any.whl

dev_setup/functions_catalog.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import copy
+import re
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from dev_setup.catalog import CONFIG_DIR, CatalogError
+
+USER_CATALOG_PATH = CONFIG_DIR / "functions.yaml"
+BUNDLED_CATALOG = "functions.yaml"
+
+VERSION = 1
+VALID_KEY = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+VALID_PARAM_NAME = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+TYPES = {"script", "shell-eval"}
+REGISTER_MODES = {"bashrc", "eval"}
+
+SUPPORTED_FIELDS = {
+    "name",
+    "description",
+    "category",
+    "type",
+    "register",
+    "params",
+    "script",
+    "help_cmd",
+    "docs_url",
+}
+SUPPORTED_PARAM_FIELDS = {"name", "description", "required", "default"}
+
+
+def bundled_catalog_path() -> str:
+    return f"dev_setup/{BUNDLED_CATALOG}"
+
+
+def load_catalog_file(path: Path, *, required: bool = False) -> dict[str, dict[str, Any]]:
+    if not path.exists():
+        if required:
+            raise CatalogError(f"Catalog file not found: {path}")
+        return {}
+
+    try:
+        raw = yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError as exc:
+        raise CatalogError(f"Invalid YAML in {path}: {exc}") from exc
+
+    return validate_catalog(raw, source=path)
+
+
+def validate_catalog(raw: Any, *, source: Path | str = "<catalog>") -> dict[str, dict[str, Any]]:
+    if not isinstance(raw, dict):
+        raise CatalogError(f"{source}: catalog must be a mapping")
+    if raw.get("version") != VERSION:
+        raise CatalogError(f"{source}: version must be {VERSION}")
+
+    functions = raw.get("functions")
+    if functions is None:
+        return {}
+    if not isinstance(functions, dict):
+        raise CatalogError(f"{source}: functions must be a mapping")
+
+    validated: dict[str, dict[str, Any]] = {}
+    for key, data in functions.items():
+        if not isinstance(key, str) or not VALID_KEY.match(key):
+            raise CatalogError(f"{source}: invalid function key {key!r}")
+        if not isinstance(data, dict):
+            raise CatalogError(f"{source}: function {key!r} must be a mapping")
+
+        unknown = sorted(set(data) - SUPPORTED_FIELDS)
+        if unknown:
+            fields = ", ".join(unknown)
+            raise CatalogError(f"{source}: function {key!r} has unknown field(s): {fields}")
+
+        item = copy.deepcopy(data)
+        item.setdefault("name", key)
+        item.setdefault("description", "")
+        item.setdefault("category", "custom")
+
+        fn_type = item.get("type")
+        if fn_type not in TYPES:
+            raise CatalogError(
+                f"{source}: function {key!r} type must be one of {sorted(TYPES)}, got {fn_type!r}"
+            )
+
+        if not item.get("script"):
+            raise CatalogError(f"{source}: function {key!r} must set 'script'")
+
+        register = item.get("register")
+        if fn_type == "shell-eval":
+            if register is None:
+                item["register"] = "bashrc"
+            elif register not in REGISTER_MODES:
+                raise CatalogError(
+                    f"{source}: function {key!r} register must be one of "
+                    f"{sorted(REGISTER_MODES)}, got {register!r}"
+                )
+        elif register is not None:
+            raise CatalogError(
+                f"{source}: function {key!r} sets 'register' but type is {fn_type!r} "
+                "('register' only applies to type 'shell-eval')"
+            )
+
+        item["params"] = _validate_params(item.get("params"), key=key, source=source)
+
+        validated[key] = item
+
+    return validated
+
+
+def _validate_params(params: Any, *, key: str, source: Path | str) -> list[dict[str, Any]]:
+    if params is None:
+        return []
+    if not isinstance(params, list):
+        raise CatalogError(f"{source}: function {key!r} params must be a list")
+
+    validated: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for i, param in enumerate(params):
+        if not isinstance(param, dict):
+            raise CatalogError(f"{source}: function {key!r} params[{i}] must be a mapping")
+
+        unknown = sorted(set(param) - SUPPORTED_PARAM_FIELDS)
+        if unknown:
+            fields = ", ".join(unknown)
+            raise CatalogError(
+                f"{source}: function {key!r} params[{i}] has unknown field(s): {fields}"
+            )
+
+        name = param.get("name")
+        if not isinstance(name, str) or not VALID_PARAM_NAME.match(name):
+            raise CatalogError(
+                f"{source}: function {key!r} params[{i}] name must be a valid shell "
+                f"identifier, got {name!r}"
+            )
+        if name in seen:
+            raise CatalogError(f"{source}: function {key!r} has duplicate param name {name!r}")
+        seen.add(name)
+
+        item = copy.deepcopy(param)
+        item.setdefault("description", "")
+        item.setdefault("required", True)
+        item.setdefault("default", "")
+        if not isinstance(item["required"], bool):
+            raise CatalogError(f"{source}: function {key!r} params[{i}] required must be a bool")
+        validated.append(item)
+
+    return validated
+
+
+def catalog_document(functions: dict[str, dict[str, Any]]) -> dict[str, Any]:
+    return {"version": VERSION, "functions": functions}
+
+
+def read_user_catalog() -> dict[str, dict[str, Any]]:
+    return load_catalog_file(USER_CATALOG_PATH)
+
+
+def write_user_catalog(functions: dict[str, dict[str, Any]]) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    USER_CATALOG_PATH.write_text(_dump(catalog_document(functions)))
+
+
+def load_bundled_catalog() -> dict[str, dict[str, Any]]:
+    resource = resources.files("dev_setup").joinpath(BUNDLED_CATALOG)
+    try:
+        raw = yaml.safe_load(resource.read_text()) or {}
+    except FileNotFoundError as exc:
+        raise CatalogError(f"Catalog file not found: {bundled_catalog_path()}") from exc
+    except yaml.YAMLError as exc:
+        raise CatalogError(f"Invalid YAML in {bundled_catalog_path()}: {exc}") from exc
+    return validate_catalog(raw, source=bundled_catalog_path())
+
+
+def load_effective_catalog() -> tuple[
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+]:
+    bundled = load_bundled_catalog()
+    user = read_user_catalog()
+    effective = merge_catalogs(bundled, user)
+    return effective, bundled, user
+
+
+def merge_catalogs(
+    bundled: dict[str, dict[str, Any]],
+    user: dict[str, dict[str, Any]],
+) -> dict[str, dict[str, Any]]:
+    merged = copy.deepcopy(bundled)
+    for key, data in user.items():
+        merged[key] = copy.deepcopy(data)
+    return merged
+
+
+def save_user_function(key: str, data: dict[str, Any]) -> None:
+    validate_catalog(catalog_document({key: data}), source=USER_CATALOG_PATH)
+    user = read_user_catalog()
+    user[key] = copy.deepcopy(data)
+    write_user_catalog(user)
+
+
+def delete_user_function(key: str) -> bool:
+    user = read_user_catalog()
+    if key not in user:
+        return False
+    del user[key]
+    write_user_catalog(user)
+    return True
+
+
+def _dump(data: dict[str, Any]) -> str:
+    return yaml.safe_dump(data, sort_keys=False, default_flow_style=False)

dev_setup/functions_registry.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+
+from dev_setup import functions_catalog as catalog
+
+# field name -> catalog YAML key (only where they differ)
+_YAML_KEY: dict[str, str] = {}
+_NON_CATALOG = ("key", "builtin")
+
+
+@dataclass
+class FunctionParam:
+    name: str = ""
+    description: str = ""
+    required: bool = True
+    default: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict) -> FunctionParam:
+        return cls(
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            required=data.get("required", True),
+            default=data.get("default", ""),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "required": self.required,
+            "default": self.default,
+        }
+
+
+@dataclass
+class FunctionDef:
+    key: str = ""
+    name: str = ""
+    description: str = ""
+    category: str = "custom"
+    type: str = "script"
+    register: str = ""
+    params: list[FunctionParam] = field(default_factory=list)
+    script: str = ""
+    help_cmd: str = ""
+    docs_url: str = ""
+    builtin: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            self.name = self.key
+
+    @classmethod
+    def from_dict(cls, data: dict, key: str) -> FunctionDef:
+        kwargs = {
+            f.name: data.get(_YAML_KEY.get(f.name, f.name), f.default)
+            for f in fields(cls)
+            if f.name not in _NON_CATALOG and f.name != "params"
+        }
+        kwargs["params"] = [FunctionParam.from_dict(p) for p in data.get("params", [])]
+        return cls(key=key, **kwargs)
+
+    def to_dict(self) -> dict:
+        d: dict = {
+            "name": self.name,
+            "description": self.description,
+            "category": self.category,
+            "type": self.type,
+        }
+        if self.register:
+            d["register"] = self.register
+        if self.params:
+            d["params"] = [p.to_dict() for p in self.params]
+        for f in ("script", "help_cmd", "docs_url"):
+            val = getattr(self, f)
+            if val:
+                d[f] = val
+        return d
+
+    def save(self) -> None:
+        catalog.save_user_function(self.key, self.to_dict())
+
+
+_registry: dict[str, FunctionDef] = {}
+_order: list[str] = []
+_initialized = False
+
+
+def _register(fn: FunctionDef) -> None:
+    if fn.key not in _registry:
+        _registry[fn.key] = fn
+        _order.append(fn.key)
+    else:
+        _registry[fn.key] = fn
+
+
+def _load_builtins() -> None:
+    effective, bundled, user = catalog.load_effective_catalog()
+    for key, data in effective.items():
+        fn = FunctionDef.from_dict(data, key=key)
+        fn.builtin = key in bundled and key not in user
+        _register(fn)
+
+
+def init() -> None:
+    global _initialized
+    if _initialized:
+        return
+    _initialized = True
+    _load_builtins()
+
+
+def reload() -> None:
+    global _initialized
+    _registry.clear()
+    _order.clear()
+    _initialized = False
+    init()
+
+
+def get(key: str) -> FunctionDef | None:
+    init()
+    return _registry.get(key)
+
+
+def all_functions() -> list[FunctionDef]:
+    init()
+    return [_registry[k] for k in _order if k in _registry]
+
+
+def exists(key: str) -> bool:
+    init()
+    return key in _registry
+
+
+def register(fn: FunctionDef) -> None:
+    """Register (or replace) a function in the live registry."""
+    init()
+    _register(fn)
+
+
+def deregister(key: str) -> None:
+    """Remove a function from the live registry by key."""
+    init()
+    _registry.pop(key, None)
+    if key in _order:
+        _order.remove(key)