Metadata-Version: 2.4
Name: pyelectrasmart
Version: 1.0.0
Summary: Python API library for Electra Smart air conditioners (maintained fork of pyElectra).
Author: Noam Okman
Author-email: Jafar Atili <at.jafar@outlook.com>
Maintainer: Noam Okman
License: Apache-2.0
Project-URL: homepage, https://github.com/noamokman/pyelectrasmart
Project-URL: repository, https://github.com/noamokman/pyelectrasmart
Project-URL: changelog, https://github.com/noamokman/pyelectrasmart/blob/main/CHANGELOG.md
Keywords: home,automation,Electra,smart,Electra Smart,Air Condition,aiohttp
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp
Dynamic: license-file

# pyElectraSmart

[![PyPI](https://img.shields.io/pypi/v/pyelectrasmart?label=pypi%20package)](https://pypi.org/project/pyelectrasmart)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/pyelectrasmart)](https://pypi.org/project/pyelectrasmart)

A **maintained fork** of [`pyElectra`](https://pypi.org/project/pyelectra/) — a Python
library to control **Electra Smart** air conditioners.

The original `pyElectra` (last release **1.2.4**, July 2024) is unmaintained and its
pinned release ships a `KeyError: 'deviceToken'` setup crash and a wrong
current-temperature reading. This fork keeps the same public API and import name
(`electrasmart`), fixes those bugs, and applies several code-quality corrections so
projects can pick up the fixes with a one-line dependency bump.

## Install

```sh
pip install pyelectrasmart
# or, if you use uv:
uv add pyelectrasmart
```

> Drop-in replacement: swap `pyElectra==1.2.4` → `pyelectrasmart==1.0.0`. The import
> name stays `electrasmart`, so no source changes are needed.

## Usage

```python
import asyncio

import aiohttp

from electrasmart import ElectraAPI, ElectraApiError
from electrasmart.api.utils import generate_imei


async def main():
    session = aiohttp.ClientSession(
        connector=aiohttp.TCPConnector(ssl=False),
        timeout=aiohttp.ClientTimeout(total=10),
    )
    api = ElectraAPI(session)

    # 1. Register your phone number
    imei = generate_imei()
    resp = await api.generate_new_token(phone_number="0521234567", imei=imei)
    print(resp)

    # 2. Confirm the OTP you received by SMS
    resp = await api.validate_one_time_password(
        otp="123456", imei=imei, phone_number="0521234567"
    )
    token = resp["data"]["token"]

    # 3. Connect with the token and enumerate devices
    api = ElectraAPI(session, imei=imei, token=token)
    await api.fetch_devices()
    for ac in api.devices:
        print(ac.name, ac.get_temperature(), ac.get_sensor_temperature())

    await session.close()


asyncio.run(main())
```

## Changes vs. upstream `pyElectra` 1.2.4

- **Fix: `KeyError: 'deviceToken'` crash** — the token field is not present in every
  device record; it is now read tolerantly (`data.get("deviceToken", "")`).
- **Fix: current-temperature miscalculation** — `I_RAT` / `I_CALC_AT` telemetry is a
  ×256 left-shifted integer (raw `5632` == `22` °C); it is now normalized back to
  Celsius inside the library.
- **Fix: correct API error messages** — exception messages are now formatted as `f`
  strings instead of leaving `%s` unsubstituted, and `Recieved` → `Received`.
- **Fix: don't leak the session ID into logs** — the `SID`, which authorizes cloud
  requests, is no longer logged.
- **Fix: don't log full device records** — `GET_DEVICES` payloads may contain
  `deviceToken` and device identifiers; only the device type is logged.
- **Fix: structured concurrency in `fetch_devices()`** — telemetry requests run in an
  `asyncio.TaskGroup` so a failing task can't leave siblings orphaned, and the
  underlying `ElectraApiError` is preserved for callers.
- Requires Python **>= 3.11** (for `asyncio.TaskGroup` / `ExceptionGroup`).

## Development

```sh
uv sync
uv run pytest
uv build
```

## License

Apache-2.0 — the same as the upstream `pyElectra` project. Original author: Jafar Atili.
