51 lines
4.2 KiB
Markdown
51 lines
4.2 KiB
Markdown
# DataStack Python SDK Documentation
|
|||
|
|
|
||
|
|
Welcome to the official developer documentation for the **DataStack Python SDK** (`datastack`).
|
||
|
|
|
||
|
|
This documentation suite provides a complete, compact technical reference for installing, configuring, operating, and troubleshooting the SDK in production environments.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. Documentation Index
|
||
|
|
|
||
|
|
| Guide | Description | Target Audience |
|
||
|
|
| :--- | :--- | :--- |
|
||
|
|
| **[Installation (`INSTALLATION.md`)](./INSTALLATION.md)** | Supported Python runtimes, package installation, virtual environments, and dependency requirements. | All Developers |
|
||
|
|
| **[Quickstart (`QUICKSTART.md`)](./QUICKSTART.md)** | 5-minute zero-boilerplate integration guide using `config.datastack.py`. | Getting Started |
|
||
|
|
| **[API Reference (`API_REFERENCE.md`)](./API_REFERENCE.md)** | Full specification of `DataStack`, public methods, parameter types, defaults, and return schemas. | Integration Engineers |
|
||
|
|
| **[Configuration Guide (`CONFIGURATION.md`)](./CONFIGURATION.md)** | Auto-discovery rules, configuration keys, environment variables (`DATASTACK_*`), and precedence order. | DevOps & Systems Engineers |
|
||
|
|
| **[Practical Examples (`EXAMPLES.md`)](./EXAMPLES.md)** | Real-world patterns: IoT sensor streaming, batch transactions, CSV/JSON file ingestion, and context managers. | Application Developers |
|
||
|
|
| **[Error Handling (`ERROR_HANDLING.md`)](./ERROR_HANDLING.md)** | Exception hierarchy, error codes (`401`, `403`, `413`, `429`), retry backoff, and non-retryable errors. | Production Support & QA |
|
||
|
|
| **[Lifecycle & Resilience (`LIFECYCLE.md`)](./LIFECYCLE.md)** | Smart Heartbeat Monitor, connection state machine, zero-CPU IDLE mode, and offline disk spooling. | Systems Architects |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. Architecture at a Glance
|
||
|
|
|
||
|
|
The DataStack Python SDK is built around a resilient dual-transport and auto-recovery architecture:
|
||
|
|
|
||
|
|
```text
|
||
|
|
┌────────────────────────────┐
|
||
|
|
│ DataStack Python SDK │
|
||
|
|
└──────────────┬─────────────┘
|
||
|
|
│
|
||
|
|
┌─────────────────────────┴─────────────────────────┐
|
||
|
|
│ Primary Transport │ Auto Fallback
|
||
|
|
▼ ▼
|
||
|
|
┌───────────────────────┐ ┌───────────────────────┐
|
||
|
|
│ Socket.IO Ingestion │ │ HTTP REST Fallback │
|
||
|
|
│ Port 4000 (WebSocket) │ │ Port 3000 (/api/events│
|
||
|
|
└───────────┬───────────┘ └───────────┬───────────┘
|
||
|
|
│ │
|
||
|
|
└─────────────────────────┬─────────────────────────┘
|
||
|
|
│ Both Unreachable (Offline)
|
||
|
|
▼
|
||
|
|
┌───────────────────────────┐
|
||
|
|
│ Offline Disk Spooler │
|
||
|
|
│ (.datastack_spool/*.jsonl)│
|
||
|
|
└───────────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
1. **Primary Real-Time Streaming (Port 4000)**: Events emit via Socket.IO WebSocket (`sync_data`, `batch_sync`). Once connected and verified (`ping_verify`), the background Heartbeat Monitor transitions to **zero-CPU IDLE mode**.
|
||
|
|
2. **Automatic HTTP Fallback (Port 3000)**: If the WebSocket disconnects, all calls seamlessly route through `POST /api/events` while the Heartbeat Monitor probes background reconnection.
|
||
|
|
3. **Offline Disk Spooling**: If the device loses internet entirely, events are safely persisted to `.datastack_spool/spool.jsonl` and automatically replayed in order once connectivity returns.
|