lib-shopify-graphql 2.0.0__py3-none-any.whl

lib_shopify_graphql/__init__.py

@@ -0,0 +1,356 @@
+"""Public package surface for lib_shopify_graphql.
+
+This package provides a Python interface for the Shopify GraphQL Admin API.
+
+Architecture:
+    This library follows Clean Architecture principles:
+    - **Domain**: Pure exceptions and business rules
+    - **Application**: Use cases and ports (Protocol interfaces)
+    - **Adapters**: Shopify SDK implementations
+    - **Composition**: Wiring adapters to ports
+
+Core API:
+    - :func:`login`: Authenticate with Shopify using client credentials grant.
+    - :func:`logout`: Terminate an active Shopify session.
+    - :func:`get_product_by_id`: Retrieve full product information.
+    - :func:`create_product`: Create a new product.
+    - :func:`duplicate_product`: Duplicate an existing product.
+    - :func:`delete_product`: Delete a product permanently.
+    - :func:`update_product`: Update product fields (partial update).
+    - :func:`update_variant`: Update variant fields (partial update).
+    - :func:`update_variants_bulk`: Bulk update multiple variants.
+    - :func:`set_inventory`: Set absolute inventory quantity.
+    - :func:`adjust_inventory`: Adjust inventory by delta.
+    - :func:`delete_metafield`: Delete a single metafield.
+    - :func:`delete_metafields`: Delete multiple metafields.
+    - :func:`tokencache_clear`: Clear cached OAuth tokens.
+    - :func:`skucache_clear`: Clear cached SKU-to-GID mappings.
+    - :func:`cache_clear_all`: Clear all caches (tokens and SKU mappings).
+
+Models:
+    - :class:`ShopifyCredentials`: Credentials for authentication.
+    - :class:`ShopifySession`: Active session wrapper.
+    - :class:`Product`: Full product data.
+    - :class:`ProductVariant`: Product variant data.
+    - :class:`ProductImage`: Product image data.
+    - :class:`ProductOption`: Product option definition.
+    - :class:`Money`: Monetary value with currency.
+    - :class:`PriceRange`: Min/max price range.
+    - :class:`SEO`: Search engine optimization data.
+    - :class:`Metafield`: Custom metadata attached to resources.
+
+Product Creation Model:
+    - :class:`ProductCreate`: Input model for creating a new product.
+
+Product Lifecycle Results:
+    - :class:`DuplicateProductResult`: Result of duplicating a product.
+    - :class:`DeleteProductResult`: Result of deleting a product.
+
+Partial Update Models:
+    - :data:`UNSET`: Sentinel indicating field should not be updated.
+    - :class:`ProductUpdate`: Partial update for product fields.
+    - :class:`VariantUpdate`: Partial update for variant fields.
+    - :class:`VariantUpdateRequest`: Update request with flexible identifier.
+    - :class:`BulkUpdateResult`: Result of bulk update operations.
+    - :class:`InventoryLevel`: Inventory level at a location.
+
+Metafield Deletion Models:
+    - :class:`MetafieldIdentifier`: Identifies a metafield for deletion.
+    - :class:`MetafieldDeleteResult`: Result of metafield deletion.
+    - :class:`MetafieldDeleteFailure`: A failed metafield deletion.
+
+Exceptions:
+    - :class:`ShopifyError`: Base exception for all Shopify operations.
+    - :class:`AuthenticationError`: Authentication failed.
+    - :class:`ProductNotFoundError`: Product not found.
+    - :class:`VariantNotFoundError`: Variant not found.
+    - :class:`AmbiguousSKUError`: SKU matches multiple variants.
+    - :class:`SessionNotActiveError`: Session not active.
+    - :class:`GraphQLError`: GraphQL query errors.
+
+Ports (for dependency injection):
+    - :class:`TokenProviderPort`: OAuth token provider interface.
+    - :class:`GraphQLClientPort`: GraphQL client interface.
+    - :class:`SessionManagerPort`: Session manager interface.
+    - :class:`CachePort`: Key-value cache interface.
+    - :class:`SKUResolverPort`: SKU to GID resolver interface.
+    - :class:`LocationResolverPort`: Location resolver interface.
+
+Adapters:
+    - :class:`JsonFileCacheAdapter`: JSON file cache with filelock.
+    - :class:`MySQLCacheAdapter`: MySQL-based cache.
+    - :class:`CachedSKUResolver`: Cached SKU resolver implementation.
+    - :class:`LocationResolver`: Location resolver with fallback.
+
+Utilities:
+    - :func:`get_config`: Load layered configuration.
+    - :func:`print_info`: Display package metadata.
+    - :func:`create_adapters`: Create adapter bundle for DI.
+"""
+
+from __future__ import annotations
+
+# Package metadata
+from .__init__conf__ import print_info
+
+# Adapters
+from .adapters import (
+    DEFAULT_GRAPHQL_TIMEOUT_SECONDS,
+    PYMYSQL_AVAILABLE,
+    CachedSKUResolver,
+    CachedTokenProvider,
+    JsonFileCacheAdapter,
+    LocationResolver,
+    MySQLCacheAdapter,
+)
+
+# Application ports (for dependency injection)
+from .application.ports import (
+    CachePort,
+    GraphQLClientPort,
+    LocationResolverPort,
+    SessionManagerPort,
+    SKUResolverPort,
+    TokenProviderPort,
+)
+
+# Composition root
+from .composition import (
+    AdapterBundle,
+    create_adapters,
+    create_cached_token_provider,
+    get_default_adapters,
+)
+
+# Configuration
+from .config import get_config
+
+# Domain exceptions
+from .exceptions import (
+    AmbiguousSKUError,
+    AuthenticationError,
+    GraphQLError,
+    GraphQLErrorEntry,
+    GraphQLErrorLocation,
+    GraphQLTimeoutError,
+    ImageNotFoundError,
+    ImageUploadError,
+    ProductNotFoundError,
+    SessionNotActiveError,
+    ShopifyError,
+    VariantNotFoundError,
+)
+
+# Data models
+from .models import (
+    SEO,
+    UNSET,
+    BulkUpdateResult,
+    DeleteProductResult,
+    DuplicateProductResult,
+    ImageCreateFailure,
+    ImageCreateResult,
+    ImageCreateSuccess,
+    ImageDeleteResult,
+    ImageReorderResult,
+    ImageSource,
+    ImageUpdate,
+    InventoryLevel,
+    InventoryPolicy,
+    InventoryQuantityName,
+    InventoryReason,
+    MediaStatus,
+    Metafield,
+    MetafieldDeleteFailure,
+    MetafieldDeleteResult,
+    MetafieldIdentifier,
+    MetafieldInput,
+    MetafieldType,
+    Money,
+    PageInfo,
+    PriceRange,
+    Product,
+    ProductConnection,
+    ProductCreate,
+    ProductImage,
+    ProductOption,
+    ProductStatus,
+    ProductUpdate,
+    ProductVariant,
+    SelectedOption,
+    ShopifyCredentials,
+    ShopifySessionInfo,
+    StagedUploadTarget,
+    UnsetType,
+    UpdateFailure,
+    UpdateSuccess,
+    VariantUpdate,
+    VariantUpdateRequest,
+    WeightUnit,
+)
+
+# Shopify client API
+from .shopify_client import (
+    CacheCheckResult,
+    CacheMismatch,
+    ShopifySession,
+    adjust_inventory,
+    cache_clear_all,
+    create_image,
+    create_images,
+    create_product,
+    delete_image,
+    delete_images,
+    delete_metafield,
+    delete_metafields,
+    delete_product,
+    duplicate_product,
+    get_product_by_id,
+    get_product_by_sku,
+    get_product_id_from_sku,
+    iter_products,
+    list_products,
+    list_products_paginated,
+    login,
+    logout,
+    reorder_images,
+    set_inventory,
+    skucache_check,
+    skucache_clear,
+    skucache_rebuild,
+    tokencache_clear,
+    update_image,
+    update_product,
+    update_variant,
+    update_variants_bulk,
+)
+
+__all__ = [
+    # Shopify API - Session
+    "login",
+    "logout",
+    "ShopifySession",
+    # Shopify API - Create
+    "create_product",
+    # Shopify API - Read
+    "get_product_by_id",
+    "get_product_by_sku",
+    "get_product_id_from_sku",
+    "iter_products",
+    "list_products",
+    "list_products_paginated",
+    # Shopify API - Duplicate
+    "duplicate_product",
+    # Shopify API - Update
+    "update_product",
+    "update_variant",
+    "update_variants_bulk",
+    "set_inventory",
+    "adjust_inventory",
+    # Shopify API - Delete
+    "delete_image",
+    "delete_images",
+    "delete_metafield",
+    "delete_metafields",
+    "delete_product",
+    # Shopify API - Images
+    "create_image",
+    "create_images",
+    "reorder_images",
+    "update_image",
+    # Shopify API - Cache
+    "CacheCheckResult",
+    "CacheMismatch",
+    "cache_clear_all",
+    "skucache_check",
+    "skucache_clear",
+    "skucache_rebuild",
+    "tokencache_clear",
+    # Models - Read
+    "ShopifyCredentials",
+    "ShopifySessionInfo",
+    "Product",
+    "ProductVariant",
+    "ProductImage",
+    "ProductOption",
+    "Money",
+    "PriceRange",
+    "SEO",
+    "Metafield",
+    "MetafieldType",
+    "MediaStatus",
+    "ProductStatus",
+    "InventoryPolicy",
+    "InventoryQuantityName",
+    "InventoryReason",
+    "SelectedOption",
+    "WeightUnit",
+    "InventoryLevel",
+    # Models - Pagination
+    "PageInfo",
+    "ProductConnection",
+    # Models - Create
+    "ProductCreate",
+    # Models - Partial Update
+    "UNSET",
+    "UnsetType",
+    "ProductUpdate",
+    "VariantUpdate",
+    "MetafieldInput",
+    "VariantUpdateRequest",
+    "BulkUpdateResult",
+    "UpdateSuccess",
+    "UpdateFailure",
+    # Models - Metafield Deletion
+    "MetafieldIdentifier",
+    "MetafieldDeleteResult",
+    "MetafieldDeleteFailure",
+    # Models - Product Lifecycle
+    "DeleteProductResult",
+    "DuplicateProductResult",
+    # Models - Image Management
+    "ImageCreateFailure",
+    "ImageCreateResult",
+    "ImageCreateSuccess",
+    "ImageDeleteResult",
+    "ImageReorderResult",
+    "ImageSource",
+    "ImageUpdate",
+    "StagedUploadTarget",
+    # Exceptions
+    "ShopifyError",
+    "AuthenticationError",
+    "ProductNotFoundError",
+    "VariantNotFoundError",
+    "ImageNotFoundError",
+    "ImageUploadError",
+    "AmbiguousSKUError",
+    "SessionNotActiveError",
+    "GraphQLError",
+    "GraphQLErrorEntry",
+    "GraphQLErrorLocation",
+    "GraphQLTimeoutError",
+    # Configuration
+    "get_config",
+    "print_info",
+    # Application ports (for dependency injection)
+    "TokenProviderPort",
+    "GraphQLClientPort",
+    "SessionManagerPort",
+    "CachePort",
+    "SKUResolverPort",
+    "LocationResolverPort",
+    # Adapters
+    "JsonFileCacheAdapter",
+    "MySQLCacheAdapter",
+    "CachedSKUResolver",
+    "CachedTokenProvider",
+    "LocationResolver",
+    "PYMYSQL_AVAILABLE",
+    "DEFAULT_GRAPHQL_TIMEOUT_SECONDS",
+    # Composition
+    "AdapterBundle",
+    "create_adapters",
+    "create_cached_token_provider",
+    "get_default_adapters",
+]

