stashapp-cli 0.1.0__py3-none-any.whl

stashapp_cli/core.py

@@ -0,0 +1,165 @@
+"""Shared Stash GraphQL transport, configuration, and output primitives."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+DEFAULT_TIMEOUT = 30.0
+# Prefix of every graphql_error message that `call` raises.
+GRAPHQL_ERROR_PREFIX = "Stash GraphQL error: "
+_active_timeout: ContextVar[float] = ContextVar(
+    "stash_timeout", default=DEFAULT_TIMEOUT
+)
+
+
+class CliError(Exception):
+    """An expected CLI failure with a documented process exit code."""
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: int,
+        code: str | None = None,
+        details: dict | None = None,
+    ):
+        super().__init__(message)
+        self.exit_code = exit_code
+        # Structured fields added to the JSON error envelope beside code/message.
+        self.details = details or {}
+        self.code = code or {
+            2: "usage_error",
+            3: "not_found",
+            4: "authentication_error",
+        }.get(exit_code, "internal_error")
+
+
+@contextmanager
+def request_timeout(seconds: float):
+    """Use ``seconds`` for all transport calls in this command invocation."""
+    token = _active_timeout.set(seconds)
+    try:
+        yield
+    finally:
+        _active_timeout.reset(token)
+
+
+def current_timeout() -> float:
+    """Return the timeout, in seconds, active for this command invocation."""
+    return _active_timeout.get()
+
+
+def get_server() -> str:
+    """Return the configured Stash server base URL, or raise an authentication error."""
+    server = os.environ.get("STASH_URL")
+    if not server:
+        raise CliError(
+            "STASH_URL is not set. Example: export STASH_URL=http://localhost:9999",
+            4,
+            "authentication_error",
+        )
+    return server.rstrip("/")
+
+
+def get_api_key() -> str:
+    """Return the configured Stash API key, or raise an authentication error."""
+    key = os.environ.get("STASH_API_KEY")
+    if not key:
+        raise CliError(
+            "STASH_API_KEY is not set. Generate one from Stash under "
+            "Settings > Security > Authentication, then "
+            "export STASH_API_KEY=<key>.",
+            4,
+            "authentication_error",
+        )
+    return key
+
+
+def call(query: str, variables: dict | None = None) -> dict:
+    """Make an authenticated GraphQL request to Stash and return the `data` payload.
+
+    Args:
+        query: A GraphQL query or mutation document.
+        variables: Optional variables for the document.
+
+    Returns:
+        The parsed `data` object from the GraphQL response.
+
+    Raises:
+        CliError: For HTTP, connection, or GraphQL-level failures with a
+            documented exit code.
+    """
+    url = f"{get_server()}/graphql"
+    body: dict[str, object] = {"query": query}
+    if variables is not None:
+        body["variables"] = variables
+
+    req = urllib.request.Request(
+        url, data=json.dumps(body).encode("utf-8"), method="POST"
+    )
+    req.add_header("ApiKey", get_api_key())
+    req.add_header("Content-Type", "application/json")
+    req.add_header("Accept", "application/json")
+
+    try:
+        with urllib.request.urlopen(req, timeout=_active_timeout.get()) as resp:
+            raw = resp.read()
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode("utf-8", "replace")
+        exit_code = {401: 4, 403: 4, 404: 3}.get(e.code, 1)
+        code = {
+            401: "authentication_error",
+            403: "authentication_error",
+            404: "not_found",
+        }.get(e.code, "transport_error")
+        raise CliError(
+            f"HTTP {e.code} calling Stash GraphQL: {detail[:500]}", exit_code, code
+        ) from e
+    except (TimeoutError, urllib.error.URLError) as e:
+        if isinstance(e, TimeoutError) or isinstance(e.reason, TimeoutError):
+            raise CliError(
+                f"Timed out calling Stash GraphQL after {_active_timeout.get():g} seconds",
+                1,
+                "timeout",
+            ) from e
+        raise CliError(
+            f"Could not reach {url}: {e.reason}", 1, "transport_error"
+        ) from e
+
+    result = json.loads(raw)
+    if errors := result.get("errors"):
+        messages = "; ".join(err.get("message", str(err)) for err in errors)
+        raise CliError(f"{GRAPHQL_ERROR_PREFIX}{messages}", 1, "graphql_error")
+    return result.get("data") or {}
+
+
+def not_found_error(noun: str, object_id: str) -> CliError:
+    """The `<noun>_not_found` error for an update of an object that is missing."""
+    return CliError(
+        f"No {noun} has id {object_id}.",
+        2,
+        f"{noun}_not_found",
+        {"missing_ids": [object_id]},
+    )
+
+
+def returned_id(operation: str, data: dict, object_id: str) -> str:
+    """`object_id` if the bulk `operation` result lists it; otherwise raise."""
+    returned = [str(item["id"]) for item in data.get(operation) or [] if item]
+    if object_id not in returned:
+        raise CliError(
+            f"Stash did not return {object_id} from {operation}; "
+            "the update may not have been applied.",
+            1,
+            "graphql_error",
+        )
+    return object_id
+
+
+def output(data) -> None:
+    """Pretty-print `data` as indented JSON to stdout."""
+    print(json.dumps(data, indent=2, ensure_ascii=False))

stashapp_cli/images.py

@@ -0,0 +1,72 @@
+"""Replacement of large scraped image data URIs in command results."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+from pathlib import Path
+
+from . import core
+
+_IMAGE_KEYS = {"image", "images", "front_image", "back_image"}
+_EXTENSIONS = {
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "image/webp": "webp",
+    "image/gif": "gif",
+}
+
+
+def _decode(value: str) -> tuple[str, bytes] | None:
+    try:
+        header, encoded = value[5:].split(",", 1)
+        if ";base64" not in header:
+            return None
+        media_type = header.split(";", 1)[0]
+        if not media_type:
+            return None
+        return media_type, base64.b64decode(encoded, validate=True)
+    except (ValueError, binascii.Error):
+        return None
+
+
+def _replace_value(value: object, image_dir: Path | None) -> object:
+    if not isinstance(value, str) or not value.startswith("data:"):
+        return value
+    decoded = _decode(value)
+    if decoded is None:
+        return {"omitted": True, "error": "invalid_data_uri"}
+    media_type, data = decoded
+    if image_dir is None:
+        return {"omitted": True, "media_type": media_type, "bytes": len(data)}
+    name = (
+        f"{hashlib.sha256(data).hexdigest()[:16]}.{_EXTENSIONS.get(media_type, 'bin')}"
+    )
+    path = image_dir.resolve() / name
+    try:
+        image_dir.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(data)
+    except OSError as error:
+        raise core.CliError(
+            f"Could not write image {path}: {error}", 1, "image_write_failed"
+        ) from error
+    return str(path)
+
+
+def replace_images(result: object, image_dir: Path | None) -> object:
+    """Walk a scrape result and replace data URI values in image fields."""
+    if isinstance(result, list):
+        return [replace_images(item, image_dir) for item in result]
+    if not isinstance(result, dict):
+        return result
+    replaced = {}
+    for key, value in result.items():
+        if key in _IMAGE_KEYS:
+            if key == "images" and isinstance(value, list):
+                replaced[key] = [_replace_value(item, image_dir) for item in value]
+            else:
+                replaced[key] = _replace_value(value, image_dir)
+        else:
+            replaced[key] = replace_images(value, image_dir)
+    return replaced

