fherma 0.1.0__py3-none-any.whl

fherma/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

fherma/api.py

@@ -0,0 +1,107 @@
+"""A thin client over the platform's API.
+
+Scaffolding is not here: it is a function of a signature, and `fherma_lang`
+computes it in this process. The platform is asked for the signature and for
+what only it knows — versions, points, status.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from .config import Profile
+from .errors import AuthError, NetworkError, UsageError
+
+#: Bumped when the wire contract changes. The server answers with the range it
+#: speaks, so an outdated client is told to update rather than shown a 400.
+API_VERSION = 1
+
+
+@dataclass(frozen=True)
+class SpecRef:
+    """`kernel/spec@version`, with the version optional."""
+
+    kernel: str
+    spec: str
+    version: str | None = None
+
+    @classmethod
+    def parse(cls, text: str) -> SpecRef:
+        body, _, version = text.partition("@")
+        kernel, sep, spec = body.partition("/")
+        if not sep or not kernel or not spec:
+            raise UsageError(
+                f"{text!r} is not a specification reference",
+                hint="Write it as kernel/spec@version, for example polymult/rlwe@1.0.0",
+            )
+        return cls(kernel=kernel, spec=spec, version=version or None)
+
+    @property
+    def path(self) -> str:
+        tail = f"@{self.version}" if self.version else ""
+        return f"/specs/{self.kernel}/{self.spec}{tail}"
+
+    def __str__(self) -> str:
+        tail = f"@{self.version}" if self.version else ""
+        return f"{self.kernel}/{self.spec}{tail}"
+
+
+class Api:
+    def __init__(self, profile: Profile) -> None:
+        self._profile = profile
+        headers = {"accept": "application/json", "x-fherma-api": str(API_VERSION)}
+        if profile.token:
+            headers["authorization"] = f"Bearer {profile.token}"
+        self._client = httpx.Client(
+            base_url=f"{profile.url.rstrip('/')}/api",
+            headers=headers,
+            timeout=30.0,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ── plumbing ────────────────────────────────────────────────────────────
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.RequestError as error:
+            raise NetworkError(
+                f"cannot reach {self._profile.url}",
+                hint=f"{error.__class__.__name__}: {error}",
+            ) from error
+
+        if response.status_code in (401, 403):
+            raise AuthError(
+                "not authorised",
+                hint="Run `fherma auth login`, or set FHERMA_TOKEN.",
+            )
+        if response.status_code == 404:
+            raise UsageError(f"not found: {path}")
+        if response.status_code == 426:
+            raise NetworkError(
+                "this version of the CLI is too old for the platform",
+                hint="Run `pip install --upgrade fherma`.",
+            )
+        if response.status_code >= 400:
+            raise NetworkError(
+                f"the platform answered {response.status_code}",
+                hint=_short(response.text),
+            )
+        return response.json() if response.content else None
+
+    # ── endpoints ───────────────────────────────────────────────────────────
+    def whoami(self) -> dict:
+        return self._request("GET", "/auth/me")
+
+    def spec(self, ref: SpecRef) -> dict:
+        """Specification data: signature, description, points, status."""
+        return self._request("GET", ref.path)
+
+
+def _short(text: str, limit: int = 200) -> str:
+    text = " ".join(text.split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"

fherma/cli.py

@@ -0,0 +1,89 @@
+"""Entry point.
+
+Command groups are not listed here. They are discovered through the
+`fherma.commands` entry point group, so adding a noun means adding a module and
+one line to `pyproject.toml` — and a separate distribution can add one without
+touching this project at all.
+
+`doctor` and `completion` are the exception, attached below by hand. They are
+not nouns the platform has; they are about the installation, and they have to
+keep working on the day discovery itself is what broke.
+"""
+
+from __future__ import annotations
+
+import sys
+from importlib.metadata import entry_points
+
+import click
+
+from . import config, output, toolchain
+from .api import Api
+from .commands.toolchain import completion, doctor
+from .errors import Exit, FhermaError
+
+
+class Context:
+    """Shared state. Commands reach it through `click.pass_obj`."""
+
+    def __init__(self, profile_name: str | None) -> None:
+        self.profile = config.load(profile_name)
+        self._api: Api | None = None
+
+    @property
+    def api(self) -> Api:
+        # Built lazily so that offline commands — `check`, `case` — never open a
+        # connection and never need a token.
+        if self._api is None:
+            self._api = Api(self.profile)
+        return self._api
+
+
+def _print_version(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
+    """`--version` reports the toolchain, not this package.
+
+    An install is two distributions that move independently, and a bug report
+    quoting only one of them is a bug report missing half its evidence.
+    """
+    if not value or ctx.resilient_parsing:
+        return
+    click.echo(toolchain.describe())
+    ctx.exit()
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option("-V", "--version", is_flag=True, is_eager=True, expose_value=False,
+              callback=_print_version, help="Show the version of every installed part.")
+@click.option("--profile", envvar="FHERMA_PROFILE",
+              help="Which configured platform to talk to.")
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable output.")
+@click.pass_context
+def cli(ctx: click.Context, profile: str | None, as_json: bool) -> None:
+    """FHERMA — the kernel catalogue, from the command line."""
+    output.set_json(as_json)
+    ctx.obj = Context(profile)
+
+
+cli.add_command(doctor)
+cli.add_command(completion)
+
+
+def _install_groups() -> None:
+    for entry in entry_points(group="fherma.commands"):
+        cli.add_command(entry.load(), name=entry.name)
+
+
+def main() -> None:
+    _install_groups()
+    try:
+        cli.main(standalone_mode=False)
+    except FhermaError as error:
+        output.fail(error.message, error.hint)
+        sys.exit(int(error.exit_code))
+    except click.ClickException as error:
+        error.show()
+        sys.exit(int(Exit.USAGE))
+    except click.Abort:
+        output.fail("aborted")
+        sys.exit(int(Exit.USAGE))
+    sys.exit(int(Exit.OK))

fherma/commands/__init__.py

@@ -0,0 +1 @@
+"""Command groups, discovered through entry points."""

fherma/commands/auth.py

@@ -0,0 +1,57 @@
+"""Who we are to the platform."""
+
+from __future__ import annotations
+
+import click
+
+from .. import config, output
+from ..api import Api
+from ..errors import AuthError
+
+
+@click.group()
+def group() -> None:
+    """Log in, log out, and see who you are."""
+
+
+@group.command()
+@click.option("--token", prompt="API token", hide_input=True,
+              help="Read from the terminal when not given, so it stays out of shell history.")
+@click.pass_obj
+def login(ctx, token: str) -> None:
+    """Store a token for this profile."""
+    # Verify before writing. A token that is saved and then turns out to be
+    # wrong is worse than one that was never saved: the failure surfaces later,
+    # somewhere else.
+    probe = Api(config.Profile(name=ctx.profile.name, url=ctx.profile.url, token=token))
+    try:
+        me = probe.whoami()
+    finally:
+        probe.close()
+
+    config.save_token(ctx.profile.name, ctx.profile.url, token)
+    output.ok(f"logged in as {me.get('handle', 'unknown')} on {ctx.profile.name}")
+    output.emit({"profile": ctx.profile.name, "handle": me.get("handle")})
+
+
+@group.command()
+@click.pass_obj
+def logout(ctx) -> None:
+    """Forget the stored token for this profile."""
+    if config.forget_token(ctx.profile.name):
+        output.ok(f"token removed from profile {ctx.profile.name}")
+    else:
+        output.note(f"no token stored for profile {ctx.profile.name}")
+    output.emit({"profile": ctx.profile.name, "token": None})
+
+
+@group.command()
+@click.pass_obj
+def whoami(ctx) -> None:
+    """Show the account this profile is using."""
+    if not ctx.profile.token:
+        raise AuthError("no token for this profile", hint="Run `fherma auth login`.")
+    me = ctx.api.whoami()
+    output.say(f"{me.get('handle')} — {me.get('display_name', '')}")
+    output.note(f"{ctx.profile.name} · {ctx.profile.url}")
+    output.emit(me)

fherma/commands/testing.py

@@ -0,0 +1,187 @@
+"""The generator, the oracle and the verifier of a specification.
+
+These three say where test data comes from, what the right answer is, and how a
+verdict is reached. Their shapes are the same for every kernel in the catalogue;
+only the types differ, and those come from the specification's signature.
+
+The scaffold is produced by `fherma-lang`, in this process. The platform is
+asked for one thing — the signature — so `init` needs no server at all when the
+signature is already on disk.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from fherma_lang import LanguageError, emit, parse, reference
+from fherma_lang.emit import PARTS
+
+from .. import output, project
+from ..api import SpecRef
+from ..errors import CheckFailed, UsageError
+
+
+@click.group()
+def group() -> None:
+    """Write and check the generator, oracle and verifier."""
+
+
+@group.command(short_help="fetch the bundle to write them in")
+@click.argument("spec", required=False, metavar="KERNEL/SPEC[@VERSION]")
+@click.option("--signature", type=click.Path(exists=True, dir_okay=False, path_type=Path),
+              help="Scaffold from a signature on disk instead of asking the platform.")
+@click.option("--generator", "wanted", flag_value="generator", multiple=True,
+              help="Scaffold the generator.")
+@click.option("--oracle", "wanted", flag_value="oracle", multiple=True,
+              help="Scaffold the oracle.")
+@click.option("--verifier", "wanted", flag_value="verifier", multiple=True,
+              help="Scaffold the verifier. All three when none is named.")
+@click.option("--out", type=click.Path(file_okay=False, path_type=Path), metavar="DIR",
+              help="Where to write. Named after the specification when omitted.")
+@click.option("--force", is_flag=True, help="Overwrite files that are already there.")
+@click.option("--update", is_flag=True,
+              help="Rewrite the generated files only, leaving yours untouched.")
+@click.pass_obj
+def init(ctx, spec: str | None, signature: Path | None, wanted: tuple[str, ...],
+         out: Path | None, force: bool, update: bool) -> None:
+    """Fetch the bundle for a specification.
+
+    \b
+      fherma testing init polymult/rlwe@1.0.0
+      fherma testing init polymult/rlwe             # the latest published version
+      fherma testing init polymult/rlwe --oracle --verifier
+      fherma testing init --signature ./sig.fhk     # no platform involved
+    """
+    if bool(spec) == bool(signature):
+        raise UsageError(
+            "name a specification, or pass --signature",
+            hint="fherma testing init polymult/rlwe@1.0.0",
+        )
+
+    ref: SpecRef | None = None
+    if signature:
+        text = signature.read_text(encoding="utf-8")
+    else:
+        ref = SpecRef.parse(spec)
+        data = ctx.api.spec(ref)
+        text = (data.get("signature") or "").strip()
+        if not text:
+            raise UsageError(
+                f"{ref} has no signature yet",
+                hint="A specification is scaffolded from its signature; this one is empty.",
+            )
+        # The reference may have arrived without a version; report the resolved one.
+        ref = SpecRef(kernel=data.get("kernel", ref.kernel),
+                      spec=data.get("slug", ref.spec),
+                      version=data.get("version", ref.version))
+
+    try:
+        parts = [p for p in PARTS if p in wanted] or None
+        declaration = parse(text)
+        files = emit(declaration, kind="testing", parts=parts)
+    except LanguageError as failure:
+        diagnostic = failure.diagnostic
+        raise CheckFailed(f"{diagnostic.code}: {diagnostic.message}",
+                          hint=diagnostic.hint) from failure
+
+    # A bundle scaffolded from a local file is still a bundle: later commands
+    # have to recognise it. The declaration names itself, so the marker never
+    # depends on having asked the platform.
+    marker = str(ref) if ref else reference(declaration)
+
+    root = (out or Path(_directory(ref, signature))).resolve()
+    written, kept = _write(root, files, force=force, update=update)
+
+    project.write(root, kind="testing", spec=marker, fingerprint=_fingerprint(text))
+
+    output.ok(f"{'updated' if update else 'scaffolded'} {root}")
+    for entry in written:
+        output.note(f"  {entry}")
+    if kept:
+        output.note(f"  kept: {', '.join(kept)}")
+
+    if not update:
+        output.say("")
+        if parts:
+            rest = [f"--{p}" for p in PARTS if p not in parts]
+            output.say(f"Only the {', '.join(parts)}."
+                       + (f" Add [bold]{' '.join(rest)}[/bold] for the rest." if rest else ""))
+        else:
+            output.say("Write [bold]generate.py[/bold] and [bold]oracle.py[/bold], "
+                       "then run [bold]fherma testing check[/bold].")
+
+    output.emit({
+        "root": str(root),
+        "spec": marker,
+        "parts": list(parts or PARTS),
+        "written": written,
+        "kept": kept,
+    })
+
+
+@group.command(short_help="what the platform thinks of this bundle")
+@click.pass_obj
+def status(ctx) -> None:
+    """Show the specification's state and what it is still missing."""
+    here = project.require_kind("testing")
+    ref = SpecRef.parse(here.spec)
+    data = ctx.api.spec(ref)
+
+    output.say(f"{ref} — {data.get('title', '')}")
+    output.note(f"status: {data.get('status', 'unknown')}")
+
+    signature = (data.get("signature") or "").strip()
+    if here.fingerprint and signature and _fingerprint(signature) != here.fingerprint:
+        output.bad("the specification's signature has changed since this bundle was made")
+        output.note("  run `fherma testing init --update` to refresh the generated files")
+
+    output.emit(data)
+
+
+# ── writing ─────────────────────────────────────────────────────────────────
+def _write(root: Path, files, *, force: bool, update: bool) -> tuple[list[str], list[str]]:
+    """Lay the bundle out.
+
+    Two rules, and both matter more than they look. A directory holding work is
+    never written into unasked; and an update rewrites only what was generated,
+    because the whole point of the split is that authored files are the author's.
+    """
+    if root.exists() and any(root.iterdir()) and not (force or update):
+        raise UsageError(
+            f"{root} is not empty",
+            hint="Pass --force to write into it, or --update to refresh generated files only.",
+        )
+
+    written: list[str] = []
+    kept: list[str] = []
+
+    for file in files:
+        target = root / file.path
+        authored = not file.generated
+
+        if authored and (update or (target.exists() and not force)):
+            kept.append(file.path)
+            continue
+
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(file.content, encoding="utf-8")
+        written.append(file.path)
+
+    for name in ("vectors", "assets"):
+        (root / name).mkdir(parents=True, exist_ok=True)
+
+    return written, kept
+
+
+def _directory(ref: SpecRef | None, signature: Path | None) -> str:
+    if ref:
+        return f"{ref.kernel}-{ref.spec}" + (f"-{ref.version}" if ref.version else "")
+    return signature.stem if signature else "bundle"
+
+
+def _fingerprint(signature: str) -> str:
+    """What the bundle was made from, so a later command can notice a change."""
+    import hashlib
+
+    return "sha256:" + hashlib.sha256(signature.encode("utf-8")).hexdigest()[:16]