lib_shopify_graphql/__init__conf__.py

@@ -0,0 +1,74 @@
+"""Static package metadata surfaced to CLI commands and documentation.
+
+Purpose
+-------
+Expose the current project metadata as simple constants. These values are kept
+in sync with ``pyproject.toml`` by development automation (tests, push
+pipelines), so runtime code does not query packaging metadata.
+
+Contents
+--------
+* Module-level constants describing the published package.
+* :func:`print_info` rendering the constants for the CLI ``info`` command.
+
+System Role
+-----------
+Lives in the adapters/platform layer; CLI transports import these constants to
+present authoritative project information without invoking packaging APIs.
+"""
+
+from __future__ import annotations
+
+#: Distribution name declared in ``pyproject.toml``.
+name = "lib_shopify_graphql"
+#: Human-readable summary shown in CLI help output.
+title = "Python library for Shopify GraphQL API interactions"
+#: Current release version pulled from ``pyproject.toml`` by automation.
+version = "2.0.0"
+#: Repository homepage presented to users.
+homepage = "https://github.com/bitranox/lib_shopify_graphql"
+#: Author attribution surfaced in CLI output.
+author = "bitranox"
+#: Contact email surfaced in CLI output.
+author_email = "bitranox@gmail.com"
+#: Console-script name published by the package.
+shell_command = "lib-shopify-graphql"
+
+#: Vendor identifier for lib_layered_config paths (macOS/Windows)
+LAYEREDCONF_VENDOR: str = "bitranox"
+#: Application display name for lib_layered_config paths (macOS/Windows)
+LAYEREDCONF_APP: str = "Lib Shopify Graphql"
+#: Configuration slug for lib_layered_config Linux paths and environment variables
+LAYEREDCONF_SLUG: str = "lib-shopify-graphql"
+
+
+def print_info() -> None:
+    """Print the summarised metadata block used by the CLI ``info`` command.
+
+    Why
+        Provides a single, auditable rendering function so documentation and
+        CLI output always match the system design reference.
+
+    Side Effects
+        Writes to ``stdout``.
+
+    Examples
+    --------
+    >>> print_info()  # doctest: +ELLIPSIS
+    Info for lib_shopify_graphql:
+    ...
+    """
+
+    fields = [
+        ("name", name),
+        ("title", title),
+        ("version", version),
+        ("homepage", homepage),
+        ("author", author),
+        ("author_email", author_email),
+        ("shell_command", shell_command),
+    ]
+    pad = max(len(label) for label, _ in fields)
+    lines = [f"Info for {name}:", ""]
+    lines.extend(f"    {label.ljust(pad)} = {value}" for label, value in fields)
+    print("\n".join(lines))

