stashapp-client 0.1.3__tar.gz

stashapp_client-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Written2001
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stashapp_client-0.1.3/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: stashapp-client
+Version: 0.1.3
+Summary: Python client for the Stash GraphQL API
+Author-email: Written2001 <knasdkn@protonmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Written2001/stash_client
+Project-URL: Repository, https://github.com/Written2001/stash_client
+Project-URL: Issues, https://github.com/Written2001/stash_client/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: graphql-core>=3.2
+Requires-Dist: pandas>=2.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# stashapp-client
+
+An SDL-first Python client for the [Stash](https://github.com/stashapp/stash) GraphQL API. The package generates an operation registry from the Stash schema and binds query and mutation methods to `StashClient` at runtime.
+
+## Installation
+
+Install the latest published release from PyPI:
+
+```bash
+python -m pip install stashapp-client
+```
+
+For development from a checkout of this repository:
+
+```bash
+python -m pip install -e .
+```
+
+For development tools:
+
+```bash
+python -m pip install -e '.[dev]'
+```
+
+Releases follow [Semantic Versioning](https://semver.org/). See
+[`CHANGELOG.md`](CHANGELOG.md) for release history.
+
+## Connect
+
+Create a credentials file containing the GraphQL URL and API key on separate lines:
+
+```text
+https://stash.example/graphql
+YOUR_API_KEY
+```
+
+Then create a client:
+
+```python
+from stashapp_client import StashClient
+
+client = StashClient.from_credentials_file(".stash_credentials")
+print(client.has_connection())
+```
+
+Credentials can also come directly from arguments or environment variables:
+
+```python
+client = StashClient(
+    url="https://stash.example/graphql",
+    api_key="YOUR_API_KEY",
+)
+
+# Reads STASH_URL and STASH_API_KEY.
+client = StashClient.from_env()
+```
+
+Always close the client when finished, or use it as a context manager:
+
+```python
+with StashClient.from_credentials_file(".stash_credentials") as client:
+    print(client.findTags())
+```
+
+## TLS
+
+Pass `verify=False` only for a trusted internal endpoint. A CA bundle path is preferred for self-signed certificates:
+
+```python
+client = StashClient.from_credentials_file(
+    ".stash_credentials",
+    verify="/path/to/internal-ca.pem",
+)
+```
+
+`STASHAPI_TLS_VERIFY=false` disables verification, while a path value selects a CA bundle.
+
+## Use The API
+
+Operation methods are created from the bundled registry, so queries and mutations use schema-defined names and keyword arguments:
+
+```python
+from stashapp_client import between, find_filter, includes, scene_filter
+
+scenes = client.findScenes(
+    scene_filter=scene_filter(
+        title=includes("vacation"),
+        rating100=between(80, 100),
+        tags=includes(182),
+    ),
+    filter=find_filter(per_page=50),
+)
+
+tags = client.findTags(
+    tag_filter={"favorite": True},
+    filter=find_filter(per_page=50),
+)
+```
+
+Filter arguments use the GraphQL operation names, such as `scene_filter`,
+`gallery_filter`, and `tag_filter`. The `*_filter()` helpers cover common
+criteria and reject unknown helper fields. You can also pass a raw dictionary
+for any field in the generated schema:
+
+```python
+scenes = client.findScenes(
+    scene_filter={
+        "organized": False,
+        "duration": {"modifier": "GREATER_THAN", "value": 600},
+        "performers": {"modifier": "INCLUDES", "value": 84},
+    }
+)
+```
+
+Mutations use the same generated operation methods and schema-defined argument names:
+
+```python
+new_tag = client.tagCreate(input={"name": "Reviewed"})
+client.tagDestroy(input={"id": "123"})
+```
+
+Set `per_page` to `-1` to fetch all pages of a list result:
+
+```python
+all_tags = client.findTags(filter={"per_page": -1})
+```
+
+List-of-object results are returned as `pandas.DataFrame`; scalar results are returned as ordinary Python values. Use `field` to extract a response path and `response` to control the response shape:
+
+```python
+titles = client.findScenes(field=["scenes", "title"])
+count = client.findTags(field="count")
+metadata = client.findTags(response="object")
+envelope = client.findTags(response="raw")
+```
+
+Nested DataFrame columns remain as Python lists or dictionaries. Optional helpers are available for common transformations:
+
+```python
+from stashapp_client.response import explode_column, flatten_column
+
+flat = flatten_column(scenes, "studio")
+tags = explode_column(scenes, "tags")
+```
+
+## Generate Operations
+
+The bundled registry is generated from the Stash schema. Build artifacts from a schema snapshot with:
+
+```bash
+stashapp-client build-ops --schema ./schema.json
+```
+
+This writes `schema.json`, `operations_registry.json`, `fragments.py`, and `inputs.py` to the current directory by default. Override any output with `--out-schema`, `--out-registry`, `--out-fragments`, or `--out-inputs`.
+
+Regenerate from a live server:
+
+```bash
+stashapp-client sync-schema \
+    --credentials-file .stash_credentials \
+    --out-schema ./schema.json
+```
+
+Compare two schema snapshots before rebuilding:
+
+```bash
+stashapp-client diff-schema \
+    --base ./schema.json \
+    --current ./candidate-schema.json
+```
+
+`diff-schema` exits with status `1` when changes are found, which makes it suitable for CI.
+
+## Custom Registry
+
+Use a different generated registry when testing or targeting another schema version:
+
+```python
+client = StashClient(
+    url="https://stash.example/graphql",
+    api_key="YOUR_API_KEY",
+    registry_path="./operations_registry.json",
+)
+```

stashapp_client-0.1.3/README.md

@@ -0,0 +1,184 @@
+# stashapp-client
+
+An SDL-first Python client for the [Stash](https://github.com/stashapp/stash) GraphQL API. The package generates an operation registry from the Stash schema and binds query and mutation methods to `StashClient` at runtime.
+
+## Installation
+
+Install the latest published release from PyPI:
+
+```bash
+python -m pip install stashapp-client
+```
+
+For development from a checkout of this repository:
+
+```bash
+python -m pip install -e .
+```
+
+For development tools:
+
+```bash
+python -m pip install -e '.[dev]'
+```
+
+Releases follow [Semantic Versioning](https://semver.org/). See
+[`CHANGELOG.md`](CHANGELOG.md) for release history.
+
+## Connect
+
+Create a credentials file containing the GraphQL URL and API key on separate lines:
+
+```text
+https://stash.example/graphql
+YOUR_API_KEY
+```
+
+Then create a client:
+
+```python
+from stashapp_client import StashClient
+
+client = StashClient.from_credentials_file(".stash_credentials")
+print(client.has_connection())
+```
+
+Credentials can also come directly from arguments or environment variables:
+
+```python
+client = StashClient(
+    url="https://stash.example/graphql",
+    api_key="YOUR_API_KEY",
+)
+
+# Reads STASH_URL and STASH_API_KEY.
+client = StashClient.from_env()
+```
+
+Always close the client when finished, or use it as a context manager:
+
+```python
+with StashClient.from_credentials_file(".stash_credentials") as client:
+    print(client.findTags())
+```
+
+## TLS
+
+Pass `verify=False` only for a trusted internal endpoint. A CA bundle path is preferred for self-signed certificates:
+
+```python
+client = StashClient.from_credentials_file(
+    ".stash_credentials",
+    verify="/path/to/internal-ca.pem",
+)
+```
+
+`STASHAPI_TLS_VERIFY=false` disables verification, while a path value selects a CA bundle.
+
+## Use The API
+
+Operation methods are created from the bundled registry, so queries and mutations use schema-defined names and keyword arguments:
+
+```python
+from stashapp_client import between, find_filter, includes, scene_filter
+
+scenes = client.findScenes(
+    scene_filter=scene_filter(
+        title=includes("vacation"),
+        rating100=between(80, 100),
+        tags=includes(182),
+    ),
+    filter=find_filter(per_page=50),
+)
+
+tags = client.findTags(
+    tag_filter={"favorite": True},
+    filter=find_filter(per_page=50),
+)
+```
+
+Filter arguments use the GraphQL operation names, such as `scene_filter`,
+`gallery_filter`, and `tag_filter`. The `*_filter()` helpers cover common
+criteria and reject unknown helper fields. You can also pass a raw dictionary
+for any field in the generated schema:
+
+```python
+scenes = client.findScenes(
+    scene_filter={
+        "organized": False,
+        "duration": {"modifier": "GREATER_THAN", "value": 600},
+        "performers": {"modifier": "INCLUDES", "value": 84},
+    }
+)
+```
+
+Mutations use the same generated operation methods and schema-defined argument names:
+
+```python
+new_tag = client.tagCreate(input={"name": "Reviewed"})
+client.tagDestroy(input={"id": "123"})
+```
+
+Set `per_page` to `-1` to fetch all pages of a list result:
+
+```python
+all_tags = client.findTags(filter={"per_page": -1})
+```
+
+List-of-object results are returned as `pandas.DataFrame`; scalar results are returned as ordinary Python values. Use `field` to extract a response path and `response` to control the response shape:
+
+```python
+titles = client.findScenes(field=["scenes", "title"])
+count = client.findTags(field="count")
+metadata = client.findTags(response="object")
+envelope = client.findTags(response="raw")
+```
+
+Nested DataFrame columns remain as Python lists or dictionaries. Optional helpers are available for common transformations:
+
+```python
+from stashapp_client.response import explode_column, flatten_column
+
+flat = flatten_column(scenes, "studio")
+tags = explode_column(scenes, "tags")
+```
+
+## Generate Operations
+
+The bundled registry is generated from the Stash schema. Build artifacts from a schema snapshot with:
+
+```bash
+stashapp-client build-ops --schema ./schema.json
+```
+
+This writes `schema.json`, `operations_registry.json`, `fragments.py`, and `inputs.py` to the current directory by default. Override any output with `--out-schema`, `--out-registry`, `--out-fragments`, or `--out-inputs`.
+
+Regenerate from a live server:
+
+```bash
+stashapp-client sync-schema \
+    --credentials-file .stash_credentials \
+    --out-schema ./schema.json
+```
+
+Compare two schema snapshots before rebuilding:
+
+```bash
+stashapp-client diff-schema \
+    --base ./schema.json \
+    --current ./candidate-schema.json
+```
+
+`diff-schema` exits with status `1` when changes are found, which makes it suitable for CI.
+
+## Custom Registry
+
+Use a different generated registry when testing or targeting another schema version:
+
+```python
+client = StashClient(
+    url="https://stash.example/graphql",
+    api_key="YOUR_API_KEY",
+    registry_path="./operations_registry.json",
+)
+```

stashapp_client-0.1.3/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stashapp-client"
+version = "0.1.3"
+description = "Python client for the Stash GraphQL API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Written2001", email = "knasdkn@protonmail.com"}]
+requires-python = ">=3.10"
+dependencies = [
+    "graphql-core>=3.2",
+    "pandas>=2.0",
+    "requests>=2.31",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+stashapp-client = "stashapp_client.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Written2001/stash_client"
+Repository = "https://github.com/Written2001/stash_client"
+Issues = "https://github.com/Written2001/stash_client/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+stashapp_client = ["generated/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

stashapp_client-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stashapp_client-0.1.3/src/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-0.1.3/src/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()