dirigent-cli 0.9.0__py3-none-any.whl

dirigent_cli/params.py

@@ -0,0 +1,389 @@
+"""Building a run's parameters from the command line, against the pipeline's own schema.
+
+Precedence is schema defaults, then ``-P`` files in the order given, then ``-p`` flags in
+the order given. Objects deep-merge; arrays and scalars replace, except that a bracketed
+index in a ``-p`` key sets one element of an array in place.
+"""
+
+import re
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any, Final, cast
+
+import yaml
+
+from dirigent_common import JsonMap
+from dirigent_core.documents import safe_load
+
+TRUE_WORDS: Final = frozenset({"true", "yes", "y", "on", "1"})
+FALSE_WORDS: Final = frozenset({"false", "no", "n", "off", "0"})
+
+STRUCTURED: Final = frozenset({"object", "array"})
+
+#: What ``[]`` addresses: one past the last element, wherever the array happens to end.
+APPEND: Final = -1
+
+#: One dotted segment: a name, then any number of ``[index]`` or ``[]`` brackets.
+SEGMENT: Final = re.compile(r"(?P<name>[^\[\]]*)(?P<indices>(?:\[[^\[\]]*\])*)")
+
+INDEX: Final = re.compile(r"\[([^\[\]]*)\]")
+
+#: A step of a parsed key: an object key, an array index, or ``APPEND``.
+type Step = str | int
+
+
+class ParamError(Exception):
+    """A parameter could not be read, addressed, or coerced; the message says which."""
+
+
+def parse_pair(pair: str) -> tuple[str, str]:
+    """Split one ``key=value`` argument, refusing anything that is not one."""
+    if "=" not in pair:
+        raise ParamError(f"-p expects key=value, not {pair!r}")
+    key, _, value = pair.partition("=")
+    if not key:
+        raise ParamError(f"-p expects key=value, not {pair!r}")
+    return key, value
+
+
+def split_key(key: str) -> list[Step]:
+    """Split a key into its path of object keys and array indices."""
+    if not key:
+        raise ParamError(f"-p {key}: a dotted key names each level, so it may not have an empty segment")
+    path: list[Step] = []
+    for segment in key.split("."):
+        match = SEGMENT.fullmatch(segment)
+        if match is None:
+            raise ParamError(f"-p {key}: {segment!r} is not a name followed by [index] brackets")
+        name = match["name"]
+        if not name:
+            raise ParamError(f"-p {key}: a dotted key names each level, so it may not have an empty segment")
+        if name.isdigit():
+            raise ParamError(
+                f"-p {key}: a dotted path cannot tell the index {name!r} from an object key named {name!r}. "
+                f"Address an element with brackets instead ({path[-1] if path else 'name'}[{name}]=...)"
+            )
+        path.append(name)
+        path.extend(_index(raw, key) for raw in INDEX.findall(match["indices"]))
+    return path
+
+
+def _index(raw: str, key: str) -> int:
+    """Read what one pair of brackets addresses: an element, or the end of the array."""
+    if not raw:
+        return APPEND
+    if not raw.isdigit():
+        if raw.lstrip("-").isdigit():
+            raise ParamError(f"-p {key}: an index counts from the start of the array, so {raw!r} is not one")
+        raise ParamError(f"-p {key}: an index is a whole number or nothing at all, not {raw!r}")
+    return int(raw)
+
+
+def render_path(path: Sequence[Step]) -> str:
+    """Render a parsed path the way it is written on the command line."""
+    written = ""
+    for step in path:
+        if isinstance(step, str):
+            written = f"{written}.{step}" if written else step
+        else:
+            written += "[]" if step == APPEND else f"[{step}]"
+    return written
+
+
+def _article(word: str) -> str:
+    """Prefix a schema's word with the article that reads."""
+    return f"an {word}" if word[:1] in "aeiou" else f"a {word}"
+
+
+def _holds(value: Any) -> str:
+    """Name what a value already at a path is, for a message about addressing it wrongly."""
+    match value:
+        case bool():
+            return "a boolean"
+        case dict():
+            return "an object"
+        case list():
+            return "an array"
+        case int() | float():
+            return "a number"
+        case str():
+            return "a string"
+        case _:
+            return "a scalar"
+
+
+def read_params_file(path: Path) -> JsonMap:
+    """Read a whole parameter payload from a YAML or JSON file."""
+    try:
+        loaded = safe_load(path.read_text())
+    except (OSError, yaml.YAMLError) as error:
+        raise ParamError(f"{path} could not be read: {error}") from error
+    if loaded is None:
+        return {}
+    if not isinstance(loaded, dict):
+        raise ParamError(f"{path} should hold a mapping of parameters, not {type(loaded).__name__}")
+    return cast("JsonMap", loaded)
+
+
+def _schema_at(schema: JsonMap, path: Sequence[Step], where: str) -> JsonMap | None:
+    """Resolve the subschema a path addresses, or say the path is not declared.
+
+    ``where`` names the channel a value arrived on -- a flag or a file -- so both are refused
+    by this one walk rather than by two rules that can drift apart.
+    """
+    current: JsonMap | None = schema
+    walked: list[Step] = []
+    for step in path:
+        if current is None:
+            return None
+        declared = _type_of(current)
+        if isinstance(step, int):
+            if declared is not None and declared != "array":
+                raise ParamError(
+                    f"{where}: the schema calls {render_path(walked)!r} {_article(declared)}, "
+                    f"so it takes a key, not an index"
+                )
+            items: object = current.get("items")
+            current = cast("JsonMap", items) if isinstance(items, dict) else None
+            walked.append(step)
+            continue
+        if declared == "array":
+            raise ParamError(
+                f"{where}: the schema calls {render_path(walked)!r} an array, "
+                f"so it takes an index, not the key {step!r}"
+            )
+        raw: object = current.get("properties")
+        properties = cast("JsonMap", raw) if isinstance(raw, dict) else None
+        found = properties.get(step) if properties is not None else None
+        if found is None:
+            if _is_open(current, properties):
+                return None
+            location = render_path([*walked, step])
+            known = _known(current)
+            raise ParamError(f"{where}: the pipeline declares no parameter {location!r} ({known})")
+        current = cast("JsonMap", found)
+        walked.append(step)
+    return current
+
+
+def _is_open(schema: JsonMap, properties: JsonMap | None) -> bool:
+    """Report whether a schema level accepts a name it does not list.
+
+    Stricter than JSON Schema, which allows extra properties unless told otherwise: a
+    level that lists any property is treated as closed unless it also says
+    ``additionalProperties``.
+    """
+    if not properties:
+        return True
+    extra = schema.get("additionalProperties")
+    return extra is True or isinstance(extra, dict)
+
+
+def _known(schema: JsonMap) -> str:
+    """Render what a schema level does declare, for an error naming an unknown path."""
+    properties: object = schema.get("properties")
+    if not isinstance(properties, dict):
+        return "it declares no parameters"
+    names = ", ".join(sorted(cast("Mapping[str, object]", properties)))
+    return f"it declares {names}" if names else "it declares no parameters"
+
+
+def coerce(value: str, schema: JsonMap | None, key: str) -> Any:
+    """Turn one command-line string into the value the schema says belongs at that path."""
+    declared = _type_of(schema)
+    if declared in STRUCTURED:
+        return _structured(value, declared, key)
+    match declared:
+        case "integer":
+            return _integer(value, key)
+        case "number":
+            return _number(value, key)
+        case "boolean":
+            return _boolean(value, key)
+        case "string":
+            return _checked_enum(value, schema, key)
+        case _:
+            parsed: Any = safe_load(value) if value else value
+            return _checked_enum(parsed, schema, key)
+
+
+def _type_of(schema: JsonMap | None) -> str | None:
+    """Read the type a subschema declares, tolerating the list form, ``anyOf`` and enum-only.
+
+    An optional field is spelled ``anyOf: [{type: string}, {type: null}]`` by the generator
+    every connection kind's schema comes from, and a branch left unread there falls through to
+    YAML, where ``#ops`` is a comment rather than a channel.
+    """
+    if schema is None:
+        return None
+    declared = schema.get("type")
+    if isinstance(declared, str):
+        return declared
+    if isinstance(declared, list):
+        strings = [item for item in cast("list[object]", declared) if isinstance(item, str) and item != "null"]
+        return strings[0] if strings else None
+    if isinstance(schema.get("anyOf"), list):
+        for branch in cast("list[object]", schema["anyOf"]):
+            if not isinstance(branch, dict):
+                continue
+            found = _type_of(cast("JsonMap", branch))
+            if found is not None and found != "null":
+                return found
+    if isinstance(schema.get("enum"), list):
+        members = cast("list[object]", schema["enum"])
+        return "string" if all(isinstance(item, str) for item in members) else None
+    return None
+
+
+def _structured(value: str, declared: str, key: str) -> Any:
+    """Read an inline object or array, in either JSON or YAML."""
+    try:
+        parsed = safe_load(value)
+    except yaml.YAMLError as error:
+        raise ParamError(f"-p {key}: {value!r} is not valid JSON or YAML ({error})") from error
+    if declared == "array" and not isinstance(parsed, list):
+        raise ParamError(f"-p {key}: this parameter is an array, and {value!r} is not one")
+    if declared == "object" and not isinstance(parsed, dict):
+        raise ParamError(f"-p {key}: this parameter is an object, and {value!r} is not one")
+    return cast("Any", parsed)
+
+
+def _integer(value: str, key: str) -> int:
+    """Read an integer, refusing anything that only looks like one."""
+    try:
+        return int(value)
+    except ValueError as error:
+        raise ParamError(f"-p {key}: this parameter is an integer, and {value!r} is not one") from error
+
+
+def _number(value: str, key: str) -> float:
+    """Read a number."""
+    try:
+        return float(value)
+    except ValueError as error:
+        raise ParamError(f"-p {key}: this parameter is a number, and {value!r} is not one") from error
+
+
+def _boolean(value: str, key: str) -> bool:
+    """Read a boolean from the words a person actually types."""
+    lowered = value.strip().lower()
+    if lowered in TRUE_WORDS:
+        return True
+    if lowered in FALSE_WORDS:
+        return False
+    raise ParamError(f"-p {key}: this parameter is a boolean; write true or false, not {value!r}")
+
+
+def _checked_enum(value: Any, schema: JsonMap | None, key: str) -> Any:
+    """Refuse a value the schema's enum does not list, naming what it does list."""
+    if schema is None:
+        return value
+    members = schema.get("enum")
+    if isinstance(members, list) and value not in members:
+        allowed = ", ".join(repr(item) for item in cast("list[object]", members))
+        raise ParamError(f"-p {key}: {value!r} is not one of {allowed}")
+    return value
+
+
+def assign(target: JsonMap, path: Sequence[Step], value: Any, key: str) -> None:
+    """Set a value at a parsed path, creating the objects and arrays it passes through."""
+    container: Any = target
+    for position, step in enumerate(path[:-1]):
+        container = _descend(
+            container, step, path[: position + 1], wants_list=isinstance(path[position + 1], int), key=key
+        )
+    _read(container, path[-1], path, key)
+    _put(container, path[-1], value)
+
+
+def _descend(container: Any, step: Step, walked: Sequence[Step], *, wants_list: bool, key: str) -> Any:
+    """Read one step further in, creating the container there when nothing is yet."""
+    existing = _read(container, step, walked, key)
+    if existing is None:
+        fresh: Any = [] if wants_list else {}
+        _put(container, step, fresh)
+        return fresh
+    if not _fits(existing, wants_list=wants_list):
+        wanted = "an array" if wants_list else "an object"
+        raise ParamError(f"-p {key}: {render_path(walked)!r} holds {_holds(existing)}, not {wanted}")
+    return existing
+
+
+def _fits(value: Any, *, wants_list: bool) -> bool:
+    """Report whether a value already at a path is the container the next step needs."""
+    return isinstance(value, dict | list) and isinstance(value, list) == wants_list
+
+
+def _read(container: Any, step: Step, walked: Sequence[Step], key: str) -> Any:
+    """Read what is at one step, refusing a step the container cannot take."""
+    parent = render_path(walked[:-1])
+    if isinstance(step, str):
+        if isinstance(container, list):
+            raise ParamError(f"-p {key}: {parent!r} holds an array, so {step!r} is not a key it takes")
+        keys: JsonMap = container
+        return keys.get(step)
+    if isinstance(container, dict):
+        raise ParamError(f"-p {key}: {parent!r} holds an object, so [{step}] is not an element it takes")
+    elements: list[Any] = container
+    if step == APPEND or step == len(elements):
+        return None
+    if step > len(elements):
+        raise ParamError(
+            f"-p {key}: {parent!r} holds {_count(len(elements))}, so [{step}] would leave a gap; "
+            f"the next element is [{len(elements)}], which [] also writes"
+        )
+    return elements[step]
+
+
+def _count(total: int) -> str:
+    """Say how many elements an array holds."""
+    return "1 element" if total == 1 else f"{total} elements"
+
+
+def _put(container: Any, step: Step, value: Any) -> None:
+    """Write a value at one step, appending when the index is the end of the array."""
+    if isinstance(step, str):
+        cast("JsonMap", container)[step] = value
+        return
+    elements = cast("list[Any]", container)
+    if step == APPEND or step == len(elements):
+        elements.append(value)
+    else:
+        elements[step] = value
+
+
+def deep_merge(base: JsonMap, incoming: Mapping[str, Any]) -> JsonMap:
+    """Merge one mapping into another: objects merge, everything else replaces."""
+    merged = dict(base)
+    for key, value in incoming.items():
+        existing = merged.get(key)
+        if isinstance(existing, dict) and isinstance(value, dict):
+            merged[key] = deep_merge(cast("JsonMap", existing), cast("Mapping[str, Any]", value))
+        else:
+            merged[key] = value
+    return merged
+
+
+def build_params(
+    schema: JsonMap,
+    *,
+    pairs: Sequence[str] = (),
+    files: Sequence[Path] = (),
+) -> JsonMap:
+    """Build one parameter object from files and flags, coerced against the pipeline's schema.
+
+    A name the schema does not declare is refused whichever channel it arrived on, so a typo
+    in a file fails here rather than being stored and ignored.
+    """
+    params: JsonMap = {}
+    for path in files:
+        payload = read_params_file(path)
+        for name in payload:
+            _schema_at(schema, [name], f"params file {path}")
+        params = deep_merge(params, payload)
+    for pair in pairs:
+        key, raw = parse_pair(pair)
+        parts = split_key(key)
+        subschema = _schema_at(schema, parts, f"-p {key}")
+        assign(params, parts, coerce(raw, subschema, key), key)
+    return params

