Configuration Options

The Clio SDK offers several configuration options to customize its behavior for different environments and use cases.

Configuration Parameters

api_key (Required)

Your Clio API key for authentication.

monitor = ClioMonitor(api_key="clio_your_key_here")

• Type: str
• Required: Yes
• Format: Must start with clio_
• Security: Never logged or exposed in error messages

base_url

The Clio API server URL.

# Production (default)
monitor = ClioMonitor(
    api_key="clio_key",
    base_url="https://api.cliomonitoring.com"
)

# Local development
monitor = ClioMonitor(
    api_key="clio_key",
    base_url="http://localhost:8000"
)

• Type: str
• Default: "https://api.cliomonitoring.com"
• Validation: Must be a valid HTTP/HTTPS URL
• Security: HTTP URLs issue warnings for non-localhost addresses

retry_attempts

Number of times to retry failed operations.

# Default retries
monitor = ClioMonitor(api_key="clio_key", retry_attempts=3)

# More aggressive retries for unreliable networks
monitor = ClioMonitor(api_key="clio_key", retry_attempts=5)

# Fail fast for development
monitor = ClioMonitor(api_key="clio_key", retry_attempts=1)

• Type: int
• Default: 3
• Range: 1-10 (practical limits)
• Applies to: Upload failures, API timeouts, network errors

raise_on_error

Whether to raise exceptions on errors or log them silently.

# Development - get detailed errors
monitor = ClioMonitor(
    api_key="clio_key",
    raise_on_error=True
)

# Production - graceful degradation
monitor = ClioMonitor(
    api_key="clio_key",
    raise_on_error=False  # Default
)

• Type: bool
• Default: False
• Development: Use True for debugging
• Production: Use False for resilience

timeout

HTTP request timeout in seconds.

# Fast local network
monitor = ClioMonitor(api_key="clio_key", timeout=10)

# Default timeout
monitor = ClioMonitor(api_key="clio_key", timeout=30)

# Slow/unreliable network
monitor = ClioMonitor(api_key="clio_key", timeout=120)

• Type: int
• Default: 30 seconds
• Upload timeouts: Calculated dynamically based on file size
• Minimum: 10 seconds recommended

verify_ssl

Whether to verify SSL certificates.

# Production - verify SSL (default)
monitor = ClioMonitor(api_key="clio_key", verify_ssl=True)

# Development with self-signed certs
monitor = ClioMonitor(api_key="clio_key", verify_ssl=False)

• Type: bool
• Default: True
• Production: Always use True
• Development: Only disable for localhost/self-signed certificates

Environment-Specific Configurations

Development

import os
from clio import ClioMonitor

monitor = ClioMonitor(
    api_key=os.getenv("CLIO_API_KEY"),
    base_url="http://localhost:8000",  # Local server
    retry_attempts=1,                  # Fail fast
    raise_on_error=True,              # See all errors
    timeout=60,                       # Generous timeout
    verify_ssl=False                  # Local dev server
)

Testing/CI

monitor = ClioMonitor(
    api_key=os.getenv("CLIO_API_KEY"),
    base_url="https://staging-api.cliomonitoring.com",
    retry_attempts=3,                 # Some resilience
    raise_on_error=False,            # Don't fail tests
    timeout=90,                      # CI can be slow
    verify_ssl=True
)

Production

monitor = ClioMonitor(
    api_key=os.getenv("CLIO_API_KEY"),
    base_url="https://api.cliomonitoring.com",
    retry_attempts=5,                # Maximum resilience
    raise_on_error=False,           # Graceful degradation
    timeout=120,                    # Handle slow uploads
    verify_ssl=True                 # Security required
)

Configuration Validation

The SDK validates all configuration on initialization:

API Key Validation

# ❌ Empty key
ClioMonitor(api_key="")
# ValueError: API key is required

# ❌ Wrong format
ClioMonitor(api_key="invalid_key")
# ValueError: Invalid API key format

# ✅ Correct format
ClioMonitor(api_key="clio_abc123...")

URL Validation

# ❌ Invalid URL
ClioMonitor(api_key="clio_key", base_url="not-a-url")
# ValueError: Invalid base_url format

# ❌ Unsupported scheme
ClioMonitor(api_key="clio_key", base_url="ftp://example.com")
# ValueError: base_url must use http or https scheme

# ⚠️ Insecure HTTP (warning issued)
ClioMonitor(api_key="clio_key", base_url="http://api.example.com")
# SecurityWarning: Using HTTP for non-localhost connections is insecure