lib_shopify_graphql/__main__.py

@@ -0,0 +1,113 @@
+"""Module entry point ensuring SystemExit semantics match project standards.
+
+Provides the ``python -m lib_shopify_graphql`` path mandated by the
+project's packaging guidelines. The wrapper delegates to
+:func:`lib_shopify_graphql.cli.main` so that module execution mirrors the
+installed console script, including traceback handling and exit-code mapping.
+
+This module contains:
+    - :func:`_open_cli_session`: wires ``cli_session`` with the agreed limits.
+    - :func:`_command_to_run` / :func:`_command_name`: expose the command and label
+      used by the module entry.
+    - :func:`_module_main`: drives execution and returns the exit code.
+
+Note:
+    Lives in the adapters layer. It bridges CPython's module execution entry point
+    to the shared CLI helper while reusing the same ``cli_session`` orchestration
+    documented in ``docs/systemdesign/module_reference.md``.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+from typing import Final
+
+import lib_log_rich.runtime
+import rich_click as click
+from lib_cli_exit_tools import cli_session
+
+from . import __init__conf__, cli
+
+# Match the CLI defaults so truncation behaviour stays consistent across entry
+# points regardless of whether users call the console script or ``python -m``.
+#: Character budget for truncated tracebacks when running via module entry.
+TRACEBACK_SUMMARY_LIMIT: Final[int] = cli.TRACEBACK_SUMMARY_LIMIT
+#: Character budget for verbose tracebacks when running via module entry.
+TRACEBACK_VERBOSE_LIMIT: Final[int] = cli.TRACEBACK_VERBOSE_LIMIT
+
+
+CommandRunner = Callable[..., int]
+logger = logging.getLogger(__name__)
+
+
+def _open_cli_session() -> AbstractContextManager[CommandRunner]:
+    """Return the configured ``cli_session`` context manager.
+
+    ``cli_session`` wires ``lib_cli_exit_tools`` with the tracing limits we
+    want for module execution. Wrapping it keeps the configuration in a
+    single place.
+
+    Returns:
+        Context manager that yields the callable responsible for invoking
+        the Click command.
+    """
+    return cli_session(
+        summary_limit=TRACEBACK_SUMMARY_LIMIT,
+        verbose_limit=TRACEBACK_VERBOSE_LIMIT,
+    )
+
+
+def _command_to_run() -> click.Command:
+    """Expose the click command that powers the module entry.
+
+    Keeps the module entry explicit about which command is being executed
+    while remaining easy to stub in tests.
+
+    Returns:
+        Reference to the root CLI command group.
+    """
+    return cli.cli
+
+
+def _command_name() -> str:
+    """Return the shell-friendly name announced by the session.
+
+    ``lib_cli_exit_tools`` uses this value when presenting help and error
+    messages; we centralise the derivation so tests can assert against it.
+
+    Returns:
+        Name of the console script as published through entry points.
+    """
+    return __init__conf__.shell_command
+
+
+def _module_main() -> int:
+    """Execute the CLI entry point and return a normalised exit code.
+
+    Implements ``python -m lib_shopify_graphql`` by delegating to the
+    shared CLI composition while respecting the configured traceback
+    budgets.
+
+    Returns:
+        Exit code reported by the CLI run.
+
+    Note:
+        Logging initialization is deferred to cli() to support profile-specific
+        configuration. Shuts down lib_log_rich runtime on exit only if it was
+        initialized (e.g., --help exits before initialization).
+    """
+    try:
+        with _open_cli_session() as run:
+            return run(
+                _command_to_run(),
+                prog_name=_command_name(),
+            )
+    finally:
+        if lib_log_rich.runtime.is_initialised():
+            lib_log_rich.runtime.shutdown()
+
+
+if __name__ == "__main__":
+    raise SystemExit(_module_main())

lib_shopify_graphql/_compat.py

@@ -0,0 +1,32 @@
+"""Python version compatibility utilities.
+
+This module provides backports for features not available in all supported
+Python versions. The library supports Python 3.10+, but some standard library
+features (like StrEnum) were added in Python 3.11.
+
+Note:
+    This is the ONLY place compatibility shims should be defined.
+    All modules should import from here, not define their own shims.
+"""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 11):  # noqa: UP036 - intentional, we support Python 3.10
+    from enum import StrEnum
+else:
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        """Backport of StrEnum for Python 3.10.
+
+        StrEnum was added in Python 3.11. This provides equivalent
+        functionality for Python 3.10 users.
+        """
+
+        def __str__(self) -> str:
+            return str(self.value)
+
+
+__all__ = ["StrEnum"]

lib_shopify_graphql/adapters/__init__.py

@@ -0,0 +1,68 @@
+"""Adapters layer - implementations of application ports.
+
+This layer contains concrete implementations that interface with
+external systems:
+    - Shopify SDK adapter for API communication
+    - GraphQL query and mutation definitions
+    - Cache adapters (JSON file, MySQL)
+    - SKU and location resolvers
+
+Adapters implement the ports defined in the application layer
+and are wired at the composition root.
+
+Note:
+    GraphQL queries, mutations, limits, and query builders are internal
+    implementation details and not exported in the public API. Import them
+    directly from their submodules if needed:
+
+        from lib_shopify_graphql.adapters.queries import (
+            GraphQLLimits, build_product_query, get_limits_from_config,
+        )
+        from lib_shopify_graphql.adapters.mutations import (
+            PRODUCT_UPDATE_MUTATION, ...
+        )
+        from lib_shopify_graphql.adapters.parsers import (
+            parse_product, ...
+        )
+"""
+
+from __future__ import annotations
+
+from .cache_json import JsonFileCacheAdapter
+from .cache_mysql import PYMYSQL_AVAILABLE, MySQLCacheAdapter
+from .constants import (
+    DEFAULT_GRAPHQL_TIMEOUT_SECONDS,
+    get_default_cache_dir,
+    get_default_sku_cache_path,
+    get_default_token_cache_path,
+)
+from .location_resolver import LocationResolver
+from .shopify_sdk import (
+    ShopifyGraphQLClient,
+    ShopifySessionManager,
+    ShopifyTokenProvider,
+)
+from .sku_resolver import CachedSKUResolver
+from .token_cache import CachedTokenProvider
+
+__all__ = [
+    # Public constants
+    "DEFAULT_GRAPHQL_TIMEOUT_SECONDS",
+    "PYMYSQL_AVAILABLE",
+    # Cache path helpers
+    "get_default_cache_dir",
+    "get_default_sku_cache_path",
+    "get_default_token_cache_path",
+    # Shopify SDK adapters
+    "ShopifyGraphQLClient",
+    "ShopifySessionManager",
+    "ShopifyTokenProvider",
+    # Cache adapters
+    "JsonFileCacheAdapter",
+    "MySQLCacheAdapter",
+    # Token caching
+    "CachedTokenProvider",
+    # Resolvers
+    "CachedSKUResolver",
+    "LocationResolver",
+]