dirigent_cli/profiles.py

@@ -0,0 +1,221 @@
+"""Profiles: which server the CLI talks to, and how it gets a token for it.
+
+A profile is client-side addressing only and must never hold a database URL: a CLI that
+could reach the database would bypass authentication, attribution, and validation.
+"""
+
+import os
+import shutil
+import subprocess
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, Final, cast
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+from dirigent_client import API_PREFIX
+from dirigent_common import EntityName
+
+PROJECT_PROFILES: Final = Path(".dirigent") / "profiles.yaml"
+USER_PROFILES: Final = Path.home() / ".config" / "dirigent" / "profiles.yaml"
+
+URL_ENV: Final = "DG_URL"
+TOKEN_ENV: Final = "DG_TOKEN"
+PROFILE_ENV: Final = "DG_PROFILE"
+
+DEFAULT_URL: Final = "http://127.0.0.1:3333"
+
+DATABASE_SCHEMES: Final = ("postgresql", "postgres", "sqlite", "mysql")
+
+TOKEN_COMMAND_TIMEOUT: Final = 30.0
+
+
+class ProfileError(Exception):
+    """A profile could not be read, found, or turned into a usable token."""
+
+
+class Profile(BaseModel):
+    """One named server and how to obtain a token for it."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = "local"
+    url: str = DEFAULT_URL
+    token: SecretStr | None = None
+    """An inline token, which is fine for a local dev server and nowhere else."""
+
+    token_env: str | None = None
+    token_cmd: str | None = None
+
+    api_prefix: str = API_PREFIX
+    """Where this instance serves its API, for one configured with a different prefix."""
+
+    @model_validator(mode="after")
+    def _refuse_a_database_url(self) -> "Profile":
+        """Refuse a profile pointing at a database rather than at an API."""
+        scheme = self.url.split("://", 1)[0].split("+", 1)[0].lower()
+        if scheme in DATABASE_SCHEMES:
+            raise ValueError(
+                f"profile {self.name!r} names a database URL. Profiles address a server over HTTP; "
+                f"a database URL belongs in DIRIGENT_DATABASE_URL on the host that runs it"
+            )
+        return self
+
+    def resolve_token(self, environ: Mapping[str, str] | None = None) -> str | None:
+        """Obtain the token this profile describes, by whichever of the three mechanisms it uses."""
+        if self.token is not None:
+            return self.token.get_secret_value()
+        if self.token_env:
+            value = (environ if environ is not None else os.environ).get(self.token_env)
+            if not value:
+                raise ProfileError(f"profile {self.name!r} reads its token from ${self.token_env}, which is not set")
+            return value
+        if self.token_cmd:
+            return self._run_token_command()
+        return None
+
+    def _run_token_command(self) -> str:
+        """Run the command that prints the token, and refuse anything that is not a token."""
+        command = self.token_cmd or ""
+        argv = command.split()
+        if not argv or shutil.which(argv[0]) is None:
+            raise ProfileError(f"profile {self.name!r} runs {command!r} for its token, which is not on PATH")
+        try:
+            finished = subprocess.run(  # noqa: S603 - the command is the operator's own configuration
+                argv,
+                capture_output=True,
+                text=True,
+                timeout=TOKEN_COMMAND_TIMEOUT,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as error:
+            raise ProfileError(f"profile {self.name!r}: {command!r} did not finish in time") from error
+        if finished.returncode != 0:
+            detail = finished.stderr.strip() or f"exit code {finished.returncode}"
+            raise ProfileError(f"profile {self.name!r}: {command!r} failed ({detail})")
+        token = finished.stdout.strip()
+        if not token:
+            raise ProfileError(f"profile {self.name!r}: {command!r} printed nothing")
+        return token
+
+
+class ProfileStore(BaseModel):
+    """A profiles file: the named servers, and which one is used when none is asked for."""
+
+    model_config = ConfigDict(frozen=True)
+
+    default: str | None = None
+    profiles: dict[EntityName, Profile] = Field(default_factory=dict[str, Profile])
+    path: Path | None = None
+
+    def select(self, name: str | None) -> Profile | None:
+        """Choose a profile by name, by the file's default, or by there being only one."""
+        wanted = name or self.default
+        if wanted is None:
+            return next(iter(self.profiles.values())) if len(self.profiles) == 1 else None
+        found = self.profiles.get(wanted)
+        if found is None:
+            known = ", ".join(sorted(self.profiles)) or "this file defines none"
+            where = f" in {self.path}" if self.path else ""
+            raise ProfileError(f"no profile named {wanted!r}{where} ({known})")
+        return found
+
+
+def candidate_paths(start: Path | None = None) -> list[Path]:
+    """List the profiles files that apply here, most specific first."""
+    here = (start or Path.cwd()).resolve()
+    found = [directory / PROJECT_PROFILES for directory in [here, *here.parents]]
+    return [*found, USER_PROFILES]
+
+
+def load_store(path: Path) -> ProfileStore:
+    """Read one profiles file, naming the profile in every error it raises."""
+    try:
+        loaded: object = yaml.safe_load(path.read_text())
+    except (OSError, yaml.YAMLError) as error:
+        raise ProfileError(f"{path} could not be read: {error}") from error
+    if loaded is None:
+        loaded = {}
+    if not isinstance(loaded, dict):
+        raise ProfileError(f"{path} should hold a mapping with 'default' and 'profiles' keys")
+    raw = cast("dict[str, Any]", loaded)
+    declared = raw.get("profiles")
+    profiles: dict[str, Profile] = {}
+    if isinstance(declared, dict):
+        for name, body in cast("dict[str, Any]", declared).items():
+            if not isinstance(body, dict):
+                raise ProfileError(f"{path}: profile {name!r} is not a mapping")
+            try:
+                profiles[name] = Profile(name=name, **cast("dict[str, Any]", body))
+            except ValueError as error:
+                raise ProfileError(f"{path}: {error}") from error
+    default = raw.get("default")
+    return ProfileStore(
+        default=default if isinstance(default, str) else None,
+        profiles=profiles,
+        path=path,
+    )
+
+
+def find_store(start: Path | None = None) -> ProfileStore:
+    """Read the first profiles file that exists, or an empty store when none does."""
+    for path in candidate_paths(start):
+        if path.is_file():
+            return load_store(path)
+    return ProfileStore()
+
+
+class Endpoint(BaseModel):
+    """The resolved answer to "which server, with what token"."""
+
+    model_config = ConfigDict(frozen=True)
+
+    url: str
+    token: str | None = None
+    profile: str | None = None
+    source: str = "default"
+    api_prefix: str = API_PREFIX
+
+
+def resolve_endpoint(
+    *,
+    url: str | None = None,
+    token: str | None = None,
+    profile: str | None = None,
+    start: Path | None = None,
+    environ: dict[str, str] | None = None,
+    needs_token: bool = True,
+) -> Endpoint:
+    """Resolve the server and token: flags first, then ``DG_*``, then the selected profile.
+
+    With ``needs_token`` off, a profile whose token cannot be resolved yields no token rather
+    than refusing, which is what the command that mints one asks for.
+    """
+    env = environ if environ is not None else dict(os.environ)
+    store = find_store(start)
+    chosen = store.select(profile or env.get(PROFILE_ENV))
+
+    if url is not None:
+        source = "flag"
+    elif env.get(URL_ENV):
+        source, url = "environment", env[URL_ENV]
+    elif chosen is not None:
+        source, url = f"profile {chosen.name}", chosen.url
+    else:
+        source, url = "default", DEFAULT_URL
+
+    resolved_token = token or env.get(TOKEN_ENV) or None
+    if resolved_token is None and chosen is not None:
+        try:
+            resolved_token = chosen.resolve_token(env)
+        except ProfileError:
+            if needs_token:
+                raise
+    return Endpoint(
+        url=url.rstrip("/"),
+        token=resolved_token,
+        profile=chosen.name if chosen else None,
+        source=source,
+        api_prefix=chosen.api_prefix if chosen else API_PREFIX,
+    )