lib-shopify-graphql 2.0.0__tar.gz

lib_shopify_graphql-2.0.0/.data_arch_violations.json

@@ -0,0 +1,131 @@
+{
+  "pass": 2,
+  "status": "complete",
+  "files": {
+    "models/_entities.py": {"violations": [], "status": "clean"},
+    "models/_operations.py": {
+      "violations": [],
+      "status": "fixed",
+      "fixes_applied": [
+        "Created GraphQLErrorLocation Pydantic model",
+        "Created GraphQLErrorExtensions Pydantic model with extra='allow'",
+        "Created ProductUpdateMutationProduct model",
+        "Created ProductUpdateResponseData wrapper model",
+        "Created SelectedOptionData model for variant options",
+        "Created VariantMutationResult typed model",
+        "Created VariantsBulkUpdateMutationData model",
+        "Created VariantsBulkUpdateResponseData wrapper model",
+        "Created VariantsBulkUpdateResponse typed response model",
+        "Created TruncationInfo, TruncationFields, FieldTruncationInfo models"
+      ]
+    },
+    "models/_mutations.py": {
+      "violations": [],
+      "status": "fixed",
+      "fixes_applied": [
+        "Added is_field_set() method for typed field access",
+        "Added get_field_value() method for typed field access",
+        "Kept get_set_fields() for boundary conversion to GraphQL input"
+      ]
+    },
+    "models/_enums.py": {
+      "violations": [],
+      "status": "fixed",
+      "fixes_applied": [
+        "Removed local StrEnum shim",
+        "Now imports StrEnum from shared _compat.py module"
+      ]
+    },
+    "models/_images.py": {
+      "violations": [],
+      "status": "fixed",
+      "fixes_applied": [
+        "Created StagedUploadParameter model for typed parameters",
+        "Changed StagedUploadTarget.parameters from dict to list[StagedUploadParameter]",
+        "Added get_parameters_dict() method for boundary conversion"
+      ]
+    },
+    "models/_internal.py": {"violations": [], "status": "clean"},
+    "adapters/parsers.py": {
+      "violations": [],
+      "status": "fixed",
+      "fixes_applied": [
+        "Updated parse_variant_from_mutation to accept VariantMutationResult model",
+        "Updated parse_staged_upload_target to return StagedUploadTarget model",
+        "Updated get_truncation_info to return TruncationInfo model"
+      ]
+    },
+    "adapters/shopify_sdk.py": {"violations": [], "status": "clean"},
+    "shopify_client/_products.py": {
+      "violations": [],
+      "status": "acceptable",
+      "notes": "dict params are for raw GraphQL response validation at adapter boundary"
+    },
+    "shopify_client/_variants.py": {
+      "violations": [],
+      "status": "fixed",
+      "fixes_applied": [
+        "Updated _convert_graphql_error_data_to_entry to use typed model attributes",
+        "Changed loc.get() to loc.line and loc.column access",
+        "Changed extensions dict conversion to use model_dump()"
+      ]
+    },
+    "shopify_client/_common.py": {
+      "violations": [],
+      "status": "fixed",
+      "fixes_applied": [
+        "Created _AdaptersCache TypedDict for type-safe adapter storage",
+        "Replaced dict[str, Any] cache with typed _AdaptersCache",
+        "Removed cast() calls - TypedDict provides proper typing",
+        "Created _ensure_adapters_cache() helper that returns typed cache"
+      ]
+    },
+    "application/ports.py": {"violations": [], "status": "clean"},
+    "exceptions.py": {
+      "violations": [],
+      "status": "acceptable",
+      "notes": "GraphQLErrorEntry.extensions uses dict[str, object] for exception error data at boundary"
+    },
+    "enums.py": {
+      "violations": [],
+      "status": "fixed",
+      "fixes_applied": [
+        "Removed local StrEnum shim",
+        "Now imports StrEnum from shared _compat.py module"
+      ]
+    },
+    "_compat.py": {
+      "violations": [],
+      "status": "new",
+      "notes": "Consolidated StrEnum compatibility shim for Python 3.10 support"
+    },
+    "cli/_test_limits.py": {
+      "violations": [],
+      "status": "fixed",
+      "fixes_applied": [
+        "Updated to use TruncationInfo typed model instead of dict",
+        "Changed all dict access to model attribute access"
+      ]
+    }
+  },
+  "total_violations_fixed": 36,
+  "remaining_violations": 0,
+  "last_updated": "2026-01-13",
+  "summary": {
+    "key_changes": [
+      "Consolidated StrEnum compatibility shim to single _compat.py module",
+      "Replaced dict[str, Any] with typed Pydantic models throughout",
+      "Created typed models for GraphQL mutation responses",
+      "Created typed models for truncation analysis",
+      "Created TypedDict for adapter cache storage",
+      "Updated parsers to return typed models instead of dicts",
+      "Updated consumers to use model attributes instead of dict access"
+    ],
+    "patterns_applied": [
+      "Pydantic at boundaries (input/output)",
+      "No internal dicts for structured data",
+      "Single conversion at boundary",
+      "TypedDict for typed dictionary patterns"
+    ]
+  }
+}

