stash-graphql-client 0.11.0

Async Python client for Stash GraphQL API

stash-graphql-client

Async Python client for Stash GraphQL API.

🔗 Quick Links

• 📦 PyPI Package - Install via pip
• 📚 Documentation - Full API reference and guides
• 🎬 Stash Project - Upstream media server this client connects to
• 📝 Changelog - Version history and release notes
• 🤝 Contributing - Development guide and contribution guidelines
• 🔒 Security Policy - Vulnerability reporting and security best practices

Features

• ORM-like interface for GraphQL: Use .save(), .delete(), and relationship helpers instead of writing mutations manually.
• Identity map with Pydantic v2 wrap validators: Same entity ID = same Python object reference. Nested objects with IDs are automatically separated into the identity map. Caching integrated at model construction—no separate cache layer needed.
• Smart partial updates: UNSET sentinel marks fields have not been requested or received data from the server. Fields you change get sent in mutations. UNSET is also part of the three-state logic for knowing the difference between unknown and intentionally NULL.
• Type-safe with Pydantic v2: Full runtime validation, IDE autocomplete, and error detection at development time.
• Django-style filtering: Familiar rating100__gte=80 syntax instead of building complex GraphQL filter objects.
• Lazy field population: populate() fetches only missing fields with nested __ syntax (files__path, studio__parent__name). filter_and_populate() and populated_filter_iter() combine filtering with auto-population.
• Streaming iteration: find_iter() provides async generator pagination for large result sets without loading everything into memory.
• Get-or-create: store.get_or_create() upsert pattern for entities.
• Async-first architecture: Built for async/await throughout with native support for concurrent operations.
• Full Stash API coverage: Complete CRUD operations for all entity types, job management, metadata operations, and real-time subscriptions.

---

Quick Example

from stash_graphql_client import StashContext
from stash_graphql_client.types import Scene, UNSET

    context = StashContext(conn={"Host": "localhost", "Port": 9999})
    client = context.client
    # Find and update a scene
    scene = await client.find_scene("scene-id")
    scene.rating100 = 95
    # scene.details stays UNSET (no data loaded for it, won't be sent)
    await scene.save(client)  # Only sends rating100

    # Django-style filtering via the context's store
    store = context.store
    top_rated = await store.find(Scene, rating100__gte=90)

---

Learn More

• 📚 Full Documentation - Complete guides and API reference
• 🎯 Getting Started Guide - Step-by-step tutorials
• 💡 Usage Patterns - Common recipes and best practices
• 🏗️ Architecture Overview - Design decisions and comparisons
• 🔍 API Reference - Complete API documentation

---

Installation

From PyPI (Recommended)

pip install stash-graphql-client

With Poetry

poetry add stash-graphql-client

From Source

git clone https://github.com/Jakan-Kink/stash-graphql-client.git
cd stash-graphql-client
poetry install

Requirements: Python 3.12+ • Poetry (for development)

---

Connection Options

conn = {
    "Scheme": "http",      # or "https"
    "Host": "localhost",   # Stash server host
    "Port": 9999,          # Stash server port
    "ApiKey": "...",       # Optional API key
}

---

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later).

See LICENSE for the full license text.

This license ensures:

• ✅ Open source code sharing
• ✅ Network use requires source disclosure
• ✅ Compatible with Stash (also AGPL-3.0)
• ✅ Derivative works must also be AGPL-3.0