stashapp-cli 0.1.0__py3-none-any.whl

stashapp_cli/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from stashapp-cli!"

stashapp_cli/cli.py

@@ -0,0 +1,149 @@
+"""stashapp-cli: inspect and modify Stash's GraphQL entities directly.
+
+Layers: a raw `graphql` escape hatch, generic per-resource `find`/`get`/
+`create`/`update` commands, and named platform-quirk commands (`tag
+find-or-create`, `scrape group-url`/`scene-url`). Every mutating command is
+gated by the global `--apply` flag (dry-run by default); destructive commands
+(`performer merge`, and raw GraphQL *Destroy/*Delete/*Merge, ...) additionally
+require `--force`. Results print as JSON on stdout; human-facing status and
+errors print to stderr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.metadata
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+
+from . import commands, core
+from .commands._common import add_examples, positive_seconds
+
+
+def _package_version() -> str:
+    """Return installed metadata, with a source-tree fallback for development."""
+    try:
+        return importlib.metadata.version("stashapp-cli")
+    except importlib.metadata.PackageNotFoundError:
+        pyproject = Path(__file__).parents[2] / "pyproject.toml"
+        try:
+            import tomllib
+
+            return tomllib.loads(pyproject.read_text())["project"]["version"]
+        except (OSError, KeyError, tomllib.TOMLDecodeError):
+            return "unknown"
+
+
+def _emit_error(error: core.CliError, json_errors: bool) -> None:
+    if json_errors:
+        core.output(
+            {"error": {"code": error.code, "message": str(error), **error.details}}
+        )
+    else:
+        print(str(error), file=sys.stderr)
+
+
+def _normalize_apply(argv: list[str]) -> list[str]:
+    """Normalize global arguments that argparse cannot otherwise disambiguate."""
+    normalized = list(argv)
+    for index, value in enumerate(normalized[:-1]):
+        if value == "--timeout" and normalized[index + 1].lower() in {
+            "-inf",
+            "-infinity",
+        }:
+            normalized[index : index + 2] = [f"--timeout={normalized[index + 1]}"]
+            break
+    if normalized.count("--apply") != 1:
+        return normalized
+    index = normalized.index("--apply")
+    if index == 0:
+        return normalized
+    return ["--apply", *normalized[:index], *normalized[index + 1 :]]
+
+
+# --- entrypoint ------------------------------------------------------------
+
+
+def iter_leaf_commands(
+    parser: argparse.ArgumentParser, path: tuple[str, ...] = ()
+) -> Iterator[tuple[tuple[str, ...], argparse.ArgumentParser]]:
+    """Yield `(path, parser)` for every leaf command below `parser`."""
+    subparsers = [
+        action
+        for action in parser._actions
+        if isinstance(action, argparse._SubParsersAction)
+    ]
+    if not subparsers:
+        yield path, parser
+        return
+    for action in subparsers:
+        for name, child in action.choices.items():
+            yield from iter_leaf_commands(child, (*path, name))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="stashapp-cli", description=__doc__)
+    parser.add_argument(
+        "--apply",
+        action="store_true",
+        help=(
+            "Perform mutating commands instead of reporting a dry run "
+            "(default: dry-run; inert on read-only commands)."
+        ),
+    )
+    parser.add_argument(
+        "--json-errors",
+        action="store_true",
+        help="Write expected failures as one JSON error envelope on stdout.",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=positive_seconds,
+        default=core.DEFAULT_TIMEOUT,
+        metavar="SECONDS",
+        help="Maximum seconds for each Stash request (default: 30).",
+    )
+    parser.add_argument("--version", action="version", version=_package_version())
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    for module in commands.COMMAND_MODULES:
+        module.register(subparsers)
+    add_examples(
+        parser,
+        "export STASH_URL=http://localhost:9999; export STASH_API_KEY",
+        "stashapp-cli studio find --name ExampleStudio",
+        'stashapp-cli group create --input \'{"name": "Film"}\'',
+        "stashapp-cli group create --input @group.json --apply",
+        "stashapp-cli --json-errors --timeout 5 scene get 1",
+    )
+    parser.epilog = (parser.epilog or "") + (
+        "\n\nExit statuses: 0 success; 1 runtime or GraphQL failure; "
+        "2 usage or invalid input (including destructive_mutation: a destructive\n"
+        "command sent with --apply but without --force); "
+        "3 Stash endpoint returned HTTP 404; "
+        "4 missing credential or authentication failure."
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(
+        _normalize_apply(list(argv))
+        if argv is not None
+        else _normalize_apply(sys.argv[1:])
+    )
+    try:
+        with core.request_timeout(args.timeout):
+            result = args.func(args)
+    except core.CliError as error:
+        _emit_error(error, args.json_errors)
+        sys.exit(error.exit_code)
+    except Exception as error:  # noqa: BLE001
+        _emit_error(core.CliError(f"Unexpected error: {error}", 1), args.json_errors)
+        sys.exit(1)
+    core.output(result)
+
+
+if __name__ == "__main__":
+    main()

stashapp_cli/commands/__init__.py

@@ -0,0 +1,39 @@
+"""stashapp-cli command modules, one per noun.
+
+Each module exposes `register(subparsers)`. `cli.build_parser` registers them
+in the order of `COMMAND_MODULES`, which is also the order in `--help`.
+"""
+
+from __future__ import annotations
+
+from . import (
+    backup,
+    generate,
+    graphql,
+    group,
+    introspect,
+    job,
+    performer,
+    scan,
+    scene,
+    scrape,
+    stashbox,
+    studio,
+    tag,
+)
+
+COMMAND_MODULES = (
+    studio,
+    tag,
+    group,
+    scene,
+    performer,
+    scrape,
+    scan,
+    generate,
+    job,
+    backup,
+    stashbox,
+    introspect,
+    graphql,
+)

stashapp_cli/commands/_common.py

@@ -0,0 +1,440 @@
+"""Helpers shared by the command modules."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from .. import core, images
+
+
+class CommandKind(StrEnum):
+    """Whether a leaf command reads, writes, or makes an irreversible change."""
+
+    READ = "read"
+    WRITE = "write"
+    DESTRUCTIVE = "destructive"
+
+
+_KIND_NOTES = {
+    CommandKind.READ: "Read command: never changes Stash; --apply has no effect.",
+    CommandKind.WRITE: "Write command: a dry run unless --apply is given.",
+    CommandKind.DESTRUCTIVE: (
+        "Destructive command: a dry run unless --apply is given. An\n"
+        "irreversible change also needs --force; without it the command exits 2\n"
+        "with code destructive_mutation."
+    ),
+}
+
+FORCE_HELP = "Required with --apply to send an irreversible change; there is no undo."
+
+
+def add_examples(parser: argparse.ArgumentParser, *examples: str) -> None:
+    parser.epilog = "Examples:\n  " + "\n  ".join(examples)
+    parser.formatter_class = argparse.RawDescriptionHelpFormatter
+
+
+def add_leaf(
+    subparsers: argparse._SubParsersAction,
+    name: str,
+    *,
+    kind: CommandKind,
+    func: Callable[[argparse.Namespace], object],
+    help: str,
+    examples: tuple[str, ...],
+) -> argparse.ArgumentParser:
+    """Register a leaf command with its kind, examples, and kind note.
+
+    Destructive commands get `--force`; no other kind does.
+    """
+    parser = subparsers.add_parser(name, help=help)
+    parser.set_defaults(func=func, kind=kind)
+    add_examples(parser, *examples)
+    parser.epilog = f"{parser.epilog}\n\n{_KIND_NOTES[kind]}"
+    if kind is CommandKind.DESTRUCTIVE:
+        parser.add_argument("--force", action="store_true", help=FORCE_HELP)
+    return parser
+
+
+def object_id(value: str, noun: str) -> str:
+    """Return `value`, or raise usage_error unless it is ASCII digits.
+
+    Checked in the command, not with an argparse `type=`, so that
+    `--json-errors` reports the `usage_error` code.
+    """
+    if not (value.isascii() and value.isdigit()):
+        raise core.CliError(
+            f"{noun.capitalize()} ID must be a non-negative integer, not {value!r}.",
+            2,
+            "usage_error",
+        )
+    return value
+
+
+def add_get_command(
+    subparsers: argparse._SubParsersAction,
+    noun: str,
+    get: Callable[[str], dict | None],
+    *,
+    example_id: int,
+) -> argparse.ArgumentParser:
+    """Register `<noun> get ID`, a read that prints one object or `null`."""
+    leaf = add_leaf(
+        subparsers,
+        "get",
+        kind=CommandKind.READ,
+        func=lambda args: get(object_id(args.id, noun)),
+        help=f"Fetch one {noun} by ID, or null if there is none.",
+        examples=(f"stashapp-cli {noun} get {example_id}",),
+    )
+    leaf.description = (
+        f"Print the {noun} with this ID as one JSON object, with the fields that\n"
+        f"`{noun} find` returns. Print null when no {noun} has this ID."
+    )
+    leaf.add_argument(
+        "id", metavar="ID", help=f"{noun.capitalize()} ID: a non-negative integer."
+    )
+    return leaf
+
+
+def read_text_arg(value: str) -> str:
+    """Read raw text from a literal value, `@file`, or `@-` (stdin)."""
+    if value.startswith("@"):
+        path = value[1:]
+        if path == "-":
+            return sys.stdin.read()
+        try:
+            return Path(path).read_text()
+        except OSError as error:
+            raise core.CliError(
+                f"Could not read {path}: {error}", 2, "usage_error"
+            ) from error
+    return value
+
+
+def read_json_arg(value: str) -> dict:
+    """Read JSON from a literal value, `@file`, or `@-` (stdin)."""
+    try:
+        return json.loads(read_text_arg(value))
+    except json.JSONDecodeError as error:
+        raise core.CliError(
+            f"Invalid JSON argument: {error}", 2, "usage_error"
+        ) from error
+
+
+def require_force(args: argparse.Namespace, matched: list[str]) -> None:
+    """Refuse an applied destructive change unless `--force` was given.
+
+    `matched` names what makes the change destructive; empty means it is not.
+    Call after the dry-run branch so `--force` without `--apply` stays a dry run.
+    """
+    if args.apply and matched and not args.force:
+        raise core.CliError(
+            "Refusing to send destructive mutation (matched: "
+            + ", ".join(matched)
+            + "); there is no undo. Re-run with --apply --force if this is intended.",
+            2,
+            "destructive_mutation",
+        )
+
+
+def add_update_target(parser: argparse.ArgumentParser, input_type: str) -> None:
+    """Add the optional positional ID and optional `--input` of an update."""
+    parser.add_argument(
+        "id",
+        nargs="?",
+        default=None,
+        metavar="ID",
+        help="Object to update; fills or must match the id in --input.",
+    )
+    parser.add_argument(
+        "--input",
+        default=None,
+        help=f"{input_type} as JSON, @file, or @- (optional when ID is given).",
+    )
+
+
+def resolve_update_input(
+    args: argparse.Namespace, overrides: dict | None = None
+) -> dict:
+    """Merge the positional ID into `--input` and check that there is a change.
+
+    `overrides` holds fields that options set; they replace the same fields in
+    `--input` and count as a change.
+    """
+    if args.id is None:
+        if args.input is None:
+            raise core.CliError("Pass an ID or --input.", 2, "usage_error")
+        input_data = read_json_arg(args.input)
+        if overrides and isinstance(input_data, dict):
+            input_data.update(overrides)
+        return input_data
+
+    input_data = read_json_arg(args.input) if args.input is not None else {}
+    if not isinstance(input_data, dict):
+        raise core.CliError(
+            "--input must be a JSON object when ID is given.", 2, "usage_error"
+        )
+    input_data.update(overrides or {})
+    if "id" in input_data:
+        if str(input_data["id"]) != args.id:
+            raise core.CliError(
+                f"ID {args.id} does not match id {input_data['id']} in --input.",
+                2,
+                "usage_error",
+            )
+    else:
+        input_data["id"] = args.id
+    if input_data.keys() == {"id"}:
+        raise core.CliError(
+            f"Nothing to update for ID {args.id}; pass the fields to change in "
+            "--input, or an --add-* or --remove-* option.",
+            2,
+            "usage_error",
+        )
+    return input_data
+
+
+@dataclass(frozen=True)
+class ListField:
+    """A list field that `--add-<option>` and `--remove-<option>` change in bulk."""
+
+    option: str  # "tag-id", "url", "performer-id", "alias"
+    field: str  # "tag_ids", "urls", "performer_ids", "alias_list"
+    key: str  # "ids" (BulkUpdateIds) or "values" (BulkUpdateStrings)
+    metavar: str  # "TAG_ID", "URL", "PERFORMER_ID", "ALIAS"
+
+    @property
+    def dests(self) -> tuple[str, str]:
+        name = self.option.replace("-", "_")
+        return f"add_{name}", f"remove_{name}"
+
+
+TAG_IDS = ListField("tag-id", "tag_ids", "ids", "TAG_ID")
+URLS = ListField("url", "urls", "values", "URL")
+PERFORMER_IDS = ListField("performer-id", "performer_ids", "ids", "PERFORMER_ID")
+ALIASES = ListField("alias", "alias_list", "values", "ALIAS")
+STUDIO_ALIASES = ListField("alias", "aliases", "values", "ALIAS")
+TAG_ALIASES = ListField("alias", "aliases", "values", "ALIAS")
+PARENT_IDS = ListField("parent-id", "parent_ids", "ids", "PARENT_ID")
+CHILD_IDS = ListField("child-id", "child_ids", "ids", "CHILD_ID")
+
+LIST_OPTION_NOTE = "Repeatable; needs ID and cannot be combined with --input."
+
+
+def add_list_options(
+    parser: argparse.ArgumentParser, fields: tuple[ListField, ...]
+) -> None:
+    """Register repeatable `--add-<option>` and `--remove-<option>` for `fields`."""
+    for list_field in fields:
+        add_dest, remove_dest = list_field.dests
+        for verb, dest in (("add", add_dest), ("remove", remove_dest)):
+            parser.add_argument(
+                f"--{verb}-{list_field.option}",
+                dest=dest,
+                action="append",
+                default=None,
+                metavar=list_field.metavar,
+                help=f"{verb.capitalize()} one {list_field.field} value. "
+                + LIST_OPTION_NOTE,
+            )
+
+
+def unique(values: list[str]) -> list[str]:
+    """`values` without repeats, in the order first given."""
+    return list(dict.fromkeys(values))
+
+
+def bulk_update_input(
+    args: argparse.Namespace, fields: tuple[ListField, ...]
+) -> dict | None:
+    """The `BulkUpdate*` input for the list options in `fields`, or `None`."""
+    input_data: dict = {"ids": [args.id]}
+    for list_field in fields:
+        add_dest, remove_dest = list_field.dests
+        add, remove = getattr(args, add_dest), getattr(args, remove_dest)
+        if add and remove:
+            raise core.CliError(
+                f"--add-{list_field.option} and --remove-{list_field.option} "
+                "cannot be combined; run two commands.",
+                2,
+                "usage_error",
+            )
+        if add or remove:
+            input_data[list_field.field] = {
+                list_field.key: unique(add or remove),
+                "mode": "ADD" if add else "REMOVE",
+            }
+    return input_data if len(input_data) > 1 else None
+
+
+def require_list_target(args: argparse.Namespace) -> None:
+    """Check that add and remove options have the positional ID and no `--input`."""
+    if args.id is None:
+        raise core.CliError(
+            "The --add-* and --remove-* options need the ID argument.",
+            2,
+            "usage_error",
+        )
+    if args.input is not None:
+        raise core.CliError(
+            "The --add-* and --remove-* options cannot be combined with --input; "
+            "run two commands.",
+            2,
+            "usage_error",
+        )
+
+
+def mutation_result(operation: str, apply: bool, input_data: dict, perform):
+    """Dry-run report of `input_data`, or perform the write and report its id."""
+    if not apply:
+        # Image data URIs are left out of the report; `perform` sends them as given.
+        report = images.replace_images(input_data, None)
+        return {"applied": False, "operation": operation, "input": report}
+    return {"applied": True, "operation": operation, "id": perform()}
+
+
+def job_result(operation: str, apply: bool, input_data: dict, perform):
+    """Dry-run report of `input_data`, or start the job and report its job id."""
+    if not apply:
+        return {"applied": False, "operation": operation, "input": input_data}
+    return {"applied": True, "operation": operation, "job_id": perform()}
+
+
+def read_input_object(value: str | None) -> dict:
+    """Read an optional `--input` that must be a JSON object; `{}` when absent."""
+    if value is None:
+        return {}
+    input_data = read_json_arg(value)
+    if not isinstance(input_data, dict):
+        raise core.CliError("--input must be a JSON object.", 2, "usage_error")
+    return input_data
+
+
+def positive_seconds(value: str) -> float:
+    """Argparse type for a positive, finite number of seconds."""
+    # argparse prefixes the option name, for example "argument --timeout: ...".
+    message = "must be a positive number of seconds"
+    try:
+        seconds = float(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(message) from error
+    if not math.isfinite(seconds) or seconds <= 0:
+        raise argparse.ArgumentTypeError(message)
+    return seconds
+
+
+def positive_int(value: str) -> int:
+    """Argparse type for an integer of 1 or more."""
+    message = "must be an integer of 1 or more"
+    try:
+        number = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(message) from error
+    if number < 1:
+        raise argparse.ArgumentTypeError(message)
+    return number
+
+
+@dataclass(frozen=True)
+class FindSpec:
+    """How one `find` command differs from the others."""
+
+    result_key: str  # "studios", "groups", "scenes", "performers", "tags"
+    name_field: str  # the criterion that --name sets: "name", or "title" for scenes
+    match_aliases: bool  # whether --name also matches the aliases criterion
+    sort: str  # "name", or "path" for scenes
+
+
+# A filter level may hold only one of these, so options cannot be merged next
+# to one the caller gave.
+_SUB_FILTERS = ("AND", "OR", "NOT")
+
+
+def add_find_options(parser: argparse.ArgumentParser, spec: FindSpec) -> None:
+    """Add `--name`, `--filter-json`, `--page`, and `--per-page`, and note the result."""
+    if spec.match_aliases:
+        matches = f"the {spec.name_field} or any alias"
+    elif spec.name_field == "name":
+        matches = "the name only, not aliases"
+    else:
+        matches = f"the {spec.name_field}"
+    parser.add_argument(
+        "--name",
+        default=None,
+        help=f"Match {matches} exactly, ignoring case.",
+    )
+    parser.add_argument(
+        "--filter-json",
+        default=None,
+        help="Filter object as JSON, @file, or @- (default: match everything).",
+    )
+    parser.add_argument("--page", type=positive_int, default=1, help="Default: 1.")
+    parser.add_argument(
+        "--per-page", type=positive_int, default=50, help="Default: 50."
+    )
+    parser.epilog = f"{parser.epilog}\n\n" + (
+        f'Prints {{"count": N, "{spec.result_key}": [...]}}: the number of matches '
+        f"and one page\nof them, sorted by {spec.sort} ascending. Without --name or "
+        "--filter-json, every\nobject matches. --name is added to --filter-json, "
+        "so a match meets both. A\nfilter that already sets what --name sets, or "
+        "that has a top-level AND, OR,\nor NOT while --name is given, is a "
+        "usage_error."
+    )
+
+
+def find_filter(
+    args: argparse.Namespace, spec: FindSpec, extra: dict | None = None
+) -> dict:
+    """The filter to send: `--filter-json` with the `--name` and `extra` criteria.
+
+    `extra` holds criteria that other options set, such as `studios`. The name
+    criteria go under `AND`, because a level cannot hold both its own `OR` (the
+    alias match) and the caller's criteria combined by AND.
+    """
+    user = read_json_arg(args.filter_json) if args.filter_json is not None else {}
+    if not isinstance(user, dict):
+        raise core.CliError("--filter-json must be a JSON object.", 2, "usage_error")
+    if args.name == "":
+        raise core.CliError("--name needs a non-empty value.", 2, "usage_error")
+
+    extra = extra or {}
+    set_fields = list(extra)
+    if args.name is not None:
+        set_fields.append(spec.name_field)
+        if spec.match_aliases:
+            set_fields.append("aliases")
+    if conflicts := [field for field in set_fields if field in user]:
+        raise core.CliError(
+            f"--filter-json already has {', '.join(conflicts)}, which an option "
+            "also sets. Put the criterion in --filter-json or in the option, "
+            "not both.",
+            2,
+            "usage_error",
+        )
+    if not set_fields:
+        return user
+    if sub_filters := [key for key in _SUB_FILTERS if key in user]:
+        raise core.CliError(
+            f"--filter-json has a top-level {', '.join(sub_filters)}, so the "
+            "options cannot be added to it. Put the name, studio, or code "
+            "criterion in the filter instead.",
+            2,
+            "usage_error",
+        )
+
+    merged = {**user, **extra}
+    if args.name is not None:
+        name_filter: dict = {
+            spec.name_field: {"value": args.name, "modifier": "EQUALS"}
+        }
+        if spec.match_aliases:
+            name_filter["OR"] = {"aliases": {"value": args.name, "modifier": "EQUALS"}}
+        merged["AND"] = name_filter
+    return merged