stashapp-cli 0.1.0__py3-none-any.whl

stashapp_cli/queries/sources.py

@@ -0,0 +1,76 @@
+"""Configured stash-boxes and installed scrapers.
+
+These documents select only a stash-box's `endpoint` and `name`. Never add
+`api_key`: stashapp-cli must not read or print stash-box credentials.
+"""
+
+from __future__ import annotations
+
+from .. import core
+
+_STASH_BOXES_QUERY = """
+query StashBoxes {
+  configuration { general { stashBoxes { endpoint name } } }
+}
+"""
+
+_SOURCES_QUERY = """
+query Sources($types: [ScrapeContentType!]!) {
+  configuration { general { stashBoxes { endpoint name } } }
+  listScrapers(types: $types) { id }
+}
+"""
+
+_SOURCES_DETAIL_QUERY = """
+query SourceDetails($types: [ScrapeContentType!]!) {
+  configuration { general { stashBoxes { endpoint name } } }
+  listScrapers(types: $types) {
+    id
+    name
+    scene { supported_scrapes }
+    performer { supported_scrapes }
+    group { supported_scrapes }
+  }
+}
+"""
+
+
+def _stash_boxes(data: dict) -> list[dict]:
+    general = (data.get("configuration") or {}).get("general") or {}
+    return [
+        {"endpoint": box["endpoint"], "name": box["name"]}
+        for box in general.get("stashBoxes") or []
+    ]
+
+
+def list_stash_boxes() -> list[dict]:
+    """Configured stash-boxes as `{"endpoint", "name"}`, in Stash's order."""
+    return _stash_boxes(core.call(_STASH_BOXES_QUERY))
+
+
+def list_sources(content_type: str) -> tuple[list[dict], list[str]]:
+    """Configured stash-boxes and the ids of scrapers for `content_type`.
+
+    `content_type` is a Stash `ScrapeContentType`, for example `SCENE`.
+    """
+    data = core.call(_SOURCES_QUERY, {"types": [content_type]})
+    scraper_ids = [scraper["id"] for scraper in data.get("listScrapers") or []]
+    return _stash_boxes(data), scraper_ids
+
+
+def list_source_details(types: list[str]) -> dict:
+    """Configured boxes and detailed installed scraper capabilities."""
+    data = core.call(_SOURCES_DETAIL_QUERY, {"types": types})
+    scrapers = []
+    for scraper in data.get("listScrapers") or []:
+        scrapers.append(
+            {
+                "id": scraper["id"],
+                "name": scraper["name"],
+                "scene": (scraper.get("scene") or {}).get("supported_scrapes") or [],
+                "performer": (scraper.get("performer") or {}).get("supported_scrapes")
+                or [],
+                "group": (scraper.get("group") or {}).get("supported_scrapes") or [],
+            }
+        )
+    return {"stash_boxes": _stash_boxes(data), "scrapers": scrapers}

stashapp_cli/queries/stashbox.py

@@ -0,0 +1,67 @@
+"""Stash-box fingerprint submission and the scene read that plans it.
+
+These documents never select fingerprint values or a stash-box `api_key`.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .. import core
+
+_SCENE_FINGERPRINTS_QUERY = """
+query SceneFingerprints($ids: [ID!]) {
+  findScenes(ids: $ids) {
+    scenes {
+      id
+      stash_ids { endpoint }
+      files { duration fingerprints { type } }
+    }
+  }
+}
+"""
+
+_SUBMIT_FINGERPRINTS_MUTATION = """
+mutation SubmitFingerprints($input: StashBoxFingerprintSubmissionInput!) {
+  submitStashBoxFingerprints(input: $input)
+}
+"""
+
+_SCENE_NOT_FOUND = re.compile(r"\bscene with id (\S+) not found\b", re.IGNORECASE)
+
+
+def get_scene_fingerprints(scene_ids: list[str]) -> list[dict]:
+    """Fetch the stash-box endpoints and file fingerprint types of scenes.
+
+    Stash fails the whole read at the first missing id, so `missing_ids` in
+    the `scene_not_found` error holds only that id. If Stash instead returns
+    fewer scenes without an error, `missing_ids` lists every id it left out.
+    """
+    try:
+        data = core.call(_SCENE_FINGERPRINTS_QUERY, {"ids": list(scene_ids)})
+    except core.CliError as error:
+        if match := _SCENE_NOT_FOUND.search(str(error)):
+            raise core.CliError(
+                str(error),
+                2,
+                "scene_not_found",
+                details={"missing_ids": [match.group(1)]},
+            ) from error
+        raise
+    scenes = (data.get("findScenes") or {}).get("scenes") or []
+    returned = {str(scene["id"]) for scene in scenes}
+    missing = [scene_id for scene_id in scene_ids if scene_id not in returned]
+    if missing:
+        raise core.CliError(
+            f"Stash returned no scene for id(s) {', '.join(missing)}.",
+            2,
+            "scene_not_found",
+            details={"missing_ids": missing},
+        )
+    return scenes
+
+
+def submit_fingerprints(input_data: dict) -> bool:
+    """Send a `StashBoxFingerprintSubmissionInput` and return Stash's result."""
+    data = core.call(_SUBMIT_FINGERPRINTS_MUTATION, {"input": input_data})
+    return data["submitStashBoxFingerprints"]

