- Standardize Python SDK (`datastack`) documentation with a new multi-file suite. - Update `datastack-sdk` to serve as a backward-compatible shim for the canonical `datastack` package. - Update project manifest and memory map to reflect current SDK structure and v2.2.0 features.
3.0 KiB
Quickstart Guide
Get up and running with the DataStack Python SDK in under 5 minutes.
1. Prerequisites
- A running DataStack instance (local dev or production server).
- A signed client token obtained from the Admin Console at
/vcon/clientsor/vcon/sdk.
2. Step 1: Create config.datastack.py
Place a config.datastack.py file in your application root directory (next to your main entry script). The SDK automatically searches your current working directory and up to three parent levels.
# config.datastack.py
DATASTACK_CONFIG = {
"SERVER_URL": "http://localhost:4000", # Port 4000 WebSocket Ingestion Server
"API_URL": "http://localhost:3000", # Port 3000 REST API & HTTP Fallback
"CLIENT_TOKEN": "YOUR_SIGNED_CLIENT_JWT", # Provisioned in /vcon/clients
"CLIENT_ID": "pos_terminal_01", # Optional (auto-derived from JWT if omitted)
"AUTO_CONNECT": True,
}
3. Step 2: Push Your First Telemetry Event
Create main.py and run it:
from datastack import DataStack
# Automatically discovers config.datastack.py, connects, and verifies handshake
client = DataStack()
# Push a single event
response = client.send({
"service": "checkout_worker",
"orderId": "ORD-98214",
"amount": 49.95,
"currency": "USD",
"status": "completed",
})
print("Ingestion Result:", response)
# Output:
# {'status': 'ok', 'eventId': 'evt_1700000000000_a1b2c3d4', 'transport': 'WEBSOCKET'}
# Graceful cleanup
client.disconnect()
4. Step 3: High-Volume Batch Streaming
Send multiple records in a single network round-trip. If the batch exceeds the server's maximum payload limit (413 PAYLOAD_TOO_LARGE), the SDK automatically splits the batch in half recursively:
from datastack import DataStack
client = DataStack()
metrics_batch = [
{"host": "worker-01", "cpu": 42.1, "mem_mb": 1024},
{"host": "worker-02", "cpu": 68.4, "mem_mb": 2048},
{"host": "worker-03", "cpu": 15.2, "mem_mb": 512},
]
result = client.send_batch(metrics_batch)
print(f"Processed: {result['processed']}, Duplicates: {result['duplicates']}")
client.disconnect()
5. Step 4: Direct File Ingestion
Stream an entire .csv, .json, .jsonl, or .ndjson dataset directly from disk. Records are assigned deterministic SHA-256 event IDs to guarantee idempotent delivery without memory bloat:
from datastack import DataStack
client = DataStack()
# Stream records in chunks of 250 rows
summary = client.send_file("device_logs.csv", chunk_size=250)
print(f"File: {summary['fileName']}, Processed {summary['processed']} rows.")
client.disconnect()
6. Context Manager (Auto-Cleanup)
Use Python's with statement to guarantee clean disconnection when execution completes:
from datastack import DataStack
with DataStack() as client:
client.send({"action": "system_startup", "timestamp_utc": "2026-11-17T12:00:00Z"})
print("Status:", client.status()["connectionState"])
# Client disconnects cleanly here automatically