Skip to content

konigle

konigle

Konigle Integration Quickstart Python SDK

A comprehensive Python SDK for the Konigle platform APIs, providing type-safe, thread-safe, and async-capable access to CMS, commerce, and marketing resources.

Basic usage

import konigle

client = konigle.Client(api_key="your-api-key") products = client.products.list(status='published')

Async usage

import konigle

async with konigle.AsyncClient(api_key="your-api-key") as client: products = await client.products.list(status='published')

APIError

Bases: KonigleError

Base class for API-related errors with structured information.

PARAMETER DESCRIPTION
message

Human-readable error message

TYPE: str

status_code

HTTP status code from the API response

TYPE: Optional[int] DEFAULT: None

response

Full response data from the API

TYPE: Optional[Dict[str, Any]] DEFAULT: None

__str__()

Enhanced string representation with context.

AsyncClient

Main asynchronous client for Konigle API.

This client provides async access to all Konigle API resources through dedicated async manager objects. It handles session management and configuration automatically.

Example

async with konigle.AsyncClient(api_key="your-api-key") as client: products = await client.products.list() product = await client.products.get("product-id")

__aenter__() async

Async context manager entry.

__aexit__(exc_type, exc_val, exc_tb) async

Async context manager exit with cleanup.

__init__(api_key, base_url=BASE_URL, timeout=30.0, retry_count=3, retry_backoff=0.5, max_connections=100, keepalive_connections=20, user_agent=None, log_level='WARNING', log_requests=False, log_responses=False, enable_retry=True, **kwargs)

Initialize the async Konigle client.

PARAMETER DESCRIPTION
api_key

Konigle API key for authentication

TYPE: str

base_url

Base URL for the Konigle API

TYPE: Optional[str] DEFAULT: BASE_URL

timeout

Request timeout in seconds

TYPE: Optional[float] DEFAULT: 30.0

retry_count

Number of retries for failed requests

TYPE: Optional[int] DEFAULT: 3

retry_backoff

Base backoff time for exponential retry

TYPE: Optional[float] DEFAULT: 0.5

max_connections

Maximum number of HTTP connections in pool

TYPE: Optional[int] DEFAULT: 100

keepalive_connections

Number of connections to keep alive

TYPE: Optional[int] DEFAULT: 20

user_agent

Custom user agent string

TYPE: Optional[str] DEFAULT: None

log_level

Logging level (DEBUG, INFO, WARNING, ERROR)

TYPE: Optional[str] DEFAULT: 'WARNING'

log_requests

Whether to log HTTP requests

TYPE: Optional[bool] DEFAULT: False

log_responses

Whether to log HTTP responses

TYPE: Optional[bool] DEFAULT: False

enable_retry

Whether to enable automatic retries

TYPE: Optional[bool] DEFAULT: True

**kwargs

Additional configuration options

DEFAULT: {}

aclose() async

Close the async client and cleanup resources.

from_env() classmethod

Create async client from environment variables.

Environment variables should be prefixed with KONIQ_.

RETURNS DESCRIPTION
AsyncClient

AsyncClient instance configured from environment variables

AuthenticationError

Bases: APIError

Invalid API key or authentication failure (HTTP 401).

This error indicates that the provided API key is invalid, expired, or missing from the request.

AuthorizationError

Bases: APIError

Insufficient permissions for the requested operation (HTTP 403).

The API key is valid but doesn't have permission to perform the requested action on the specified resource.

Client

Main synchronous client for Konigle API.

This client provides access to all Konigle API resources through dedicated manager objects. It handles session management and configuration automatically.

Example: 

import konigle

client = konigle.Client(api_key="your-api-key")
products = client.products.list()
product = client.products.get("product-id")

__enter__()

Context manager entry.

__exit__(exc_type, exc_val, exc_tb)

Context manager exit with cleanup.

__init__(api_key, base_url=BASE_URL, timeout=30.0, retry_count=3, retry_backoff=0.5, max_connections=100, keepalive_connections=20, user_agent=None, log_level='WARNING', log_requests=False, log_responses=False, enable_retry=True, **kwargs)

Initialize the Konigle client.

PARAMETER DESCRIPTION
api_key

Konigle API key for authentication

TYPE: str

base_url

Base URL for the Konigle API

TYPE: Optional[str] DEFAULT: BASE_URL

timeout

Request timeout in seconds

TYPE: Optional[float] DEFAULT: 30.0

retry_count

Number of retries for failed requests

TYPE: Optional[int] DEFAULT: 3

retry_backoff

Base backoff time for exponential retry

TYPE: Optional[float] DEFAULT: 0.5

max_connections

Maximum number of HTTP connections in pool

TYPE: Optional[int] DEFAULT: 100

keepalive_connections

Number of connections to keep alive

TYPE: Optional[int] DEFAULT: 20

user_agent

Custom user agent string

TYPE: Optional[str] DEFAULT: None

log_level

Logging level (DEBUG, INFO, WARNING, ERROR)

TYPE: Optional[str] DEFAULT: 'WARNING'

log_requests

Whether to log HTTP requests

TYPE: Optional[bool] DEFAULT: False

log_responses

Whether to log HTTP responses

TYPE: Optional[bool] DEFAULT: False

enable_retry

Whether to enable automatic retries

TYPE: Optional[bool] DEFAULT: True

**kwargs

Additional configuration options

DEFAULT: {}

close()

Close the client and cleanup resources.

from_env() classmethod

Create client from environment variables.

Environment variables should be prefixed with KONIQ_.

RETURNS DESCRIPTION
Client

Client instance configured from environment variables

ClientConfig

Bases: BaseModel

Client configuration schema with validation and defaults.

This class defines all configuration options available for the Konigle SDK clients, with sensible defaults and environment variable support.

