stashapp-cli 0.1.0__py3-none-any.whl

stashapp_cli/commands/backup.py

@@ -0,0 +1,70 @@
+"""backup command: back up the Stash database."""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import core, queries
+from ._common import CommandKind, add_leaf
+
+_SERVER_LOG_MESSAGE = (
+    "Stash wrote the backup; its path is only in the Stash server log."
+)
+_DOWNLOAD_MESSAGE = (
+    "Stash wrote the backup to a temporary file; download it from download_url."
+)
+
+
+def cmd_backup(args: argparse.Namespace) -> object:
+    input_data = {"download": args.download}
+    if not args.apply:
+        return {"applied": False, "operation": "backupDatabase", "input": input_data}
+    try:
+        download_url = queries.backup.backup_database(args.download)
+    except core.CliError as error:
+        if error.code != "timeout":
+            raise
+        raise core.CliError(
+            f"{error} The backup may still finish on the Stash server; check the "
+            "server log, or re-run with a larger global --timeout "
+            "(for example --timeout 300).",
+            error.exit_code,
+            error.code,
+            error.details,
+        ) from error
+    return {
+        "applied": True,
+        "operation": "backupDatabase",
+        "download": args.download,
+        "download_url": download_url if args.download else None,
+        "message": _DOWNLOAD_MESSAGE if args.download else _SERVER_LOG_MESSAGE,
+    }
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    parser = add_leaf(
+        subparsers,
+        "backup",
+        kind=CommandKind.WRITE,
+        func=cmd_backup,
+        help="Back up the Stash database (dry-run by default; see global --apply).",
+        examples=(
+            "stashapp-cli backup",
+            "stashapp-cli backup --apply",
+            "stashapp-cli --timeout 300 backup --apply",
+            "stashapp-cli backup --download --apply",
+        ),
+    )
+    parser.add_argument(
+        "--download",
+        action="store_true",
+        help="Return a URL to download the backup instead of keeping it on the server.",
+    )
+    parser.epilog = f"{parser.epilog}" + (
+        "\n\nWithout --download, Stash keeps the backup in its backup directory on "
+        "the\nserver, and its path appears only in the Stash server log. With "
+        "--download,\nthe backup is a temporary file to download from "
+        "download_url; it is not\nkept in the backup directory. Stash finishes "
+        "the backup before it answers,\nso a large database can need a larger "
+        "global --timeout."
+    )

stashapp_cli/commands/generate.py

