openshock 0.1.0b1

The official OpenShock Python SDK to integrate with an OpenShock backend easily

OpenShock Python SDK

The official OpenShock Python SDK to integrate with an OpenShock backend easily. Provides a typed REST API client with planned support for live WebSocket connections.

Install

pip install openshock

Quick start

from openshock import OpenShockClient

client = OpenShockClient(api_token="your-api-token")

# Get backend info
info = client.meta.backend_info()
print(f"OpenShock {info.version}")

# List your shockers
shockers = client.shockers.list_own()

# Send a vibrate command
from openshock import Control

client.shockers.control([
    Control(id="shocker-uuid", type="Vibrate", intensity=50, duration=1000)
])

client.close()

Or use as a context manager:

with OpenShockClient(api_token="your-api-token") as client:
    stats = client.meta.online_stats()
    print(f"Devices online: {stats.devices_online}")

Resources

Resource	Description	Example
client.meta	Backend info and stats	client.meta.backend_info()
client.account	User info and API tokens	client.account.user_self()
client.devices	Hub (device) management	client.devices.list()
client.shockers	Shocker CRUD, control, logs	client.shockers.control(...)
client.shares	Public share links and codes	client.shares.list_public()
client.user_shares	User-to-user shares (V2)	client.user_shares.get()
client.sessions	Login session management	client.sessions.list()

For hub/device endpoints, use OpenShockHubClient:

from openshock import OpenShockHubClient

hub = OpenShockHubClient(hub_token="device-token")
lcg = hub.hub.assign_lcg()
print(f"Connect to {lcg.host}:{lcg.port}")

Authentication

Two client types for two auth schemes:

• OpenShockClient(api_token=...) — User API token (OpenShockToken header)
• OpenShockHubClient(hub_token=...) — Device token (DeviceToken header)

Create API tokens at openshock.app under Settings > API Tokens.

Typed models

All responses are parsed into typed dataclasses:

from openshock import (
    BackendInfo, Stats, User, Token, Device, Shocker,
    ShockerPermissions, ShockerLimits, ShockerLog, Control,
    Session, PublicShare, UserShares, ShareInvite, PauseReason,
)

Self-hosting

To connect to a self-hosted instance:

client = OpenShockClient(
    api_token="your-token",
    base_url="https://api.your-instance.com",
)

Development

git clone https://github.com/OpenShock/SDK.Python.git
cd SDK.Python
pip install -e ".[dev]"

# Format
ruff format .

# Lint
ruff check .

# Type check
mypy openshock/

# Test
pytest

License

MIT