stashapp_cli/introspect.py

@@ -0,0 +1,343 @@
+"""Schema check: confirm the Stash GraphQL field/type names stashapp-cli depends on.
+
+`stashapp-cli introspect` reports missing names. For a fuller view when comparing
+Stash versions, `uv run python -m stashapp_cli.introspect` prints the matching
+Query and Mutation fields and every field of `DUMP_TYPES`.
+
+Stash renamed "Movie" to "Group" at some point in its history, and different
+installed versions may expose `scrapeGroupURL` vs the older `scrapeMovieURL`,
+or a `groups`/`movies` field on Scene, etc. Rather than assume one naming,
+this queries the live schema and reports what's actually there so the
+`queries` package can be adjusted to match before any write happens.
+"""
+
+from __future__ import annotations
+
+from . import core
+
+# Types this module dumps in full for a human comparing Stash versions --
+# includes the legacy Movie-era name alongside the modern Group-era ones so
+# a human can see at a glance which generation of names is live.
+DUMP_TYPES: tuple[str, ...] = (
+    "Scene",
+    "SceneUpdateInput",
+    "BulkSceneUpdateInput",
+    "Group",
+    "GroupCreateInput",
+    "GroupUpdateInput",
+    "MovieCreateInput",
+    "GroupDescriptionInput",
+    "SceneFilterType",
+    "GroupFilterType",
+)
+
+# Field/type names the `queries` package's GraphQL documents actually depend on --
+# checked by `stashapp-cli introspect`.
+EXPECTED_SCHEMA: dict[str, tuple[str, ...]] = {
+    "Query": (
+        "findStudios",
+        "findStudio",
+        "findTags",
+        "findTag",
+        "findGroups",
+        "findGroup",
+        "findScenes",
+        "findPerformers",
+        "findPerformer",
+        "scrapeGroupURL",
+        "scrapeSceneURL",
+        "scrapeSingleScene",
+        "scrapePerformerURL",
+        "configuration",
+        "listScrapers",
+        "findJob",
+    ),
+    "Mutation": (
+        "tagCreate",
+        "tagUpdate",
+        "bulkTagUpdate",
+        "groupCreate",
+        "groupUpdate",
+        "sceneUpdate",
+        "performerCreate",
+        "performerUpdate",
+        "metadataScan",
+        "metadataGenerate",
+        "metadataIdentify",
+        "bulkSceneUpdate",
+        "bulkPerformerUpdate",
+        "bulkGroupUpdate",
+        "bulkStudioUpdate",
+        "studioCreate",
+        "studioUpdate",
+        "performerMerge",
+        "tagsDestroy",
+        "tagsMerge",
+        "backupDatabase",
+        "submitStashBoxFingerprints",
+    ),
+    "Scene": ("groups", "stash_ids", "files", "custom_fields", "code"),
+    "SceneGroup": ("group", "scene_index"),
+    "StashID": ("endpoint", "stash_id", "updated_at"),
+    # Add and remove list options.
+    "BulkSceneUpdateInput": ("ids", "tag_ids", "urls", "performer_ids"),
+    "BulkPerformerUpdateInput": ("ids", "tag_ids", "urls", "alias_list"),
+    "BulkGroupUpdateInput": ("ids", "tag_ids", "urls"),
+    "BulkStudioUpdateInput": ("ids", "tag_ids", "urls"),
+    "BulkTagUpdateInput": ("ids", "aliases", "parent_ids", "child_ids"),
+    "BulkUpdateIds": ("ids", "mode"),
+    "BulkUpdateStrings": ("values", "mode"),
+    "BulkUpdateIdMode": (),
+    "SceneGroupInput": ("group_id", "scene_index"),
+    "StashIDInput": ("endpoint", "stash_id", "updated_at"),
+    # Studio create, performer merge and its loss report, and backup.
+    "StudioCreateInput": ("name", "urls", "parent_id"),
+    "StudioUpdateInput": ("id", "name", "parent_id", "details", "aliases"),
+    "TagUpdateInput": (
+        "id",
+        "name",
+        "sort_name",
+        "description",
+        "favorite",
+        "ignore_auto_tag",
+        "aliases",
+        "image",
+        "custom_fields",
+        "parent_ids",
+        "child_ids",
+    ),
+    "PerformerMergeInput": ("source", "destination", "values"),
+    "TagsMergeInput": ("source", "destination", "values"),
+    "BackupDatabaseInput": ("download",),
+    "Performer": (
+        "name",
+        "disambiguation",
+        "alias_list",
+        "details",
+        "urls",
+        "image_path",
+        "custom_fields",
+        "stash_ids",
+    ),
+    # The find commands: the criteria that --name and --studio-id set, the
+    # paging and sort, and the result fields not checked elsewhere.
+    "StudioFilterType": ("name", "aliases", "AND"),
+    "PerformerFilterType": ("name", "aliases", "AND"),
+    "FindFilterType": ("page", "per_page", "sort", "direction"),
+    "Studio": (
+        "aliases",
+        "details",
+        "image_path",
+        "custom_fields",
+        "parent_studio",
+        "stash_ids",
+    ),
+    "Group": (
+        "aliases",
+        "front_image_path",
+        "back_image_path",
+        "custom_fields",
+        "studio",
+    ),
+    "Tag": (
+        "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",
+        "children",
+    ),
+    # Fingerprint submission. Only fingerprint types are read, never values.
+    "StashBoxFingerprintSubmissionInput": ("scene_ids", "stash_box_endpoint"),
+    "VideoFile": ("duration", "fingerprints"),
+    "Fingerprint": ("type",),
+    # Stash-box and source lookup. StashBox.api_key exists but is never read.
+    "ConfigResult": ("general",),
+    "ConfigGeneralResult": ("stashBoxes",),
+    "StashBox": ("endpoint", "name"),
+    "Scraper": ("id", "name", "scene", "performer", "group"),
+    "ScraperSpec": ("supported_scrapes",),
+    "ScraperSourceInput": ("scraper_id", "stash_box_endpoint"),
+    "ScrapeSingleSceneInput": ("scene_id", "query"),
+    "ScrapedScene": (
+        "title",
+        "code",
+        "details",
+        "director",
+        "urls",
+        "date",
+        "duration",
+        "remote_site_id",
+        "image",
+        "studio",
+        "tags",
+        "performers",
+        "groups",
+    ),
+    "ScrapedStudio": (
+        "stored_id",
+        "name",
+        "urls",
+        "details",
+        "aliases",
+        "remote_site_id",
+        "image",
+        "parent",
+    ),
+    "ScrapedTag": ("stored_id", "name", "remote_site_id"),
+    "ScrapedPerformer": (
+        "stored_id",
+        "name",
+        "disambiguation",
+        "gender",
+        "urls",
+        "aliases",
+        "birthdate",
+        "death_date",
+        "country",
+        "ethnicity",
+        "hair_color",
+        "eye_color",
+        "height",
+        "weight",
+        "measurements",
+        "fake_tits",
+        "penis_length",
+        "circumcised",
+        "career_start",
+        "career_end",
+        "tattoos",
+        "piercings",
+        "details",
+        "remote_site_id",
+        "tags",
+        "images",
+    ),
+    "ScrapedGroup": (
+        "stored_id",
+        "name",
+        "aliases",
+        "date",
+        "duration",
+        "rating",
+        "director",
+        "synopsis",
+        "urls",
+        "studio",
+        "tags",
+        "front_image",
+        "back_image",
+    ),
+    # Background jobs: scan run, generate run, scene identify, job get/wait.
+    "Job": (
+        "id",
+        "status",
+        "progress",
+        "description",
+        "error",
+        "addTime",
+        "startTime",
+        "endTime",
+    ),
+    "FindJobInput": ("id",),
+    "ScanMetadataInput": (
+        "paths",
+        "rescan",
+        "scanGenerateCovers",
+        "scanGeneratePhashes",
+    ),
+    "GenerateMetadataInput": ("covers", "phashes", "sceneIDs", "paths"),
+    "IdentifyMetadataInput": ("sources", "sceneIDs", "paths"),
+    "IdentifySourceInput": ("source",),
+    "JobStatus": (),
+    # These types appear directly in the CLI's GraphQL documents. Empty
+    # tuples mean the type's existence, rather than particular fields, matters.
+    "SceneFilterType": ("title", "code", "AND"),
+    "GroupFilterType": ("name", "studios", "AND"),
+    "TagFilterType": ("name", "aliases", "AND"),
+    "GroupCreateInput": (),
+    "GroupUpdateInput": (),
+    "SceneUpdateInput": ("groups", "stash_ids"),
+    "PerformerUpdateInput": (),
+    "GenderEnum": (),
+    "ScrapeContentType": (),
+    "ScrapeType": (),
+}
+
+_TYPE_FIELDS_QUERY = """
+query TypeFields($name: String!) {
+  __type(name: $name) {
+    name
+    kind
+    fields { name }
+    inputFields { name }
+  }
+}
+"""
+
+
+def type_info(type_name: str) -> dict | None:
+    data = core.call(_TYPE_FIELDS_QUERY, {"name": type_name})
+    return data.get("__type")
+
+
+def _names(info: dict | None) -> list[str]:
+    if not info:
+        return []
+    return [f["name"] for f in (info.get("fields") or info.get("inputFields") or [])]
+
+
+def missing_schema_names() -> list[str]:
+    """Return "Type.field" names in EXPECTED_SCHEMA absent from the live schema."""
+    missing = []
+    for type_name, field_names in EXPECTED_SCHEMA.items():
+        info = type_info(type_name)
+        if not info:
+            if not field_names:
+                missing.append(type_name)
+                continue
+            missing.extend(f"{type_name}.{field_name}" for field_name in field_names)
+            continue
+        present = set(_names(info))
+        for field_name in field_names:
+            if field_name not in present:
+                missing.append(f"{type_name}.{field_name}")
+    return missing
+
+
+def main() -> None:
+    print("Checking Stash GraphQL schema at", core.get_server(), "\n")
+
+    query_fields = _names(type_info("Query"))
+    mutation_fields = _names(type_info("Mutation"))
+
+    print("Query fields matching group/movie/scrape:")
+    for name in sorted(query_fields):
+        if any(kw in name.lower() for kw in ("group", "movie", "scrape")):
+            print(f"  - {name}")
+
+    print("\nMutation fields matching group/movie/scene/tag:")
+    for name in sorted(mutation_fields):
+        if any(kw in name.lower() for kw in ("group", "movie", "scene", "tag")):
+            print(f"  - {name}")
+
+    for type_name in DUMP_TYPES:
+        info = type_info(type_name)
+        print(f"\n{type_name}: {'(not found)' if info is None else ''}")
+        for name in _names(info):
+            print(f"  - {name}")
+
+
+if __name__ == "__main__":
+    main()

