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.

Why we recommend uv: supply-chain protection

This repository commits a uv.lock. It pins every package the project needs, transitive dependencies included, to an exact version and to the hashes of that version's files. The exclude-newer setting under [tool.uv] in pyproject.toml adds a cooldown: uv leaves any release younger than that out of the lock. CI installs from the lock, so a hijacked release that gets pulled again within the cooldown never reaches our builds, and a file whose hash does not match is refused.

That protection stays in this repository. The installable package declares only lower bounds (>=) for its dependencies, so a plain pip install takes the newest release of every transitive dependency at the moment you run it. If one of them was hijacked an hour earlier, you get the hijacked version. pipx install and uv tool install without options do the same.

To install the command line tool with a cooldown of your own (uv then skips any release younger than 7 days, transitive ones included), or to run the exact tree our CI tests:

uv tool install --exclude-newer "7 days" lib_shopify_graphql
git clone https://github.com/bitranox/lib_shopify_graphql.git && cd lib_shopify_graphql && uv sync --locked && uv run lib_shopify_graphql --help

If you depend on lib_shopify_graphql in your own project, give that project the same cooldown (7 days here, as an example) and commit the uv.lock that uv add lib_shopify_graphql writes:

[tool.uv]
exclude-newer = "7 days"

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