stashapp_cli/queries/studio.py

@@ -0,0 +1,145 @@
+"""Studio lookups and writes."""
+
+from __future__ import annotations
+
+import re
+
+from .. import core
+from ._get import ObjectSpec, get_object
+from ._image_flags import add_page_image_flags
+
+_IMAGE_FLAGS = {"image_path": "has_image"}
+
+_FIND_STUDIO_QUERY = """
+query FindStudio($name: String!) {
+  findStudios(studio_filter: {name: {value: $name, modifier: EQUALS}}, filter: {per_page: 1}) {
+    studios { id name }
+  }
+}
+"""
+
+
+def find_studio_id(name: str) -> str | None:
+    data = core.call(_FIND_STUDIO_QUERY, {"name": name})
+    studios = data.get("findStudios", {}).get("studios", [])
+    return studios[0]["id"] if studios else None
+
+
+_STUDIO_FIELDS = """
+      id
+      name
+      aliases
+      details
+      urls
+      image_path
+      custom_fields
+      parent_studio { id }
+      stash_ids { endpoint stash_id }
+"""
+
+STUDIO = ObjectSpec("findStudio", _STUDIO_FIELDS, _IMAGE_FLAGS)
+
+
+def get_studio(studio_id: str) -> dict | None:
+    """One studio by id, in the shape find_studios returns, or `None`."""
+    return get_object(STUDIO, studio_id)
+
+
+_FIND_STUDIOS_QUERY = f"""
+query FindStudios($studio_filter: StudioFilterType!, $page: Int!, $per_page: Int!) {{
+  findStudios(
+    studio_filter: $studio_filter
+    filter: {{page: $page, per_page: $per_page, sort: "name", direction: ASC}}
+  ) {{
+    count
+    studios {{
+{_STUDIO_FIELDS}
+    }}
+  }}
+}}
+"""
+
+
+def find_studios(studio_filter: dict, page: int, per_page: int = 50) -> dict:
+    """One page of the studios matching a Stash studio filter.
+
+    Each studio also gets a `has_image` flag; see `_image_flags` for the rule.
+    """
+    result = core.call(
+        _FIND_STUDIOS_QUERY,
+        {"studio_filter": studio_filter, "page": page, "per_page": per_page},
+    )["findStudios"]
+    return add_page_image_flags(result, "studios", _IMAGE_FLAGS)
+
+
+_CREATE_STUDIO_MUTATION = """
+mutation CreateStudio($input: StudioCreateInput!) {
+  studioCreate(input: $input) {
+    id
+    name
+  }
+}
+"""
+
+
+def create_studio(input_data: dict) -> str:
+    data = core.call(_CREATE_STUDIO_MUTATION, {"input": input_data})
+    return data["studioCreate"]["id"]
+
+
+_UPDATE_STUDIO_MUTATION = """
+mutation UpdateStudio($input: StudioUpdateInput!) {
+  studioUpdate(input: $input) {
+    id
+    name
+  }
+}
+"""
+
+
+def update_studio(input_data: dict) -> str:
+    data = core.call(_UPDATE_STUDIO_MUTATION, {"input": input_data})
+    return data["studioUpdate"]["id"]
+
+
+_BULK_UPDATE_STUDIO_MUTATION = """
+mutation BulkUpdateStudio($input: BulkStudioUpdateInput!) {
+  bulkStudioUpdate(input: $input) {
+    id
+  }
+}
+"""
+
+# Stash's message for a missing studio includes the id, so it is matched by
+# pattern.
+_STUDIO_NOT_FOUND = re.compile(r"\bstudio with id\b.*\bnot found\b", re.IGNORECASE)
+
+
+def bulk_update_studio(input_data: dict) -> str:
+    """Send a one-studio bulkStudioUpdate and return the studio id."""
+    (studio_id,) = input_data["ids"]
+    try:
+        data = core.call(_BULK_UPDATE_STUDIO_MUTATION, {"input": input_data})
+    except core.CliError as error:
+        if error.code == "graphql_error" and _STUDIO_NOT_FOUND.search(str(error)):
+            raise core.not_found_error("studio", studio_id) from error
+        raise
+    return core.returned_id("bulkStudioUpdate", data, studio_id)
+
+
+_GET_STUDIO_ALIASES_QUERY = """
+query GetStudioAliases($id: ID!) {
+  findStudio(id: $id) {
+    id
+    aliases
+  }
+}
+"""
+
+
+def get_studio_aliases(studio_id: str) -> list[str] | None:
+    """The studio's aliases, or `None` when there is no such studio."""
+    studio = core.call(_GET_STUDIO_ALIASES_QUERY, {"id": studio_id})["findStudio"]
+    if studio is None:
+        return None
+    return studio.get("aliases") or []

