Tendrl

Docs / Contact / sdks/python/configuration

Python SDK: Configuration

All configuration is passed to the Client constructor. Every parameter has a sensible default; only api_key is required (unless using the TENDRL_KEY environment variable or agent mode).

Constructor Parameters

Core

Parameter Type Default Description
mode str "api" "api" for direct HTTPS or "agent" for Nano Agent socket
api_key str None Entity API key. Falls back to TENDRL_KEY env var
headless bool False Disable background threads (synchronous only)
debug bool False Enable verbose logging

Batching & Performance

Parameter Type Default Description
min_batch_size int 10 Minimum messages per batch
max_batch_size int 100 Maximum messages per batch
min_batch_interval float 0.1 Minimum seconds between batch sends
max_batch_interval float 1.0 Maximum seconds before forced send
max_queue_size int 1000 Maximum messages in the queue
target_cpu_percent float 65.0 Target CPU % for dynamic batch sizing
target_mem_percent float 75.0 Target memory % for dynamic batch sizing

The SDK dynamically adjusts batch size based on CPU and memory usage. When system load is high, batch sizes shrink to reduce pressure. When load is low, batches grow for efficiency.

Offline Storage

Parameter Type Default Description
offline_storage bool False Enable SQLite message persistence
db_path str "tendrl_offline.db" Path to the SQLite database file

When enabled, messages that can't be sent (network down) are stored in SQLite with a TTL. They're automatically retried when connectivity returns.

Message Polling

Parameter Type Default Description
callback Callable None Catch-all when no @client.on() route matches
state_callback Callable None Catch-all when no @client.on_state() handler is set
check_msg_rate float 3.0 Seconds between message and state polls
check_msg_limit int 1 Maximum messages retrieved per poll

Inbound routing (@client.on())

Decorator Description
@client.on(msg_type=...) Match a specific message type
@client.on(tag=...) Match a single tag
@client.on(tags=[...]) Match if message has any listed tag
@client.on(tags_all=[...]) Match if message has all listed tags
@client.on_default Catch-all when no route matches

Inbound state (@client.on_state())

Decorator Description
@client.on_state() Handler when polled state table changes

Heartbeat

Parameter Type Default Description
send_heartbeat bool True Send periodic heartbeats with system metrics
heartbeat_interval int 30 Seconds between heartbeats

Heartbeats include memory and disk usage. They're automatically disabled in headless mode.

Environment Variables

Variable Purpose
TENDRL_KEY API key (used when api_key is not passed to constructor)
TENDRL_SOCKET Agent-mode socket path override (matches the Nano Agent's -socket flag)

Example Configurations

Development (Verbose, No Offline)

python

client = Client(
    api_key="dev_key",
    debug=True,
    send_heartbeat=False
)

Production IoT Device

python

client = Client(
    api_key="device_key",
    offline_storage=True,
    db_path="/var/lib/myapp/tendrl.db",
    max_batch_size=200,
    heartbeat_interval=60
)

High-Throughput Service

python

client = Client(
    mode="agent",  # Use Nano Agent for better performance
    min_batch_size=50,
    max_batch_size=500,
    max_queue_size=5000,
    target_cpu_percent=80.0
)

Simple Script (Headless)

python

client = Client(
    api_key="script_key",
    headless=True
)
# No start() needed; publish() sends directly
response = client.publish({"event": "deploy_complete"}, wait_response=True)

Socket Paths (Agent Mode)

When using mode="agent", the SDK connects to the Nano Agent's Unix socket:

Platform Socket Path
Linux/macOS /var/lib/tendrl/tendrl_agent.sock
Windows C:\ProgramData\tendrl\tendrl_agent.sock

Ensure the Nano Agent is running and your user is in the tendrl group.

← Back to Contact docs