fherma/commands/toolchain.py

@@ -0,0 +1,164 @@
+"""`doctor` and `completion` — commands about the installation itself.
+
+These two are registered directly on the root rather than through entry points.
+Everything else is a noun the platform has (`auth`, `testing`); these are about
+the tool on this machine, and they must keep working when the rest does not.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+
+import click
+
+from .. import config, output, toolchain
+from ..errors import CheckFailed
+
+#: `ok` — nothing to do. `warn` — works, but something is worth knowing.
+#: `bad` — the toolchain is broken here, and `doctor` exits non-zero.
+OK, WARN, BAD = "ok", "warn", "bad"
+
+MARKS = {OK: "[green]✓[/green]", WARN: "[yellow]•[/yellow]", BAD: "[red]✗[/red]"}
+
+
+@dataclass(frozen=True)
+class Check:
+    label: str
+    status: str
+    detail: str
+    hint: str | None = None
+
+
+def _python() -> Check:
+    if not toolchain.python_is_supported():
+        least = ".".join(str(part) for part in toolchain.MINIMUM_PYTHON)
+        return Check("python", BAD, toolchain.python_version(),
+                     f"FHERMA needs Python {least} or newer.")
+    # The interpreter's path goes on the hint line: it is long, it wraps badly,
+    # and it is only ever read when the answer is "not the python you think".
+    return Check("python", OK, toolchain.python_version(), sys.executable)
+
+
+def _packages() -> list[Check]:
+    checks = []
+    for component in toolchain.components():
+        if component.installed:
+            checks.append(Check(component.name, OK, component.version))
+        else:
+            # Only reachable when someone installed the two halves separately
+            # and got one of them; `pip install fherma` cannot produce it.
+            checks.append(Check(component.name, BAD, "not installed",
+                                f"Run `pip install {component.name}`."))
+    return checks
+
+
+def _commands() -> Check:
+    groups = toolchain.groups()
+    if not groups:
+        return Check("commands", BAD, "none registered",
+                     "Reinstall: entry points are missing from the metadata.")
+    extra = {group.name for group in toolchain.plugins()}
+    names = ", ".join(
+        f"{group.name} ({group.source})" if group.name in extra else group.name
+        for group in groups
+    )
+    return Check("commands", OK, names)
+
+
+def _profile(profile: config.Profile) -> list[Check]:
+    where = config.CONFIG_FILE if config.CONFIG_FILE.exists() else None
+    checks = [Check("profile", OK, f"{profile.name} → {profile.url}",
+                    None if where else "No config file yet; defaults are in use.")]
+    if profile.token:
+        checks.append(Check("credentials", OK, "token present"))
+    else:
+        # Not a failure: `--signature` scaffolding never touches the platform.
+        checks.append(Check("credentials", WARN, "no token",
+                            "Run `fherma auth login` when you need the platform."))
+    return checks
+
+
+def _platform(context) -> Check:
+    try:
+        who = context.api.whoami()
+    except Exception as error:  # noqa: BLE001 — doctor reports, never raises
+        return Check("platform", BAD, "unreachable", getattr(error, "message", str(error)))
+    name = who.get("email") or who.get("name") or "authenticated"
+    return Check("platform", OK, name)
+
+
+@click.command()
+@click.option("--online", is_flag=True,
+              help="Also contact the platform and check the token is accepted.")
+@click.pass_obj
+def doctor(context, online: bool) -> None:
+    """Check that the toolchain is installed and whole.
+
+    Offline by default, because the usual reason to run this is that something
+    is wrong, and a network timeout would bury the answer.
+
+    \b
+    Exits 1 if anything is broken. A missing token is not broken: scaffolding
+    from a local signature never needs one.
+    """
+    checks = [_python(), *_packages(), _commands(), *_profile(context.profile)]
+    if online:
+        checks.append(_platform(context))
+
+    output.emit({
+        "checks": [{"name": c.label, "status": c.status, "detail": c.detail} for c in checks],
+        "ok": all(c.status != BAD for c in checks),
+        **toolchain.summary(),
+    })
+
+    width = max(len(check.label) for check in checks)
+    indent = " " * (width + 4)   # past the mark, the label and the gap
+    for check in checks:
+        output.say(f"{MARKS[check.status]} {check.label:<{width}}  {check.detail}")
+        if check.hint:
+            output.note(f"{indent}{check.hint}")
+
+    broken = [check for check in checks if check.status == BAD]
+    if broken:
+        raise CheckFailed(
+            f"{len(broken)} of {len(checks)} checks failed",
+            hint=broken[0].hint or f"Start with: {broken[0].label}.",
+        )
+
+
+@click.command()
+@click.argument("shell", required=False,
+                type=click.Choice(["bash", "zsh", "fish"], case_sensitive=False))
+@click.pass_context
+def completion(context: click.Context, shell: str | None) -> None:
+    """Print a shell completion script for `fherma`.
+
+    \b
+    Append it to the file your shell already reads:
+        fherma completion zsh  >> ~/.zshrc
+        fherma completion bash >> ~/.bashrc
+        fherma completion fish  > ~/.config/fish/completions/fherma.fish
+
+    The shell is guessed from $SHELL when not named.
+    """
+    from click.shell_completion import get_completion_class
+
+    shell = (shell or _guess_shell() or "").lower()
+    if not shell:
+        raise click.UsageError("cannot tell which shell this is; name one: bash, zsh, fish")
+
+    completion_class = get_completion_class(shell)
+    if completion_class is None:  # pragma: no cover — Choice has already filtered
+        raise click.UsageError(f"no completion support for {shell}")
+
+    # The root command, not this one: completion is for the whole tool. Reading
+    # it off the context avoids importing `cli`, which imports this module.
+    root = context.find_root().command
+    script = completion_class(root, {}, "fherma", "_FHERMA_COMPLETE").source()
+    click.echo(script)
+
+
+def _guess_shell() -> str | None:
+    return os.path.basename(os.environ.get("SHELL", "")) or None