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=80syntax 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()andpopulated_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/awaitthroughout 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
import asyncio
from stash_graphql_client import StashContext
from stash_graphql_client.types import UNSET, Scene
async def main():
context = StashContext(conn={"Host": "localhost", "Port": 9999})
async with context as 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)
asyncio.run(main())
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
1 maintainer
Metadata
1 maintainer
Release files for stash-graphql-client 0.12.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| stash_graphql_client-0.12.12.tar.gz | 238.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stash_graphql_client-0.12.12-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 523.9 kB
Release files / stash_graphql_client-0.12.12.tar.gz
| Download URL | stash_graphql_client-0.12.12.tar.gz |
|---|---|
| Size | 238.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0c69249f8251d83b16d01325c32d7011d1c702f3e5408f0db62474fe78f0e635
|
|
BLAKE2b-256 checksum How to use checksums |
6fd924540557013b2e1a0ac8a0d1302a72ecff12afee2155c289215140bc6914
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 23, 2026.
Transparency logRelease files / stash_graphql_client-0.12.12-py3-none-any.whl
| Download URL | stash_graphql_client-0.12.12-py3-none-any.whl |
|---|---|
| Size | 285.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bc8a57d844cf812c5d8352617a12bf3649677d35d38f8851a9867ae2a93df233
|
|
BLAKE2b-256 checksum How to use checksums |
6a4c74d14144bfe133bc9361d2b41471ead85dc8f86b60434f4e7be9010134cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 23, 2026.
Transparency log
