JigsawStack Python SDK

Common errors

• jigsawstack.exceptions.AuthenticationError: Missing API key.

  cause The JigsawStack API client was initialized without a valid API key.
  fix Set the `JIGSAWSTACK_API_KEY` environment variable or pass the `api_key` argument directly to the `JigsawStack` constructor: `client = JigsawStack(api_key='YOUR_API_KEY')`.

• AttributeError: 'JigsawStack' object has no attribute 'old_method'

  cause An API method or service name was changed or removed in a newer version of the SDK.
  fix Consult the latest documentation for the correct method name and usage. This often occurs after significant SDK revamps like the one in v0.3.4.

• TypeError: 'NoneType' object is not subscriptable

  cause This typically occurs when trying to access a key or index on a response that is `None`, often due to an unexpected API response structure or an error from the API itself.
  fix Implement robust error handling and null checks when parsing API responses. Review the API documentation for expected response formats and potential error payloads, especially after SDK upgrades that might alter response model types.

• httpx.ConnectError: [Errno -2] Name or service not known

  cause The SDK could not connect to the JigsawStack API server due to a network issue, incorrect API endpoint, or DNS resolution failure.
  fix Check your internet connection and verify that the JigsawStack API endpoints are reachable. If you're using a custom base URL, ensure it's correct. Temporarily disabling VPN/proxy might help diagnose.

Warnings

• breaking The library frequently updates API response types and internal data models (e.g., in v0.3.7, v0.4.0, v0.4.3). This can break existing parsing logic or type checks when upgrading.
  Fix: Thoroughly review changelogs and test your code after upgrading, especially for logic dependent on specific response structures or Pydantic models. Consider pinning to exact minor versions.
• gotcha An API key is mandatory for all requests. Not providing a valid API key will result in authentication errors.
  Fix: Ensure the `JIGSAWSTACK_API_KEY` environment variable is correctly set, or pass your API key directly to the `JigsawStack` client constructor: `client = JigsawStack(api_key='YOUR_API_KEY')`.
• deprecated Previous versions (e.g., prior to v0.3.4) had known issues with multipart form requests for file uploads. While fixed, relying on very old versions for file operations is not recommended.
  Fix: Upgrade to version 0.3.4 or newer for reliable handling of file uploads and multipart requests, which included a major SDK revamp.
• gotcha As the SDK is under active development, method names, module paths, or available services might change between minor versions, especially during major internal refactors.
  Fix: Refer to the latest official documentation or GitHub README for the most up-to-date client usage patterns. If upgrading, carefully check for `AttributeError` or `ModuleNotFoundError`.

Install

• pip install jigsawstack Install stable version

Imports

• JigsawStack

  from jigsawstack import JigsawStack

Quickstart

Initializes the JigsawStack client using an API key from environment variables and performs a simple object detection task. The `JIGSAWSTACK_API_KEY` must be set for authentication.

import os
from jigsawstack import JigsawStack

# Ensure JIGSAWSTACK_API_KEY is set in your environment
api_key = os.environ.get("JIGSAWSTACK_API_KEY", "")

if not api_key:
    print("Error: JIGSAWSTACK_API_KEY environment variable not set.")
    exit(1)

client = JigsawStack(api_key=api_key)

# Example: Object Detection
try:
    response = client.image.object_detection(
        image_url="https://jigsawstack.io/images/object.jpeg"
    )
    print(f"Object Detection Response Status: {response.status_code}")
    if response.is_success:
        print(response.json())
    else:
        print(f"Error: {response.json()}")
except Exception as e:
    print(f"An error occurred: {e}")