stashapp-cli 0.1.0__py3-none-any.whl

stashapp_cli/commands/performer.py

@@ -0,0 +1,368 @@
+"""performer commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import core, queries
+from ._common import (
+    ALIASES,
+    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_force,
+    require_list_target,
+    resolve_update_input,
+)
+
+FIND = FindSpec("performers", "name", match_aliases=True, sort="name")
+
+
+def cmd_performer_find(args: argparse.Namespace) -> object:
+    return queries.performer.find_performers(
+        find_filter(args, FIND), args.page, args.per_page
+    )
+
+
+def cmd_performer_create(args: argparse.Namespace) -> object:
+    urls = args.url or []
+    input_data = {"name": args.name, "gender": args.gender, "urls": urls}
+    return mutation_result(
+        "performerCreate",
+        args.apply,
+        input_data,
+        lambda: queries.performer.create_performer(args.name, args.gender, urls),
+    )
+
+
+LIST_FIELDS = (TAG_IDS, URLS, ALIASES)
+
+
+def cmd_performer_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(
+            "bulkPerformerUpdate",
+            args.apply,
+            bulk_input,
+            lambda: queries.performer.bulk_update_performer(bulk_input),
+        )
+    input_data = resolve_update_input(args)
+    return mutation_result(
+        "performerUpdate",
+        args.apply,
+        input_data,
+        lambda: queries.performer.update_performer(input_data),
+    )
+
+
+def _alias_key(value: str) -> str:
+    return value.strip().casefold()
+
+
+def _stash_id_key(stash_id: dict) -> tuple[str, str]:
+    return (stash_id["endpoint"], stash_id["stash_id"])
+
+
+def _kept(destination: dict, values: dict, field: str) -> list:
+    """The destination's value for `field` after the merge's partial update."""
+    value = values[field] if field in values else destination.get(field)
+    if value is None:
+        return []
+    return [value] if field == "name" else list(value)
+
+
+def lost_values(destination: dict, sources: list[dict], values: dict) -> list[dict]:
+    """Report, per source, the aliases, URLs, and stash IDs the merge would drop.
+
+    Kept values come from `values` when it sets a field, because a list in
+    `values` replaces the destination's list, and from `destination` otherwise.
+    """
+    kept_aliases = {
+        _alias_key(alias)
+        for alias in _kept(destination, values, "name")
+        + _kept(destination, values, "alias_list")
+    }
+    kept_urls = set(_kept(destination, values, "urls"))
+    kept_stash_ids = {
+        _stash_id_key(stash_id) for stash_id in _kept(destination, values, "stash_ids")
+    }
+
+    report = []
+    for source in sources:
+        aliases: list[str] = []
+        seen_aliases: set[str] = set()
+        for alias in [source.get("name"), *(source.get("alias_list") or [])]:
+            if not alias:
+                continue
+            key = _alias_key(alias)
+            if key in kept_aliases or key in seen_aliases:
+                continue
+            seen_aliases.add(key)
+            aliases.append(alias)
+
+        urls: list[str] = []
+        for url in source.get("urls") or []:
+            if url not in kept_urls and url not in urls:
+                urls.append(url)
+
+        stash_ids: list[dict] = []
+        seen_stash_ids: set[tuple[str, str]] = set()
+        for stash_id in source.get("stash_ids") or []:
+            key = _stash_id_key(stash_id)
+            if key in kept_stash_ids or key in seen_stash_ids:
+                continue
+            seen_stash_ids.add(key)
+            stash_ids.append({"endpoint": key[0], "stash_id": key[1]})
+
+        report.append(
+            {
+                "id": source["id"],
+                "name": source.get("name"),
+                "lost": {"aliases": aliases, "urls": urls, "stash_ids": stash_ids},
+            }
+        )
+    return report
+
+
+def _performer_id(value: object, option: str) -> str:
+    """`value` as Stash writes a performer ID, so `03` and `3` compare equal."""
+    text = str(value).strip()
+    if isinstance(value, bool) or not text.isdecimal():
+        raise core.CliError(
+            f"{option} must be a performer ID (a non-negative integer), got {value!r}.",
+            2,
+            "usage_error",
+        )
+    return str(int(text))
+
+
+def _is_str_list(value: object) -> bool:
+    return isinstance(value, list) and all(isinstance(item, str) for item in value)
+
+
+def _is_stash_id_list(value: object) -> bool:
+    return isinstance(value, list) and all(
+        isinstance(item, dict)
+        and isinstance(item.get("endpoint"), str)
+        and isinstance(item.get("stash_id"), str)
+        for item in value
+    )
+
+
+# The `--values` fields the loss report reads, with the shape each must have.
+_VALUES_FIELD_CHECKS = {
+    "name": (lambda value: isinstance(value, str), "a string"),
+    "alias_list": (_is_str_list, "a list of strings"),
+    "urls": (_is_str_list, "a list of strings"),
+    "stash_ids": (
+        _is_stash_id_list,
+        "a list of objects with string endpoint and stash_id",
+    ),
+}
+
+
+def _check_values_fields(values: dict) -> None:
+    for field, (is_valid, expected) in _VALUES_FIELD_CHECKS.items():
+        if (
+            field in values
+            and values[field] is not None
+            and not is_valid(values[field])
+        ):
+            raise core.CliError(
+                f"--values field {field} must be {expected}.", 2, "usage_error"
+            )
+
+
+def _merge_values(raw: str | None, destination_id: str) -> dict | None:
+    """Parse and check `--values`, filling its required id with the destination."""
+    if raw is None:
+        return None
+    values = read_json_arg(raw)
+    if not isinstance(values, dict):
+        raise core.CliError(
+            "--values must be a PerformerUpdateInput JSON object.", 2, "usage_error"
+        )
+    if "url" in values:
+        raise core.CliError(
+            "--values must not set the legacy url field; performerMerge rejects "
+            "it. Use urls.",
+            2,
+            "usage_error",
+        )
+    _check_values_fields(values)
+    if "id" in values:
+        if _performer_id(values["id"], "--values id") != destination_id:
+            raise core.CliError(
+                f"Destination {destination_id} does not match id {values['id']} "
+                "in --values.",
+                2,
+                "usage_error",
+            )
+    else:
+        values["id"] = destination_id
+    return values
+
+
+def cmd_performer_merge(args: argparse.Namespace) -> object:
+    destination_id = _performer_id(args.destination, "--destination")
+    source_ids = list(
+        dict.fromkeys(_performer_id(source, "--source") for source in args.source)
+    )
+    if destination_id in source_ids:
+        raise core.CliError(
+            f"Destination {destination_id} is also a --source; a performer cannot "
+            "be merged into itself.",
+            2,
+            "usage_error",
+        )
+    values = _merge_values(args.values, destination_id)
+
+    performers = {
+        performer["id"]: performer
+        for performer in queries.performer.find_performers_by_ids(
+            [destination_id, *source_ids]
+        )
+    }
+    destination = performers[destination_id]
+    sources = lost_values(
+        destination,
+        [performers[source_id] for source_id in source_ids],
+        values or {},
+    )
+
+    input_data: dict = {"source": source_ids, "destination": destination_id}
+    if values is not None:
+        input_data["values"] = values
+    if not args.apply:
+        return {
+            "applied": False,
+            "operation": "performerMerge",
+            "input": input_data,
+            "destination": {"id": destination["id"], "name": destination.get("name")},
+            "sources": sources,
+        }
+    require_force(args, ["performerMerge"])
+    return {
+        "applied": True,
+        "operation": "performerMerge",
+        "id": queries.performer.merge_performers(input_data),
+        "sources": sources,
+    }
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    performer = subparsers.add_parser("performer", help="Performer lookups and writes.")
+    performer_sub = performer.add_subparsers(dest="performer_command", required=True)
+
+    add_get_command(
+        performer_sub, "performer", queries.performer.get_performer, example_id=8
+    )
+
+    find = add_leaf(
+        performer_sub,
+        "find",
+        kind=CommandKind.READ,
+        func=cmd_performer_find,
+        help="Find performers by exact name or alias, or by a PerformerFilterType.",
+        examples=(
+            "stashapp-cli performer find --name 'Jane Doe'",
+            'stashapp-cli performer find --filter-json \'{"gender": {"value": "FEMALE", "modifier": "EQUALS"}}\'',
+            "stashapp-cli performer find --name 'Jane Doe' --filter-json '{\"favorite\": true}'",
+            "stashapp-cli performer find --page 2 --per-page 100",
+        ),
+    )
+    add_find_options(find, FIND)
+
+    create = add_leaf(
+        performer_sub,
+        "create",
+        kind=CommandKind.WRITE,
+        func=cmd_performer_create,
+        help="Create a performer (dry-run by default; see global --apply).",
+        examples=(
+            "stashapp-cli performer create 'Jane Doe' --gender FEMALE",
+            "stashapp-cli performer create 'Jane Doe' --apply",
+        ),
+    )
+    create.add_argument("name")
+    create.add_argument("--gender", default=None)
+    create.add_argument(
+        "--url", action="append", default=None, help="May be given more than once."
+    )
+
+    update = add_leaf(
+        performer_sub,
+        "update",
+        kind=CommandKind.WRITE,
+        func=cmd_performer_update,
+        help="Update a performer (dry-run by default; see global --apply).",
+        examples=(
+            "stashapp-cli performer update 1 --input '{\"urls\": []}'",
+            'stashapp-cli performer update --input \'{"id": "1", "urls": []}\'',
+            "stashapp-cli --apply performer update --input @performer.json",
+            "stashapp-cli performer update 1 --add-alias 'Jay D' --add-tag-id 55",
+            "stashapp-cli performer update 1 --remove-url https://old.example/jane --apply",
+        ),
+    )
+    add_update_target(update, "PerformerUpdateInput")
+    add_list_options(update, LIST_FIELDS)
+
+    merge = add_leaf(
+        performer_sub,
+        "merge",
+        kind=CommandKind.DESTRUCTIVE,
+        func=cmd_performer_merge,
+        help=(
+            "Merge source performers into a destination and destroy the sources "
+            "(dry-run by default; needs --apply --force)."
+        ),
+        examples=(
+            "stashapp-cli performer merge --destination 3 --source 7 --source 9",
+            (
+                "stashapp-cli performer merge --destination 3 --source 7 "
+                '--values \'{"alias_list": ["JD", "Jane D"]}\''
+            ),
+            (
+                "stashapp-cli performer merge --destination 3 --source 7 "
+                "--values @values.json --apply --force"
+            ),
+        ),
+    )
+    merge.add_argument(
+        "--destination", required=True, metavar="ID", help="Performer to keep."
+    )
+    merge.add_argument(
+        "--source",
+        action="append",
+        required=True,
+        metavar="ID",
+        help="Performer to merge and destroy; may be given more than once.",
+    )
+    merge.add_argument(
+        "--values",
+        default=None,
+        help=(
+            "PerformerUpdateInput as JSON, @file, or @- whose fields override "
+            "the destination; its id defaults to the destination."
+        ),
+    )
+    merge.epilog = f"{merge.epilog}" + (
+        "\n\nThe dry run reads every performer and lists, per source, the "
+        "aliases (including\nits name), URLs, and stash IDs that the destination "
+        "would not keep, so the\nmerge would lose them. List fields in --values "
+        "(alias_list, urls, stash_ids)\nreplace the destination's list, so pass "
+        "the full list. To keep a lost value,\nadd it to --values and re-run "
+        "the dry run; the lost lists are empty when\nnothing would be lost."
+    )

stashapp_cli/commands/scan.py

@@ -0,0 +1,92 @@
+"""scan commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import core, queries
+from ._common import CommandKind, add_leaf, job_result, read_input_object
+
+
+def scan_input(args: argparse.Namespace) -> dict:
+    """Build a ScanMetadataInput: `--input`, then the options over their fields."""
+    input_data = read_input_object(args.input)
+    if args.paths:
+        input_data["paths"] = args.paths
+    if args.phashes:
+        input_data["scanGeneratePhashes"] = True
+    if args.covers:
+        input_data["scanGenerateCovers"] = True
+    if args.rescan:
+        input_data["rescan"] = True
+    if not input_data.get("paths"):
+        raise core.CliError(
+            "Pass at least one PATH, or paths in --input.", 2, "usage_error"
+        )
+    return input_data
+
+
+def cmd_scan_run(args: argparse.Namespace) -> object:
+    input_data = scan_input(args)
+    return job_result(
+        "metadataScan",
+        args.apply,
+        input_data,
+        lambda: queries.metadata.start_scan(input_data),
+    )
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    scan = subparsers.add_parser("scan", help="Start Stash scan jobs.")
+    scan_sub = scan.add_subparsers(dest="scan_command", required=True)
+
+    run = add_leaf(
+        scan_sub,
+        "run",
+        kind=CommandKind.WRITE,
+        func=cmd_scan_run,
+        help="Start a scan job for library paths and print its job id.",
+        examples=(
+            "stashapp-cli scan run /media/new --phashes",
+            "stashapp-cli scan run /media/new --phashes --covers --apply",
+            (
+                'stashapp-cli scan run --input \'{"paths": ["/media/new"], '
+                '"scanGenerateSprites": true}\''
+            ),
+        ),
+    )
+    run.description = (
+        "Start a Stash scan job (metadataScan) and print its job_id. Wait for\n"
+        "it with `stashapp-cli job wait JOB_ID`.\n"
+        "\n"
+        "Scan options that are left out are off: a scan generates phashes or\n"
+        "covers only when --phashes or --covers is given. A scan does not add\n"
+        "phashes to files that Stash already knows; use\n"
+        "`stashapp-cli generate run --phashes` for them."
+    )
+    run.add_argument(
+        "paths",
+        nargs="*",
+        metavar="PATH",
+        help="Paths to scan; replace paths in --input. At least one is required.",
+    )
+    run.add_argument(
+        "--phashes",
+        action="store_true",
+        help="Generate phashes for new files (sets scanGeneratePhashes).",
+    )
+    run.add_argument(
+        "--covers",
+        action="store_true",
+        help="Generate covers for new files (sets scanGenerateCovers).",
+    )
+    run.add_argument(
+        "--rescan",
+        action="store_true",
+        help="Rescan files even if they have not changed (sets rescan).",
+    )
+    run.add_argument(
+        "--input",
+        default=None,
+        help="ScanMetadataInput as JSON, @file, or @-; options override its fields.",
+    )