stashapp-cli 0.1.0__py3-none-any.whl

stashapp_cli/commands/scene.py

@@ -0,0 +1,405 @@
+"""scene commands."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from collections.abc import Callable
+
+from .. import core, queries, sources
+from ._common import (
+    LIST_OPTION_NOTE,
+    PERFORMER_IDS,
+    TAG_IDS,
+    URLS,
+    CommandKind,
+    FindSpec,
+    add_find_options,
+    add_get_command,
+    add_leaf,
+    add_list_options,
+    add_update_target,
+    bulk_update_input,
+    find_filter,
+    job_result,
+    mutation_result,
+    read_input_object,
+    require_list_target,
+    resolve_update_input,
+)
+
+LIST_FIELDS = (TAG_IDS, URLS, PERFORMER_IDS)
+# Options that read the scene and send its full groups or stash_ids list.
+SCENE_LIST_DESTS = ("add_group", "remove_group", "add_stash_id", "remove_stash_id")
+
+
+FIND = FindSpec("scenes", "title", match_aliases=False, sort="path")
+
+
+def cmd_scene_find(args: argparse.Namespace) -> object:
+    if args.code == "":
+        raise _usage_error("--code needs a non-empty value.")
+    extra = None
+    if args.code is not None:
+        extra = {"code": {"value": args.code, "modifier": "EQUALS"}}
+    return queries.scene.find_scenes(
+        find_filter(args, FIND, extra), args.page, args.per_page
+    )
+
+
+def _usage_error(message: str) -> core.CliError:
+    return core.CliError(message, 2, "usage_error")
+
+
+def parse_group_value(value: str) -> tuple[str, int | None]:
+    """Split `GROUP_ID[:SCENE_INDEX]` on its first `:`."""
+    group_id, sep, index = value.partition(":")
+    if not group_id:
+        raise _usage_error(f"--add-group {value!r} has no group ID.")
+    if not sep:
+        return group_id, None
+    if not re.fullmatch(r"[0-9]+", index):
+        raise _usage_error(
+            f"--add-group {value!r}: the scene index must be a non-negative integer."
+        )
+    return group_id, int(index)
+
+
+def parse_stash_id_value(value: str) -> tuple[str, str]:
+    """Split `ENDPOINT:STASH_ID` on its last `:`, since endpoints contain `:`."""
+    endpoint, sep, stash_id = value.rpartition(":")
+    if not sep or not endpoint or not stash_id:
+        raise _usage_error(
+            f"--add-stash-id {value!r} must be ENDPOINT:STASH_ID with neither part empty."
+        )
+    return endpoint, stash_id
+
+
+def _require_value(option: str, value: str) -> str:
+    if not value:
+        raise _usage_error(f"{option} needs a non-empty value.")
+    return value
+
+
+def apply_group_changes(
+    current: list[dict],
+    add: list[tuple[str, int | None]],
+    remove: list[str],
+) -> list[dict]:
+    """The `SceneGroupInput` list after removing and then adding groups.
+
+    `current` is the scene's `groups` as read. A `scene_index` is sent only
+    when it is not null.
+    """
+    groups: list[dict] = []
+    for entry in current:
+        group_id = str(entry["group"]["id"])
+        if group_id in remove:
+            continue
+        group: dict = {"group_id": group_id}
+        if entry.get("scene_index") is not None:
+            group["scene_index"] = entry["scene_index"]
+        groups.append(group)
+    for group_id, scene_index in add:
+        existing: dict | None = next(
+            (g for g in groups if g["group_id"] == group_id), None
+        )
+        if existing is None:
+            existing = {"group_id": group_id}
+            groups.append(existing)
+        if scene_index is not None:
+            existing["scene_index"] = scene_index
+    return groups
+
+
+def apply_stash_id_changes(
+    current: list[dict],
+    add: list[tuple[str, str]],
+    remove: list[str],
+    boxes: Callable[[], list[dict]],
+) -> list[dict]:
+    """The `StashIDInput` list after removing and then adding stash IDs.
+
+    `add` holds resolved endpoints. A `remove` value is an entry endpoint or
+    the name of a configured stash-box; `boxes` is called only when a value
+    matches no entry endpoint. A kept entry keeps its `updated_at`.
+    """
+    stash_ids = [
+        {
+            key: entry[key]
+            for key in ("endpoint", "stash_id", "updated_at")
+            if key in entry
+        }
+        for entry in current
+    ]
+    for value in remove:
+        endpoints = {value}
+        if not any(entry["endpoint"] == value for entry in stash_ids):
+            endpoints = {box["endpoint"] for box in boxes() if box["name"] == value}
+        stash_ids = [entry for entry in stash_ids if entry["endpoint"] not in endpoints]
+    for endpoint, stash_id in add:
+        existing = [
+            entry["stash_id"] for entry in stash_ids if entry["endpoint"] == endpoint
+        ]
+        if stash_id in existing:
+            continue
+        if existing:
+            raise core.CliError(
+                f"The scene already has stash ID {', '.join(existing)} for {endpoint}. "
+                f"To replace it, pass --remove-stash-id {endpoint} "
+                f"--add-stash-id {endpoint}:{stash_id}.",
+                2,
+                "stash_id_conflict",
+                {"endpoint": endpoint, "stash_ids": existing},
+            )
+        stash_ids.append({"endpoint": endpoint, "stash_id": stash_id})
+    return stash_ids
+
+
+def _update_scene_lists(args: argparse.Namespace) -> object:
+    """Read the scene, change its groups or stash_ids, and send one sceneUpdate."""
+    add_groups = [parse_group_value(value) for value in args.add_group or []]
+    remove_groups = [
+        _require_value("--remove-group", value) for value in args.remove_group or []
+    ]
+    add_stash_ids = [parse_stash_id_value(value) for value in args.add_stash_id or []]
+    remove_stash_ids = [
+        _require_value("--remove-stash-id", value)
+        for value in args.remove_stash_id or []
+    ]
+
+    stash_boxes: list[dict] | None = None
+
+    def boxes() -> list[dict]:
+        nonlocal stash_boxes
+        if stash_boxes is None:
+            stash_boxes = sources.list_stash_boxes()
+        return stash_boxes
+
+    if add_stash_ids:
+        add_stash_ids = [
+            (sources.resolve_stash_box(endpoint, boxes())["endpoint"], stash_id)
+            for endpoint, stash_id in add_stash_ids
+        ]
+
+    scene = queries.scene.get_scene_lists(args.id)
+    if scene is None:
+        raise core.not_found_error("scene", args.id)
+
+    input_data: dict = {"id": args.id}
+    if add_groups or remove_groups:
+        input_data["groups"] = apply_group_changes(
+            scene.get("groups") or [], add_groups, remove_groups
+        )
+    if add_stash_ids or remove_stash_ids:
+        input_data["stash_ids"] = apply_stash_id_changes(
+            scene.get("stash_ids") or [], add_stash_ids, remove_stash_ids, boxes
+        )
+    return mutation_result(
+        "sceneUpdate",
+        args.apply,
+        input_data,
+        lambda: queries.scene.update_scene(input_data),
+    )
+
+
+def cmd_scene_update(args: argparse.Namespace) -> object:
+    scene_lists = any(getattr(args, dest) for dest in SCENE_LIST_DESTS)
+    bulk_input = bulk_update_input(args, LIST_FIELDS)
+    if scene_lists or bulk_input is not None:
+        require_list_target(args)
+        if scene_lists and bulk_input is not None:
+            raise _usage_error(
+                "The group and stash ID options cannot be combined with the tag, "
+                "URL, or performer options; run two commands."
+            )
+    if bulk_input is not None:
+        return mutation_result(
+            "bulkSceneUpdate",
+            args.apply,
+            bulk_input,
+            lambda: queries.scene.bulk_update_scene(bulk_input),
+        )
+    if scene_lists:
+        return _update_scene_lists(args)
+    input_data = resolve_update_input(args)
+    return mutation_result(
+        "sceneUpdate",
+        args.apply,
+        input_data,
+        lambda: queries.scene.update_scene(input_data),
+    )
+
+
+def identify_input(args: argparse.Namespace) -> dict:
+    """Build an IdentifyMetadataInput: `--input`, then the options over their fields.
+
+    The guards run before any `--source` is resolved, so they send nothing.
+    """
+    input_data = read_input_object(args.input)
+    if args.scene_ids is not None:
+        input_data["sceneIDs"] = args.scene_ids
+    if not (args.sources or input_data.get("sources")):
+        raise core.CliError(
+            "Pass at least one --source, or sources in --input; without sources "
+            "Stash identifies nothing.",
+            2,
+            "usage_error",
+        )
+    if not (input_data.get("sceneIDs") or input_data.get("paths")):
+        raise core.CliError(
+            "Pass --scene-id, or paths in --input; without either Stash "
+            "identifies every scene in the library.",
+            2,
+            "usage_error",
+        )
+    if args.sources is not None:
+        input_data["sources"] = [
+            {"source": sources.resolve_source(value, "SCENE")} for value in args.sources
+        ]
+    return input_data
+
+
+def cmd_scene_identify(args: argparse.Namespace) -> object:
+    input_data = identify_input(args)
+    return job_result(
+        "metadataIdentify",
+        args.apply,
+        input_data,
+        lambda: queries.metadata.start_identify(input_data),
+    )
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    scene = subparsers.add_parser("scene", help="Scene lookups and writes.")
+    scene_sub = scene.add_subparsers(dest="scene_command", required=True)
+
+    add_get_command(scene_sub, "scene", queries.scene.get_scene, example_id=1)
+
+    find = add_leaf(
+        scene_sub,
+        "find",
+        kind=CommandKind.READ,
+        func=cmd_scene_find,
+        help="Find scenes by exact title, exact code, or by a SceneFilterType.",
+        examples=(
+            "stashapp-cli scene find --name 'Film'",
+            "stashapp-cli scene find --code 'BA123'",
+            'stashapp-cli scene find --filter-json \'{"title": {"value": "Film", "modifier": "INCLUDES"}}\'',
+            "stashapp-cli scene find --name 'Film' --filter-json '{\"organized\": false}' --page 2",
+        ),
+    )
+    add_find_options(find, FIND)
+    find.add_argument(
+        "--code",
+        default=None,
+        metavar="CODE",
+        help="Match the scene code exactly, ignoring case.",
+    )
+    find.epilog = f"{find.epilog}" + (
+        "\n\nA scene code is unique only within one studio, so --code can match\n"
+        "scenes of several studios; add a studios criterion in --filter-json to\n"
+        "narrow it. --code follows the same rules as --name: it is added to the\n"
+        "filter and conflicts with a code criterion or a top-level AND, OR, or NOT."
+    )
+
+    update = add_leaf(
+        scene_sub,
+        "update",
+        kind=CommandKind.WRITE,
+        func=cmd_scene_update,
+        help="Update a scene (dry-run by default; see global --apply).",
+        examples=(
+            'stashapp-cli scene update 812 --input \'{"title": "Film"}\'',
+            'stashapp-cli scene update --input \'{"id": "1", "title": "Film"}\'',
+            "stashapp-cli scene update --input @scene.json --apply",
+            "stashapp-cli scene update 812 --add-tag-id 55 --apply",
+            "stashapp-cli scene update 812 --add-group 5:3",
+            "stashapp-cli scene update 812 --add-stash-id https://box.example/graphql:UUID",
+        ),
+    )
+    add_update_target(update, "SceneUpdateInput")
+    add_list_options(update, LIST_FIELDS)
+    update.add_argument(
+        "--add-group",
+        action="append",
+        default=None,
+        metavar="GROUP_ID[:SCENE_INDEX]",
+        help="Add the scene to a group, or set its scene number there. "
+        + LIST_OPTION_NOTE,
+    )
+    update.add_argument(
+        "--remove-group",
+        action="append",
+        default=None,
+        metavar="GROUP_ID",
+        help="Remove the scene from a group. " + LIST_OPTION_NOTE,
+    )
+    update.add_argument(
+        "--add-stash-id",
+        action="append",
+        default=None,
+        metavar="ENDPOINT:STASH_ID",
+        help="Link a stash ID; splits on the last ':'. ENDPOINT is a configured "
+        "stash-box endpoint or name. " + LIST_OPTION_NOTE,
+    )
+    update.add_argument(
+        "--remove-stash-id",
+        action="append",
+        default=None,
+        metavar="ENDPOINT",
+        help="Remove every stash ID for a stash-box endpoint or name. "
+        + LIST_OPTION_NOTE,
+    )
+
+    identify = add_leaf(
+        scene_sub,
+        "identify",
+        kind=CommandKind.WRITE,
+        func=cmd_scene_identify,
+        help="Start an identify job for scenes and print its job id.",
+        examples=(
+            (
+                "stashapp-cli scene identify --scene-id 812 --source ExampleBox "
+                "--source ExampleScraper"
+            ),
+            "stashapp-cli scene identify --scene-id 812 --source scraper:ExampleScraper --apply",
+            (
+                'stashapp-cli scene identify --source ExampleBox --input \'{"paths": '
+                '["/media/new"], "options": {"setOrganized": false}}\''
+            ),
+        ),
+    )
+    identify.description = (
+        "Start a Stash identify job (metadataIdentify) and print its job_id.\n"
+        "Wait for it with `stashapp-cli job wait JOB_ID`.\n"
+        "\n"
+        "Each --source is a configured stash-box name or endpoint, or an\n"
+        "installed scene scraper id; add scraper: or stashbox: when a value is\n"
+        "both. Sources are tried in the order given and are checked before the\n"
+        "dry run. Sources and targets are required: pass --scene-id, or paths\n"
+        "in --input. Per-source options can only be set through --input."
+    )
+    identify.add_argument(
+        "--scene-id",
+        dest="scene_ids",
+        action="append",
+        default=None,
+        metavar="ID",
+        help="Scene to identify; repeatable. Replaces sceneIDs in --input.",
+    )
+    identify.add_argument(
+        "--source",
+        dest="sources",
+        action="append",
+        default=None,
+        metavar="S",
+        help="Source to try, in order; repeatable. Replaces sources in --input.",
+    )
+    identify.add_argument(
+        "--input",
+        default=None,
+        help=(
+            "IdentifyMetadataInput as JSON, @file, or @-; options override its fields."
+        ),
+    )

stashapp_cli/commands/scrape.py

@@ -0,0 +1,133 @@
+"""scrape commands."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .. import core, images, queries, sources
+from ._common import CommandKind, add_leaf
+
+
+def cmd_scrape_group_url(args: argparse.Namespace) -> object:
+    image_dir = _image_dir(args)
+    return images.replace_images(queries.scrape.scrape_group_url(args.url), image_dir)
+
+
+def cmd_scrape_scene_url(args: argparse.Namespace) -> object:
+    image_dir = _image_dir(args)
+    return images.replace_images(queries.scrape.scrape_scene_url(args.url), image_dir)
+
+
+def cmd_scrape_performer_url(args: argparse.Namespace) -> object:
+    image_dir = _image_dir(args)
+    return images.replace_images(
+        queries.scrape.scrape_performer_url(args.url), image_dir
+    )
+
+
+def cmd_scrape_sources(args: argparse.Namespace) -> object:
+    types = [args.type.upper()] if args.type else ["SCENE", "PERFORMER", "GROUP"]
+    return queries.sources.list_source_details(types)
+
+
+def cmd_scrape_scene(args: argparse.Namespace) -> object:
+    image_dir = _image_dir(args)
+    source = sources.resolve_source(args.source, "SCENE")
+    input_data = {"scene_id": args.scene_id} if args.scene_id else {"query": args.query}
+    return images.replace_images(
+        queries.scrape.scrape_single_scene(source, input_data), image_dir
+    )
+
+
+def add_image_dir(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--image-dir", metavar="DIR", help="Write scraped data URI images to DIR."
+    )
+
+
+def _image_dir(args: argparse.Namespace) -> Path | None:
+    if not args.image_dir:
+        return None
+    path = Path(args.image_dir)
+    if path.exists() and not path.is_dir():
+        raise core.CliError(
+            f"--image-dir must be a directory: {path}", 2, "usage_error"
+        )
+    return path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    scrape = subparsers.add_parser(
+        "scrape", help="Delegate to Stash's installed scrapers."
+    )
+    scrape_sub = scrape.add_subparsers(dest="scrape_command", required=True)
+
+    source_list = add_leaf(
+        scrape_sub,
+        "sources",
+        kind=CommandKind.READ,
+        func=cmd_scrape_sources,
+        help="List configured stash-boxes and installed scrape sources.",
+        examples=("stashapp-cli scrape sources --type scene",),
+    )
+    source_list.add_argument("--type", choices=("scene", "performer", "group"))
+
+    scene = add_leaf(
+        scrape_sub,
+        "scene",
+        kind=CommandKind.READ,
+        func=cmd_scrape_scene,
+        help="Scrape one scene through a configured source.",
+        examples=(
+            "stashapp-cli scrape scene --source ExampleBox --scene-id 812",
+            "stashapp-cli scrape scene --source ExampleBox --query 'Film Title'",
+        ),
+    )
+    scene.description = (
+        "Scrape one scene (scrapeSingleScene) and print the list of matches.\n"
+        "\n"
+        "--source is a configured stash-box name or endpoint, or an installed\n"
+        "scene scraper id; add scraper: or stashbox: when a value is both.\n"
+        "Run `stashapp-cli scrape sources --type scene` to list the sources and\n"
+        "their scrape types. With --scene-id, a scraper source must support\n"
+        "FRAGMENT scrapes."
+    )
+    scene.add_argument("--source", required=True, help="Stash-box name or scraper ID.")
+    selectors = scene.add_mutually_exclusive_group(required=True)
+    selectors.add_argument("--scene-id", metavar="ID")
+    selectors.add_argument("--query", metavar="TEXT")
+    add_image_dir(scene)
+
+    group_url = add_leaf(
+        scrape_sub,
+        "group-url",
+        kind=CommandKind.READ,
+        func=cmd_scrape_group_url,
+        help="Scrape a URL for group data.",
+        examples=("stashapp-cli scrape group-url https://example.com/group",),
+    )
+    group_url.add_argument("url")
+    add_image_dir(group_url)
+
+    scene_url = add_leaf(
+        scrape_sub,
+        "scene-url",
+        kind=CommandKind.READ,
+        func=cmd_scrape_scene_url,
+        help="Scrape a URL for full scene data.",
+        examples=("stashapp-cli scrape scene-url https://example.com/scene",),
+    )
+    scene_url.add_argument("url")
+    add_image_dir(scene_url)
+
+    performer_url = add_leaf(
+        scrape_sub,
+        "performer-url",
+        kind=CommandKind.READ,
+        func=cmd_scrape_performer_url,
+        help="Scrape a URL for performer data.",
+        examples=("stashapp-cli scrape performer-url https://example.com/performer",),
+    )
+    performer_url.add_argument("url")
+    add_image_dir(performer_url)