stashapp_cli/queries/tag.py

@@ -0,0 +1,244 @@
+"""Tag lookups and creation."""
+
+from __future__ import annotations
+
+import re
+
+from .. import core
+from ._get import ObjectSpec, get_object
+from ._image_flags import add_page_image_flags
+
+_IMAGE_FLAGS = {"image_path": "has_image"}
+
+# Matches the tag's name or any of its aliases. Stash rejects an alias that
+# equals another tag's name, so at most one tag matches each way; per_page 2
+# lets find_tag prefer the name match if both somehow exist.
+_FIND_TAG_QUERY = """
+query FindTag($name: String!) {
+  findTags(
+    tag_filter: {
+      name: {value: $name, modifier: EQUALS}
+      OR: {aliases: {value: $name, modifier: EQUALS}}
+    }
+    filter: {per_page: 2}
+  ) {
+    tags { id name }
+  }
+}
+"""
+
+_CREATE_TAG_MUTATION = """
+mutation CreateTag($name: String!) {
+  tagCreate(input: {name: $name}) {
+    id
+    name
+  }
+}
+"""
+
+
+def find_tag(name: str) -> str | None:
+    """Read-only lookup by exact name or alias -- never creates the tag.
+
+    Safe to call in dry-run mode. When `name` is an alias, returns the id of
+    the tag that owns it.
+    """
+    data = core.call(_FIND_TAG_QUERY, {"name": name})
+    tags = data.get("findTags", {}).get("tags", [])
+    if not tags:
+        return None
+    for tag in tags:
+        if tag["name"].casefold() == name.casefold():
+            return tag["id"]
+    return tags[0]["id"]
+
+
+_TAG_FIELDS = (
+    "id name sort_name aliases description favorite ignore_auto_tag image_path "
+    "custom_fields scene_count scene_marker_count image_count gallery_count "
+    "performer_count studio_count group_count parents { id name } "
+    "children { id name }"
+)
+
+TAG = ObjectSpec("findTag", _TAG_FIELDS, _IMAGE_FLAGS)
+
+
+def get_tag(tag_id: str) -> dict | None:
+    """One tag by id, in the shape find_tags returns, or `None`."""
+    return get_object(TAG, tag_id)
+
+
+_FIND_TAGS_QUERY = f"""
+query FindTags($tag_filter: TagFilterType!, $page: Int!, $per_page: Int!) {{
+  findTags(
+    tag_filter: $tag_filter
+    filter: {{page: $page, per_page: $per_page, sort: "name", direction: ASC}}
+  ) {{
+    count
+    tags {{ {_TAG_FIELDS} }}
+  }}
+}}
+"""
+
+
+def find_tags(tag_filter: dict, page: int, per_page: int = 50) -> dict:
+    """One page of the tags matching a Stash tag filter.
+
+    Each tag also gets a `has_image` flag; see `_image_flags` for the rule.
+    """
+    result = core.call(
+        _FIND_TAGS_QUERY,
+        {"tag_filter": tag_filter, "page": page, "per_page": per_page},
+    )["findTags"]
+    return add_page_image_flags(result, "tags", _IMAGE_FLAGS)
+
+
+def find_or_create_tag(name: str) -> str:
+    if tag_id := find_tag(name):
+        return tag_id
+
+    try:
+        return core.call(_CREATE_TAG_MUTATION, {"name": name})["tagCreate"]["id"]
+    except core.CliError as error:
+        # find_tag already matches aliases; this covers an alias added between
+        # the lookup and the create, which Stash rejects with this message.
+        alias_match = re.search(r"is used as alias for '(.+)'", str(error))
+        if alias_match and (tag_id := find_tag(alias_match.group(1))):
+            return tag_id
+        raise
+
+
+_UPDATE_TAG_MUTATION = """
+mutation UpdateTag($input: TagUpdateInput!) {
+  tagUpdate(input: $input) {
+    id
+    name
+  }
+}
+"""
+
+
+def update_tag(input_data: dict) -> str:
+    data = core.call(_UPDATE_TAG_MUTATION, {"input": input_data})
+    return data["tagUpdate"]["id"]
+
+
+_BULK_UPDATE_TAG_MUTATION = """
+mutation BulkUpdateTag($input: BulkTagUpdateInput!) {
+  bulkTagUpdate(input: $input) {
+    id
+  }
+}
+"""
+
+# Stash's message for a missing tag includes the id, so it is matched by
+# pattern.
+_TAG_NOT_FOUND = re.compile(r"\btag with id\b.*\bnot found\b", re.IGNORECASE)
+
+
+def bulk_update_tag(input_data: dict) -> str:
+    """Send a one-tag bulkTagUpdate and return the tag id."""
+    (tag_id,) = input_data["ids"]
+    try:
+        data = core.call(_BULK_UPDATE_TAG_MUTATION, {"input": input_data})
+    except core.CliError as error:
+        if error.code == "graphql_error" and _TAG_NOT_FOUND.search(str(error)):
+            raise core.not_found_error("tag", tag_id) from error
+        raise
+    return core.returned_id("bulkTagUpdate", data, tag_id)
+
+
+# Selects what the delete and merge reports read. `image_path` is read only to
+# tell whether the tag has an image; callers must not print it.
+_FIND_TAGS_BY_IDS_QUERY = """
+query FindTagsByIds($ids: [ID!]) {
+  findTags(ids: $ids, filter: {per_page: -1}) {
+    tags {
+      id
+      name
+      sort_name
+      aliases
+      description
+      favorite
+      ignore_auto_tag
+      image_path
+      custom_fields
+      scene_count
+      scene_marker_count
+      image_count
+      gallery_count
+      performer_count
+      studio_count
+      group_count
+      parents { id name }
+      children { id name }
+    }
+  }
+}
+"""
+
+_TAG_NOT_FOUND_ID = re.compile(r"\btag with id (\d+) not found\b")
+
+
+def _tag_not_found(missing_ids: list[str]) -> core.CliError:
+    return core.CliError(
+        f"Tag not found: {', '.join(missing_ids)}.",
+        2,
+        "tag_not_found",
+        {"missing_ids": missing_ids},
+    )
+
+
+def find_tags_by_ids(ids: list[str]) -> list[dict]:
+    """The tags with `ids`, in the order Stash returns them.
+
+    Stash fails the whole read at the first missing ID; that ID, or any
+    requested ID absent from the result, raises `tag_not_found`.
+    """
+    try:
+        data = core.call(_FIND_TAGS_BY_IDS_QUERY, {"ids": ids})
+    except core.CliError as error:
+        match = _TAG_NOT_FOUND_ID.search(str(error))
+        if error.code == "graphql_error" and match:
+            raise _tag_not_found([match.group(1)]) from error
+        raise
+    tags = data.get("findTags", {}).get("tags", [])
+    found = {tag["id"] for tag in tags}
+    missing = [tag_id for tag_id in ids if tag_id not in found]
+    if missing:
+        raise _tag_not_found(missing)
+    return tags
+
+
+_DESTROY_TAGS_MUTATION = """
+mutation DestroyTags($ids: [ID!]!) {
+  tagsDestroy(ids: $ids)
+}
+"""
+
+
+def destroy_tags(ids: list[str]) -> None:
+    """Delete the tags in one all-or-nothing `tagsDestroy`."""
+    data = core.call(_DESTROY_TAGS_MUTATION, {"ids": ids})
+    if data.get("tagsDestroy") is not True:
+        raise core.CliError(
+            f"Stash did not delete the tags: tagsDestroy returned "
+            f"{data.get('tagsDestroy')!r}.",
+            1,
+            "graphql_error",
+        )
+
+
+_MERGE_TAGS_MUTATION = """
+mutation MergeTags($input: TagsMergeInput!) {
+  tagsMerge(input: $input) {
+    id
+  }
+}
+"""
+
+
+def merge_tags(input_data: dict) -> str:
+    """Merge the source tags into the destination and return its ID."""
+    data = core.call(_MERGE_TAGS_MUTATION, {"input": input_data})
+    return data["tagsMerge"]["id"]

