Documentation

Environment Variables

Configure the SDK using environment variables for secure and flexible deployments

Best Practice

Using environment variables for configuration keeps sensitive data like API keys out of your code and allows different settings for development, staging, and production environments.

Using from_env() Factory Method

The recommended way to use environment variables is with the from_env() factory method

python

from scopix import Scopix, SyncScopix

# Async client - loads all config from environment variables
async with Scopix.from_env() as client:
    result = await client.files.upload("photo.jpg")

# Sync client - same pattern
with SyncScopix.from_env() as client:
    result = client.files.upload("photo.jpg")

# Override specific values while using env vars for the rest
async with Scopix.from_env(timeout=60.0) as client:
    result = await client.files.upload("photo.jpg")

Environment Variables Reference

All supported environment variables

Variable	Type	Default	Description
`SCOPIX_API_KEY`	string	Required	Your Scopix API key
`SCOPIX_BASE_URL`	string	Production API	API base URL
`SCOPIX_TIMEOUT`	float	300.0	Request timeout in seconds
`SCOPIX_MAX_RETRIES`	int	3	Maximum retry attempts
`SCOPIX_RETRY_DELAY`	float	1.0	Initial retry delay (exponential backoff)
`SCOPIX_POLLING_INTERVAL`	float	2.0	Interval between status polls
`SCOPIX_POLLING_TIMEOUT`	float	360.0	Maximum polling wait time
`SCOPIX_TENANT_ID`	string	None	Tenant ID for multi-tenant deployments
`SCOPIX_PROXY_URL`	string	None	Proxy URL (http or https)
`SCOPIX_ENABLE_TRACING`	bool	false	Enable OpenTelemetry tracing. Accepted values: `true`, `1`, `yes`, `on` (case-insensitive)

Setting Environment Variables

Set variables in your shell or system environment

bash

# Linux / macOS
export SCOPIX_API_KEY="scopix_your_api_key_here"
export SCOPIX_TIMEOUT="60.0"

# Windows PowerShell
$env:SCOPIX_API_KEY = "scopix_your_api_key_here"
$env:SCOPIX_TIMEOUT = "60.0"

Using .env Files

Install python-dotenv

For local development, use a .env file with the optional dotenv extra

bash

# Install SDK with dotenv support
pip install "scopix[dotenv]" --extra-index-url https://scopix:YOUR_API_KEY@api.scopix.ai/api/v2/sdk/simple/

Create .env File

Create a .env file in your project root

bash

# .env file
SCOPIX_API_KEY=scopix_your_api_key_here
SCOPIX_TIMEOUT=60.0
SCOPIX_MAX_RETRIES=5
SCOPIX_RETRY_DELAY=0.5
SCOPIX_POLLING_INTERVAL=3.0
SCOPIX_POLLING_TIMEOUT=180.0

Load .env in Your Code

Use the load_dotenv() helper before creating the client

python

from scopix import load_dotenv, Scopix

# Load .env file first
load_dotenv()

# Now from_env() picks up values from .env
async with Scopix.from_env() as client:
    result = await client.files.upload("photo.jpg")
    print(result.description)

Custom .env Path

Specify a custom path to your .env file

python

from pathlib import Path
from scopix import load_dotenv, Scopix

# Load from a specific path (string or Path)
load_dotenv("/path/to/config/.env")
load_dotenv(Path("config") / ".env")

# Override existing values (useful for testing)
load_dotenv(".env.test", override=True)

async with Scopix.from_env() as client:
    result = await client.files.upload("photo.jpg")

Security Warning

Never commit .env files containing API keys to version control. Add .env to your .gitignore file.

Priority Order

When resolving configuration values, the SDK uses this priority

Explicit parameters passed to from_env()
Environment variables (from OS or .env file)
Default values defined in the SDK

python

# SCOPIX_TIMEOUT=120.0 is set in environment

# This uses timeout=60.0 (explicit parameter wins)
async with Scopix.from_env(timeout=60.0) as client:
    ...

# This uses timeout=120.0 (from environment)
async with Scopix.from_env() as client:
    ...

Accessing Constants in Code

Environment variable names are exported as constants

python

from scopix import (
    ENV_API_KEY,
    ENV_BASE_URL,
    ENV_TIMEOUT,
    ENV_MAX_RETRIES,
    ENV_RETRY_DELAY,
    ENV_POLLING_INTERVAL,
    ENV_POLLING_TIMEOUT,
    ENV_TENANT_ID,
    ENV_PROXY_URL,
    ENV_ENABLE_TRACING,
)

import os

# Check if API key is configured
if not os.environ.get(ENV_API_KEY):
    print(f"Please set {ENV_API_KEY} environment variable")

What's Next?

Client Configuration

All configuration options and patterns

Error Handling

Handle configuration and connection errors

SDK Tutorial

Learn the core SDK workflows