lib_shopify_graphql-2.0.0/.env.example

@@ -0,0 +1,192 @@
+# Copy to .env and fill values as needed.
+# IMPORTANT: Never commit .env files containing secrets to version control!
+#
+# Naming Convention for .env files (no prefix needed):
+#   Format: SECTION__KEY=value
+#   Uses double underscore (__) to create nested structures.
+#
+# For environment variables (require prefix):
+#   Format: LIB_SHOPIFY_GRAPHQL___SECTION__KEY=value
+#   Uses triple underscore (___) to separate prefix from section.
+
+# ==============================================================================
+# CI/CD Tokens (for development and release workflows)
+# ==============================================================================
+
+# Codecov upload token (required for private repos; optional for public repos)
+# Get from: https://app.codecov.io/gh/<org>/<repo>/settings
+CODECOV_TOKEN=
+
+# PyPI API token for release workflow (.github/workflows/release.yml)
+# Get from: https://pypi.org/manage/account/token/
+# Format: pypi-AgENdGVzdC5weXBpLm9yZwIk...
+PYPI_API_TOKEN=
+
+# GitHub token for API-limited tasks (e.g., gh CLI, API calls)
+# Get from: https://github.com/settings/tokens
+GITHUB_TOKEN=
+
+# ==============================================================================
+# Shopify API Credentials
+# ==============================================================================
+# This library supports two authentication methods:
+#
+# METHOD 1: Direct Access Token (Custom Apps in Shopify Admin)
+# ----------------------------------------------------------------
+# For Custom Apps created in Shopify Admin (Settings > Apps and sales channels
+# > Develop apps), you get a static Admin API access token that starts with
+# "shpat_". This token doesn't expire and is shown only once when installing.
+#
+# Set SHOPIFY__ACCESS_TOKEN and leave CLIENT_ID/CLIENT_SECRET empty.
+#
+# METHOD 2: Client Credentials Grant (Partner Apps via Dev Dashboard)
+# ----------------------------------------------------------------
+# For apps created via https://dev.shopify.com/dashboard, use OAuth 2.0
+# Client Credentials Grant. These tokens are valid for 24 hours.
+#
+# Set SHOPIFY__CLIENT_ID and SHOPIFY__CLIENT_SECRET, leave ACCESS_TOKEN empty.
+#
+# See README.md for detailed setup instructions.
+
+# Store URL (without https://)
+# Supports both .myshopify.com domains and custom domains
+# Required for both methods
+SHOPIFY__SHOP_URL=mystore.myshopify.com
+
+# ----- Method 1: Direct Access Token (Custom Apps) -----
+# Admin API access token from Custom App (starts with "shpat_")
+# NEVER commit this value!
+#SHOPIFY__ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# ----- Method 2: Client Credentials Grant (Partner Apps) -----
+# OAuth Client ID (from Dev Dashboard)
+#SHOPIFY__CLIENT_ID=your_client_id_here
+
+# OAuth Client Secret (from Dev Dashboard)
+# NEVER commit this value!
+#SHOPIFY__CLIENT_SECRET=your_client_secret_here
+
+# Shopify API version (format: YYYY-MM)
+# Default: 2026-01
+#SHOPIFY__API_VERSION=2026-01
+
+# Default location for inventory operations
+# If not set, uses shop's primary location (auto-fetched)
+# Format: GID ("gid://shopify/Location/123") or numeric ID ("123")
+# Default: "" (auto-fetch)
+#SHOPIFY__DEFAULT_LOCATION_ID=gid://shopify/Location/123456789
+
+# Default currency code (ISO 4217) for monetary operations
+# Common codes: USD, EUR, GBP, CAD, AUD, JPY
+# Default: USD
+#SHOPIFY__DEFAULT_CURRENCY=USD
+
+# ==============================================================================
+# MySQL Database Configuration (for distributed caching)
+# ==============================================================================
+# Used when cache backend is set to "mysql".
+# Database and tables are created automatically on first use.
+#
+# Connection string format: mysql://user:password@host:port/database
+# Examples:
+#   mysql://shopify_app:secret@localhost:3306/shopify_cache
+#   mysql://root@127.0.0.1/cache
+
+# MySQL connection string (shared by token and SKU caches)
+# No default - required when using mysql backend
+#SHOPIFY__MYSQL__CONNECTION=mysql://user:password@localhost:3306/shopify_cache
+
+# Auto-create database if it doesn't exist
+# Default: true
+#SHOPIFY__MYSQL__AUTO_CREATE_DATABASE=true
+
+# Connection timeout in seconds
+# Default: 10
+#SHOPIFY__MYSQL__CONNECT_TIMEOUT=10
+
+# ==============================================================================
+# Token Cache Configuration
+# ==============================================================================
+# Cache OAuth access tokens to reduce authentication requests.
+# Tokens are valid for 24 hours.
+
+# Enable token caching
+# Default: false
+#SHOPIFY__TOKEN_CACHE__ENABLED=true
+
+# Cache backend: "json" or "mysql"
+# Default: json
+#SHOPIFY__TOKEN_CACHE__BACKEND=json
+
+# Refresh margin - refresh token this many seconds before expiration
+# Default: 300 (5 minutes)
+#SHOPIFY__TOKEN_CACHE__REFRESH_MARGIN=300
+
+# --- JSON Backend ---
+
+# Path to the JSON cache file (directory created automatically)
+# No default - required when using json backend with token caching enabled
+#SHOPIFY__TOKEN_CACHE__JSON_PATH=/var/cache/shopify/token_cache.json
+
+# Lock timeout in seconds for filelock
+# Default: 10.0
+#SHOPIFY__TOKEN_CACHE__LOCK_TIMEOUT=10.0
+
+# --- MySQL Backend ---
+
+# Override shared MySQL connection for token cache only
+# Default: uses SHOPIFY__MYSQL__CONNECTION
+#SHOPIFY__TOKEN_CACHE__MYSQL_CONNECTION=mysql://user:password@localhost:3306/shopify_cache
+
+# Table name for token cache
+# Default: token_cache
+#SHOPIFY__TOKEN_CACHE__MYSQL_TABLE=token_cache
+
+# ==============================================================================
+# SKU Cache Configuration
+# ==============================================================================
+# Cache SKU-to-GID mappings to reduce API calls when updating by SKU.
+
+# Cache backend: "json" or "mysql"
+# Default: json
+#SHOPIFY__SKU_CACHE__BACKEND=json
+
+# Cache TTL in seconds
+# Default: 2592000 (30 days)
+#SHOPIFY__SKU_CACHE__TTL=2592000
+
+# --- JSON Backend ---
+
+# Path to the JSON cache file (directory created automatically)
+# No default - required when using json backend
+#SHOPIFY__SKU_CACHE__JSON_PATH=/var/cache/shopify/sku_cache.json
+
+# Lock timeout in seconds for filelock
+# Default: 10.0
+#SHOPIFY__SKU_CACHE__LOCK_TIMEOUT=10.0
+
+# --- MySQL Backend ---
+
+# Override shared MySQL connection for SKU cache only
+# Default: uses SHOPIFY__MYSQL__CONNECTION
+#SHOPIFY__SKU_CACHE__MYSQL_CONNECTION=mysql://user:password@localhost:3306/shopify_cache
+
+# Table name for SKU cache
+# Default: sku_cache
+#SHOPIFY__SKU_CACHE__MYSQL_TABLE=sku_cache
+
+# ==============================================================================
+# Logging Configuration (lib_log_rich)
+# ==============================================================================
+# Full documentation: https://github.com/bitranox/lib_log_rich
+# See defaultconfig.d/10-logging.toml for all available options.
+
+# Minimum severity level for console output
+# Values: DEBUG, INFO, WARNING, ERROR, CRITICAL
+# Default: INFO
+#LIB_LOG_RICH__CONSOLE_LEVEL=INFO
+
+# Console layout preset
+# Values: full, short, full_loc, short_loc
+# Default: full
+#LIB_LOG_RICH__CONSOLE_FORMAT_PRESET=full