stashapp_cli/queries/__init__.py

@@ -0,0 +1,40 @@
+"""Stash GraphQL documents and thin wrapper functions, one submodule per noun.
+
+Field/type names here assume a modern Stash (post Movie->Group rename):
+`scrapeGroupURL`, `groupCreate`/`groupUpdate`, and a `groups` field on
+Scene/SceneUpdateInput. Run `uv run stashapp-cli introspect` against your
+instance BEFORE the first write; it exits nonzero and lists any missing
+names -- if your Stash version differs (e.g. still
+`scrapeMovieURL`/`movieCreate`/`movies`), every query lives in this package.
+
+Callers use the submodules, for example `queries.tag.find_tag`. This package
+does not re-export their names.
+"""
+
+from . import (
+    backup,
+    group,
+    job,
+    metadata,
+    performer,
+    scene,
+    scrape,
+    sources,
+    stashbox,
+    studio,
+    tag,
+)
+
+__all__ = [
+    "backup",
+    "group",
+    "job",
+    "metadata",
+    "performer",
+    "scene",
+    "scrape",
+    "sources",
+    "stashbox",
+    "studio",
+    "tag",
+]

stashapp_cli/queries/_get.py

@@ -0,0 +1,27 @@
+"""Read one object by ID through Stash's singular `find<Noun>` queries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .. import core
+from ._image_flags import add_image_flags
+
+
+@dataclass(frozen=True)
+class ObjectSpec:
+    """How one noun's `get` differs from the others."""
+
+    query_field: str  # "findStudio", "findPerformer", "findGroup", "findTag"
+    fields: str  # the noun's field fragment, shared with its find query
+    image_flags: dict[str, str]  # path field -> has_* flag, as in find
+
+
+def get_object(spec: ObjectSpec, object_id: str) -> dict | None:
+    """The object with `object_id`, with its image flags, or `None` if missing.
+
+    Stash's singular queries return `null` for a missing ID.
+    """
+    query = f"query Get($id: ID!) {{ {spec.query_field}(id: $id) {{ {spec.fields} }} }}"
+    obj = core.call(query, {"id": object_id})[spec.query_field]
+    return None if obj is None else add_image_flags(obj, spec.image_flags)

stashapp_cli/queries/_image_flags.py

@@ -0,0 +1,30 @@
+"""Derived `has_*` image flags for find results.
+
+Stash has no field that says whether an object has an image. It marks a
+missing image in two ways: a URL with a `default=true` query parameter, or
+`null`. This module is the one place that reads those two markers.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import parse_qs, urlsplit
+
+
+def _has_image(path: str | None) -> bool:
+    if path is None:
+        return False
+    return "true" not in parse_qs(urlsplit(path).query).get("default", [])
+
+
+def add_image_flags(obj: dict, fields: dict[str, str]) -> dict:
+    """Set `obj[flag]` for each `path_field: flag` pair in `fields`; return `obj`."""
+    for path_field, flag in fields.items():
+        obj[flag] = _has_image(obj.get(path_field))
+    return obj
+
+
+def add_page_image_flags(page: dict, key: str, fields: dict[str, str]) -> dict:
+    """Add the flags to every object in `page[key]`; return `page`."""
+    for obj in page[key]:
+        add_image_flags(obj, fields)
+    return page