# ✅ Valid HTTPS
ClioMonitor(api_key="clio_key", base_url="https://api.cliomonitoring.com")

Parameter Validation

# ❌ Invalid retry count
ClioMonitor(api_key="clio_key", retry_attempts=0)
# Minimum 1 retry recommended

# ❌ Invalid timeout
ClioMonitor(api_key="clio_key", timeout=-1)
# Must be positive

Advanced Configuration

Custom Headers

Currently not directly supported, but you can access the internal config:

monitor = ClioMonitor(api_key="clio_key")
# Access internal config
config = monitor.config
headers = config.headers  # Contains Authorization header

Proxy Configuration

For corporate environments with proxies, configure at the OS level:

export HTTPS_PROXY=https://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

The SDK will automatically use these proxy settings.

Custom CA Certificates

For custom certificate authorities:

import ssl
import httpx

# This would require custom implementation
# Currently not directly supported

Configuration File Support

While the SDK doesn’t directly support configuration files, you can create your own:

clio_config.py

import os
from dataclasses import dataclass

@dataclass
class ClioConfig:
    api_key: str
    base_url: str = "https://api.cliomonitoring.com"
    retry_attempts: int = 3
    raise_on_error: bool = False
    timeout: int = 30
    verify_ssl: bool = True

    @classmethod
    def from_env(cls):
        return cls(
            api_key=os.getenv("CLIO_API_KEY"),
            base_url=os.getenv("CLIO_BASE_URL", cls.base_url),
            retry_attempts=int(os.getenv("CLIO_RETRY_ATTEMPTS", cls.retry_attempts)),
            raise_on_error=os.getenv("CLIO_RAISE_ON_ERROR", "false").lower() == "true",
            timeout=int(os.getenv("CLIO_TIMEOUT", cls.timeout)),
            verify_ssl=os.getenv("CLIO_VERIFY_SSL", "true").lower() == "true"
        )

# Usage
config = ClioConfig.from_env()
monitor = ClioMonitor(**config.__dict__)

Configuration Best Practices

1. Environment-Specific Values

import os

def get_clio_config():
    env = os.getenv("ENVIRONMENT", "development")

    if env == "production":
        return {
            "retry_attempts": 5,
            "raise_on_error": False,
            "timeout": 120,
            "verify_ssl": True
        }
    elif env == "testing":
        return {
            "retry_attempts": 2,
            "raise_on_error": False,
            "timeout": 60,
            "verify_ssl": True
        }
    else:  # development
        return {
            "retry_attempts": 1,
            "raise_on_error": True,
            "timeout": 30,
            "verify_ssl": False
        }

config = get_clio_config()
monitor = ClioMonitor(api_key=os.getenv("CLIO_API_KEY"), **config)

2. Validation Functions

def validate_clio_config():
    api_key = os.getenv("CLIO_API_KEY")
    if not api_key:
        raise ValueError("CLIO_API_KEY environment variable required")

    if not api_key.startswith("clio_"):
        raise ValueError("Invalid API key format")

    return api_key

# Use in your application startup
api_key = validate_clio_config()
monitor = ClioMonitor(api_key=api_key)

3. Configuration Testing

def test_clio_configuration():
    """Test Clio configuration without making API calls"""
    try:
        monitor = ClioMonitor(
            api_key=os.getenv("CLIO_API_KEY"),
            base_url=os.getenv("CLIO_BASE_URL", "https://api.cliomonitoring.com")
        )
        print("✅ Configuration valid")
        return True
    except ValueError as e:
        print(f"❌ Configuration error: {e}")
        return False

# Run during application startup
if not test_clio_configuration():
    exit(1)

Troubleshooting Configuration

Common Issues

1. API Key Format: Ensure it starts with clio_
2. URL Format: Must be valid HTTP/HTTPS URL
3. Environment Variables: Check they’re set correctly
4. Network Access: Ensure the base_url is accessible
5. SSL Issues: Verify certificate validity or disable verification for development

Debug Configuration

monitor = ClioMonitor(api_key="clio_key", raise_on_error=True)
print(f"Configuration: {monitor.config}")
# Shows masked configuration for debugging

Configuration Logging

import logging
logging.basicConfig(level=logging.DEBUG)

# The SDK will log configuration details (with masked sensitive data)
monitor = ClioMonitor(api_key="clio_key")