lib_shopify_graphql

lib_shopify_graphql is a Python library for interacting with the Shopify GraphQL Admin API.

Features:

• Shopify GraphQL API - Client Credentials Grant authentication (OAuth 2.0)
• Product CRUD - Create, read, update, delete, and duplicate products
• Product Listing - Cursor-based pagination for listing products with query filtering
• Image Management - Add, update, delete, and reorder product images (URL or file upload)
• Partial Updates - UNSET sentinel pattern for updating only specified fields
• Bulk Operations - Update multiple variants in a single API call
• Inventory Management - Set or adjust inventory with location fallback
• Metafield Operations - Delete metafields from products and variants
• Token Caching - Cache OAuth tokens to reduce authentication overhead
• SKU Resolution - Cached SKU-to-GID mapping with ambiguity detection
• High Performance - Uses orjson for fast JSON serialization (3-10x faster than stdlib)
• Typed Pydantic models - Full validation for credentials, products, variants, images
• Clean Architecture - Layered design with ports/adapters for testability
• Dependency Injection - Custom adapters for testing and customization
• CLI entry point styled with rich-click (rich output + click ergonomics)
• Layered configuration with lib_layered_config (defaults -> app -> host -> user -> .env -> env)
• Rich structured logging with lib_log_rich (console, journald, eventlog, Graylog/GELF)
• Exit-code helpers powered by lib_cli_exit_tools
• Wraps official ShopifyAPI package from PyPI

Table of Contents

• Installation
• Quick Start
• Partial Updates
• Architecture
• Documentation
  • CLI Usage
  • Caching
  • Shopify App Setup
  • API Reference
• Further Documentation

Installation

Recommended: Install via UV (10-20x faster than pip/poetry):

pip install --upgrade uv
uv venv && source .venv/bin/activate  # Create and activate venv
uv pip install lib_shopify_graphql

Optional Extras

The library supports optional features via extras:

# Install with MySQL support
uv pip install lib_shopify_graphql[mysql]

# Install with pip
pip install lib_shopify_graphql[mysql]

# Install multiple extras
uv pip install "lib_shopify_graphql[mysql,dev]"

For alternative install paths (pip, pipx, uvx, source builds, etc.), see INSTALL.md.

Python 3.10+ Baseline

• The project targets Python 3.10 and newer.
• Runtime dependencies stay on current stable releases.
• CI workflows exercise GitHub's rolling runner images covering Python 3.10, 3.11, 3.12, and 3.13.

Quick Start

from lib_shopify_graphql import (
    login,
    logout,
    get_product_by_id,
    get_product_id_from_sku,
    list_products,
    list_products_paginated,
    ShopifyCredentials,
)

# Create credentials
credentials = ShopifyCredentials(
    shop_url="mystore.myshopify.com",
    client_id="your_client_id",
    client_secret="your_client_secret",
)

# Login (obtains access token via client credentials grant)
session = login(credentials)
print(f"Connected to: {session.info.shop_url}")

# Get product by ID
product = get_product_by_id(session, "123456789")  # or full GID
print(f"Product: {product.title}")
print(f"Status: {product.status}")
print(f"Variants: {len(product.variants)}")

# List all products (auto-pagination)
products = list_products(session)
for product in products:
    print(f"- {product.title} ({product.handle})")

# Or use manual pagination for large catalogs
result = list_products_paginated(session, first=50)
while result.page_info.has_next_page:
    result = list_products_paginated(session, first=50, after=result.page_info.end_cursor)
    for product in result.products:
        print(f"- {product.title}")

# Logout when done
logout(session)

Partial Updates

The library uses a sentinel pattern for partial updates, allowing you to update only specific fields:

• UNSET (default) - Don't update this field
• None - Clear this field (set to null on Shopify)
• value - Update to this value

from decimal import Decimal
from lib_shopify_graphql import (
    login,
    update_variant,
    update_variants_bulk,
    set_inventory,
    adjust_inventory,
    VariantUpdate,
    VariantUpdateRequest,
    UNSET,
)

session = login(credentials)

# Update price only (other fields unchanged)
update_variant(
    session,
    "SKU-12345",  # Can use SKU or GID
    VariantUpdate(price=Decimal("29.99")),
)

# Clear compare_at_price (remove sale)
update_variant(
    session,
    "gid://shopify/ProductVariant/123",
    VariantUpdate(compare_at_price=None),
)

# Bulk update multiple variants
result = update_variants_bulk(
    session,
    "gid://shopify/Product/456",
    [
        VariantUpdateRequest(
            sku="SKU-001",
            update=VariantUpdate(price=Decimal("19.99")),
        ),
        VariantUpdateRequest(
            sku="SKU-002",
            update=VariantUpdate(barcode="123456789012"),
        ),
    ],
)
print(f"Updated: {result.success_count}, Failed: {result.failure_count}")

# Set absolute inventory
set_inventory(session, "SKU-12345", quantity=100)

# Adjust inventory by delta
adjust_inventory(session, "SKU-12345", delta=-5)

logout(session)

Architecture

The library follows Clean Architecture principles with distinct layers:

lib_shopify_graphql/
├── domain/             # Core business rules (pure Python, no dependencies)
├── application/        # Use cases and ports (Protocol interfaces)
│   └── ports.py        # TokenProviderPort, GraphQLClientPort, SessionManagerPort
├── adapters/           # External system implementations
│   ├── shopify_sdk.py  # Shopify SDK implementations
│   ├── parsers.py      # GraphQL response parsers
│   ├── queries.py      # GraphQL query definitions
│   ├── mutations.py    # GraphQL mutation definitions
│   └── cache_*.py      # Cache adapter implementations
├── composition.py      # Dependency injection wiring
├── shopify_client/     # Core API package (login, logout, product operations)
│   ├── _session.py     # Session management
│   ├── _products.py    # Product operations
│   ├── _variants.py    # Variant operations
│   ├── _inventory.py   # Inventory operations
│   ├── _images.py      # Image operations
│   └── _cache.py       # Cache management
├── models/             # Pydantic data models package
│   ├── _entities.py    # Read models (Product, Variant, etc.)
│   ├── _mutations.py   # Partial update models
│   └── _operations.py  # Operation results
└── exceptions.py       # Domain exceptions

Layer dependencies point inward only:

• Adapters -> Application -> Domain
• Domain has no framework dependencies
• Application ports have no adapter dependencies

Enforced via import-linter:

[tool.importlinter]
root_package = "lib_shopify_graphql"

[[tool.importlinter.contracts]]
name = "Clean Architecture layers"
type = "layers"
layers = [
  "lib_shopify_graphql.adapters",
  "lib_shopify_graphql.application",
  "lib_shopify_graphql.domain",
]

Documentation

Further Documentation

• Install Guide
• Development Handbook
• Contributor Guide
• Changelog
• License