stash-graphql-client 0.10.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 pattern sends only changed fields in mutations. Update one field without affecting others.
• 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.
• 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

async with StashContext(conn={"Host": "localhost", "Port": 9999}) as client:
    # Find and update a scene
    scene = await client.find_scene("scene-id")
    scene.rating100 = 95
    scene.details = UNSET  # Don't touch this field
    await scene.save(client)  # Only sends rating100

    # Django-style filtering
    from stash_graphql_client import StashEntityStore
    store = StashEntityStore(client)
    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