stashapp_cli/sources.py

@@ -0,0 +1,116 @@
+"""Resolve stash-box and scrape-source values against the Stash configuration.
+
+Commands call these before building a dry-run report, so an invalid value
+fails the same way with or without `--apply`. Every failure exits 2.
+"""
+
+from __future__ import annotations
+
+from . import core, queries
+
+# Source prefixes that choose a scraper or a stash-box when a value is both.
+SCRAPER_PREFIX = "scraper"
+STASHBOX_PREFIX = "stashbox"
+
+
+def _box_label(box: dict) -> str:
+    return f"{box['name']} ({box['endpoint']})"
+
+
+def _matching_boxes(value: str, boxes: list[dict]) -> list[dict]:
+    return [box for box in boxes if value in (box["endpoint"], box["name"])]
+
+
+def list_stash_boxes() -> list[dict]:
+    """Configured stash-boxes as `{"endpoint", "name"}`; empty if none."""
+    return queries.sources.list_stash_boxes()
+
+
+def resolve_stash_box(value: str, boxes: list[dict] | None = None) -> dict:
+    """Return the configured stash-box whose endpoint or name is `value`."""
+    if boxes is None:
+        boxes = list_stash_boxes()
+    if not boxes:
+        raise core.CliError(
+            "No stash-box is configured in Stash. Add one in Stash under "
+            "Settings > Metadata Providers.",
+            2,
+            "no_stash_box_configured",
+        )
+    matches = _matching_boxes(value, boxes)
+    if len(matches) != 1:
+        raise core.CliError(
+            f"{value!r} is not a configured stash-box. Use a name or endpoint: "
+            + ", ".join(_box_label(box) for box in boxes)
+            + ".",
+            2,
+            "unknown_stash_box_endpoint",
+            details={"stash_boxes": boxes},
+        )
+    return matches[0]
+
+
+def resolve_source(value: str, content_type: str) -> dict:
+    """Resolve `value` to a Stash `ScraperSourceInput` for `content_type`.
+
+    A configured stash-box endpoint or name gives `stash_box_endpoint`; the id
+    of an installed scraper for `content_type` gives `scraper_id`. A
+    `scraper:` or `stashbox:` prefix chooses one kind and never matches the
+    other.
+    """
+    boxes, scraper_ids = queries.sources.list_sources(content_type)
+    prefix, _, rest = value.partition(":")
+    if prefix == STASHBOX_PREFIX:
+        return {"stash_box_endpoint": resolve_stash_box(rest, boxes)["endpoint"]}
+    if prefix == SCRAPER_PREFIX:
+        if rest in scraper_ids:
+            return {"scraper_id": rest}
+        raise _unknown_source(value, content_type, boxes)
+
+    box_matches = _matching_boxes(value, boxes)
+    is_scraper = value in scraper_ids
+    if len(box_matches) + is_scraper > 1:
+        matches: dict = {"stash_boxes": box_matches}
+        if is_scraper:
+            matches["scraper_id"] = value
+        # `stashbox:VALUE` is only unique when one stash-box matches; otherwise
+        # each stash-box is named by its endpoint.
+        box_forms = (
+            [f"{STASHBOX_PREFIX}:{value}"]
+            if len(box_matches) == 1
+            else [f"{STASHBOX_PREFIX}:{box['endpoint']}" for box in box_matches]
+        )
+        forms = ([f"{SCRAPER_PREFIX}:{value}"] if is_scraper else []) + box_forms
+        raise core.CliError(
+            f"{value!r} matches more than one source: "
+            + ", ".join(
+                [f"stash-box {_box_label(box)}" for box in box_matches]
+                + ([f"scraper {value}"] if is_scraper else [])
+            )
+            + ". Pass one of: "
+            + ", ".join(forms)
+            + ".",
+            2,
+            "ambiguous_source",
+            details={"matches": matches},
+        )
+    if box_matches:
+        return {"stash_box_endpoint": box_matches[0]["endpoint"]}
+    if is_scraper:
+        return {"scraper_id": value}
+    raise _unknown_source(value, content_type, boxes)
+
+
+def _unknown_source(value: str, content_type: str, boxes: list[dict]) -> core.CliError:
+    boxes_text = (
+        "configured stash-boxes: " + ", ".join(_box_label(box) for box in boxes)
+        if boxes
+        else "no stash-boxes are configured"
+    )
+    return core.CliError(
+        f"{value!r} is not a configured stash-box or an installed "
+        f"{content_type.lower()} scraper ({boxes_text}). Run "
+        "`stashapp-cli scrape sources` to list the valid sources.",
+        2,
+        "unknown_source",
+    )