Files
DataStack/sdk/python/datastack/docs/README.md
Team Dark Devil 40a6855724 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.
2026-11-18 10:03:40 +06:00

52 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.