stashapp-client 0.1.3__py3-none-any.whl

stashapp_client/__init__.py

@@ -0,0 +1,74 @@
+"""Python client for the Stash GraphQL API."""
+
+from .client import StashClient
+from .criteria import (
+    between,
+    equals,
+    excludes,
+    gql_criterion,
+    greater_than,
+    includes,
+    includes_all,
+    is_null,
+    less_than,
+    matches_regex,
+    not_equals,
+    not_matches_regex,
+    not_null,
+    stash_id,
+    stash_ids,
+)
+from .errors import (
+    GraphQLError,
+    StashConnectionError,
+    StashError,
+    StashResponseError,
+    TransportError,
+)
+from .filters import (
+    find_filter,
+    gallery_filter,
+    group_filter,
+    image_filter,
+    marker_filter,
+    performer_filter,
+    scene_filter,
+    studio_filter,
+    tag_filter,
+)
+from .mutation import MutationPlan, prepare_mutations
+
+__all__ = [
+    "GraphQLError",
+    "MutationPlan",
+    "StashClient",
+    "StashConnectionError",
+    "StashError",
+    "StashResponseError",
+    "TransportError",
+    "between",
+    "equals",
+    "excludes",
+    "find_filter",
+    "gallery_filter",
+    "gql_criterion",
+    "greater_than",
+    "group_filter",
+    "image_filter",
+    "includes",
+    "includes_all",
+    "is_null",
+    "less_than",
+    "marker_filter",
+    "matches_regex",
+    "not_equals",
+    "not_matches_regex",
+    "not_null",
+    "performer_filter",
+    "prepare_mutations",
+    "scene_filter",
+    "stash_id",
+    "stash_ids",
+    "studio_filter",
+    "tag_filter",
+]

stashapp_client/cli.py

