Metadata-Version: 2.4
Name: aioshelly
Version: 13.28.0
Summary: Asynchronous library to control Shelly devices.
Author-email: Paulus Schoutsen <paulus@home-assistant.io>
License-Expression: Apache-2.0
Project-URL: Source code, https://github.com/home-assistant-libs/aioshelly
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.14.0
Requires-Dist: bleak-retry-connector>=3.0.0
Requires-Dist: bluetooth-data-tools>=1.28.0
Requires-Dist: habluetooth>=6.3.0
Requires-Dist: orjson>=3.11.6
Requires-Dist: yarl
Requires-Dist: zeroconf>=0.148.0
Provides-Extra: lint
Requires-Dist: prek==0.4.10; extra == "lint"
Requires-Dist: pydocstyle==6.3.0; extra == "lint"
Requires-Dist: ruff==0.15.22; extra == "lint"
Requires-Dist: types-requests; extra == "lint"
Requires-Dist: ty==0.0.61; extra == "lint"
Provides-Extra: dev
Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
Requires-Dist: pytest==9.1.1; extra == "dev"
Requires-Dist: requests; extra == "dev"
Requires-Dist: tox==4.57.0; extra == "dev"
Dynamic: license-file

[![codecov](https://codecov.io/gh/home-assistant-libs/aioshelly/graph/badge.svg?token=DDH79OVIQ0)](https://codecov.io/gh/home-assistant-libs/aioshelly)
[![ci](https://img.shields.io/github/actions/workflow/status/home-assistant-libs/aioshelly/test.yml?branch=main&label=CI&logo=github&style=flat-square)](https://github.com/home-assistant-libs/aioshelly/actions/workflows/test.yml?query=branch%3Amain)

# Aioshelly

Asynchronous library to control Shelly devices

**This library is under development**

## Requirements

- Python >= 3.11
- bluetooth-data-tools
- aiohttp
- orjson

## Install

```bash
pip install aioshelly
```

## Install from Source

Run the following command inside this folder

```bash
pip install --upgrade .
```

## Prepare the development environment

Run the following commands inside this folder

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install uv
uv pip install .[dev] .[lint]
prek install
```

> [!NOTE]
> To activate venv on Windows use this command
>
> ```pwsh
> .\.venv\Scripts\Activate.ps1
>```

## Examples

### Gen1 Device (Block/CoAP) example

```python
import asyncio
from pprint import pprint

import aiohttp

from aioshelly.block_device import COAP, BlockDevice
from aioshelly.common import ConnectionOptions
from aioshelly.exceptions import DeviceConnectionError, InvalidAuthError


async def test_block_device():
    """Test Gen1 Block (CoAP) based device."""
    options = ConnectionOptions("192.168.1.165", "username", "password")

    async with aiohttp.ClientSession() as aiohttp_session, COAP() as coap_context:
        try:
            device = await BlockDevice.create(aiohttp_session, coap_context, options)
        except InvalidAuthError as err:
            print(f"Invalid or missing authorization, error: {repr(err)}")
            return
        except DeviceConnectionError as err:
            print(f"Error connecting to {options.ip_address}, error: {repr(err)}")
            return

        for block in device.blocks:
            print(block)
            pprint(block.current_values())
            print()


if __name__ == "__main__":
    asyncio.run(test_block_device())
```

### Gen2+ (RPC/WebSocket) device example

```python
import asyncio
from pprint import pprint

import aiohttp

from aioshelly.common import ConnectionOptions
from aioshelly.exceptions import DeviceConnectionError, InvalidAuthError
from aioshelly.rpc_device import RpcDevice, WsServer


async def test_rpc_device():
    """Test Gen2+ RPC (WebSocket) based device."""
    options = ConnectionOptions("192.168.1.188", "username", "password")
    ws_context = WsServer()
    await ws_context.initialize(8123)

    async with aiohttp.ClientSession() as aiohttp_session:
        try:
            device = await RpcDevice.create(aiohttp_session, ws_context, options)
        except InvalidAuthError as err:
            print(f"Invalid or missing authorization, error: {repr(err)}")
            return
        except DeviceConnectionError as err:
            print(f"Error connecting to {options.ip_address}, error: {repr(err)}")
            return

        pprint(device.status)


if __name__ == "__main__":
    asyncio.run(test_rpc_device())
```

## Example script

The repository includes example script to quickly try it out.

### Connect to a device and print its status whenever we receive a state change:

```bash
python3 tools/example.py -ip <ip> [-u <username>] [-p <password] -i
```

### Connect to all the devices in `devices.json` at once and print their status:

```bash
python3 tools/example.py -d -i
```

### Show usage help

```bash
python3 tools/example.py -h
```

## Contribution guidelines

Object hierarchy and property/method names should match the [Shelly API](https://shelly-api-docs.shelly.cloud/).
