lorebase-cli 0.2.3__py3-none-any.whl

lorebase_cli/main.py

@@ -0,0 +1,156 @@
+"""The `lorebase` command line application."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from typer.core import TyperGroup
+
+import lorebase_client
+from lorebase_cli import __version__
+from lorebase_cli.commands import (
+    admin,
+    agents,
+    audit,
+    data,
+    documents,
+    domains,
+    history,
+    proposals,
+    schema,
+    sources,
+    trace,
+)
+from lorebase_cli.context import AppContext
+from lorebase_cli.failures import EXIT_USAGE, CliError, render_failure
+from lorebase_cli.settings import ENV_CONFIG, ENV_PROFILE, load_settings
+from lorebase_client import LorebaseError
+
+CLICK_USAGE_EXIT = 2  # exit code Typer gives to usage errors; ours is EXIT_USAGE
+
+EPILOG = (
+    "Exit codes: 0 success, 1 usage or configuration error (also not found), "
+    "2 validation failure or conflict, 3 authentication or permission failure, "
+    "4 server error or server unreachable."
+)
+
+
+def _is_invalid_request(error: Exception) -> bool:
+    """A request model of the client rejected the arguments (a pydantic validation error)."""
+    return type(error).__module__.startswith("pydantic") and isinstance(error, ValueError)
+
+
+class LorebaseGroup(TyperGroup):
+    """Turns failures into messages on standard error and the documented exit codes."""
+
+    def invoke(self, ctx: Any) -> Any:  # Typer's vendored Context class is not public
+        try:
+            return super().invoke(ctx)
+        except typer.TyperException as error:  # usage errors: bad option, missing argument
+            show = getattr(error, "show", None)
+            if callable(show):
+                show()
+            else:  # pragma: no cover - every TyperException of typer 0.27 can show itself
+                typer.echo(f"error: {error}", err=True)
+            code = getattr(error, "exit_code", EXIT_USAGE)
+            raise typer.Exit(EXIT_USAGE if code == CLICK_USAGE_EXIT else code) from None
+        except (LorebaseError, CliError) as error:
+            app = ctx.find_object(AppContext)
+            text, code = render_failure(error, json_mode=bool(app and app.json_mode))
+            typer.echo(text, err=True)
+            raise typer.Exit(code) from None
+        except ValueError as error:
+            if not _is_invalid_request(error):
+                raise
+            typer.echo(f"error: invalid arguments\n{error}", err=True)
+            raise typer.Exit(EXIT_USAGE) from None
+
+
+app = typer.Typer(
+    cls=LorebaseGroup,
+    name="lorebase",
+    help="Command line client of a Lorebase Keeper.\n\n"
+    "Point it at a server with LOREBASE_URL and LOREBASE_API_KEY (or LOREBASE_TOKEN), or a "
+    "profile in ~/.config/lorebase/config.toml. Every command takes --json for machine output. "
+    "Run `lorebase --install-completion` for shell completion.",
+    epilog=EPILOG,
+    no_args_is_help=True,
+    add_completion=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version(show: bool) -> None:
+    if show:
+        typer.echo(f"lorebase {__version__} (client {lorebase_client.__version__})")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            "--config", help=f"Config file (default: ~/.config/lorebase/config.toml; {ENV_CONFIG})."
+        ),
+    ] = None,
+    profile: Annotated[
+        str | None, typer.Option("--profile", help=f"Profile of the config file ({ENV_PROFILE}).")
+    ] = None,
+    url: Annotated[str | None, typer.Option("--url", help="Server URL (LOREBASE_URL).")] = None,
+    json_out: Annotated[
+        bool, typer.Option("--json", help="Print JSON instead of tables, for every command.")
+    ] = False,
+    quiet: Annotated[
+        bool, typer.Option("--quiet", "-q", help="Print no progress or notes.")
+    ] = False,
+    version: Annotated[
+        bool,
+        typer.Option("--version", callback=_version, is_eager=True, help="Show the version."),
+    ] = False,
+) -> None:
+    """Load the settings every command uses."""
+    del version
+    settings = load_settings(
+        env=os.environ,
+        config_path=config,
+        profile=profile,
+        url=url,
+        warn=lambda message: typer.echo(f"warning: {message}", err=True),
+    )
+    state = AppContext(settings=settings, json_mode=json_out, quiet=quiet)
+    ctx.obj = state
+    ctx.call_on_close(state.close)
+
+
+app.add_typer(domains.domain_app, name="domain")
+app.add_typer(domains.branch_app, name="branch")
+app.add_typer(domains.tag_app, name="tag")
+app.add_typer(schema.schema_app, name="schema")
+app.add_typer(data.import_app, name="import")
+app.add_typer(data.record_app, name="record")
+app.add_typer(history.revision_app, name="revision")
+app.add_typer(admin.apikey_app, name="apikey")
+app.add_typer(admin.admin_app, name="admin")
+app.add_typer(audit.audit_app, name="audit")
+app.add_typer(trace.trace_app, name="trace")
+app.add_typer(proposals.proposal_app, name="proposal")
+app.add_typer(sources.sources_app, name="sources")
+app.add_typer(documents.documents_app, name="documents")
+app.command("whoami")(domains.whoami)
+app.command("query")(data.query_command)
+app.command("search")(data.search_command)
+app.command("log")(history.log_command)
+app.command("diff")(history.diff_command)
+app.command("context")(agents.context_command)
+app.command("explain")(agents.explain_command)
+app.command("health")(agents.health_command)
+
+
+def main() -> None:
+    """Entry point of the `lorebase` script."""
+    app(prog_name="lorebase")

lorebase_cli/options.py

@@ -0,0 +1,56 @@
+"""Options shared by many commands, and the shell completion of Domain ids."""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated
+
+import typer
+
+from lorebase_cli.context import default_client
+from lorebase_cli.settings import load_settings
+
+
+def complete_domain(incomplete: str) -> list[str]:
+    """Domain ids starting with `incomplete`, from the configured server (none on any failure,
+    since completion must never print errors)."""
+    try:
+        settings = load_settings(env=os.environ)
+        if not settings.url:
+            return []
+        client = default_client(settings)
+        try:
+            return [d.id for d in client.domains.iterate() if d.id.startswith(incomplete)]
+        finally:
+            client.close()
+    except (Exception, SystemExit):
+        return []
+
+
+JsonOpt = Annotated[bool, typer.Option("--json", help="Print JSON instead of a table.")]
+DomainOpt = Annotated[
+    str | None,
+    typer.Option(
+        "--domain",
+        "-d",
+        help="Domain id (default: LOREBASE_DOMAIN or `domain` in the config file).",
+        autocompletion=complete_domain,
+    ),
+]
+BranchOpt = Annotated[
+    str | None,
+    typer.Option(
+        "--branch",
+        "-b",
+        help="Branch (default: LOREBASE_BRANCH, `branch` in the config file, else the Domain's "
+        "default branch).",
+    ),
+]
+AtOpt = Annotated[
+    str | None, typer.Option("--at", help="Revision id or tag to read at (time travel).")
+]
+LimitOpt = Annotated[
+    int | None,
+    typer.Option("--limit", "-n", min=1, help="Most items to print (default: list_limit setting)."),
+]
+AllOpt = Annotated[bool, typer.Option("--all", help="Print every item, however many.")]

lorebase_cli/output.py

@@ -0,0 +1,169 @@
+"""Rendering of results: JSON for machines, tables for people.
+
+Tables are plain aligned text by default (stable in pipes and tests); on a terminal they use
+`rich` when it is installed (it comes with Typer). Long cells are cut at
+`settings.max_cell_width`. Informational messages go to standard error so that standard output
+only holds the result.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import date, datetime
+from decimal import Decimal
+from typing import IO, Any
+
+ELLIPSIS = "…"
+
+
+@dataclass(frozen=True)
+class Column:
+    """A table column: header, key of the value and optional formatter."""
+
+    header: str
+    key: str
+    format: Callable[[Any], str] | None = None
+
+
+def to_jsonable(value: Any) -> Any:
+    """Plain JSON data of models, dates and decimals."""
+    dump = getattr(value, "model_dump", None)  # a pydantic model of the client
+    if callable(dump):
+        return dump(mode="json", by_alias=True)
+    if isinstance(value, Mapping):
+        return {str(k): to_jsonable(v) for k, v in value.items()}
+    if isinstance(value, list | tuple):
+        return [to_jsonable(v) for v in value]
+    if isinstance(value, datetime | date):
+        return value.isoformat()
+    if isinstance(value, Decimal):
+        return str(value)
+    return value
+
+
+def cell(value: Any) -> str:
+    """Text of a table cell."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, datetime):
+        return value.isoformat(timespec="seconds")
+    if isinstance(value, list | tuple):
+        return ", ".join(cell(v) for v in value)
+    if isinstance(value, Mapping):
+        return json.dumps(to_jsonable(value), separators=(",", ":"), ensure_ascii=False)
+    return str(value).replace("\n", " ")
+
+
+def shorten(text: str, width: int) -> str:
+    return text if len(text) <= width else text[: width - 1] + ELLIPSIS
+
+
+def short_id(value: str | None, length: int = 12) -> str:
+    """The first characters of a Revision id."""
+    return "" if value is None else value[:length]
+
+
+class Output:
+    """Where a command writes its result."""
+
+    def __init__(
+        self,
+        *,
+        json_mode: bool = False,
+        max_cell_width: int = 60,
+        stdout: IO[str] | None = None,
+        stderr: IO[str] | None = None,
+    ) -> None:
+        self.json_mode = json_mode
+        self.max_cell_width = max_cell_width
+        self._stdout = stdout
+        self._stderr = stderr
+
+    @property
+    def stdout(self) -> IO[str]:
+        return self._stdout or sys.stdout
+
+    @property
+    def stderr(self) -> IO[str]:
+        return self._stderr or sys.stderr
+
+    def info(self, message: str) -> None:
+        """A note for the person running the command (standard error)."""
+        print(message, file=self.stderr)
+
+    def text(self, text: str) -> None:
+        """Raw text on standard output (a schema document)."""
+        self.stdout.write(text if text.endswith("\n") else text + "\n")
+
+    def data(self, payload: Any) -> None:
+        """The JSON document of a result."""
+        print(json.dumps(to_jsonable(payload), indent=2, ensure_ascii=False), file=self.stdout)
+
+    def emit(self, payload: Any, human: Callable[[], None]) -> None:
+        """JSON in JSON mode, otherwise whatever `human` prints."""
+        if self.json_mode:
+            self.data(payload)
+        else:
+            human()
+
+    def table(
+        self,
+        rows: Sequence[Mapping[str, Any]],
+        columns: Sequence[Column],
+        *,
+        truncate: bool = True,
+    ) -> None:
+        """Rows with the given columns (long cells cut unless `truncate` is off); nothing but
+        the header for no rows."""
+        grid = [
+            [
+                shorten(
+                    column.format(row.get(column.key))
+                    if column.format
+                    else cell(row.get(column.key)),
+                    self.max_cell_width if truncate else sys.maxsize,
+                )
+                for column in columns
+            ]
+            for row in rows
+        ]
+        headers = [column.header for column in columns]
+        if self._use_rich():
+            self._rich_table(headers, grid)
+            return
+        widths = [max(len(h), *(len(line[i]) for line in grid), 0) for i, h in enumerate(headers)]
+        for line in (headers, *grid):
+            print(
+                "  ".join(c.ljust(w) for c, w in zip(line, widths, strict=True)).rstrip(),
+                file=self.stdout,
+            )
+
+    def pairs(self, items: Sequence[tuple[str, Any]]) -> None:
+        """Name and value per line."""
+        rows = [{"name": name, "value": value} for name, value in items]
+        self.table(rows, [Column("field", "name"), Column("value", "value")], truncate=False)
+
+    def _use_rich(self) -> bool:
+        if self._stdout is not None or not sys.stdout.isatty():
+            return False
+        try:
+            import rich  # noqa: F401
+        except ImportError:  # pragma: no cover - rich ships with typer
+            return False
+        return True
+
+    def _rich_table(self, headers: list[str], grid: list[list[str]]) -> None:  # pragma: no cover
+        from rich.console import Console
+        from rich.table import Table
+
+        table = Table(show_header=True, header_style="bold")
+        for header in headers:
+            table.add_column(header, overflow="fold")
+        for line in grid:
+            table.add_row(*line)
+        Console().print(table)

lorebase_cli/settings.py

@@ -0,0 +1,169 @@
+"""CLI settings: command line, then environment, then the config file, then defaults.
+
+The config file is TOML, by default `$XDG_CONFIG_HOME/lorebase/config.toml` (falling back to
+`~/.config/lorebase/config.toml`); `--config` or `LOREBASE_CONFIG` names another one:
+
+    profile = "local"              # profile used when none is asked for
+
+    [profiles.local]
+    url = "http://localhost:8080"
+    api_key = "lbk_..."            # or token = "<OIDC access token>"
+    domain = "supply"              # default for --domain
+    branch = "work"                # default for --branch
+
+    [import]
+    batch_size = 1000              # rows per request
+
+    [output]
+    list_limit = 50                # items printed by list commands without --all
+    max_cell_width = 60            # longer table cells are cut
+
+Keys outside `[profiles.*]` apply to every profile. Credentials are not accepted as command
+line options (they would end up in shell history): use the environment or the config file,
+which should be readable by its owner only.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any
+
+from lorebase_cli.failures import CliError
+
+ENV_CONFIG = "LOREBASE_CONFIG"
+ENV_PROFILE = "LOREBASE_PROFILE"
+ENV_DOMAIN = "LOREBASE_DOMAIN"
+ENV_BRANCH = "LOREBASE_BRANCH"
+ENV_BATCH_SIZE = "LOREBASE_BATCH_SIZE"
+ENV_LIST_LIMIT = "LOREBASE_LIST_LIMIT"
+
+DEFAULT_BATCH_SIZE = 1000
+DEFAULT_LIST_LIMIT = 50
+DEFAULT_MAX_CELL_WIDTH = 60
+CONFIG_DIR = "lorebase"
+CONFIG_FILE = "config.toml"
+
+
+@dataclass(frozen=True)
+class CliSettings:
+    """Everything the commands need from configuration."""
+
+    url: str | None = None
+    api_prefix: str | None = None
+    api_key: str | None = None
+    token: str | None = None
+    timeout: float | None = None
+    domain: str | None = None
+    branch: str | None = None
+    batch_size: int = DEFAULT_BATCH_SIZE
+    list_limit: int = DEFAULT_LIST_LIMIT
+    max_cell_width: int = DEFAULT_MAX_CELL_WIDTH
+    profile: str | None = None
+    config_path: Path | None = None
+
+
+def default_config_path(env: Mapping[str, str]) -> Path:
+    """Where the config file is looked for when none is named."""
+    base = env.get("XDG_CONFIG_HOME")
+    root = Path(base) if base else Path.home() / ".config"
+    return root / CONFIG_DIR / CONFIG_FILE
+
+
+def _read(path: Path, *, explicit: bool) -> dict[str, Any]:
+    if not path.exists():
+        if explicit:
+            raise CliError(f"config file not found: {path}")
+        return {}
+    try:
+        return tomllib.loads(path.read_text())
+    except (OSError, tomllib.TOMLDecodeError) as error:
+        raise CliError(f"cannot read config file {path}: {error}") from error
+
+
+def _positive(value: object, name: str) -> int:
+    try:
+        number = int(str(value))
+    except ValueError:
+        number = 0
+    if number < 1:
+        raise CliError(f"{name} must be a positive integer, got {value!r}")
+    return number
+
+
+def _number(value: object, name: str) -> float:
+    try:
+        return float(str(value))
+    except ValueError:
+        raise CliError(f"{name} must be a number, got {value!r}") from None
+
+
+def _text(table: Mapping[str, Any], key: str) -> str | None:
+    value = table.get(key)
+    return None if value is None else str(value)
+
+
+def load_settings(
+    *,
+    env: Mapping[str, str] | None = None,
+    config_path: Path | None = None,
+    profile: str | None = None,
+    url: str | None = None,
+    warn: Any = None,
+) -> CliSettings:
+    """Merge the command line values given, the environment and the config file.
+
+    `warn` is called with a message when the config file holds credentials and other users
+    can read it.
+    """
+    environment = os.environ if env is None else env
+    named = config_path or (Path(environment[ENV_CONFIG]) if environment.get(ENV_CONFIG) else None)
+    path = named or default_config_path(environment)
+    document = _read(path, explicit=named is not None)
+
+    chosen = profile or environment.get(ENV_PROFILE) or document.get("profile")
+    profiles = document.get("profiles", {})
+    if chosen is not None and chosen not in profiles:
+        known = ", ".join(sorted(profiles)) or "none"
+        raise CliError(f"profile {chosen!r} is not in {path} (profiles: {known})")
+    layer: dict[str, Any] = {**document, **(profiles.get(chosen, {}) if chosen else {})}
+    importing = {**document.get("import", {}), **layer.get("import", {})}
+    output = {**document.get("output", {}), **layer.get("output", {})}
+
+    def pick(env_name: str, key: str) -> str | None:
+        return environment.get(env_name) or _text(layer, key)
+
+    from_file = (layer.get("api_key") and not environment.get("LOREBASE_API_KEY")) or (
+        layer.get("token") and not environment.get("LOREBASE_TOKEN")
+    )
+    shared = stat.S_IRWXG | stat.S_IRWXO
+    if warn and from_file and path.exists() and path.stat().st_mode & shared:
+        warn(f"{path} holds credentials and other users can read it; run: chmod 600 {path}")
+
+    settings = CliSettings(
+        url=url or pick("LOREBASE_URL", "url"),
+        api_prefix=pick("LOREBASE_API_PREFIX", "api_prefix"),
+        api_key=pick("LOREBASE_API_KEY", "api_key"),
+        token=pick("LOREBASE_TOKEN", "token"),
+        domain=pick(ENV_DOMAIN, "domain"),
+        branch=pick(ENV_BRANCH, "branch"),
+        profile=chosen,
+        config_path=path if path.exists() else None,
+    )
+    timeout = pick("LOREBASE_TIMEOUT", "timeout")
+    if timeout is not None:
+        settings = replace(settings, timeout=_number(timeout, "timeout"))
+    size = environment.get(ENV_BATCH_SIZE) or importing.get("batch_size")
+    if size is not None:
+        settings = replace(settings, batch_size=_positive(size, "batch_size"))
+    limit = environment.get(ENV_LIST_LIMIT) or output.get("list_limit")
+    if limit is not None:
+        settings = replace(settings, list_limit=_positive(limit, "list_limit"))
+    width = output.get("max_cell_width")
+    if width is not None:
+        settings = replace(settings, max_cell_width=_positive(width, "max_cell_width"))
+    return settings