@@ -0,0 +1,88 @@
+"""generate commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import queries
+from ._common import CommandKind, add_leaf, job_result, read_input_object
+
+
+def generate_input(args: argparse.Namespace) -> dict:
+    """Build a GenerateMetadataInput: `--input`, then the options over their fields."""
+    input_data = read_input_object(args.input)
+    if args.phashes:
+        input_data["phashes"] = True
+    if args.covers:
+        input_data["covers"] = True
+    if args.scene_ids is not None:
+        input_data["sceneIDs"] = args.scene_ids
+    if args.paths is not None:
+        input_data["paths"] = args.paths
+    return input_data
+
+
+def cmd_generate_run(args: argparse.Namespace) -> object:
+    input_data = generate_input(args)
+    return job_result(
+        "metadataGenerate",
+        args.apply,
+        input_data,
+        lambda: queries.metadata.start_generate(input_data),
+    )
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    generate = subparsers.add_parser(
+        "generate", help="Start Stash generate jobs (phashes, covers, ...)."
+    )
+    generate_sub = generate.add_subparsers(dest="generate_command", required=True)
+
+    run = add_leaf(
+        generate_sub,
+        "run",
+        kind=CommandKind.WRITE,
+        func=cmd_generate_run,
+        help="Start a generate job and print its job id.",
+        examples=(
+            "stashapp-cli generate run --phashes --scene-id 812 --scene-id 813",
+            "stashapp-cli generate run --covers --path /media/new --apply",
+            "stashapp-cli generate run --scene-id 5 --input '{\"sprites\": true}'",
+        ),
+    )
+    run.description = (
+        "Start a Stash generate job (metadataGenerate) and print its job_id.\n"
+        "Wait for it with `stashapp-cli job wait JOB_ID`.\n"
+        "\n"
+        "Generate options that are left out are off. With no --scene-id and no\n"
+        "--path (and none in --input), Stash generates for the whole library."
+    )
+    run.add_argument(
+        "--phashes", action="store_true", help="Generate phashes (sets phashes)."
+    )
+    run.add_argument(
+        "--covers", action="store_true", help="Generate covers (sets covers)."
+    )
+    run.add_argument(
+        "--scene-id",
+        dest="scene_ids",
+        action="append",
+        default=None,
+        metavar="ID",
+        help="Scene to generate for; repeatable. Replaces sceneIDs in --input.",
+    )
+    run.add_argument(
+        "--path",
+        dest="paths",
+        action="append",
+        default=None,
+        metavar="PATH",
+        help="Path to generate for; repeatable. Replaces paths in --input.",
+    )
+    run.add_argument(
+        "--input",
+        default=None,
+        help=(
+            "GenerateMetadataInput as JSON, @file, or @-; options override its fields."
+        ),
+    )

stashapp_cli/commands/graphql.py

@@ -0,0 +1,212 @@
+"""graphql command: send a raw GraphQL document (escape hatch)."""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import core
+from ._common import (
+    CommandKind,
+    add_leaf,
+    read_json_arg,
+    read_text_arg,
+    require_force,
+)
+
+# Name tokens that mark a mutation as irreversible, matched case-insensitively.
+# Substrings cover e.g. sceneDestroy, scenesDestroy, deleteFiles, delete_file,
+# delete_generated, tagsMerge; exact names cover whole-database operations.
+DESTRUCTIVE_SUBSTRINGS = ("destroy", "delete", "merge")
+DESTRUCTIVE_NAMES = frozenset(
+    name.lower()
+    for name in (
+        "metadataClean",
+        "migrate",
+        "migrateHashNaming",
+        "migrateSceneScreenshots",
+        "migrateBlobs",
+        "anonymiseDatabase",
+        "optimiseDatabase",
+    )
+)
+
+# Yielded by `_tokens` in place of a name when a string literal is unterminated.
+_UNTERMINATED = object()
+
+# Brace tokens yielded by `_tokens`; name tokens never equal these.
+_PUNCTUATORS = frozenset({"{", "}"})
+
+
+def cmd_graphql(args: argparse.Namespace) -> object:
+    query = read_text_arg(args.query)
+    variables = read_json_arg(args.variables) if args.variables else None
+    if not _is_mutation(query):
+        return core.call(query, variables)
+    destructive = _destructive_tokens(query)
+    if not args.apply:
+        return {
+            "applied": False,
+            "operation": "graphql",
+            "input": {"query": query, "variables": variables},
+            "destructive": bool(destructive),
+        }
+    require_force(args, destructive)
+    return core.call(query, variables)
+
+
+def _is_mutation(query: str) -> bool:
+    """Detect a top-level ``mutation`` operation, conservatively.
+
+    Only the first token of a top-level definition is its keyword, so
+    ``mutation`` as an alias, field, or operation/fragment name does not
+    count. Unterminated strings and unbalanced braces count as mutations.
+    """
+    depth = 0
+    expect_definition = True
+    for token in _tokens(query):
+        if token is _UNTERMINATED:
+            return True
+        if token == "{":
+            # At depth 0 with no keyword yet, this is a shorthand query.
+            expect_definition = False
+            depth += 1
+        elif token == "}":
+            depth -= 1
+            if depth < 0:
+                return True
+            expect_definition = depth == 0
+        elif depth == 0 and expect_definition:
+            if token == "mutation":
+                return True
+            expect_definition = False
+    return depth != 0
+
+
+def _is_destructive(query: str) -> bool:
+    """Conservatively detect irreversible operation names outside literals."""
+    return bool(_destructive_tokens(query))
+
+
+def _destructive_tokens(query: str) -> list[str]:
+    """Return the distinct destructive names in `query`, in document order."""
+    matched: list[str] = []
+    for token in _tokens(query):
+        if token in _PUNCTUATORS:
+            continue
+        if token is _UNTERMINATED:
+            name = "<unterminated string>"
+        else:
+            lowered = token.lower()
+            if lowered not in DESTRUCTIVE_NAMES and not any(
+                part in lowered for part in DESTRUCTIVE_SUBSTRINGS
+            ):
+                continue
+            name = token
+        if name not in matched:
+            matched.append(name)
+    return matched
+
+
+def _tokens(query: str):
+    """Yield GraphQL name and brace tokens, skipping comments and strings.
+
+    Yields `_UNTERMINATED` and stops if a string literal never closes.
+    """
+    index = 0
+    length = len(query)
+
+    while index < length:
+        character = query[index]
+
+        if character == "#":
+            index += 1
+            while index < length and query[index] not in "\r\n":
+                index += 1
+            if index < length and query[index] == "\r":
+                index += 1
+                if index < length and query[index] == "\n":
+                    index += 1
+            elif index < length:
+                index += 1
+            continue
+
+        if character == '"':
+            if query.startswith('"""', index):
+                index += 3
+                while index < length:
+                    if query.startswith('"""', index):
+                        index += 3
+                        break
+                    if query.startswith('\\"""', index):
+                        index += 4
+                        continue
+                    index += 1
+                else:
+                    yield _UNTERMINATED
+                    return
+                continue
+
+            index += 1
+            while index < length:
+                character = query[index]
+                if character == "\\":
+                    index += 2
+                    continue
+                if character == '"':
+                    index += 1
+                    break
+                if character in "\r\n":
+                    yield _UNTERMINATED
+                    return
+                index += 1
+            else:
+                yield _UNTERMINATED
+                return
+            continue
+
+        if character.isascii() and (character.isalpha() or character == "_"):
+            token_start = index
+            index += 1
+            while (
+                index < length
+                and query[index].isascii()
+                and (query[index].isalnum() or query[index] == "_")
+            ):
+                index += 1
+            yield query[token_start:index]
+            continue
+
+        if character in _PUNCTUATORS:
+            yield character
+
+        index += 1
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    parser = add_leaf(
+        subparsers,
+        "graphql",
+        kind=CommandKind.DESTRUCTIVE,
+        func=cmd_graphql,
+        help="Send a raw GraphQL document to Stash (escape hatch).",
+        examples=(
+            "stashapp-cli graphql --query 'query { findTags { tags { id } } }'",
+            'stashapp-cli graphql --query @query.graphql --variables \'{"name": "hd"}\'',
+            "stashapp-cli graphql --query @mutation.graphql --apply",
+            "stashapp-cli graphql --query @destroy.graphql --apply --force",
+        ),
+    )
+    parser.add_argument(
+        "--query", required=True, help="GraphQL document as text, @file, or @-."
+    )
+    parser.add_argument(
+        "--variables",
+        default=None,
+        help="Variables as JSON, @file, or @- (default: none).",
+    )
+    parser.epilog = f"{parser.epilog}" + (
+        "\n\nQueries are sent as-is. Mutations are dry runs unless --apply is "
+        "given.\nDestructive mutations (names containing destroy/delete/merge, "
+        "metadataClean,\nmigrate, migrateBlobs, ... database maintenance) also "
+        "need --force; without\nit they exit 2 with code destructive_mutation."
+    )

