Nanashi-OpenShockPY 0.1.0.0

UNOFFICIAL Lightweight Python client for the OpenShock API

OpenShock Python

Unofficial, lightweight helper for the OpenShock API. Designed to be easy to use for anyone, with optional advanced controls for developers.

What this project offers

• Simple Python client to list devices/shockers and send actions (shock, vibrate, beep).
• Full coverage of the OpenShock v1 and v2 APIs: hubs, shockers, shares, tokens, logs, sessions and account endpoints.
• Matching synchronous and asynchronous clients with the same method names.
• Optional CLI for quick checks without writing code.
• Keeps your API key in memory only; the CLI can store it securely via your system keyring.

License TL;DR (see full LICENSE.md for complete terms)

• Free for non-commercial, ethical use; you may study, modify, and share it.
• You can include it in other open-source projects as a separate library component.
• You must share source code for adaptations you distribute.
• No commercial use, monetization, or commercial AI training without a separate license.
• Adaptations must keep this license (unless used as a distinct component as allowed in Section 6A).

Quick start (Python)

1. Install the library:

   pip install Nanashi-OpenShockPY
   

2. Get your OpenShock API key from your account dashboard.

3. Create a client with a User-Agent and your API key:

   from OpenShockPY import OpenShockClient, OpenShockPYError
   
   client = OpenShockClient(
       api_key="YOUR_API_KEY",
       user_agent="YourAppName/YourAppVersion",
   )
   

4. List devices or send an action:

   print(client.list_devices())
   client.shock("YOUR_SHOCKER_ID", intensity=50, duration=1000)
   
   # Or send to all shockers at once using "all" as the shocker ID
   client.shock("all", intensity=50, duration=1000)
   # Alternatively, use the explicit *_all methods
   client.shock_all(intensity=50, duration=1000)
   

5. (Optional) Use as a context manager for automatic cleanup:

   with OpenShockClient(api_key="YOUR_API_KEY", user_agent="YourAppName/YourAppVersion") as client:
       client.list_devices()
   # Session is automatically closed when the block exits
   

   Note: The client also cleans up automatically when garbage collected, so the context manager is optional.

Optional CLI (no coding needed)

Install with CLI support:

pip install "Nanashi-OpenShockPY[cli]"

Store your API key securely, then list devices:

openshock login --api-key YOUR_KEY
openshock devices

Send a command (use a shocker ID, not a device ID):

openshock shock --shocker-id YOUR_SHOCKER_ID --intensity 40 --duration 1500

Or send a command to all shockers at once:

openshock shock --shocker-id all --intensity 40 --duration 1500

Other commands: shockers, vibrate, beep, stop, pause, unpause, logs, whoami, tokens, logout.

The CLI automatically sets an appropriate User-Agent. If the openshock command is not on your PATH, every example also works as python -m OpenShockPY.cli <command>.

Async client (opt-in)

If you prefer non-blocking operation, there is an experimental asynchronous client available: AsyncOpenShockClient. Install the optional dependencies:

pip install Nanashi-OpenShockPY[async]

Usage:

import asyncio
from OpenShockPY import AsyncOpenShockClient

async def main():
    async with AsyncOpenShockClient(api_key="YOUR_API_KEY", user_agent="YourAppName/YourAppVersion") as client:
        devices = await client.list_devices()
        await client.shock_all(intensity=50, duration=1000)

asyncio.run(main())

⚠️ Experimental / Unsupported: The AsyncOpenShockClient is an opt-in, experimental client provided for convenience. It is not officially supported or fully tested in production scenarios. Use at your own risk — APIs, behavior, or method signatures may change without notice. If stability and long-term support are required, prefer the synchronous OpenShockClient.

Installation options

• Library only (most people): pip install Nanashi-OpenShockPY
• Library + CLI extras (adds keyring): pip install "Nanashi-OpenShockPY[cli]"
• Library + Async extras (adds httpx, pytest-asyncio, respx): pip install "Nanashi-OpenShockPY[async]"
• Library + all extras: pip install "Nanashi-OpenShockPY[all]"
• Development/editable install from this repo: pip install -e . (or pip install -e ".[cli]" for CLI, pip install -e ".[all]" for all extras)

Responsible use and licensing

• This project is for non-commercial, ethical use only. Commercial use requires a separate license.
• Respect local laws and the rights and safety of others when issuing control commands.
• Full terms: LICENSE.md.

Need more detail?

Advanced options, API notes, and developer tips are available in ADVANCED.md.