> **Production-Grade Python Client for DataStack** — featuring automatic `config.datastack.py` configuration discovery, real-time Socket.IO streaming (`Port 4000`), automatic Heartbeat HTTP fallback (`Port 3000`), offline disk spooling, and direct `.csv`, `.json`, and `.jsonl` file ingestion.
---
## 1. Installation
### Install from Local Repository
```bash
pip install ./sdk/python/datastack
```
### Editable Development Mode
```bash
pip install -e ./sdk/python/datastack
```
### PyPI Package Installation
```bash
pip install datastack
```
---
## 2. Zero-Boilerplate Setup with `config.datastack.py`
Create a file named **`config.datastack.py`** in your Python project's root directory (you can also copy a pre-filled version directly from the DataStack Admin Console at **`/vcon/sdk`**):
```python
# config.datastack.py
DATASTACK_CONFIG={
"SERVER_URL":"http://localhost:4000",# Port 4000 Socket.IO Ingestion Service
"API_URL":"http://localhost:3000",# Port 3000 HTTP Fallback & File Ingestion API
"CLIENT_TOKEN":"YOUR_CLIENT_JWT_TOKEN",# Provisioned in /vcon/clients
## 4. Smart Connection State Machine & Auto-Recovery
The DataStack Python SDK maintains a 4-state resilience lifecycle managed by `HeartbeatMonitor`:
1.**`CONNECTED_IDLE` (Primary WebSocket Active — Heartbeat IDLE)**:
- Events stream over Socket.IO (`Port 4000`) with sub-millisecond overhead.
- The Heartbeat Monitor sleeps in **IDLE mode** (`heartbeatMode: "IDLE"`), consuming zero network or CPU resources.
2.**`FALLBACK_HTTP` (WebSocket Disconnected — Auto HTTP Fallback Active)**:
- If the WebSocket connection drops or closes, `send()`, `send_batch()`, and `send_file()` automatically switch to `POST {API_URL}/api/events` so zero application calls fail.
- Simultaneously, the Heartbeat Monitor wakes up (`heartbeatMode: "ACTIVE_RECOVERY"`), probes and reconnects the WebSocket in the background, verifies the handshake (`ping_verify`), and transitions back to **`CONNECTED_IDLE` (`IDLE` mode)**.
3.**`OFFLINE_SPOOL` (Device Offline — Local Disk Spooling)**:
- If the client machine loses internet connectivity completely, events are safely appended to `.datastack_spool/spool.jsonl` with deterministic `eventId`s.
- When the device comes back online, the Heartbeat Monitor detects connectivity, reconnects the WebSocket, replays all spooled events without duplicates, and returns to **`CONNECTED_IDLE` (`IDLE` mode)**.
4.**Structured Error Handling & Auto-Chunking**:
- **`413 PAYLOAD_TOO_LARGE`**: Batch/file payloads automatically split in half (`chunk // 2`) recursively and retry.
- **`429 RATE_LIMIT_EXCEEDED`**: Automatically retries with exponential backoff and random jitter.