2026-11-17 21:22:55 +06:00
# DataStack Python SDK (`datastack-sdk`)
2026-10-23 11:43:49 -05:00
2026-11-17 21:22:55 +06:00
[](../LICENSE)
[](https://www.python.org/)
[](https://vib.tools/)
Official Python client library for **DataStack — Self-Hosted Real-Time Telemetry & Event Logging Platform** , developed by ** [Vib Tools ](https://vib.tools/ )**.
2026-11-18 05:18:55 +06:00
`datastack-sdk` is a compatibility alias for the canonical ** `datastack` ** package located at [`../sdk/python/datastack` ](../sdk/python/datastack ). Both `from datastack import DataStack` and `from datastack_sdk import DataStackClient` share a single source of truth with `config.datastack.py` auto-discovery, `CLIENT_ID` wiring, Socket.IO streaming, automatic HTTP fallback, offline disk spooling, and direct `.csv` /`.json` /`.jsonl` file streaming.
2026-11-17 21:22:55 +06:00
---
2026-10-23 11:43:49 -05:00
## Installation
2026-11-18 05:18:55 +06:00
Install the canonical package directly from `sdk/python/datastack` :
```bash
pip install ./sdk/python/datastack
```
Or install the compatibility alias from `sdk-python` :
2026-10-23 11:43:49 -05:00
```bash
pip install ./sdk-python
```
2026-11-17 21:22:55 +06:00
---
2026-10-23 11:43:49 -05:00
## Quick Start
```python
from datastack_sdk import DataStackClient
2026-11-17 21:22:55 +06:00
# 1. Initialize the client with a signed JWT token from /vcon/clients or /vcon/sdk
2026-10-23 11:43:49 -05:00
client = DataStackClient (
server_url = "http://localhost:4000" ,
2026-11-18 05:18:55 +06:00
api_url = "http://localhost:3000" ,
2026-11-17 21:22:55 +06:00
token = "YOUR_CLIENT_JWT_TOKEN" ,
2026-11-18 05:18:55 +06:00
client_id = "YOUR_CLIENT_ID" , # optional (auto-derived from JWT sub/clientId)
2026-10-23 11:43:49 -05:00
)
2026-11-18 05:18:55 +06:00
# 2. Connect to the DataStack Socket.IO server (or auto HTTP fallback)
2026-10-23 11:43:49 -05:00
if client . connect ():
2026-11-17 21:22:55 +06:00
# 3. Stream a single structured event and wait for server acknowledgment
res = client . sync (
data = {
"event_type" : "service_heartbeat" ,
"service" : "billing-worker" ,
"latency_ms" : 18.4 ,
"status" : "healthy" ,
},
timeout = 5.0 ,
)
2026-10-23 11:43:49 -05:00
print ( "Sync result:" , res )
2026-11-17 21:22:55 +06:00
# 4. Stream a batch of events in a single round-trip
batch_res = client . batch_sync (
records = [
{ "metric" : "cpu_load" , "value" : 42.1 , "unit" : "%" },
{ "metric" : "mem_usage" , "value" : 68.5 , "unit" : "%" },
{ "metric" : "disk_free_gb" , "value" : 124.0 , "unit" : "GB" },
],
timeout = 10.0 ,
)
2026-10-23 11:43:49 -05:00
print ( "Batch result:" , batch_res )
2026-11-17 21:22:55 +06:00
# 5. Disconnect cleanly
2026-10-23 11:43:49 -05:00
client . disconnect ()
```
2026-11-17 21:22:55 +06:00
---
## API Reference
### `DataStackClient(server_url="http://localhost:4000", token="", reconnection_attempts=5, reconnection_delay=1)`
Creates a new Socket.IO client instance configured for DataStack handshake authentication.
### `client.connect(wait_timeout=5) -> bool`
Establishes a WebSocket/Socket.IO connection to the DataStack Port 4000 ingestion server using `auth={"token": self.token}` . Returns `True` on success or `False` on connection failure.
### `client.sync(data, event_id=None, timeout=5.0) -> dict`
Emits a single event (`sync_data` ) and blocks via `threading.Event.wait(timeout)` until the server responds.
- **Returns**: `{"success": True, "eventId": "evt_..."}` or `{"success": False, "eventId": "evt_...", "error": "..."}` .
### `client.batch_sync(records, timeout=10.0) -> dict`
Emits a list of event dictionaries (`batch_sync` ) and blocks via `threading.Event.wait(timeout)` until the server acknowledges the batch.
- **Returns**: `{"success": True, "processed": N, "rejected": M}` .
### `client.disconnect()`
Cleanly closes the active Socket.IO connection.
---
2026-11-18 10:03:40 +06:00
## Canonical Documentation Suite
For exhaustive documentation on configuration auto-discovery, HTTP fallback, offline disk spooling, direct file streaming, and error handling, consult the canonical documentation:
- **[Python SDK Documentation Hub ](../sdk/python/datastack/docs/README.md )**
- **[Installation Guide ](../sdk/python/datastack/docs/INSTALLATION.md )**
- **[Quickstart Guide ](../sdk/python/datastack/docs/QUICKSTART.md )**
- **[API Reference ](../sdk/python/datastack/docs/API_REFERENCE.md )**
- **[Configuration Guide ](../sdk/python/datastack/docs/CONFIGURATION.md )**
- **[Practical Examples ](../sdk/python/datastack/docs/EXAMPLES.md )**
- **[Error Handling Guide ](../sdk/python/datastack/docs/ERROR_HANDLING.md )**
- **[Lifecycle & Resilience ](../sdk/python/datastack/docs/LIFECYCLE.md )**
---
2026-11-17 21:22:55 +06:00
## Author & Support
Developed and maintained by ** [Vib Tools ](https://vib.tools/ )**:
- **Website**: [https://vib.tools/ ](https://vib.tools/ )
- **GitHub**: [https://github.com/vibtoolshq ](https://github.com/vibtoolshq )
- **General Email**: [hello@vibtools.io ](mailto:hello@vibtools.io )
- **Technical Support**: [support@vibtools.io ](mailto:support@vibtools.io )
## License
Released under the [MIT License ](../LICENSE ).