lorebase_cli/sources.py

@@ -0,0 +1,118 @@
+"""Readers of import files: CSV, TSV, JSON Lines, a JSON array and Parquet.
+
+Each reader yields one dict per row, lazily, so that a large file is never held in memory
+whole (a JSON array is the exception). The format comes from `--format` or the file suffix.
+Parquet needs `pyarrow`, an optional dependency (`pip install "lorebase-cli[parquet]"`).
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from lorebase_cli.failures import CliError
+
+STDIN = "-"
+FORMATS = ("csv", "tsv", "jsonl", "json", "parquet")
+SUFFIXES = {
+    ".csv": "csv",
+    ".tsv": "tsv",
+    ".jsonl": "jsonl",
+    ".ndjson": "jsonl",
+    ".json": "json",
+    ".parquet": "parquet",
+}
+PARQUET_BATCH_ROWS = 10_000
+
+
+def detect_format(path: str, given: str | None) -> str:
+    """The format named, or the one the suffix of `path` implies."""
+    if given:
+        if given not in FORMATS:
+            raise CliError(f"unknown format {given!r}; use one of {', '.join(FORMATS)}")
+        return given
+    suffix = Path(path).suffix.lower()
+    if suffix in SUFFIXES:
+        return SUFFIXES[suffix]
+    raise CliError(
+        f"cannot tell the format of {path!r} from its suffix; pass --format ({', '.join(FORMATS)})"
+    )
+
+
+def read_rows(path: str, fmt: str, *, delimiter: str | None = None) -> Iterator[dict[str, Any]]:
+    """Rows of the file (`-` is standard input, for text formats)."""
+    if fmt == "parquet":
+        if path == STDIN:
+            raise CliError("Parquet cannot be read from standard input")
+        return _parquet(Path(path))
+    if fmt in ("csv", "tsv"):
+        return _csv(path, delimiter or ("\t" if fmt == "tsv" else ","))
+    if fmt == "jsonl":
+        return _jsonl(path)
+    return _json_array(path)
+
+
+def _lines(path: str) -> Iterator[str]:
+    if path == STDIN:
+        yield from sys.stdin
+        return
+    try:
+        handle = Path(path).open(encoding="utf-8-sig", newline="")  # noqa: SIM115 - closed below
+    except OSError as error:
+        raise CliError(f"cannot read {path}: {error.strerror or error}") from error
+    with handle:
+        yield from handle
+
+
+def _csv(path: str, delimiter: str) -> Iterator[dict[str, Any]]:
+    reader = csv.DictReader(_lines(path), delimiter=delimiter)
+    if reader.fieldnames is None:
+        raise CliError(f"{path}: no header row")
+    for number, row in enumerate(reader, start=2):
+        if None in row:
+            raise CliError(f"{path}: line {number} has more cells than the header")
+        yield row
+
+
+def _jsonl(path: str) -> Iterator[dict[str, Any]]:
+    for number, line in enumerate(_lines(path), start=1):
+        if not line.strip():
+            continue
+        try:
+            row = json.loads(line)
+        except ValueError:
+            raise CliError(f"{path}: line {number} is not valid JSON") from None
+        if not isinstance(row, dict):
+            raise CliError(f"{path}: line {number} is not a JSON object")
+        yield row
+
+
+def _json_array(path: str) -> Iterator[dict[str, Any]]:
+    text = "".join(_lines(path))
+    try:
+        rows = json.loads(text)
+    except ValueError:
+        raise CliError(f"{path}: not valid JSON") from None
+    if not isinstance(rows, list) or not all(isinstance(r, dict) for r in rows):
+        raise CliError(f"{path}: expected a JSON array of objects")
+    yield from rows
+
+
+def _parquet(path: Path) -> Iterator[dict[str, Any]]:
+    try:
+        import pyarrow.parquet as parquet  # type: ignore[import-untyped]
+    except ImportError:
+        raise CliError(
+            "reading Parquet needs pyarrow: pip install 'lorebase-cli[parquet]'"
+        ) from None
+    try:
+        file = parquet.ParquetFile(path)
+    except (OSError, ValueError) as error:  # missing, unreadable or not a Parquet file
+        raise CliError(f"cannot read {path}: {error}") from error
+    with file:
+        for batch in file.iter_batches(batch_size=PARQUET_BATCH_ROWS):
+            yield from batch.to_pylist()

lorebase_cli-0.2.3.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: lorebase-cli
+Version: 0.2.3
+Summary: Lorebase CLI
+Requires-Python: >=3.12
+Requires-Dist: lorebase-client<0.3,>=0.2
+Requires-Dist: typer>=0.27
+Provides-Extra: linkml
+Requires-Dist: pyyaml>=6.0; extra == 'linkml'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=15; extra == 'parquet'