feat(sdk): refactor Python SDK documentation
- 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.
This commit is contained in:
1 parent
4279da45bb
commit
40a6855724
38 files changed
+3315
-141
No files matched your search
@@ -0,0 +1,112 @@
|
||||
# Quickstart Guide
|
||||
|
||||
Get up and running with the DataStack Python SDK in under 5 minutes.
|
||||
|
||||
---
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
1. A running DataStack instance (local dev or production server).
|
||||
2. A signed client token obtained from the Admin Console at **`/vcon/clients`** or **`/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.
|
||||
|
||||
```python
|
||||
# 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:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```python
|
||||
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
|
||||
```
|
||||
Reference in new issue
Block a user