Metadata-Version: 2.4
Name: pyshock
Version: 0.1.1
Summary: An up to date implementation of the PiShock and OpenShock APIs in Python. Includes functionality as a library and as a command line program.
Keywords: pishock,openshock,iot,remote-control,hardware
Author: jwinpbe
Author-email: jwinpbe <jwin_pbe@proton.me>
License-Expression: AGPL-3.0-or-later
License-File: COPYING
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware
Classifier: Typing :: Typed
Requires-Dist: niquests>=3.18.6
Requires-Dist: cyclopts>=4.10.2 ; extra == 'cli'
Requires-Dist: platformdirs>=4.9.6 ; extra == 'cli'
Requires-Dist: rich>=13.0 ; extra == 'cli'
Requires-Python: >=3.10
Project-URL: Repository, https://github.com/jwinpbe/pyshock
Project-URL: Issues, https://github.com/jwinpbe/pyshock/issues
Provides-Extra: cli
Description-Content-Type: text/markdown

# PyShock

Python client for the new, unified PiShock API and the Openshock API.

Control a shocker from the terminal, or add control to your program!

## Install

For the command line tool:

```
uv tool install 'pyshock[cli]'
```

Use it as a library in your python program:

```
uv add pyshock
```

## Usage

Set up credentials:

```
pyshock init
```

Control a device:

```
pyshock shock --duration 2 --intensity 75 --shocker-id 00000

# or, if you only have one shocker associated with your account:
pyshock shock 2 75
```

Run `pyshock info 00000` for device details. Run `pyshock devices` to list devices and capabilities.

## Authentication

Pass credentials on the command line or cache them with `pyshock init`.

With a flag:

```
pyshock --key KEY shock --duration 2 --intensity 15 --shocker-id 00000
```

Interactively:

```
pyshock auth

Enter your API key: _____
```

Or in one step:

```
pyshock auth --key KEY
```

PyShock stores credentials in your user configuration folder. Shockers are cached to avoid API lookups. Refresh with `pyshock devices`.

Be advised, your API key will be stored in plain text. 

## API

### PiShockAPI

```python
from pyshock import PiShockAPI, ShockerOperation

with PiShockAPI(api_key="key") as api:
    for shocker in api.list_shockers():
        print(shocker.name, shocker.shocker_id)

    shared_shocker = api.get_shocker_by_share_code("ABC123456")

    api.operate_shocker(
        shocker=shared_shocker,
        operation=ShockerOperation.SHOCK,
        duration=2000, # 2 seconds
        intensity=50,
    )
```

Operations: `ShockerOperation.SHOCK`, `VIBRATE`, `BEEP`. Duration in milliseconds (0-15000), intensity 0-100.

### OpenShockAPI

```python
from pyshock import OpenShockAPI, ShockerOperation

# Token authentication (limited endpoints)
with OpenShockAPI(api_token="token") as api:
    for shocker in api.list_shockers():
        print(shocker.name, shocker.shocker_id)
        api.operate_shocker(
            shocker=shocker,
            operation=ShockerOperation.SHOCK,
            duration=2000,
            intensity=50,
        )

# Cookie authentication (full access, including share codes)
from http.cookiejar import MozillaCookieJar

jar = MozillaCookieJar("cookies.txt")
jar.load(ignore_discard=True, ignore_expires=True)
cookie = jar["openShockSession"].value

with OpenShockAPI(session_cookie=cookie) as api:
    account = api.get_account()
    print(account.username)

    for shocker in api.list_share_codes():
        print(shocker.name, shocker.shocker_id)

    api.link_share_code("ABC123456")
```

Operations: `ShockerOperation.SHOCK`, `VIBRATE`, `BEEP`. Duration in milliseconds (300-65535), intensity 0-100.

## Requirements

Python 3.10+. Niquests for the library. The `[cli]` extra adds cyclopts, platformdirs, and rich for the terminal interface.

## License

Your choice of AGPLv3-or-later or commercial. See LICENSE for more information.
