stashapp-cli 0.1.0__py3-none-any.whl

stashapp_cli/commands/tag.py

@@ -0,0 +1,694 @@
+"""tag commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import core, queries
+from ..queries._image_flags import add_image_flags
+from ._common import (
+    CHILD_IDS,
+    PARENT_IDS,
+    TAG_ALIASES,
+    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("tags", "name", match_aliases=True, sort="name")
+
+
+def cmd_tag_find(args: argparse.Namespace) -> object:
+    return queries.tag.find_tags(find_filter(args, FIND), args.page, args.per_page)
+
+
+def cmd_tag_find_or_create(args: argparse.Namespace) -> object:
+    if tag_id := queries.tag.find_tag(args.name):
+        return {"applied": False, "operation": "tagFind", "id": tag_id}
+    return mutation_result(
+        "tagCreate",
+        args.apply,
+        {"name": args.name},
+        lambda: queries.tag.find_or_create_tag(args.name),
+    )
+
+
+LIST_FIELDS = (TAG_ALIASES, PARENT_IDS, CHILD_IDS)
+_HIERARCHY_DESTS = tuple(
+    dest for field in (PARENT_IDS, CHILD_IDS) for dest in field.dests
+)
+
+
+def _normalise_hierarchy_args(args: argparse.Namespace) -> None:
+    """Rewrite the tag ID and the parent and child IDs in Stash's decimal form."""
+    if args.id is not None:
+        args.id = _tag_id(args.id)
+    for dest in _HIERARCHY_DESTS:
+        if values := getattr(args, dest):
+            setattr(args, dest, [_tag_id(value) for value in values])
+
+
+def _tag_label(tag_id: str, tags: list[dict]) -> str:
+    for tag in tags:
+        for ref in [tag, *_refs(tag, "parents"), *_refs(tag, "children")]:
+            if ref["id"] == tag_id and ref.get("name"):
+                return f"{ref['name']} ({tag_id})"
+    return tag_id
+
+
+def _loop_error(label: str, target: str, advice: str = "") -> core.CliError:
+    """The `usage_error` for a tag that would be both a parent and a child.
+
+    `label` names the tag and `target` the tag to update. Stash accepts the two-tag
+    loop in one update, then refuses every later update of `target`.
+    """
+    return core.CliError(
+        f"Tag {label} and {target} would form a loop: {label} would be both a "
+        f"parent and a child of {target}. Stash accepts this and then refuses to "
+        f"change {target}.{advice}",
+        2,
+        "usage_error",
+    )
+
+
+def _check_hierarchy_clash(args: argparse.Namespace, tags: list[dict]) -> None:
+    """Fail when an added parent or child would be on both sides of the tag.
+
+    Stash accepts a tag that is both a parent and a child, then refuses every
+    later update of the tag, so the clash must be stopped before it is sent.
+    """
+    tag = next(tag for tag in tags if tag["id"] == args.id)
+    parents = {ref["id"] for ref in _refs(tag, "parents")}
+    children = {ref["id"] for ref in _refs(tag, "children")}
+    add_parent = args.add_parent_id or []
+    add_child = args.add_child_id or []
+    for tag_id in add_parent:
+        if tag_id in add_child:
+            raise _loop_error(
+                _tag_label(tag_id, tags),
+                f"tag {args.id}",
+                " It is in both --add-parent-id and --add-child-id.",
+            )
+        if tag_id in children:
+            raise _clash_move(tag_id, tags, args.id, "child", "parent")
+    for tag_id in add_child:
+        if tag_id in parents:
+            raise _clash_move(tag_id, tags, args.id, "parent", "child")
+
+
+def _clash_move(
+    tag_id: str, tags: list[dict], own_id: str, is_now: str, wanted: str
+) -> core.CliError:
+    return _loop_error(
+        _tag_label(tag_id, tags),
+        f"tag {own_id}",
+        f" It is already a {is_now} of tag {own_id}, so it cannot also be added "
+        f"as a {wanted}. To move it, remove it first with --remove-{is_now}-id "
+        "in a separate command.",
+    )
+
+
+def _input_ids(value: list) -> set[str]:
+    """The tag IDs of an `--input` list, written as `_tag_id` writes them."""
+    ids = set()
+    for entry in value:
+        text = str(entry).strip()
+        ids.add(str(int(text)) if text.isascii() and text.isdecimal() else text)
+    return ids
+
+
+def _check_input_loop(input_data: object) -> None:
+    """Fail when `--input` would put a tag in both `parent_ids` and `child_ids`.
+
+    A list in the input replaces the tag's list; the other list is the tag's
+    current one, read only when the input sets exactly one of the two. A value
+    that is not a list is left to Stash.
+    """
+    if not isinstance(input_data, dict):
+        return
+    lists: dict[str, list] = {
+        field: value
+        for field in ("parent_ids", "child_ids")
+        if isinstance(value := input_data.get(field), list)
+    }
+    if not lists:
+        return
+    tags: list[dict] = []
+    own = str(input_data.get("id")).strip()
+    final = {field: _input_ids(value) for field, value in lists.items()}
+    if len(lists) == 1:
+        if not (own.isascii() and own.isdecimal()):
+            return
+        (field,) = lists
+        other = "child_ids" if field == "parent_ids" else "parent_ids"
+        tags = queries.tag.find_tags_by_ids([_tag_id(own)])
+        ref_field = "children" if other == "child_ids" else "parents"
+        final[other] = {ref["id"] for ref in _refs(tags[0], ref_field)}
+    both = sorted(final["parent_ids"] & final["child_ids"])
+    if both:
+        raise _loop_error(_tag_label(both[0], tags), f"tag {own}")
+
+
+def cmd_tag_update(args: argparse.Namespace) -> object:
+    fields = {
+        field: value
+        for field, value in (
+            ("name", args.name),
+            ("sort_name", args.sort_name),
+            ("description", args.description),
+            ("favorite", args.favorite),
+            ("ignore_auto_tag", args.ignore_auto_tag),
+        )
+        if value is not None
+    }
+    if any(getattr(args, dest) for dest in _HIERARCHY_DESTS):
+        _normalise_hierarchy_args(args)
+    bulk_input = bulk_update_input(args, LIST_FIELDS)
+    if bulk_input is not None:
+        require_list_target(args)
+        if fields:
+            raise core.CliError(
+                "The alias, parent, and child options cannot be combined with "
+                "--name, --sort-name, --description, or the flag options; run "
+                "two commands.",
+                2,
+                "usage_error",
+            )
+        if args.add_parent_id or args.add_child_id:
+            wanted = list(
+                dict.fromkeys(
+                    [args.id, *(args.add_parent_id or []), *(args.add_child_id or [])]
+                )
+            )
+            _check_hierarchy_clash(args, queries.tag.find_tags_by_ids(wanted))
+        return mutation_result(
+            "bulkTagUpdate",
+            args.apply,
+            bulk_input,
+            lambda: queries.tag.bulk_update_tag(bulk_input),
+        )
+    input_data = resolve_update_input(args, fields)
+    _check_input_loop(input_data)
+    return mutation_result(
+        "tagUpdate",
+        args.apply,
+        input_data,
+        lambda: queries.tag.update_tag(input_data),
+    )
+
+
+def _tag_id(value: str) -> str:
+    """`value` as Stash writes a tag ID, so `03` and `3` compare equal."""
+    text = value.strip()
+    if not (text.isascii() and text.isdecimal()):
+        raise core.CliError(
+            f"Tag ID must be a non-negative integer, got {value!r}.",
+            2,
+            "usage_error",
+        )
+    return str(int(text))
+
+
+_USED_BY = (
+    ("scenes", "scene_count"),
+    ("scene_markers", "scene_marker_count"),
+    ("images", "image_count"),
+    ("galleries", "gallery_count"),
+    ("performers", "performer_count"),
+    ("studios", "studio_count"),
+    ("groups", "group_count"),
+)
+
+
+def _delete_report(tag: dict) -> dict:
+    return {
+        "id": tag["id"],
+        "name": tag["name"],
+        "aliases": tag.get("aliases") or [],
+        "description": tag.get("description"),
+        "used_by": {key: tag.get(field) or 0 for key, field in _USED_BY},
+        "parents": tag.get("parents") or [],
+        "children": tag.get("children") or [],
+    }
+
+
+def cmd_tag_delete(args: argparse.Namespace) -> object:
+    ids = list(dict.fromkeys(_tag_id(text) for text in args.ids))
+    found = {tag["id"]: tag for tag in queries.tag.find_tags_by_ids(ids)}
+    report = [_delete_report(found[tag_id]) for tag_id in ids]
+    if not args.apply:
+        return {
+            "applied": False,
+            "operation": "tagsDestroy",
+            "input": {"ids": ids},
+            "tags": report,
+        }
+    require_force(args, ["tagsDestroy"])
+    queries.tag.destroy_tags(ids)
+    return {
+        "applied": True,
+        "operation": "tagsDestroy",
+        "ids": ids,
+        "tags": report,
+    }
+
+
+def _alias_key(value: str) -> str:
+    return value.strip().casefold()
+
+
+def _is_str_list(value: object) -> bool:
+    return isinstance(value, list) and all(isinstance(item, str) for item in value)
+
+
+# The `--values` fields the merge report reads, with the shape each must have.
+_VALUES_FIELD_CHECKS = (
+    (("name", "sort_name", "description", "image"), str, "a string"),
+    (("favorite", "ignore_auto_tag"), bool, "a boolean"),
+    (("custom_fields",), dict, "an object"),
+)
+_VALUES_LIST_FIELDS = ("aliases", "parent_ids", "child_ids")
+
+
+def _check_values_fields(values: dict) -> None:
+    for fields, kind, expected in _VALUES_FIELD_CHECKS:
+        for field in fields:
+            if values.get(field) is not None and not isinstance(values[field], kind):
+                raise core.CliError(
+                    f"--values field {field} must be {expected}.", 2, "usage_error"
+                )
+    for field in _VALUES_LIST_FIELDS:
+        if values.get(field) is not None and not _is_str_list(values[field]):
+            raise core.CliError(
+                f"--values field {field} must be a list of strings.", 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 TagUpdateInput JSON object.", 2, "usage_error"
+        )
+    _check_values_fields(values)
+    if "id" in values and _tag_id(str(values["id"])) != destination_id:
+        raise core.CliError(
+            f"Destination {destination_id} does not match id {values['id']} "
+            "in --values.",
+            2,
+            "usage_error",
+        )
+    values["id"] = destination_id
+    return values
+
+
+def _refs(tag: dict, field: str) -> list[dict]:
+    return tag.get(field) or []
+
+
+def _hierarchy_ids(
+    destination: dict,
+    sources: list[dict],
+    values: dict | None,
+    keep: bool,
+) -> dict[str, list[str]]:
+    """The destination's final `parent_ids` and `child_ids` after the merge.
+
+    A list in `values` wins. Otherwise the default is the union of the
+    destination's and the sources' tags, and `keep=False` keeps only the
+    destination's own. The destination and the sources are always left out,
+    because the sources are deleted.
+    """
+    excluded = {destination["id"], *(source["id"] for source in sources)}
+    final = {}
+    for field, ref_field in (("parent_ids", "parents"), ("child_ids", "children")):
+        if values and values.get(field) is not None:
+            final[field] = list(values[field])
+            continue
+        tags = [destination, *sources] if keep else [destination]
+        final[field] = list(
+            dict.fromkeys(
+                ref["id"]
+                for tag in tags
+                for ref in _refs(tag, ref_field)
+                if ref["id"] not in excluded
+            )
+        )
+    return final
+
+
+def _check_no_loop(final: dict[str, list[str]], names: dict[str, str]) -> None:
+    both = [tag_id for tag_id in final["parent_ids"] if tag_id in final["child_ids"]]
+    if both:
+        label = f"{names[both[0]]} ({both[0]})" if both[0] in names else both[0]
+        raise _loop_error(label, "the destination")
+
+
+def _kept_custom_fields(destination: dict, values: dict) -> dict:
+    kept = dict(destination.get("custom_fields") or {})
+    changes = values.get("custom_fields") or {}
+    if changes.get("full") is not None:
+        kept = dict(changes["full"])
+    kept.update(changes.get("partial") or {})
+    for key in changes.get("remove") or []:
+        kept.pop(key, None)
+    return kept
+
+
+def _lost_aliases(destination: dict, source: dict, values: dict) -> list[str]:
+    if values.get("aliases") is None:
+        return []
+    name = values["name"] if values.get("name") is not None else destination["name"]
+    kept = {_alias_key(alias) for alias in [name, *values["aliases"]]}
+    lost: list[str] = []
+    for alias in [source["name"], *(source.get("aliases") or [])]:
+        key = _alias_key(alias)
+        if alias and key not in kept:
+            kept.add(key)
+            lost.append(alias)
+    return lost
+
+
+def _kept(destination: dict, values: dict, field: str) -> object:
+    return values[field] if field in values else destination.get(field)
+
+
+def _lost_report(
+    destination: dict,
+    source: dict,
+    values: dict,
+    final: dict[str, list[str]],
+) -> dict:
+    excluded = {destination["id"]}
+    lost: dict = {"aliases": _lost_aliases(destination, source, values)}
+    for field in ("description", "sort_name"):
+        value = source.get(field)
+        lost[field] = (
+            value if value and value != _kept(destination, values, field) else None
+        )
+    for field in ("favorite", "ignore_auto_tag"):
+        kept = values.get(field)
+        if kept is None:
+            kept = destination.get(field)
+        lost[field] = bool(source.get(field)) and not kept
+    has_image = add_image_flags(dict(source), {"image_path": "has_image"})["has_image"]
+    lost["image"] = has_image and values.get("image") is None
+    kept_fields = _kept_custom_fields(destination, values)
+    lost["custom_fields"] = {
+        key: value
+        for key, value in (source.get("custom_fields") or {}).items()
+        if key not in kept_fields or kept_fields[key] != value
+    }
+    for field, ref_field in (("parents", "parent_ids"), ("children", "child_ids")):
+        lost[field] = [
+            ref
+            for ref in _refs(source, field)
+            if ref["id"] not in excluded and ref["id"] not in final[ref_field]
+        ]
+    return lost
+
+
+def _gains(destination: dict, final: dict[str, list[str]], tags: list[dict]) -> dict:
+    names = {
+        ref["id"]: ref["name"]
+        for tag in tags
+        for field in ("parents", "children")
+        for ref in _refs(tag, field)
+    }
+    gains = {}
+    for field, ref_field in (("parents", "parent_ids"), ("children", "child_ids")):
+        current = {ref["id"] for ref in _refs(destination, field)}
+        gains[field] = [
+            {"id": tag_id, "name": names.get(tag_id)}
+            for tag_id in final[ref_field]
+            if tag_id not in current
+        ]
+    return gains
+
+
+def _merge_report(destination: dict, sources: list[dict], values, final) -> dict:
+    return {
+        "destination": {
+            "id": destination["id"],
+            "name": destination["name"],
+            "gains": _gains(destination, final, [destination, *sources]),
+        },
+        "sources": [
+            {
+                "id": source["id"],
+                "name": source["name"],
+                "used_by": {key: source.get(field) or 0 for key, field in _USED_BY},
+                "lost": _lost_report(destination, source, values or {}, final),
+            }
+            for source in sources
+        ],
+    }
+
+
+def cmd_tag_merge(args: argparse.Namespace) -> object:
+    destination_id = _tag_id(args.destination)
+    source_ids = list(dict.fromkeys(_tag_id(text) for text in args.source))
+    if destination_id in source_ids:
+        raise core.CliError(
+            f"Destination {destination_id} is also a --source; a tag cannot be "
+            "merged into itself.",
+            2,
+            "usage_error",
+        )
+    values = _merge_values(args.values, destination_id)
+
+    found = {
+        tag["id"]: tag
+        for tag in queries.tag.find_tags_by_ids([destination_id, *source_ids])
+    }
+    destination = found[destination_id]
+    sources = [found[source_id] for source_id in source_ids]
+
+    final = _hierarchy_ids(destination, sources, values, args.keep_hierarchy)
+    names = {
+        ref["id"]: ref["name"]
+        for tag in found.values()
+        for field in ("parents", "children")
+        for ref in _refs(tag, field)
+    }
+    _check_no_loop(final, names)
+
+    sent = dict(values) if values is not None else {}
+    if args.keep_hierarchy:
+        # Stash drops the sources' tags unless the list is sent, so send a field
+        # only when it differs from what the destination keeps on its own.
+        own = _hierarchy_ids(destination, sources, None, keep=False)
+        for field in ("parent_ids", "child_ids"):
+            if field not in sent and final[field] != own[field]:
+                sent[field] = final[field]
+    input_data: dict = {"source": source_ids, "destination": destination_id}
+    if sent:
+        input_data["values"] = {"id": destination_id, **sent}
+
+    report = _merge_report(destination, sources, values, final)
+    if not args.apply:
+        return {
+            "applied": False,
+            "operation": "tagsMerge",
+            "input": input_data,
+            **report,
+        }
+    require_force(args, ["tagsMerge"])
+    return {
+        "applied": True,
+        "operation": "tagsMerge",
+        "id": queries.tag.merge_tags(input_data),
+        **report,
+    }
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    tag = subparsers.add_parser("tag", help="Tag lookups and creation.")
+    tag_sub = tag.add_subparsers(dest="tag_command", required=True)
+
+    add_get_command(tag_sub, "tag", queries.tag.get_tag, example_id=55)
+
+    find = add_leaf(
+        tag_sub,
+        "find",
+        kind=CommandKind.READ,
+        func=cmd_tag_find,
+        help=(
+            "Find tags by exact name or alias, or by a TagFilterType; an alias "
+            "returns the tag that owns it."
+        ),
+        examples=(
+            "stashapp-cli tag find --name hd",
+            "stashapp-cli tag find --filter-json '{\"favorite\": true}'",
+            'stashapp-cli tag find --name hd --filter-json \'{"is_missing": "image"}\'',
+            "stashapp-cli tag find --per-page 2",
+        ),
+    )
+    add_find_options(find, FIND)
+
+    find_or_create = add_leaf(
+        tag_sub,
+        "find-or-create",
+        kind=CommandKind.WRITE,
+        func=cmd_tag_find_or_create,
+        help=(
+            "Find a tag by name or alias, creating it if missing. An existing "
+            "name or alias reports operation tagFind and writes nothing."
+        ),
+        examples=(
+            "stashapp-cli tag find-or-create hd",
+            "stashapp-cli --apply tag find-or-create hd",
+        ),
+    )
+    find_or_create.add_argument("name")
+
+    update = add_leaf(
+        tag_sub,
+        "update",
+        kind=CommandKind.WRITE,
+        func=cmd_tag_update,
+        help="Update a tag (dry-run by default; see global --apply).",
+        examples=(
+            "stashapp-cli tag update 55 --name 'High Definition'",
+            "stashapp-cli tag update 55 --description 'HD video' --favorite --apply",
+            "stashapp-cli tag update 55 --add-alias HD",
+            "stashapp-cli tag update 55 --remove-alias HD --apply",
+            "stashapp-cli tag update 55 --add-parent-id 3",
+            "stashapp-cli tag update 55 --remove-child-id 8 --apply",
+            "stashapp-cli tag update 55 --input @tag.json --apply",
+        ),
+    )
+    add_update_target(update, "TagUpdateInput")
+    update.add_argument(
+        "--name", default=None, help="Tag name; overrides name in --input."
+    )
+    update.add_argument(
+        "--sort-name",
+        default=None,
+        help="Sort name; overrides sort_name in --input.",
+    )
+    update.add_argument(
+        "--description",
+        default=None,
+        help="Description; overrides description in --input.",
+    )
+    update.add_argument(
+        "--favorite",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Set or clear favorite; overrides favorite in --input.",
+    )
+    update.add_argument(
+        "--ignore-auto-tag",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Set or clear ignore_auto_tag; overrides ignore_auto_tag in --input.",
+    )
+    add_list_options(update, LIST_FIELDS)
+    update.epilog = f"{update.epilog}" + (
+        "\n\nA tag that is both a parent and a child of the same tag is a "
+        "two-tag loop. Stash\naccepts it in one update and then refuses every "
+        "later update of the tag. The\ncommand stops with usage_error before "
+        "this happens, for the add options, for\n--input with parent_ids or "
+        "child_ids, and for `tag merge`. The raw `graphql`\ncommand is not "
+        "checked."
+    )
+
+    delete = add_leaf(
+        tag_sub,
+        "delete",
+        kind=CommandKind.DESTRUCTIVE,
+        func=cmd_tag_delete,
+        help=(
+            "Delete tags by ID; there is no undo (dry-run by default; needs "
+            "--apply --force)."
+        ),
+        examples=(
+            "stashapp-cli tag delete 44",
+            "stashapp-cli tag delete 44 45 46",
+            "stashapp-cli tag delete 44 45 --apply --force",
+        ),
+    )
+    delete.add_argument("ids", nargs="+", metavar="ID", help="Tag to delete.")
+    delete.epilog = f"{delete.epilog}" + (
+        "\n\nThe dry run reads every tag and reports, per tag, how many scenes, "
+        "markers,\nimages, galleries, performers, studios, and groups use it, "
+        "and its parent and\nchild tags. A child tag is kept but loses this "
+        "parent. A missing ID fails with\ntag_not_found before anything is "
+        "deleted. Run `stashapp-cli backup` first."
+    )
+
+    merge = add_leaf(
+        tag_sub,
+        "merge",
+        kind=CommandKind.DESTRUCTIVE,
+        func=cmd_tag_merge,
+        help=(
+            "Merge source tags into a destination and delete the sources "
+            "(dry-run by default; needs --apply --force)."
+        ),
+        examples=(
+            "stashapp-cli tag merge --destination 3 --source 7 --source 9",
+            (
+                "stashapp-cli tag merge --destination 3 --source 7 "
+                '--values \'{"description": "HD video"}\''
+            ),
+            "stashapp-cli tag merge --destination 3 --source 7 --no-keep-hierarchy",
+            (
+                "stashapp-cli tag merge --destination 3 --source 7 "
+                "--values @values.json --apply --force"
+            ),
+        ),
+    )
+    merge.add_argument(
+        "--destination", required=True, metavar="ID", help="Tag to keep."
+    )
+    merge.add_argument(
+        "--source",
+        action="append",
+        required=True,
+        metavar="ID",
+        help="Tag to merge and delete; may be given more than once.",
+    )
+    merge.add_argument(
+        "--values",
+        default=None,
+        help=(
+            "TagUpdateInput as JSON, @file, or @- whose fields are applied to "
+            "the destination; its id defaults to the destination."
+        ),
+    )
+    merge.add_argument(
+        "--keep-hierarchy",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help=(
+            "Give the destination the parent and child tags of the sources "
+            "(default on); --no-keep-hierarchy drops them."
+        ),
+    )
+    merge.epilog = f"{merge.epilog}" + (
+        "\n\nStash moves the scenes, performers, and other links of each source "
+        "to the\ndestination and adds the source names as aliases. It drops the "
+        "source's\ndescription, sort name, favorite and ignore_auto_tag flags, "
+        "image, custom\nfields, and parent and child tags. The parent and child "
+        "tags are kept by\ndefault (--no-keep-hierarchy turns that off); to keep "
+        "the rest, put it in\n--values. The dry run lists what would be lost per "
+        "source (lost) and what the\ndestination gains (gains). A parent_ids or "
+        "child_ids in --values replaces the\ndefault. --apply without --force "
+        "fails with destructive_mutation. Run\n`stashapp-cli backup` first."
+    )