lib_shopify_graphql-2.0.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    allow:
+      - dependency-type: "direct"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"

lib_shopify_graphql-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,210 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    # Run daily at 3:17 AM UTC (off-peak hours, odd minute to avoid congestion)
+    - cron: '17 3 * * *'
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        # Test against Python 3.10 through 3.13
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    env:
+      PYO3_USE_ABI3_FORWARD_COMPATIBILITY: "1"
+      PYTHONIOENCODING: "utf-8"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Install rtoml for metadata extraction
+        shell: bash
+        run: pip install rtoml
+      - name: Extract project metadata
+        shell: python
+        run: |
+          import os
+          import rtoml
+          from pathlib import Path
+
+          data = rtoml.loads(Path('pyproject.toml').read_text('utf-8'))
+          project = data['project']['name']
+          module = project.replace('-', '_')
+          dash = project.replace('_', '-')
+          scripts = list(data['project'].get('scripts', {}).keys())
+          cli_bin = scripts[0] if scripts else dash
+
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as env:
+              env.write(f"PROJECT_NAME={project}\n")
+              env.write(f"PACKAGE_MODULE={module}\n")
+              env.write(f"CLI_BIN={cli_bin}\n")
+      - name: Install make on Windows
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          choco install -y make
+          echo "C:\\ProgramData\\chocolatey\\bin" >> $env:GITHUB_PATH
+      - name: Install journald prerequisites
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y python3-systemd
+
+      - name: Upgrade pip
+        shell: bash
+        run: python -m pip install --upgrade pip
+
+      - name: Install dev deps
+        shell: bash
+        run: |
+          uv pip install -e .[dev] --system
+
+      - name: Install Windows Event Log prerequisites
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          uv pip install pywin32 --system
+      - name: Cache ruff
+        uses: actions/cache@v5
+        with:
+          path: .ruff_cache
+          key: ruff-${{ runner.os }}-${{ github.sha }}
+          restore-keys: |
+            ruff-${{ runner.os }}-
+      - name: Cache pyright
+        uses: actions/cache@v5
+        with:
+          path: .pyright
+          key: pyright-${{ runner.os }}-py${{ matrix.python }}-${{ github.sha }}
+          restore-keys: |
+            pyright-${{ runner.os }}-py${{ matrix.python }}-
+            pyright-${{ runner.os }}-
+      - name: Run full test suite (lint, types, tests, coverage, codecov)
+        shell: bash
+        env:
+          TEST_VERBOSE: "1"
+        run: make test
+      - name: Build wheel/sdist
+        shell: bash
+        run: python -m build
+      - name: Verify wheel install in clean env
+        shell: bash
+        run: |
+          python -m venv .venv_wheel
+          . .venv_wheel/bin/activate 2>/dev/null || . .venv_wheel/Scripts/activate 2>/dev/null
+          pip install dist/*.whl
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+
+  pipx-uv:
+    name: pipx/uv verification (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install rtoml for metadata extraction
+        shell: bash
+        run: pip install rtoml
+      - name: Extract project metadata
+        shell: python
+        run: |
+          import os
+          import rtoml
+          from pathlib import Path
+
+          data = rtoml.loads(Path('pyproject.toml').read_text('utf-8'))
+          project = data['project']['name']
+          module = project.replace('-', '_')
+          dash = project.replace('_', '-')
+          scripts = list(data['project'].get('scripts', {}).keys())
+          cli_bin = scripts[0] if scripts else dash
+
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as env:
+              env.write(f"PROJECT_NAME={project}\n")
+              env.write(f"PACKAGE_MODULE={module}\n")
+              env.write(f"CLI_BIN={cli_bin}\n")
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: pipx install from wheel
+        run: |
+          python -m pip install pipx
+          pipx install dist/*.whl
+          # pipx installs to ~/.local/bin, ensure it's in PATH
+          export PATH="$HOME/.local/bin:$PATH"
+          "$CLI_BIN" --version
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: uv tool install
+        run: |
+          uv tool install .
+          # uv installs to ~/.local/bin, ensure it's in PATH
+          export PATH="$HOME/.local/bin:$PATH"
+          "$CLI_BIN" --version
+
+  notebooks:
+    name: Execute notebooks (ubuntu, Python 3.13)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+      - name: Install notebook runner deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install nbclient nbformat ipykernel jupyter_client
+          python -m ipykernel install --user --name python3 --display-name "Python 3"
+      - name: Execute Quickstart notebook
+        env:
+          PIP_DISABLE_PIP_VERSION_CHECK: "1"
+          PIP_NO_INPUT: "1"
+        run: |
+          python - << 'PY'
+          from pathlib import Path
+
+          import nbformat
+          from nbclient import NotebookClient
+
+          nb_path = Path('notebooks/Quickstart.ipynb')
+          if not nb_path.exists():
+              raise SystemExit(f"Notebook not found: {nb_path}")
+
+          notebook = nbformat.read(nb_path, as_version=4)
+          client = NotebookClient(
+              notebook,
+              timeout=900,
+              kernel_name='python3',
+              allow_errors=False,
+          )
+          client.execute()
+
+          out_path = Path('notebooks/Quickstart-executed.ipynb')
+          nbformat.write(notebook, out_path)
+          print(f"Executed notebook written to: {out_path}")
+          PY

lib_shopify_graphql-2.0.0/.github/workflows/codeql.yml

@@ -0,0 +1,39 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    - cron: '0 8 * * 1'
+
+jobs:
+  analyze:
+    name: CodeQL Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

lib_shopify_graphql-2.0.0/.github/workflows/integrationtest.yml

@@ -0,0 +1,59 @@
+name: Integration Tests
+
+on:
+  workflow_dispatch:  # Manual trigger only (requires real Shopify credentials)
+  schedule:
+    # Run weekly on Sunday at 4:17 AM UTC
+    - cron: '17 4 * * 0'
+
+jobs:
+  integration:
+    name: Integration Tests (Python 3.14, Linux)
+    runs-on: ubuntu-latest
+    env:
+      PYTHONIOENCODING: "utf-8"
+      # Shopify credentials from repository secrets
+      # Format: LIB_SHOPIFY_GRAPHQL___SECTION__KEY (triple underscore after prefix)
+      LIB_SHOPIFY_GRAPHQL___SHOPIFY__SHOP_URL: ${{ secrets.SHOPIFY_SHOP_URL }}
+      LIB_SHOPIFY_GRAPHQL___SHOPIFY__CLIENT_ID: ${{ secrets.SHOPIFY_CLIENT_ID }}
+      LIB_SHOPIFY_GRAPHQL___SHOPIFY__CLIENT_SECRET: ${{ secrets.SHOPIFY_CLIENT_SECRET }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install journald prerequisites
+        shell: bash
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y python3-systemd
+
+      - name: Upgrade pip
+        shell: bash
+        run: python -m pip install --upgrade pip
+
+      - name: Install dev deps
+        shell: bash
+        run: uv pip install -e .[dev] --system
+
+      - name: Check Shopify credentials
+        shell: bash
+        run: |
+          if [ -z "$LIB_SHOPIFY_GRAPHQL___SHOPIFY__SHOP_URL" ] || [ -z "$LIB_SHOPIFY_GRAPHQL___SHOPIFY__CLIENT_ID" ] || [ -z "$LIB_SHOPIFY_GRAPHQL___SHOPIFY__CLIENT_SECRET" ]; then
+            echo "::error::Missing Shopify credentials. Set SHOPIFY_SHOP_URL, SHOPIFY_CLIENT_ID, and SHOPIFY_CLIENT_SECRET as repository secrets."
+            exit 1
+          fi
+          echo "Shopify credentials configured for: $LIB_SHOPIFY_GRAPHQL___SHOPIFY__SHOP_URL"
+
+      - name: Run integration tests (test-slow)
+        shell: bash
+        run: make test-slow