@@ -0,0 +1,93 @@
+"""Command-line entry point for schema and operation generation."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from .client import StashClient
+from .codegen import attach_documents, render_fragments, render_inputs
+from .introspection import introspect_schema, load_schema, save_schema
+from .registry import build_registry, save_registry
+from .schema_diff import compare_schemas, format_report, has_changes, report_json
+
+
+def _path_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--out-schema", type=Path, default=Path("schema.json"))
+    parser.add_argument("--out-registry", type=Path, default=Path("operations_registry.json"))
+    parser.add_argument("--out-fragments", type=Path, default=Path("fragments.py"))
+    parser.add_argument("--out-inputs", type=Path, default=Path("inputs.py"))
+
+
+def _write_artifacts(schema: dict[str, Any], provenance: dict[str, Any], args: Any) -> None:
+    save_schema({"data": {"__schema": schema}}, args.out_schema)
+    registry = attach_documents(build_registry(schema), schema)
+    registry["provenance"] = provenance
+    save_registry(registry, args.out_registry)
+    args.out_fragments.write_text(render_fragments(schema), encoding="utf-8")
+    args.out_inputs.write_text(render_inputs(schema), encoding="utf-8")
+
+
+def _verify_value(value: str) -> bool | str:
+    lowered = value.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    return value
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="stashapp-client")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    build = commands.add_parser("build-ops", help="build artifacts from a schema snapshot")
+    build.add_argument("--schema", type=Path, required=True)
+    _path_options(build)
+
+    sync = commands.add_parser("sync-schema", help="introspect a live server and build artifacts")
+    sync.add_argument("--credentials-file", type=Path, required=True)
+    sync.add_argument("--verify", type=_verify_value, default=True)
+    sync.add_argument("--timeout", type=float, default=30)
+    _path_options(sync)
+
+    diff = commands.add_parser("diff-schema", help="compare two schema snapshots")
+    diff.add_argument("--base", type=Path, required=True)
+    diff.add_argument("--current", type=Path, required=True)
+    diff.add_argument("--json", action="store_true", dest="as_json")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _parser().parse_args(argv)
+    if args.command == "build-ops":
+        _write_artifacts(
+            load_schema(args.schema),
+            {"source": "introspection-snapshot", "path": str(args.schema)},
+            args,
+        )
+        return
+    if args.command == "diff-schema":
+        report = compare_schemas(load_schema(args.base), load_schema(args.current))
+        print(report_json(report) if args.as_json else format_report(report))
+        if has_changes(report):
+            raise SystemExit(1)
+        return
+
+    client = StashClient.from_credentials_file(
+        args.credentials_file, verify=args.verify, timeout=args.timeout
+    )
+    try:
+        schema = introspect_schema(client)
+    finally:
+        client.close()
+    _write_artifacts(
+        schema,
+        {"source": "live-introspection", "path": str(args.credentials_file)},
+        args,
+    )
+
+
+if __name__ == "__main__":
+    main()

stashapp_client/client.py

@@ -0,0 +1,126 @@
+"""Stash client configuration and low-level GraphQL execution."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import requests
+from requests import Session
+
+from .errors import StashConnectionError, StashResponseError, TransportError
+from .response import extract_response
+from .runtime_bind import load_and_bind
+
+
+class StashClient:
+    """A configured client for one Stash GraphQL endpoint."""
+
+    def __init__(
+        self,
+        url: str,
+        api_key: str,
+        *,
+        verify: bool | str = True,
+        timeout: float = 30,
+        session: Session | None = None,
+        registry_path: str | os.PathLike[str] | None = None,
+    ) -> None:
+        if not url:
+            raise ValueError("url is required")
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.url = url
+        self.api_key = api_key
+        self.verify = verify
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        selected_registry = registry_path or Path(__file__).parent / "generated" / "operations_registry.json"
+        if selected_registry.exists():
+            load_and_bind(self, str(selected_registry))
+
+    @classmethod
+    def from_credentials_file(
+        cls,
+        path: str | os.PathLike[str],
+        *,
+        verify: bool | str = True,
+        timeout: float = 30,
+        **kwargs: Any,
+    ) -> "StashClient":  # noqa: UP037
+        lines = Path(path).read_text(encoding="utf-8").splitlines()
+        values = [line.strip() for line in lines if line.strip()]
+        if len(values) < 2:
+            raise ValueError("credentials file must contain URL and API key")
+        if isinstance(verify, str) and not os.path.isabs(verify):
+            verify = str(Path(path).parent / verify)
+        return cls(values[0], values[1], verify=verify, timeout=timeout, **kwargs)
+
+    @classmethod
+    def from_env(
+        cls, *, verify: bool | str = True, timeout: float = 30, **kwargs: Any
+    ) -> "StashClient":  # noqa: UP037
+        configured_verify = os.environ.get("STASHAPI_TLS_VERIFY")
+        if configured_verify is not None:
+            verify = _parse_verify(configured_verify)
+        return cls(
+            os.environ.get("STASH_URL", ""),
+            os.environ.get("STASH_API_KEY", ""),
+            verify=verify,
+            timeout=timeout,
+            **kwargs,
+        )
+
+    def execute(
+        self,
+        query: str,
+        variables: dict[str, Any] | None = None,
+        *,
+        response: str = "data",
+        field: str | list[str] | None = None,
+    ) -> Any:
+        """Execute a GraphQL document and extract its result."""
+        try:
+            result = self.session.post(
+                self.url,
+                json={"query": query, "variables": variables or {}},
+                headers={"ApiKey": self.api_key, "Content-Type": "application/json"},
+                verify=self.verify,
+                timeout=self.timeout,
+            )
+            result.raise_for_status()
+            envelope = result.json()
+        except requests.RequestException as exc:
+            raise TransportError(str(exc)) from exc
+        except ValueError as exc:
+            raise StashResponseError("server returned invalid JSON") from exc
+        if not isinstance(envelope, dict):
+            raise StashResponseError("GraphQL response must be a JSON object")
+        return extract_response(envelope, response=response, field=field)
+
+    def has_connection(self) -> bool:
+        """Return whether the endpoint accepts a minimal GraphQL request."""
+        try:
+            self.execute("query ConnectionCheck { __typename }")
+        except Exception as exc:
+            raise StashConnectionError(str(exc)) from exc
+        return True
+
+    def close(self) -> None:
+        self.session.close()
+
+    def __enter__(self) -> "StashClient":  # noqa: PYI034, UP037
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+def _parse_verify(value: str) -> bool | str:
+    lowered = value.strip().lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    return value

stashapp_client/codegen.py

