Config

The Config class handles validation and storage of SDK configuration parameters. It’s used internally by ClioMonitor but can be useful for advanced configuration scenarios.

Constructor

Config(api_key, **kwargs)

Creates a new configuration object with validation.

from clio.config import Config

config = Config(
    api_key="clio_your_api_key",
    base_url="https://api.cliomonitoring.com",
    retry_attempts=3,
    raise_on_error=False,
    timeout=30,
    verify_ssl=True
)

Parameters

Parameter	Type	Default	Description
api_key	str	Required	Clio API key (must start with clio_)
base_url	str	"https://api.cliomonitoring.com"	API server URL
retry_attempts	int	3	Upload retry attempts (1-10)
raise_on_error	bool	False	Raise exceptions on errors
timeout	int	30	HTTP request timeout in seconds
verify_ssl	bool	True	Verify SSL certificates

Validation

The constructor performs comprehensive validation:

API Key Validation:

• Must not be empty
• Must start with clio_
• Should be at least 20 characters long

URL Validation:

• Must be a valid URL format
• Must use http or https scheme
• Issues security warning for non-localhost HTTP URLs

Parameter Validation:

• retry_attempts should be between 1-10
• timeout should be positive
• All required parameters must be provided

Raises

• ValueError - Invalid API key format or empty key
• ValueError - Invalid base_url format or unsupported scheme
• SecurityWarning - HTTP URL used with non-localhost host

Examples

# Basic configuration
config = Config(api_key="clio_abc123...")

# Development configuration
config = Config(
    api_key="clio_abc123...",
    base_url="http://localhost:8000",
    raise_on_error=True,
    timeout=60
)

# Production configuration with retries
config = Config(
    api_key="clio_abc123...",
    base_url="https://api.cliomonitoring.com",
    retry_attempts=5,
    verify_ssl=True,
    timeout=120
)

Properties

api_key

The API key used for authentication. Never logged or exposed in error messages.

config = Config(api_key="clio_secret123")
print(config.api_key)  # "clio_secret123" (only in direct access)

base_url

The API server URL, normalized to remove trailing slashes.

config = Config(api_key="clio_abc123", base_url="https://api.cliomonitoring.com/")
print(config.base_url)  # "https://api.cliomonitoring.com" (trailing slash removed)

retry_attempts

Number of times to retry failed operations.

config = Config(api_key="clio_abc123", retry_attempts=5)
print(config.retry_attempts)  # 5

raise_on_error

Whether exceptions should be raised on errors.

# Silent mode - logs errors but continues
config = Config(api_key="clio_abc123", raise_on_error=False)

# Strict mode - raises exceptions
config = Config(api_key="clio_abc123", raise_on_error=True)

timeout

HTTP request timeout in seconds.

config = Config(api_key="clio_abc123", timeout=60)
print(config.timeout)  # 60

verify_ssl

Whether to verify SSL certificates.

# Production - verify SSL (default)
config = Config(api_key="clio_abc123", verify_ssl=True)

# Development - skip SSL verification (not recommended)
config = Config(api_key="clio_abc123", verify_ssl=False)

headers

Property that returns HTTP headers for API requests. The API key is included in the Authorization header.

config = Config(api_key="clio_abc123")
headers = config.headers
print(headers)
# {
#     "Authorization": "Bearer clio_abc123...",
#     "Content-Type": "application/json"
# }

Sensitive Data

The headers property contains your API key. Be careful when logging or debugging to avoid exposing it.

Methods

__repr__()

Returns a safe string representation with masked sensitive data.

config = Config(
    api_key="clio_very_secret_api_key_12345",
    base_url="https://api.cliomonitoring.com",
    retry_attempts=3
)

print(repr(config))
# Config(api_key='clio_****', base_url='https://api.cliomonitoring.com', retry_attempts=3)

The API key is automatically masked to prevent accidental exposure in logs or debug output.

URL Validation

The Config class performs thorough URL validation:

Valid URLs

# HTTPS (recommended)
Config(api_key="clio_abc123", base_url="https://api.cliomonitoring.com")

# HTTP localhost (development)
Config(api_key="clio_abc123", base_url="http://localhost:8000")
Config(api_key="clio_abc123", base_url="http://127.0.0.1:3000")

# Custom ports
Config(api_key="clio_abc123", base_url="https://api.example.com:8443")

Invalid URLs

# Missing scheme
Config(api_key="clio_abc123", base_url="api.cliomonitoring.com")  # ❌ ValueError

# Invalid scheme
Config(api_key="clio_abc123", base_url="ftp://api.cliomonitoring.com")  # ❌ ValueError

# Empty URL
Config(api_key="clio_abc123", base_url="")  # ❌ ValueError

Security Warnings

# This will issue a SecurityWarning
Config(api_key="clio_abc123", base_url="http://api.cliomonitoring.com")
# Warning: Using HTTP for non-localhost connections is insecure

Advanced Usage

Custom Timeout Configuration

Different timeout values for different use cases:

# Quick timeout for fast networks
config = Config(api_key="clio_abc123", timeout=10)

# Extended timeout for large uploads
config = Config(api_key="clio_abc123", timeout=300)  # 5 minutes

# CI/CD environment with network restrictions
config = Config(api_key="clio_abc123", timeout=120)  # 2 minutes

Retry Configuration

Configure retry behavior based on your environment:

# Development - fail fast
config = Config(api_key="clio_abc123", retry_attempts=1)

# Production - be resilient
config = Config(api_key="clio_abc123", retry_attempts=5)

# Critical workflows - maximum retries
config = Config(api_key="clio_abc123", retry_attempts=10)

SSL Configuration

Handle different SSL scenarios:

# Production - strict SSL
config = Config(api_key="clio_abc123", verify_ssl=True)

# Development with self-signed certificates
config = Config(api_key="clio_abc123", verify_ssl=False)

# Corporate proxy with custom CA
config = Config(
    api_key="clio_abc123",
    verify_ssl=True,
    # Note: Custom CA configuration would require additional setup
)

Integration with ClioMonitor

The Config class is typically used indirectly through ClioMonitor:

from clio import ClioMonitor

# ClioMonitor creates a Config internally
monitor = ClioMonitor(
    api_key="clio_abc123",
    base_url="https://api.cliomonitoring.com",
    retry_attempts=3
)

# Access the config if needed
print(monitor.config.base_url)  # "https://api.cliomonitoring.com"
print(monitor.config)  # Config(api_key='clio_****', ...)

Error Handling

The Config class provides detailed error messages:

try:
    config = Config(api_key="invalid_key")
except ValueError as e:
    print(e)  # "Invalid API key format"

try:
    config = Config(api_key="clio_abc123", base_url="not-a-url")
except ValueError as e:
    print(e)  # "Invalid base_url format: not-a-url"

Best Practices

1. Use environment variables for API keys:

   import os
   config = Config(api_key=os.getenv("CLIO_API_KEY"))

2. Enable SSL verification in production:

   config = Config(api_key="clio_abc123", verify_ssl=True)

3. Adjust timeouts based on your network:

   # Fast local network
   config = Config(api_key="clio_abc123", timeout=15)
   
   # Slow or unreliable network
   config = Config(api_key="clio_abc123", timeout=180)

4. Configure retries for your use case:

   # Interactive development
   config = Config(api_key="clio_abc123", retry_attempts=1)
   
   # Automated CI/CD
   config = Config(api_key="clio_abc123", retry_attempts=5)

5. Use raise_on_error during development:

   # Development
   config = Config(api_key="clio_abc123", raise_on_error=True)
   
   # Production
   config = Config(api_key="clio_abc123", raise_on_error=False)