sci-protocol 0.2.0__py3-none-any.whl

pysci/_cli/main.py

@@ -0,0 +1,229 @@
+"""The ``sci`` command: argument parsing, dispatch, and error reporting."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import os
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from typing import TextIO
+
+from pysci import PROTOCOL_VERSION
+from pysci import __version__ as pysci_version
+
+from . import __version__
+from .clients.http import Transport
+from .context import Context, run_command
+from .errors import EXIT_MEANINGS, CliError, Exit
+from .output import Result, render
+from .spec import add_command
+
+DRAFT_GUIDE = """\
+write a publication (complete rules: `sci spec --section 2` and `--section 4`):
+  draft/
+    sci.json     required metadata, max 64 KiB
+    README.md    required main text, nonblank UTF-8 Markdown, max 1 MiB
+    LICENSE      written by `sci license` (CC BY 4.0 text/figures/data, MIT code)
+    files/       optional code, data, figures; max 1,000 files, ZIP max 64 MiB
+  sci.json example:
+    {
+      "title": "Spike timing predicts choice in mouse V1 across three datasets",
+      "abstract": "Question, approach, main finding, and main limitation.",
+      "categories": [{"scheme": "arxiv", "code": "q-bio.NC"}],
+      "keywords": ["spike timing", "decision making"],
+      "display": [{"path": "files/accuracy.png", "caption": "Accuracy by time bin."}],
+      "citations": [
+        {"target": "sci:sha256:<64 hex digits>", "relations": ["uses"],
+         "reason": "We reuse its preprocessing code."},
+        {"target": "doi:10.48550/arXiv.1706.03762"},
+        {"target": "https://example.org/data/release-3"}
+      ]
+    }
+  Required: title (max 200 characters) and abstract (max 2,500). Optional:
+  categories (max 3 {scheme, code}; arxiv codes such as cs.LG, q-bio.NC),
+  keywords (max 20, each max 64 characters), display (max 3 paths under
+  files/ shown first; caption max 2,000), and citations (max 1,000). Display
+  files must be static .png images: max 2 MiB, 8,000,000 pixels, and 8,192
+  pixels per side (other formats can stay in files/ but not in display).
+  Omit unused fields; null and other fields are rejected.
+  Line breaks and tabs are allowed only in abstract, citation reason, README.md,
+  and LICENSE. File paths use only ASCII letters, digits, ".", "_", and "-"
+  per component (no spaces), max 255 bytes.
+  Citations: target is "sci:sha256:<digest>" (the ID printed by `sci sign`),
+  "doi:<DOI>" (no https://doi.org/ prefix), or an http(s) URL. Optional
+  relations: uses, reviews, supports, challenges, supersedes; optional reason
+  (max 1,000). Citations are signed: add them before signing.
+  `sci sign` adds manifest.json and manifest.json.sig to the draft. Changing
+  any file afterwards needs `sci sign --replace`, which creates a new ID. To
+  correct a published result, sign a new publication that cites the old one
+  with "relations": ["supersedes"].
+"""
+
+DESCRIPTION = f"""\
+sci: sign, verify, publish, and find SCI research publications (protocol {PROTOCOL_VERSION}).
+
+A publication is a signed folder or <digest>.zip with README.md, sci.json
+(metadata and citations), an optional LICENSE, and files/. Its ID is the
+SHA-256 of manifest.json: sha256:<digest>. Everything verifies offline.
+
+local campaign (offline):
+  sci keygen                                   create ~/.sci/key.pem (owner-only)
+  sci license ./draft                          select the SCI baseline license
+  sci check ./draft                            validate and size the draft
+  sci sign ./draft --no-timestamp --output ./campaign
+  sci verify ./campaign/<digest>.zip           complete bundle checks
+  sci search "neural decoding" --in ./campaign
+  sci search --in ./campaign --limit 50        list publications, then --cursor TOKEN
+  sci read ./campaign/<digest>.zip             verified metadata and README
+  sci read ./campaign/<digest>.zip --file files/data.csv --output data.csv
+                                               reuse one verified file
+  sci publish ./campaign --to ./mirror         copy verified ZIPs to a folder
+
+remote publishing:
+  sci sign ./draft --output ./campaign         sign + FreeTSA timestamp
+  sci publish ./campaign --to https://github.com/lab/research --create
+  sci index https://sciscape.io                choose an index (no default)
+  sci submit ./campaign --archive \\
+      https://github.com/lab/research
+  sci search "neural decoding" --in @index     catalog metadata, newest first
+  sci pull sha256:<digest>                     download and verify completely
+"""
+
+EPILOG = (
+    "Run `sci COMMAND --help` for arguments, outputs, file changes, network use, exit codes,\n"
+    "and an example. Add --json to any command for a machine-readable result object.\n"
+    "State lives in ~/.sci (override with SCI_HOME): config.json, key.pem, catalog.sqlite.\n"
+    "Jobs on one machine can share it; keep it on a local disk, not a network mount.\n\n"
+    "exit codes:\n" + "\n".join(f"  {code}  {text}" for code, text in EXIT_MEANINGS.items())
+)
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:  # type: ignore[override]
+        raise _UsageError(self, message)
+
+
+class _UsageError(Exception):
+    def __init__(self, parser: argparse.ArgumentParser, message: str) -> None:
+        super().__init__(message)
+        self.parser = parser
+
+
+def _deliver(write: Callable[[], object], out: TextIO, err: TextIO) -> None:
+    """Write output. A reader that has gone away (`sci ... | head`) does not change the result."""
+    try:
+        write()
+        out.flush()
+        err.flush()
+    except BrokenPipeError:
+        # Point the closed streams at /dev/null so interpreter shutdown cannot fail on them.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        for stream in (out, err):
+            with contextlib.suppress(OSError, ValueError):
+                os.dup2(devnull, stream.fileno())
+        os.close(devnull)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    from .commands import COMMANDS
+
+    parser = _Parser(
+        prog="sci",
+        description=DESCRIPTION + "\n" + DRAFT_GUIDE,
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"sci {__version__} (pysci {pysci_version}, SCI protocol {PROTOCOL_VERSION})",
+    )
+    subparsers = parser.add_subparsers(
+        dest="command", metavar="COMMAND", title="commands", parser_class=_Parser
+    )
+    for command in COMMANDS:
+        add_command(subparsers, command)
+    return parser
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    env: Mapping[str, str] | None = None,
+    transport: Transport | None = None,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+    stdin: TextIO | None = None,
+    sleep: Callable[[float], None] | None = None,
+    runner: Callable[[Sequence[str], float], str | None] | None = None,
+    cwd: Path | None = None,
+) -> int:
+    """Run the CLI; return the exit code. Keyword arguments allow embedding and tests."""
+    out = stdout or sys.stdout
+    err = stderr or sys.stderr
+    args_list = list(sys.argv[1:] if argv is None else argv)
+    parser = build_parser()
+    wants_json = "--json" in args_list
+    try:
+        parsed: list[argparse.Namespace] = []
+
+        def parse() -> None:
+            with contextlib.redirect_stdout(out):
+                parsed.append(parser.parse_args(args_list))
+
+        _deliver(parse, out, err)
+        if not parsed:  # --help or --version, and the reader closed the pipe
+            return 0
+        args = parsed[0]
+    except _UsageError as exc:
+        command = getattr(exc.parser, "prog", "sci").removeprefix("sci").strip() or "sci"
+        if wants_json:
+            result = Result(command, exit_code=Exit.USAGE)
+            result.errors.append(CliError("usage", str(exc)).records[0])
+            _deliver(lambda: render(result, as_json=True, stdout=out, stderr=err), out, err)
+        else:
+            usage_parser = exc.parser
+            message = f"{usage_parser.prog}: error: {exc}\n"
+
+            def report_usage() -> None:
+                usage_parser.print_usage(err)
+                err.write(message)
+
+            _deliver(report_usage, out, err)
+        return int(Exit.USAGE)
+    except SystemExit as exc:  # --help and --version
+        _deliver(lambda: None, out, err)
+        return int(exc.code or 0) if isinstance(exc.code, int) else 0
+    if args.command is None:
+        _deliver(lambda: parser.print_help(out), out, err)
+        return int(Exit.USAGE)
+    import time
+
+    ctx = Context(
+        env=dict(os.environ if env is None else env),
+        stdout=out,
+        stderr=err,
+        stdin=stdin or sys.stdin,
+        transport=transport,
+        sleep=sleep or time.sleep,
+        runner=runner or run_command,
+        cwd=cwd or Path.cwd(),
+    )
+    try:
+        result = args.handler(args, ctx)
+    except CliError as exc:
+        result = Result(args.command_name, exit_code=exc.exit_code, data=exc.result)
+        result.errors.extend(exc.records)
+    except KeyboardInterrupt:
+        result = Result(args.command_name, exit_code=Exit.INCOMPLETE)
+        result.errors.append(
+            CliError("interrupted", "interrupted; completed items were kept").records[0]
+        )
+    _deliver(lambda: render(result, as_json=args.json, stdout=out, stderr=err), out, err)
+    return int(result.exit_code)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

pysci/_cli/output.py

@@ -0,0 +1,80 @@
+"""Result objects and their rendering as human text or ``--json`` machine output."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, TextIO
+
+from .errors import EXIT_MEANINGS, ErrorRecord, Exit
+
+
+@dataclass(slots=True)
+class Result:
+    """The outcome of one command.
+
+    ``data`` is the machine-readable result object; ``lines`` is the human
+    text. Errors and warnings are rendered for both audiences.
+    """
+
+    command: str
+    data: dict[str, Any] = field(default_factory=dict)
+    exit_code: int = Exit.OK
+    errors: list[ErrorRecord] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    lines: list[str] = field(default_factory=list)
+    partial: bool = False
+
+    def say(self, line: str = "") -> None:
+        self.lines.append(line)
+
+    def warn(self, message: str) -> None:
+        self.warnings.append(message)
+
+    def error(self, record: ErrorRecord) -> None:
+        self.errors.append(record)
+
+    @property
+    def status(self) -> str:
+        if self.exit_code == Exit.OK:
+            return "ok"
+        if self.partial:
+            return "partial"
+        return "failed"
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "command": self.command,
+            "status": self.status,
+            "exit_code": int(self.exit_code),
+            "result": self.data,
+            "errors": [record.to_json() for record in self.errors],
+            "warnings": list(self.warnings),
+        }
+
+
+def render(result: Result, *, as_json: bool, stdout: TextIO, stderr: TextIO) -> None:
+    if as_json:
+        stdout.write(json.dumps(result.to_json(), indent=2, ensure_ascii=False, sort_keys=False))
+        stdout.write("\n")
+        return
+    for line in result.lines:
+        stdout.write(line + "\n")
+    for warning in result.warnings:
+        stderr.write(f"warning: {warning}\n")
+    # Commands such as `check` list their issues in the report itself; do not
+    # print the same problem a second time on stderr.
+    shown = {line.strip() for line in result.lines}
+    for record in result.errors:
+        text = str(record)
+        if text in shown or text.removesuffix(" (retrying may help)") in shown:
+            continue
+        stderr.write(f"error: {text}\n")
+    if result.exit_code != Exit.OK:
+        meaning = EXIT_MEANINGS.get(int(result.exit_code), "")
+        label = "partial result" if result.partial else "failed"
+        stderr.write(f"sci {result.command}: {label} (exit {int(result.exit_code)}: {meaning})\n")
+
+
+def indent(text: str, prefix: str = "  ") -> list[str]:
+    return [prefix + line if line else line for line in text.splitlines()]