stashapp_cli/commands/group.py

@@ -0,0 +1,137 @@
+"""group commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import queries
+from ._common import (
+    TAG_IDS,
+    URLS,
+    CommandKind,
+    FindSpec,
+    add_find_options,
+    add_get_command,
+    add_leaf,
+    add_list_options,
+    add_update_target,
+    bulk_update_input,
+    find_filter,
+    mutation_result,
+    read_json_arg,
+    require_list_target,
+    resolve_update_input,
+)
+
+FIND = FindSpec("groups", "name", match_aliases=False, sort="name")
+
+
+def cmd_group_find(args: argparse.Namespace) -> object:
+    extra = None
+    if args.studio_id is not None:
+        extra = {"studios": {"value": [args.studio_id], "modifier": "INCLUDES"}}
+    return queries.group.find_groups(
+        find_filter(args, FIND, extra), args.page, args.per_page
+    )
+
+
+def cmd_group_create(args: argparse.Namespace) -> object:
+    input_data = read_json_arg(args.input)
+    return mutation_result(
+        "groupCreate",
+        args.apply,
+        input_data,
+        lambda: queries.group.create_group(input_data),
+    )
+
+
+LIST_FIELDS = (TAG_IDS, URLS)
+
+
+def cmd_group_update(args: argparse.Namespace) -> object:
+    bulk_input = bulk_update_input(args, LIST_FIELDS)
+    if bulk_input is not None:
+        require_list_target(args)
+        return mutation_result(
+            "bulkGroupUpdate",
+            args.apply,
+            bulk_input,
+            lambda: queries.group.bulk_update_group(bulk_input),
+        )
+    input_data = resolve_update_input(args)
+    return mutation_result(
+        "groupUpdate",
+        args.apply,
+        input_data,
+        lambda: queries.group.update_group(input_data),
+    )
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    group = subparsers.add_parser("group", help="Group lookups and writes.")
+    group_sub = group.add_subparsers(dest="group_command", required=True)
+
+    add_get_command(group_sub, "group", queries.group.get_group, example_id=5)
+
+    find = add_leaf(
+        group_sub,
+        "find",
+        kind=CommandKind.READ,
+        func=cmd_group_find,
+        help=(
+            "Find groups by exact name (not alias), studio, or a GroupFilterType. "
+            "Several matches are not an error; check count."
+        ),
+        examples=(
+            "stashapp-cli group find --name 'Film' --studio-id 1",
+            "stashapp-cli group find --name 'Film' | jq 'select(.count == 1) | .groups[0]'",
+            'stashapp-cli group find --filter-json \'{"is_missing": "studio"}\'',
+            "stashapp-cli group find --studio-id 1 --filter-json @group-filter.json",
+        ),
+    )
+    add_find_options(find, FIND)
+    find.add_argument(
+        "--studio-id",
+        default=None,
+        metavar="ID",
+        help="Only match groups in this studio (the studios criterion).",
+    )
+    find.epilog = f"{find.epilog}" + (
+        "\n\nStash cannot filter groups by alias, so --name matches the name only.\n"
+        "--studio-id follows the same rules as --name: it is added to the filter\n"
+        "and conflicts with a studios criterion or a top-level AND, OR, or NOT.\n"
+        "More than one group can match; check that count is 1 before using a\n"
+        "match as one group."
+    )
+
+    create = add_leaf(
+        group_sub,
+        "create",
+        kind=CommandKind.WRITE,
+        func=cmd_group_create,
+        help="Create a group (dry-run by default; see global --apply).",
+        examples=(
+            'stashapp-cli group create --input \'{"name": "Film"}\'',
+            "stashapp-cli group create --input @group.json --apply",
+        ),
+    )
+    create.add_argument(
+        "--input", required=True, help="GroupCreateInput as JSON, @file, or @-."
+    )
+
+    update = add_leaf(
+        group_sub,
+        "update",
+        kind=CommandKind.WRITE,
+        func=cmd_group_update,
+        help="Update a group (dry-run by default; see global --apply).",
+        examples=(
+            'stashapp-cli group update 1 --input \'{"name": "Film"}\'',
+            'stashapp-cli group update --input \'{"id": "1", "name": "Film"}\'',
+            "stashapp-cli --apply group update --input @group.json",
+            "stashapp-cli group update 5 --add-tag-id 7 --remove-url https://old.example/film",
+            "stashapp-cli group update 5 --add-url https://example.com/film --apply",
+        ),
+    )
+    add_update_target(update, "GroupUpdateInput")
+    add_list_options(update, LIST_FIELDS)

stashapp_cli/commands/introspect.py

@@ -0,0 +1,35 @@
+"""introspect command."""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import core, introspect
+from ._common import CommandKind, add_leaf
+
+
+def cmd_introspect(_args: argparse.Namespace) -> object:
+    missing = introspect.missing_schema_names()
+    if missing:
+        raise core.CliError(
+            "Schema drift detected, missing: " + ", ".join(missing),
+            1,
+            "schema_drift",
+            details={"missing": missing},
+        )
+    return {"drift": False, "missing": []}
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    add_leaf(
+        subparsers,
+        "introspect",
+        kind=CommandKind.READ,
+        func=cmd_introspect,
+        help=(
+            "Check the live Stash schema against the names this CLI depends "
+            "on. Drift exits 1 with code schema_drift; --json-errors adds "
+            "error.missing."
+        ),
+        examples=("stashapp-cli introspect",),
+    )

stashapp_cli/commands/job.py

@@ -0,0 +1,122 @@
+"""job commands."""
+
+from __future__ import annotations
+
+import argparse
+import time
+
+from .. import core, queries
+from ._common import CommandKind, add_leaf, object_id, positive_seconds
+
+_RECENT_JOBS_NOTE = "Stash keeps only its most recent finished jobs."
+
+
+def cmd_job_get(args: argparse.Namespace) -> object:
+    return queries.job.find_job(object_id(args.id, "Job"))
+
+
+def cmd_job_wait(args: argparse.Namespace) -> object:
+    job_id = object_id(args.id, "Job")
+    deadline = time.monotonic() + args.max_wait
+    while True:
+        job = queries.job.find_job(job_id)
+        if job is None:
+            raise core.CliError(
+                f"Stash has no job {job_id}. {_RECENT_JOBS_NOTE} Check the "
+                "result with a read command, for example `scene find`.",
+                1,
+                "job_not_found",
+            )
+        status = job.get("status")
+        if status == "FINISHED":
+            return job
+        if status == "FAILED":
+            raise core.CliError(
+                f"Job {job_id} failed: {job.get('error') or '(no error message)'}",
+                1,
+                "job_failed",
+                details={"job": job},
+            )
+        if status == "CANCELLED":
+            raise core.CliError(
+                f"Job {job_id} was cancelled.",
+                1,
+                "job_cancelled",
+                details={"job": job},
+            )
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise core.CliError(
+                f"Job {job_id} is still running in Stash (status {status}) after "
+                f"{args.max_wait:g} seconds. Run `stashapp-cli job wait {job_id}` "
+                "again to keep waiting.",
+                1,
+                "job_wait_timeout",
+                details={"job": job},
+            )
+        time.sleep(min(args.interval, remaining))
+
+
+def _add_job_id(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "id",
+        metavar="ID",
+        help="Job id, as printed in job_id by scan run, generate run, or "
+        "scene identify.",
+    )
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    job = subparsers.add_parser("job", help="Read and wait for Stash background jobs.")
+    job_sub = job.add_subparsers(dest="job_command", required=True)
+
+    get = add_leaf(
+        job_sub,
+        "get",
+        kind=CommandKind.READ,
+        func=cmd_job_get,
+        help="Fetch one job's state, or null if Stash has no such job.",
+        examples=("stashapp-cli job get 17",),
+    )
+    get.description = (
+        "Print a job's id, status, progress, description, error, addTime,\n"
+        "startTime, and endTime. Print null when Stash has no job with that id.\n"
+        f"{_RECENT_JOBS_NOTE}"
+    )
+    _add_job_id(get)
+
+    wait = add_leaf(
+        job_sub,
+        "wait",
+        kind=CommandKind.READ,
+        func=cmd_job_wait,
+        help="Wait until a job is FINISHED, CANCELLED, or FAILED.",
+        examples=(
+            "stashapp-cli job wait 17",
+            "stashapp-cli --json-errors job wait 17 --max-wait 600 --interval 5",
+        ),
+    )
+    wait.description = (
+        "Read the job at once, then every --interval seconds, until it ends.\n"
+        "Print the job when it is FINISHED. Fail with job_failed, job_cancelled,\n"
+        "or job_wait_timeout (exit 1; --json-errors adds `job`, the last state\n"
+        "read), or job_not_found (exit 1) when Stash has no such job.\n"
+        f"{_RECENT_JOBS_NOTE}\n"
+        "Each read uses the global --timeout, so a wait can run past --max-wait\n"
+        "by up to one --timeout."
+    )
+    _add_job_id(wait)
+    wait.add_argument(
+        "--max-wait",
+        type=positive_seconds,
+        default=3600.0,
+        metavar="SECONDS",
+        help="Stop waiting after this many seconds (default: 3600).",
+    )
+    wait.add_argument(
+        "--interval",
+        type=positive_seconds,
+        default=2.0,
+        metavar="SECONDS",
+        help="Seconds between reads (default: 2).",
+    )