- 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.
120 lines
4.6 KiB
Markdown
120 lines
4.6 KiB
Markdown
# DataStack Python SDK (`datastack-sdk`)
|
|
|
|
[](../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/)**.
|
|
|
|
`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.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
Install the canonical package directly from `sdk/python/datastack`:
|
|
|
|
```bash
|
|
pip install ./sdk/python/datastack
|
|
```
|
|
|
|
Or install the compatibility alias from `sdk-python`:
|
|
|
|
```bash
|
|
pip install ./sdk-python
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
```python
|
|
from datastack_sdk import DataStackClient
|
|
|
|
# 1. Initialize the client with a signed JWT token from /vcon/clients or /vcon/sdk
|
|
client = DataStackClient(
|
|
server_url="http://localhost:4000",
|
|
api_url="http://localhost:3000",
|
|
token="YOUR_CLIENT_JWT_TOKEN",
|
|
client_id="YOUR_CLIENT_ID", # optional (auto-derived from JWT sub/clientId)
|
|
)
|
|
|
|
# 2. Connect to the DataStack Socket.IO server (or auto HTTP fallback)
|
|
if client.connect():
|
|
# 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,
|
|
)
|
|
print("Sync result:", res)
|
|
|
|
# 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,
|
|
)
|
|
print("Batch result:", batch_res)
|
|
|
|
# 5. Disconnect cleanly
|
|
client.disconnect()
|
|
```
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## 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)**
|
|
|
|
---
|
|
|
|
## 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).
|