@@ -0,0 +1,176 @@
+"""Render deterministic Python artifacts from schema-derived metadata."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .fragments import combine_fragments, get_dependent_fragments
+from .registry import _compact_selection, _has_required_arguments, _named_type
+
+
+def render_inputs(schema: dict[str, Any]) -> str:
+    """Render schema-derived input metadata and validation helpers."""
+    specs = build_input_specs(schema)
+    lines = [
+        '"""Generated GraphQL input metadata and validation helpers."""',
+        "",
+        "from typing import Any",
+        "",
+        "from stashapp_client.input_validation import validate_input_value",
+        "",
+        f"INPUT_FIELDS = {specs!r}",
+        "",
+        "def validate_input(name: str, value: Any) -> Any:",
+        "    \"\"\"Validate one generated GraphQL input object and return it.\"\"\"",
+        "    return validate_input_value(name, value, INPUT_FIELDS)",
+        "",
+        "__all__ = [\"INPUT_FIELDS\", \"validate_input\"]",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def build_input_specs(schema: dict[str, Any]) -> dict[str, dict[str, dict[str, Any]]]:
+    """Return input object fields with GraphQL type and required metadata."""
+    specs: dict[str, dict[str, dict[str, Any]]] = {}
+    for definition in schema.get("types", []):
+        name = definition.get("name")
+        if definition.get("kind") != "INPUT_OBJECT" or not name:
+            continue
+        specs[name] = {
+            field["name"]: {
+                "type": _type_string(field.get("type", {})),
+                "required": field.get("type", {}).get("kind") == "NON_NULL",
+            }
+            for field in definition.get("inputFields", []) or []
+            if field.get("name")
+        }
+    return dict(sorted(specs.items()))
+
+
+def _type_string(type_ref: dict[str, Any]) -> str:
+    if type_ref.get("kind") == "NON_NULL":
+        return f"{_type_string(type_ref.get('ofType', {}))}!"
+    if type_ref.get("kind") == "LIST":
+        return f"[{_type_string(type_ref.get('ofType', {}))}]"
+    return type_ref.get("name", "Unknown")
+
+
+def render_fragments(schema: dict[str, Any]) -> str:
+    """Render full root fragments with bounded nested object selections."""
+    fragments = build_fragments(schema)
+    lines = [
+        '"""Generated schema-derived GraphQL fragments. Do not edit by hand."""',
+        "",
+        f"FRAGMENTS = {json.dumps(fragments, indent=2, sort_keys=True)}",
+        "",
+        "__all__ = [\"FRAGMENTS\"]",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def build_fragments(schema: dict[str, Any]) -> dict[str, str]:
+    """Build full root fragment documents with bounded nested selections."""
+    types = {item["name"]: item for item in schema.get("types", []) if item.get("name")}
+    fragments: dict[str, str] = {}
+    for name, definition in sorted(types.items()):
+        if definition.get("kind") in {"UNION", "INTERFACE"} and not name.startswith("__"):
+            possible = definition.get("possibleTypes", []) or []
+            spreads = " ".join(
+                f"...{item['name']}" for item in possible if item.get("name")
+            )
+            fragments[name] = f"fragment {name} on {name} {{ {spreads or '__typename'} }}"
+            continue
+        if definition.get("kind") != "OBJECT" or name.startswith("__"):
+            continue
+        selection = _root_selection(name, types)
+        fragments[name] = f"fragment {name} on {name} {{ {selection} }}"
+
+    return fragments
+
+
+def attach_documents(registry: dict[str, Any], schema: dict[str, Any]) -> dict[str, Any]:
+    """Add fragment-backed GraphQL documents to a registry in place."""
+    fragments = build_fragments(schema)
+    registry["input_fields"] = build_input_specs(schema)
+    registry["field_types"] = build_field_specs(schema)
+    for operation in registry.get("operations", []):
+        result_type = operation.get("result_type")
+        if result_type not in fragments:
+            continue
+        operation["fragment_name"] = result_type
+        operation["document"] = _operation_document(operation, fragments)
+    return registry
+
+
+def build_field_specs(schema: dict[str, Any]) -> dict[str, dict[str, str | None]]:
+    """Return schema-derived field-to-named-type metadata for path validation."""
+    specs: dict[str, dict[str, str | None]] = {}
+    for definition in schema.get("types", []):
+        name = definition.get("name")
+        if not name:
+            continue
+        specs[name] = {
+            field["name"]: _named_type(field.get("type", {}))
+            for field in definition.get("fields", []) or []
+            if field.get("name")
+        }
+    return dict(sorted(specs.items()))
+
+
+def _operation_document(operation: dict[str, Any], fragments: dict[str, str]) -> str:
+    kind = operation.get("kind", "query")
+    name = operation["name"]
+    arguments = operation.get("arguments", [])
+    definitions = ", ".join(f"${item['name']}: {item['type']}" for item in arguments)
+    passed = ", ".join(f"{item['name']}: ${item['name']}" for item in arguments)
+    fragment_name = operation["fragment_name"]
+    dependencies = get_dependent_fragments(fragment_name, fragments)
+    fragment_definitions = combine_fragments(fragment_name, dependencies, fragments)
+    variable_part = f"({definitions})" if definitions else ""
+    passed_part = f"({passed})" if passed else ""
+    document = (
+        f"{kind} {name}{variable_part} {{ "
+        f"{name}{passed_part} {{ ...{fragment_name} }} }}"
+    )
+    return f"{document}\n{fragment_definitions}"
+
+
+def _root_selection(type_name: str, types: dict[str, dict[str, Any]]) -> str:
+    definition = types.get(type_name, {})
+    selections: list[str] = []
+    for field in definition.get("fields", []) or []:
+        if field.get("isDeprecated") or _has_required_arguments(field.get("args", [])):
+            continue
+        field_type = _named_type(field.get("type", {}))
+        field_definition = types.get(field_type or "", {})
+        if field_definition.get("kind") in {"OBJECT", "UNION", "INTERFACE"}:
+            if _reenters(field_type or "", type_name, types):
+                nested = _compact_selection(field_type, types)
+            else:
+                nested = f"...{field_type}"
+            selections.append(f"{field['name']} {{ {nested} }}")
+        elif field_type:
+            selections.append(field["name"])
+    return " ".join(selections) or "__typename"
+
+
+def _reenters(type_name: str, target: str, types: dict[str, dict[str, Any]]) -> bool:
+    """Return whether following object fields from a type can reach the target."""
+    pending = [type_name]
+    visited: set[str] = set()
+    while pending:
+        current = pending.pop()
+        if current == target:
+            return True
+        if current in visited:
+            continue
+        visited.add(current)
+        definition = types.get(current, {})
+        for field in definition.get("fields", []) or []:
+            nested = _named_type(field.get("type", {}))
+            if types.get(nested or "", {}).get("kind") == "OBJECT":
+                pending.append(nested)
+    return False

stashapp_client/criteria.py

@@ -0,0 +1,73 @@
+"""Small builders for Stash GraphQL filter criteria."""
+
+from typing import Any
+
+
+def gql_criterion(modifier: str, value: Any = None, **extra: Any) -> dict[str, Any]:
+    criterion: dict[str, Any] = {"modifier": modifier}
+    if value is not None:
+        criterion["value"] = value
+    criterion.update(extra)
+    return criterion
+
+
+def equals(value: Any) -> dict[str, Any]:
+    return gql_criterion("EQUALS", value)
+
+
+def not_equals(value: Any) -> dict[str, Any]:
+    return gql_criterion("NOT_EQUALS", value)
+
+
+def includes(value: Any, *, depth: int | None = None, excludes: Any = None) -> dict[str, Any]:
+    return _hierarchy("INCLUDES", value, depth=depth, excludes=excludes)
+
+
+def includes_all(value: Any, *, depth: int | None = None, excludes: Any = None) -> dict[str, Any]:
+    return _hierarchy("INCLUDES_ALL", value, depth=depth, excludes=excludes)
+
+
+def excludes(value: Any, *, depth: int | None = None) -> dict[str, Any]:
+    return _hierarchy("EXCLUDES", value, depth=depth)
+
+
+def between(start: Any, end: Any) -> dict[str, Any]:
+    return {"value": start, "value2": end, "modifier": "BETWEEN"}
+
+
+def greater_than(value: Any) -> dict[str, Any]:
+    return gql_criterion("GREATER_THAN", value)
+
+
+def less_than(value: Any) -> dict[str, Any]:
+    return gql_criterion("LESS_THAN", value)
+
+
+def matches_regex(value: str) -> dict[str, Any]:
+    return gql_criterion("MATCHES_REGEX", value)
+
+
+def not_matches_regex(value: str) -> dict[str, Any]:
+    return gql_criterion("NOT_MATCHES_REGEX", value)
+
+
+def is_null(value: bool = True) -> dict[str, Any]:
+    return gql_criterion("IS_NULL", value)
+
+
+def not_null() -> dict[str, Any]:
+    return is_null(False)
+
+
+def stash_id(endpoint: str, value: str) -> dict[str, Any]:
+    return {"endpoint": endpoint, "stash_id": value}
+
+
+def stash_ids(endpoint: str, values: list[str]) -> dict[str, Any]:
+    return {"endpoint": endpoint, "stash_ids": values}
+
+
+def _hierarchy(modifier: str, value: Any, **kwargs: Any) -> dict[str, Any]:
+    criterion = gql_criterion(modifier, value)
+    criterion.update({key: value for key, value in kwargs.items() if value is not None})
+    return criterion

stashapp_client/errors.py

@@ -0,0 +1,29 @@
+"""Exceptions raised by the Stash client."""
+
+from typing import Any
+
+
+class StashError(Exception):
+    """Base class for client errors."""
+
+
+class TransportError(StashError):
+    """A network, TLS, or timeout error occurred."""
+
+
+class StashConnectionError(TransportError):
+    """The endpoint could not be validated as a Stash GraphQL server."""
+
+
+class StashResponseError(StashError):
+    """The server response was not a valid GraphQL response."""
+
+
+class GraphQLError(StashError):
+    """The server returned one or more GraphQL errors."""
+
+    def __init__(self, errors: list[dict[str, Any]], data: Any = None) -> None:
+        self.errors = errors
+        self.data = data
+        message = "; ".join(str(error.get("message", error)) for error in errors)
+        super().__init__(message or "GraphQL request failed")

stashapp_client/filters.py

@@ -0,0 +1,64 @@
+"""Schema-shaped builders for common Stash filter input objects."""
+
+from typing import Any
+
+from .errors import StashResponseError
+
+_FIELDS = {
+    "find": {"q", "page", "per_page", "sort", "direction"},
+    "scene": {"id", "title", "date", "details", "organized", "rating100", "duration", "tags", "performers", "studios", "performers_filter", "studios_filter", "AND", "OR", "NOT"},
+    "image": {"id", "path", "rating100", "organized", "date", "galleries", "studios", "tags", "performers", "AND", "OR", "NOT"},
+    "gallery": {"id", "title", "date", "organized", "rating100", "has_chapters", "performers", "studios", "tags", "AND", "OR", "NOT"},
+    "performer": {"id", "name", "gender", "country", "rating100", "image_count", "stash_id", "stash_id_endpoint", "AND", "OR", "NOT"},
+    "studio": {"id", "name", "url", "favorite", "scene_count", "image_count", "stash_id", "stash_id_endpoint", "AND", "OR", "NOT"},
+    "tag": {"id", "name", "favorite", "scene_count", "image_count", "stash_id", "AND", "OR", "NOT"},
+    "group": {"id", "name", "rating100", "scene_count", "performers", "studios", "tags", "AND", "OR", "NOT"},
+    "marker": {"id", "title", "seconds", "duration", "scene_id", "tags", "AND", "OR", "NOT"},
+}
+
+
+def _build(kind: str, values: dict[str, Any], *, strict: bool) -> dict[str, Any]:
+    unknown = set(values) - _FIELDS[kind]
+    if strict and unknown:
+        names = ", ".join(sorted(unknown))
+        raise StashResponseError(f"unknown fields for {kind}_filter: {names}")
+    result = dict(values)
+    if kind == "studio" and "stash_id" in result:
+        result["stash_id_endpoint"] = result.pop("stash_id")
+    return result
+
+
+def find_filter(*, strict: bool = True, **values: Any) -> dict[str, Any]:
+    return _build("find", values, strict=strict)
+
+
+def scene_filter(*, strict: bool = True, **values: Any) -> dict[str, Any]:
+    return _build("scene", values, strict=strict)
+
+
+def image_filter(*, strict: bool = True, **values: Any) -> dict[str, Any]:
+    return _build("image", values, strict=strict)
+
+
+def gallery_filter(*, strict: bool = True, **values: Any) -> dict[str, Any]:
+    return _build("gallery", values, strict=strict)
+
+
+def performer_filter(*, strict: bool = True, **values: Any) -> dict[str, Any]:
+    return _build("performer", values, strict=strict)
+
+
+def studio_filter(*, strict: bool = True, **values: Any) -> dict[str, Any]:
+    return _build("studio", values, strict=strict)
+
+
+def tag_filter(*, strict: bool = True, **values: Any) -> dict[str, Any]:
+    return _build("tag", values, strict=strict)
+
+
+def group_filter(*, strict: bool = True, **values: Any) -> dict[str, Any]:
+    return _build("group", values, strict=strict)
+
+
+def marker_filter(*, strict: bool = True, **values: Any) -> dict[str, Any]:
+    return _build("marker", values, strict=strict)