pysci/_cli/retrieval.py

@@ -0,0 +1,51 @@
+"""Resolving publication sources by ID: index lookup (§8.1.1) or explicit archives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .clients.http import Deadline
+from .clients.index import IndexClient
+from .commands.common import archive_urls, index_origin
+from .context import Context
+from .errors import CliError, Exit
+
+
+@dataclass(frozen=True, slots=True)
+class Sources:
+    descriptors: list[str]
+    index: IndexClient | None
+
+
+def resolve_sources(
+    ctx: Context,
+    digest: str,
+    *,
+    archives: list[str] | None,
+    index_url: str | None,
+    deadline: Deadline,
+) -> Sources:
+    """Archive descriptor URLs for ``digest``.
+
+    Explicit ``--archive`` URLs need no index. Otherwise the configured index
+    or ``--in URL`` is asked; ``404`` or an empty list is ``no_known_sources``.
+    """
+    explicit = archive_urls(archives)
+    if explicit and index_url:
+        raise CliError("conflicting_options", "use either --archive or --in, not both")
+    if explicit:
+        return Sources(explicit, None)
+    client = IndexClient(ctx.http, index_origin(ctx, index_url, option="--in"))
+    descriptors = client.lookup(digest, deadline)
+    unique: list[str] = []
+    for url in descriptors:
+        if url not in unique:
+            unique.append(url)
+    if not unique:
+        raise CliError(
+            "no_known_sources",
+            f"index {client.origin} knows no sources for sha256:{digest}",
+            Exit.INCOMPLETE,
+            retryable=True,
+        )
+    return Sources(unique, client)

pysci/_cli/spec.py

@@ -0,0 +1,113 @@
+"""Command definitions from which the argument parser and the help text are generated."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from .errors import EXIT_MEANINGS
+
+if TYPE_CHECKING:
+    from .context import Context
+    from .output import Result
+
+
+@dataclass(frozen=True)
+class Arg:
+    flags: tuple[str, ...]
+    help: str
+    kwargs: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def positional(self) -> bool:
+        return not self.flags[0].startswith("-")
+
+
+def arg(*flags: str, help: str, **kwargs: Any) -> Arg:
+    return Arg(tuple(flags), help, kwargs)
+
+
+TIMEOUT_ARG = arg(
+    "--timeout",
+    type=float,
+    metavar="SECONDS",
+    default=120.0,
+    help="operation deadline including retries; for batches, per publication and destination",
+)
+
+
+@dataclass(frozen=True)
+class Command:
+    """One subcommand: arguments, documentation sections, and its handler."""
+
+    name: str
+    usage_hint: str
+    summary: str
+    description: str
+    args: tuple[Arg, ...]
+    outputs: str
+    files: str
+    network: str
+    exit_codes: dict[int, str]
+    examples: tuple[str, ...]
+    run: Callable[[argparse.Namespace, Context], Result]
+    timeout: bool = False
+
+    def epilog(self) -> str:
+        lines = ["output:"]
+        lines += [f"  {line}" for line in self.outputs.strip().splitlines()]
+        lines += ["  --json prints one result object (command, status, exit_code, result,"]
+        lines += ["  errors with code/message/retryable, warnings) instead of text."]
+        lines += ["", "files changed:"]
+        lines += [f"  {line}" for line in self.files.strip().splitlines()]
+        lines += ["", "network:"]
+        lines += [f"  {line}" for line in self.network.strip().splitlines()]
+        lines += ["", "exit codes:"]
+        codes = {0: EXIT_MEANINGS[0], 2: EXIT_MEANINGS[2], **self.exit_codes}
+        for code in sorted(codes):
+            lines.append(f"  {code}  {codes[code]}")
+        lines += ["", "example:" if len(self.examples) == 1 else "examples:"]
+        lines += [f"  {example}" for example in self.examples]
+        return "\n".join(lines)
+
+
+def _help_text(spec: Arg) -> str:
+    text = spec.help
+    default = spec.kwargs.get("default")
+    if (
+        default not in (None, False, argparse.SUPPRESS, [])
+        and "default" not in text
+        and spec.kwargs.get("action") not in ("store_true", "store_false")
+    ):
+        text += " (default: %(default)s)"
+    return text.replace("%", "%%").replace("%%(default)s", "%(default)s")
+
+
+class _Formatter(argparse.RawDescriptionHelpFormatter):
+    def __init__(self, prog: str) -> None:
+        super().__init__(prog, max_help_position=30, width=100)
+
+
+def add_command(subparsers: Any, command: Command) -> argparse.ArgumentParser:
+    parser: argparse.ArgumentParser = subparsers.add_parser(
+        command.name,
+        help=command.summary,
+        description=f"{command.summary}\n\n{command.description.strip()}",
+        epilog=command.epilog(),
+        formatter_class=_Formatter,
+        usage=f"sci {command.usage_hint}" if command.usage_hint else None,
+    )
+    positional = [a for a in command.args if a.positional]
+    optional = [a for a in command.args if not a.positional]
+    for spec in positional:
+        parser.add_argument(*spec.flags, help=_help_text(spec), **spec.kwargs)
+    for spec in optional:
+        parser.add_argument(*spec.flags, help=_help_text(spec), **spec.kwargs)
+    common = parser.add_argument_group("common options")
+    common.add_argument("--json", action="store_true", help="print a machine-readable JSON result")
+    if command.timeout:
+        common.add_argument(*TIMEOUT_ARG.flags, help=_help_text(TIMEOUT_ARG), **TIMEOUT_ARG.kwargs)
+    parser.set_defaults(handler=command.run, command_name=command.name)
+    return parser