​
SDK Configuration

After installing the Ocular SDK, you’ll need to configure it with your API credentials. This guide covers all available configuration options.

​
Basic Configuration

All you need to get started is your API key. Everything else has sensible defaults.

​
Direct Initialization

This is the simplest way to get started with the SDK for testing and development.

You can also configure the SDK directly in your code:

from ocular import Ocular

# Initialize with direct configuration
ocular = Ocular(api_key="your_api_key_here")

Avoid hardcoding API keys in production code. Use environment variables instead.

​
Configuration Parameters

Understanding these parameters will help you optimize the SDK for your specific use case.

The SDK accepts the following parameters during initialization:

ParameterTypeDefaultDescription
api_keystringNoneYour Ocular API key (required)
api_urlstring”https://api.useocular.com”Base URL for the Ocular API
timeoutinteger300Request timeout in seconds
max_retriesinteger3Maximum number of retry attempts
backoff_factorfloat0.5Exponential backoff factor for retries
debugbooleanFalseEnable detailed logging

Most users will only need to set the API key. The default values work well for standard use cases.

​
Complete Example

Copy this example to quickly get started with a fully configured SDK instance.

from ocular import Ocular

# Initialize with all available options
ocular = Ocular(
    api_key="your_api_key_here",
    api_url="https://api.useocular.com",
    timeout=300,
    max_retries=3,
    backoff_factor=0.5,
    debug=False
)

# Access your workspace
workspace = ocular.workspace("your_workspace_id")

​
Environment Variables

Using environment variables is the recommended approach for production deployments.

All configuration can be set using environment variables:

VariableDescriptionDefault
OCULAR_API_KEYYour API keyRequired
OCULAR_API_URLAPI base URL”https://api.useocular.com”
OCULAR_TIMEOUTRequest timeout300
OCULAR_MAX_RETRIESMax retry attempts3
OCULAR_BACKOFF_FACTORRetry backoff factor0.5
OCULAR_DEBUGDebug modefalse

Using environment variables is recommended for production environments to keep sensitive information out of your code.

​
Using With Python dotenv

This approach combines the security of environment variables with the convenience of a configuration file.

For development, you can use a .env file with the python-dotenv package:

# .env file
OCULAR_API_KEY=your_api_key_here

Then in your code:

from dotenv import load_dotenv
import os
from ocular import Ocular

# Load environment variables from .env file
load_dotenv()

# Initialize using values from .env
ocular = Ocular(api_key=os.environ.get("OCULAR_API_KEY"))

Never commit your .env file to version control. Add it to your .gitignore file.