PARAMETER DESCRIPTION
api_key

Konigle API key for authentication
base_url

Base URL for the Konigle API
timeout

Request timeout in seconds
retry_count

Number of retries for failed requests
retry_backoff

Base backoff time for exponential retry
max_connections

Maximum number of HTTP connections in pool
keepalive_connections

Number of connections to keep alive
user_agent

Custom user agent string
log_level

Logging level (DEBUG, INFO, WARNING, ERROR)
log_requests

Whether to log HTTP requests
log_responses

Whether to log HTTP responses
enable_retry

Whether to enable automatic retries

api_key = Field(...) class-attribute instance-attribute

Konigle API key for authentication.

auth_prefix = Field(default='Token') class-attribute instance-attribute

Authentication header prefix (e.g., 'Token' or 'Bearer').

base_url = Field(default=BASE_URL) class-attribute instance-attribute

Base URL for the Konigle API.

enable_retry = Field(default=True) class-attribute instance-attribute

Whether to enable automatic retries.

keepalive_connections = Field(default=20, gt=0, le=100) class-attribute instance-attribute

Number of connections to keep alive.

log_level = Field(default='WARNING') class-attribute instance-attribute

Logging level (DEBUG, INFO, WARNING, ERROR).

log_requests = Field(default=False) class-attribute instance-attribute

Whether to log HTTP requests.

log_responses = Field(default=False) class-attribute instance-attribute

Whether to log HTTP responses.

max_connections = Field(default=100, gt=0, le=1000) class-attribute instance-attribute

Maximum number of HTTP connections in pool.

retry_backoff = Field(default=0.5, ge=0) class-attribute instance-attribute

Base backoff time for exponential retry.

retry_count = Field(default=3, ge=0, le=10) class-attribute instance-attribute

Number of retries for failed requests.

timeout = Field(default=30.0, gt=0) class-attribute instance-attribute

Request timeout in seconds.

user_agent = Field(default=None) class-attribute instance-attribute

Custom user agent string.

from_dict(config_dict) classmethod

Create configuration from a dictionary.

PARAMETER DESCRIPTION
config_dict

Dictionary containing configuration values

TYPE: Dict[str, Any]

RETURNS DESCRIPTION
ClientConfig

ClientConfig instance

from_env() classmethod

Create configuration from environment variables.

Environment variables should be prefixed with KONIQ_ and follow the field names. For example: KONIQ_API_KEY, KONIQ_BASE_URL, etc.

RETURNS DESCRIPTION
ClientConfig

ClientConfig instance populated from environment variables
RAISES DESCRIPTION
ValidationError

If required fields are missing or invalid

get_http_limits()

Get HTTPX limits configuration.

RETURNS DESCRIPTION
Dict[str, Any]

Dictionary with HTTPX limits configuration

get_user_agent()

Get the user agent string for HTTP requests.

RETURNS DESCRIPTION
str

User agent string, either custom or default

should_retry_status_code(status_code)

Determine if a status code should trigger a retry.

PARAMETER DESCRIPTION
status_code

HTTP status code

TYPE: int

RETURNS DESCRIPTION
bool

True if the status code indicates a retriable error

to_dict()

Export configuration as a dictionary.

RETURNS DESCRIPTION
Dict[str, Any]

Dictionary representation of the configuration

validate_base_url(v) classmethod

Normalize base URL by removing trailing slash.

validate_keepalive_connections()

Ensure keepalive connections doesn't exceed max connections.

validate_log_level(v) classmethod

Validate log level is a valid Python logging level.

ConflictError

Bases: APIError

Resource conflict (HTTP 409).

The request conflicts with the current state of the resource. Common causes include duplicate unique values or concurrent modifications.

KonigleError

Bases: Exception

Base exception for all SDK errors.

All Konigle SDK exceptions inherit from this base class, making it easy to catch any SDK-related error.

KonigleTimeoutError

Bases: KonigleError

Request timeout.

The request took longer than the configured timeout period.

NetworkError

Bases: KonigleError

Network connectivity issues.

This error is raised when network-level problems prevent communication with the API server.

NotFoundError

Bases: APIError

Resource not found (HTTP 404).

The requested resource does not exist or has been deleted.

RateLimitError

Bases: APIError

Rate limit exceeded (HTTP 429).

Too many requests have been made in a short time period.

PARAMETER DESCRIPTION
message

Rate limit error message

TYPE: str

retry_after

Number of seconds to wait before retrying

TYPE: Optional[int] DEFAULT: None

**kwargs

Additional arguments passed to APIError

DEFAULT: {}

__str__()

Enhanced representation including retry timing.

ServerError

Bases: APIError

Server-side errors (HTTP 5xx).

An error occurred on the server side. These errors are typically temporary and may be resolved by retrying the request.

ValidationError

Bases: APIError

Request validation failed (HTTP 400).

This error includes detailed information about which fields failed validation and why.

PARAMETER DESCRIPTION
message

General validation error message

TYPE: str

field_errors

Dictionary mapping field names to error messages

TYPE: Optional[Dict[str, Any]] DEFAULT: None

**kwargs

Additional arguments passed to APIError

DEFAULT: {}

__str__()

Enhanced representation including field-specific errors.

configure_logging(development=False)

Configure logging for environment.

PARAMETER DESCRIPTION
development

If True, configure for development with detailed output. If False, configure for production with JSON structured logs.

TYPE: bool DEFAULT: False

get_logger()

Get the main Konigle logger.

RETURNS DESCRIPTION
Logger

Main logger instance for the SDK

set_log_level(level)

Set SDK logging level.

PARAMETER DESCRIPTION
level

Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) as string or integer constant

TYPE: Union[str, int]